Ai Agent Tool Allowlists: Least Privilege for Filesystem and Shell Access

export type ToolRequest =
  | { type: "read"; path: string }
  | { type: "write"; path: string }
  | { type: "shell"; argv: string[] };

const WRITE_ALLOW = [/^src\//, /^tests\//, /^packages\/[^/]+\/src\//];
const READ_DENY = [/^\.env/, /^\.aws\//, /id_rsa$/, /credentials\.json$/];
const SHELL_ALLOW: { bin: string; args?: RegExp }[] = [
  { bin: "pnpm", args: /^(test|lint|typecheck|exec tsc)\b/ },
  { bin: "git", args: /^(status|diff|log|add|commit|checkout -b)\b/ },
  { bin: "rg", args: /.*/ },
];

const SHELL_DENY = [
  /push\s+--force/,
  /\bpublish\b/,
  /curl\s+.*\|\s*(ba)?sh/,
  /kubectl\s+delete/,
  /aws\s+iam\s+/,
  /rm\s+-rf\s+\//,
];

export function authorize(req: ToolRequest): { allow: boolean; reason: string } {
  if (req.type === "read") {
    if (READ_DENY.some((re) => re.test(req.path))) {
      return { allow: false, reason: `read_denied:${req.path}` };
    }
    return { allow: true, reason: "ok" };
  }
  if (req.type === "write") {
    if (!WRITE_ALLOW.some((re) => re.test(req.path))) {
      return { allow: false, reason: `write_not_allowlisted:${req.path}` };
    }
    return { allow: true, reason: "ok" };
  }
  const line = req.argv.join(" ");
  if (SHELL_DENY.some((re) => re.test(line))) {
    return { allow: false, reason: `shell_denied:${line}` };
  }
  const bin = req.argv[0];
  const rest = req.argv.slice(1).join(" ");
  const ok = SHELL_ALLOW.some((r) => r.bin === bin && (r.args?.test(rest) ?? true));
  return ok ? { allow: true, reason: "ok" } : { allow: false, reason: `shell_not_allowlisted:${line}` };
}

async function runTool(req: ToolRequest, ctx: { elevationToken?: string }) {
  const decision = authorize(req);
  if (decision.allow) return execute(req);
  if (ctx.elevationToken && await verifyElevation(ctx.elevationToken, req)) {
    audit.elevated(req);
    return execute(req);
  }
  throw new Error(`policy_denied:${decision.reason}`);
}