owasp/appsec-agentA TypeScript package that provides AI-powered agents for Application Security (AppSec) tasks, built on top of the frontier models.
| Path | Best for | Get started |
|---|
CLI (agent-run) | Trying agents from your terminal | Getting started |
| npm library | Building your own app or pipeline | Web integration · Development |
| AI Threat Modeler | A full web UI with login, dashboards, and exports — no CLI required | Parent app README |
Install from npm: npm install appsec-agent
ANTHROPIC_API_KEY (Anthropic console). Optional Codex provider uses CODEX_API_KEY — see Configuration.npx; if you installed globally, drop the npx prefix.npm install appsec-agent
Or install globally so agent-run is on your PATH:
npm install -g appsec-agent
Add to your shell profile (.zshrc, .bashrc, etc.), then open a new terminal:
export ANTHROPIC_API_KEY="your-key-here"
# Interactive security Q&A (default role)
npx agent-run
# List every available role
npx agent-run -l
# Review code in the current project
npx agent-run -r code_reviewer -s ./src
That’s it. For step-by-step setup, troubleshooting, and running from a git clone, see Getting started.
Each role is a specialized workflow. Pass it with -r / --role.
| Role | What it does |
|---|---|
simple_query_agent | Ask AppSec questions; optional source folder |
code_reviewer | Full-repo security review; markdown or JSON report |
pr_reviewer | PR/diff-focused review (use with --diff-context) |
pr_adversary | Second pass: drop findings without a real exploit path |
fp_adversary | Full-repo false-positive filter (confirm/dismiss verdicts) |
code_fixer | Generate a minimal fix for one finding |
qa_verifier | Run tests to check a fix didn’t break anything |
finding_validator | Re-test whether a finding still applies |
threat_modeler | STRIDE threat model + risk registry (JSON) |
threat_adversary | Second pass: filter ungrounded threats |
context_extractor | Extract repo metadata for downstream tools |
learned_guidance_synthesizer | Synthesize dismissal guidance from signal buckets |
Full descriptions: Agents guide
Copy-paste commands and JSON file formats: Examples
# PR security review (JSON report)
npx agent-run -r pr_reviewer --diff-context pr-diff.json -s ./repo -f json -o report.json
# Threat model (JSON)
npx agent-run -r threat_modeler -s ./src -f json -o threat_model_report.json
# Use OpenAI Codex instead of Claude (opt-in)
npx agent-run -r threat_modeler -s ./src -f json --provider codex -m gpt-4.1
# Add deployment context (helps prioritize findings)
npx agent-run -r code_reviewer -s ./src -c "Production API on AWS, handles PII"
# Version and help
npx agent-run -v
npx agent-run --help
| Guide | Contents |
|---|---|
| Getting started | Install, API keys, first runs, troubleshooting |
| Agents | What each role is for and when to use it |
| Examples | CLI recipes and JSON input shapes |
| Configuration | Environment variables, appsec_agent.yaml, Claude vs Codex |
| Web integration | Using the library in a server safely |
| Development | Clone, build, test, architecture |
--provider codex) backendsAI Threat Modeler bundles this package into a Dockerized Next.js app with authentication, threat-model canvas, PDF/CSV export, and chat — the easiest path if you don’t want to write integration code.
git clone https://github.com/yangsec888/ai-threat-modeler.git
cd ai-threat-modeler
docker-compose up -d --build
# Open http://localhost:3000 (default: admin / admin)
Licensed under Apache 2.0.
Sam Li — [email protected]
References: Claude Agent SDK · Anthropic API