| name | exeris-ai-bridge-path-sandbox-review |
| description | Path-sandbox review for filesystem-bound tool handlers in exeris-ai-bridge. Use on every PR touching `src/tools/docs/**` or any new filesystem-bound family. |
Exeris AI Bridge Path-Sandbox Review
Purpose
Enforce: filesystem reads in docs:* (and any future filesystem-bound family) resolve under a pinned root (EXERIS_DOCS_ROOT / ../exeris-docs default) and reject paths that escape it.
Agent-supplied strings reach handlers. Sandbox is from day 1 per ROADMAP 0.2.0.
When to Use
- Any PR adding or changing a filesystem-bound handler.
- Any PR introducing a new filesystem-bound family.
- Any PR touching the path-resolution helper / root configuration.
Required Inputs
- PR diff scoped to
src/tools/docs/** (or new family).
- Path-resolution helper code.
- Root configuration (env var, default).
Review Procedure
- Input audit — does the handler accept a
path / filename / uri / name from the agent?
- Absolute-path audit — reject reads of absolute paths supplied by the agent. Always resolve relative to a pinned root.
- Resolution audit — the path MUST be resolved with
path.resolve(root, input) (or equivalent) and the result MUST be canonicalised.
- Containment check — the canonical resolved path MUST be verified to start with the canonical root (
resolved.startsWith(rootCanonical + path.sep) or equivalent). String prefix check on unresolved paths is insufficient.
- Symlink / traversal audit — handle
.. segments, URL-encoded traversal (%2e%2e), symlinks that point outside the root. Reject if canonicalisation escapes.
- Error shape — rejection returns a structured error response (MCP
isError: true); never throws / crashes the handler.
- Test coverage — require at least one traversal-attempt test per filesystem-bound handler.
- Decision and report —
APPROVE / CONDITIONAL / REJECT.
Decision Logic
- APPROVE: Pinned root used; canonical resolution; containment verified; symlink/traversal handled; rejection returns structured error; traversal test present.
- CONDITIONAL: Sound resolution but missing traversal test — propose the test as minimum addition.
- REJECT: Absolute-path read accepted; missing containment check; throws on rejection; missing canonicalisation.
Completion Criteria
- Input, resolution, containment, traversal handling, error shape audited.
- Test coverage confirmed or proposed.
- Verdict and remediation recorded.
Review Output Template
- Scope analysed (filesystem-bound handlers)
- Input audit (agent-supplied path surfaces)
- Resolution audit (root + canonicalisation)
- Containment audit (canonical prefix check)
- Traversal / symlink audit
- Error shape (structured / throws)
- Test coverage
- Verdict (
APPROVE / CONDITIONAL / REJECT)
- Required actions (precise and minimal)
Non-Negotiable Rules
- Never accept an absolute path from the agent.
- Never rely on string prefix check before canonicalisation.
- Never let a sandbox failure crash the handler.
