plan-forge security.instructions.md

Security Instructions

Plan Forge runs with the user's full shell privileges and orchestrates writes into the user's repository. Every forge_* tool handler, every CLI command, every spawn, and every file write is a security boundary. This file rules the boundaries.

---

The 6 Rules

1. Use spawn(cmd, [arg, arg]) — never exec(stringWithInput)

exec parses its argument as a shell command. Any user-supplied substring becomes a shell injection vector. spawn with an args array passes each argument literally to the kernel, no shell involved.

// ✅ correct
import { spawn } from 'node:child_process';
const child = spawn('gh', ['issue', 'create', '--title', userTitle, '--body', userBody]);

// ❌ injection vector
import { exec } from 'node:child_process';
exec(`gh issue create --title "${userTitle}" --body "${userBody}"`);

userTitle = '"; rm -rf ~ #' exploits the exec form. The spawn form passes it as a literal title containing punctuation.

Same rule applies to spawnSync, execFile, and PowerShell Start-Process / Invoke-Expression. Use args arrays. If you need shell features (pipes, redirects), pipe the data in code, not via the shell.

2. No eval, no new Function(string), no dynamic require(userInput)

These accept code from a string and execute it. There is no input value sanitisation that makes this safe.

Common smells caught at review:

• eval(json) — use JSON.parse(json)
• new Function('return ' + expr) — use a parser library or a small DSL
• require(path.join(userDir, file)) — use import() with a validated allowlist of paths

3. Validate input at the forge_* handler boundary

Every MCP tool handler is a system boundary. Validate before doing any work:

function handle_forge_thing({ projectPath, mode }) {
  if (typeof projectPath !== 'string' || !projectPath) {
    return { ok: false, error: 'projectPath required' };
  }
  if (mode !== 'fast' && mode !== 'thorough') {
    return { ok: false, error: 'mode must be "fast" or "thorough"' };
  }
  const resolved = path.resolve(projectPath);
  if (!resolved.startsWith(allowedRoot)) {
    return { ok: false, error: 'projectPath escapes allowed root' };
  }
  // ...real work below this line
}