fettle: Command for Claude Code

$ARGUMENTS refers to any text the user typed after the slash command.

Run the full 5-phase MCP Zero-Trust Validation Protocol to audit a package, then — with human approval — add it to the root-owned allowlist ledger.

Procedure

1. Parse arguments. Extract package name and exact version from $ARGUMENTS (e.g., @playwright/[email protected]). If no version is pinned, STOP and ask for an exact version — unpinned packages are never approved.

2. Locate the ledger. The allowlist lives at ~/.config/fettle/mcp-allowlist.json by default. Precedence: a policy-pinned [gates.mcp_trust].allowlist_path in the effective config wins; otherwise the MCP_ALLOWLIST_PATH env var; otherwise the default. Check fettle config --print-effective for a pinned path.

3. Check if already approved. Read the allowlist ledger and check if this exact package@version is already present under packages. If so, report it and stop.

4. Phase 1 — Package Provenance & Supply Chain

   • Run npm view <package>@<version> --json to get publisher, download stats, repo link, publish date
   • Verify publisher is the expected organization
   • Cross-reference npm maintainers against known project contributors
   • Check for recent ownership transfers or suspicious maintainer changes
   • Run npm audit for known CVEs
   • Present findings to user with PASS/WARN/FAIL for each check

5. Phase 2 — Source Code Review

   • Download without installing: npm pack <package>@<version>
   • Extract tarball to /tmp/mcp-audit-<package>/
   • Review ALL runtime files (not just README)
   • Grep for red flags: child_process.exec, eval(, Function(, fs.writeFile, process.env, outbound network calls, obfuscated code
   • Map every exposed MCP tool to its blast radius
   • Count total lines of runtime code
   • Present findings to user

6. Phase 3 — Dependency Tree Audit

   • Count transitive dependencies
   • Check npm audit on full resolved tree
   • Flag dependencies with <100 weekly downloads or recent ownership transfers
   • Present findings to user

7. Phase 4 — Runtime Isolation Test

   • Start the MCP server in a subprocess
   • Check ports opened (ss -tulpn), filesystem paths touched, DNS lookups
   • Test one benign operation and observe side effects
   • Verify no unexpected phone-home or persistent connections
   • Present findings to user

8. Phase 5 — Permission Scoping

   • Recommend MCP tool allowlist for settings.json
   • Recommend network restrictions if supported
   • Recommend --isolated mode if available
   • Recommend output directory restrictions
   • Present recommendations to user

9. Compute tarball SHA256. Run sha256sum on the downloaded tarball.

10. Write audit report. Save the full audit report (all 5 phases with findings) to .fettle/audits/<package>-<version>.md with date and auditor.

11. Present summary and ask for human approval. Show:

    • Overall verdict: APPROVE / REJECT / CONDITIONAL
    • Phase-by-phase summary (PASS/WARN/FAIL)
    • Any conditions or restrictions
    • Ask: "Do you approve adding @ to the allowlist?"

12. If approved, update the ledger via sudo. Use a Python script that:

    • Reads the current allowlist ledger
    • Adds the new package entry under packages with version, sha256_tarball (npm) or sha256_wheel (Python), audit date, auditor, report path, and approved_by_human: true; set allow_source: true only when a source build was explicitly audited
    • Writes to a temp file then sudo copies it to the ledger path
    • Sets ownership to root:root and permissions to 0644

13. Confirm the ledger was updated by reading it back.