@mitsumi/sec-agent

LLM-led white-box security review agent for locally-cloned repositories.

Traditional scanners miss most of what a human security reviewer catches — logic-level issues like an MFA bypass hidden in application code, or a JWT secret with a hardcoded fallback, are invisible to pattern-matching tools. This agent makes an LLM the primary security analyst, with real scanners (Gitleaks, npm audit, OWASP ZAP) attached as corroborating evidence rather than the other way around. Every finding is mechanically re-verified against the actual code — a cited file:line that doesn't check out gets dropped, not reported.

Install

npm install -g @mitsumi/sec-agent

Requires Node.js ≥20.

Setup (once per machine)

1. Create ~/.sec-agent/.env with your own OpenAI API key.

   macOS / Linux / WSL (bash or zsh):

   mkdir -p ~/.sec-agent
   echo 'OPENAI_API_KEY=sk-...' > ~/.sec-agent/.env

   Windows (PowerShell):

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.sec-agent"
   "OPENAI_API_KEY=sk-..." | Out-File -Encoding utf8 "$env:USERPROFILE\.sec-agent\.env"

   WSL users: if Node/npm is installed inside WSL (node -v works from your Ubuntu shell without going through /mnt/c/...), ~ resolves to your Linux home (/home/<you>), separate from the Windows C:\Users\<you> used by a native Windows install. Create the .env file from the same shell you'll run sec-agent from.

2. Run sec-agent doctor — fetches/verifies the scanner toolchain (Gitleaks, and Docker + the OWASP ZAP image if you want dynamic testing). On WSL, PENTEST/ZAP requires Docker Desktop's WSL integration enabled (Docker Desktop → Settings → Resources → WSL Integration) rather than a separate Docker install inside the WSL distro.

Quick start

sec-agent init /path/to/repo --project-code ACME
sec-agent run /path/to/repo

run walks the full journey in one command: INDEX (inventory + methodology test plan) → REVIEW (all 7 passes + scanner evidence) → interim Assessment Report → optional PENTEST (pass --target <url> to include it) → final consolidated report → Remediation Report (once you've run it more than once against the same repo).

Reports land in ~/.sec-agent/reports/<PROJECT>/<timestamp>/ as HTML, PDF, JSON, and SARIF.

The agent is strictly read-only with respect to the code under review — it never writes inside the repo it's scanning. Everything it produces lives under ~/.sec-agent/.

Commands

| Command | Description | |---|---| | sec-agent doctor | Fetch/verify the scanner toolchain | | sec-agent init <repoPath> --project-code <CODE> | Register a repo | | sec-agent index <repoPath> | Inventory the stack and build the methodology test plan | | sec-agent review <repoPath> [--passes AUTH,SEC,...] | Run the LLM-led review passes with scanner evidence (defaults to all 7) | | sec-agent pentest <repoPath> --target <url> [--full] [--confirm] | OWASP ZAP DAST scan against a running instance | | sec-agent report <repoPath> [--assessment] [--remediation] | Emit report artifacts | | sec-agent run <repoPath> [--all] [--target <url>] [--passes ...] | The full journey in one command | | sec-agent status <findingId> [--annotate mitigated\|action-required] [--note "..."] | Look up a finding, or human-annotate it | | sec-agent history <repoPath> | Scan run history for a repo | | sec-agent memory export <path> / memory import <path> | Back up / restore the local memory store | | sec-agent hooks install <repoPath> | Opt-in git hooks that auto-run review on commit/push |

The seven review passes

Authentication & Session, Secrets & Configuration, Injection & Code Execution, Authorization/IDOR, Cloud/Storage, Dependencies, Client-side. Each pass evaluates a fixed methodology checklist against the files relevant to it, with a bounded tool to fetch one extra file by exact path if needed (capped per pass), and cross-checks against real scanner output where applicable.

License

MIT