# Security Middleware

## Scope

This middleware provides a first-pass hardening layer for agent-executed shell commands and MCP tool usage.

## Components

- `src/security/shell-parser.ts`
  - Uses `bash-parser` to parse shell scripts and extract command-level data from `Command` and `Word` nodes.
  - Traverses nested constructs (logical operators, pipelines, subshells, command expansions) so chained commands are fully visible to policy checks.
- `src/security/schemas.ts`
  - Zod schemas for shell policies, tool clearance policies, execution env policy, and security violation handling mode.
- `src/security/rules-engine.ts`
  - Enforces:
    - binary allowlist
    - cwd boundary (`AGENT_WORKTREE_ROOT`)
    - argument path boundary and `../` traversal rejection
    - protected path blocking (`AGENT_STATE_ROOT`, `AGENT_PROJECT_CONTEXT_PATH`)
    - unified tool allowlist/banlist checks
- `src/security/executor.ts`
  - Runs commands via `child_process.spawn` using explicit env construction (no implicit full parent env inheritance).
  - Supports timeout enforcement, optional uid/gid drop, and stdout/stderr stream callbacks.
- `src/security/audit-log.ts`
  - File-backed audit sink (`ndjson`) for profiling emitted shell commands and tool access decisions.

## Pipeline behavior

`SecurityViolationError` is treated as a first-class error type by `PipelineExecutor`:

- `hard_abort` (default): fail fast and stop the pipeline.
- `validation_fail`: map violation to retry-unrolled behavior so the actor can attempt a compliant alternative.

## MCP integration

`McpRegistry.resolveServerWithHandler(...)` now accepts optional tool clearance and applies it to resolved Codex MCP tool lists (`enabled_tools`, `disabled_tools`).

## Known limits and TODOs

- AST validation is token-based and does not yet model full shell evaluation semantics (e.g. runtime-generated paths from env expansion).
- Audit output is line-oriented file logging; move to a centralized telemetry pipeline for long-term profiling.
- Deno sandbox mode is not enforced yet. A future executor mode can wrap shell runs via `deno run` with strict `--allow-read/--allow-run` flags.