43 lines
2.1 KiB
Markdown
43 lines
2.1 KiB
Markdown
# 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.
|