Skip to content

Input Validation and Trust Boundaries

KiCad MCP Pro accepts structured input from MCP clients, integration adapters, workflow metadata, package managers, and user-provided KiCad projects. This page documents the validation rules used to keep those inputs inside the expected trust boundary.

General rules

  • Prefer typed schemas and explicit enums over free-form strings.
  • Treat every MCP argument, uploaded path, archive member, workflow expression, issue title, and environment variable as untrusted until validated.
  • Normalize and canonicalize before authorization decisions.
  • Validate both syntax and authorization: a path can be syntactically safe but still outside the allowed workspace.
  • Fail closed with actionable errors; do not silently broaden permissions.

Filesystem paths

Filesystem access must follow this sequence:

  1. Reject empty values, embedded NUL bytes, parent-directory traversal, and encoded traversal variants.
  2. Resolve the candidate to an absolute normalized path.
  3. Resolve symlinks with a realpath check when the target must already exist.
  4. Confirm the real path is inside an allowed workspace root.
  5. Check expected type: directory, regular file, or non-existing child path expected to be created.
  6. Enforce extension allowlists for KiCad project artifacts such as .kicad_proj, .kicad_pcb, and .kicad_sch.

When a file may not exist yet, validate the parent directory with realpath containment before accepting the child name.

KiCad project input

KiCad project files are treated as data, not as trusted code. Tools that parse KiCad artifacts should:

  • bound maximum input sizes where practical;
  • tolerate malformed or partial S-expressions without crashing;
  • avoid executing scripts or plugins embedded in a project;
  • keep generated manufacturing output in explicit output directories;
  • report heuristic confidence honestly in tool results.

Web, HTTP, and MCP transport input

HTTP or remote-MCP mode must not infer filesystem or subprocess permissions from network reachability. Any future authenticated transport must validate:

  • allowed origin or authentication context;
  • requested tool profile;
  • workspace boundary;
  • destructive-operation intent;
  • audit-safe logging that avoids secrets and private design data.

CI/CD metadata

GitHub Actions steps must not interpolate untrusted metadata directly into shell scripts. Use env: bindings and quoted variables for branch names, tag names, pull-request titles, release notes, and user-provided text. Publishing jobs must use protected environments and job-scoped permissions.

Verification

Validation behavior is checked through a combination of unit tests, CodeQL, workflow-security checks, Gitleaks, dependency audit, and fuzzing for shared parser helpers.