agentsec
Stack-aware security audit for FastAPI + React + Postgres + LLM/RAG apps — detect the stack, run only the right checks, lead with what to fix.
agentsec fingerprints your repo, runs only the security checks that apply to your stack, and emits one
prioritized report that leads with what's actually exploitable. Dependency-free static guards (zero
runtime deps, stdlib only) plus 11 optional scanners it orchestrates when installed — with first-class
coverage of the LLM / agentic layer most tools miss (prompt-injection-to-RCE, the lethal trifecta, RAG
trust boundaries, RLS misconfig). Ships as a CLI, drop-in CI/CD gates, and Claude Code skills.
$ agentsec audit .
# Security check — 3 issue(s) found
Needs work before shipping. There are serious problems to fix first.
_(1 critical, 1 high, 1 medium)_
## Fix these first
- **LLM output executed as code** — model output reaches exec()/subprocess; prompt-injection → RCE.
- **RLS policy lets owners write privileged columns** — a self-update policy leaves is_admin/tokens writable.
## Security findings (3: 1 critical, 1 high, 1 medium)
- 🔴 **CRITICAL** [llm-output-to-sink] `agent/tools.py:88` — model output passed to exec() _[OWASP-LLM:LLM01]_
- 🔴 **HIGH** [rls-update-privileged-column] `sql/0.sql:42` — owner can self-grant is_admin _[OWASP:A01]_
- 🟠 **MEDIUM** [cors-wildcard] `app/main.py:31` — allow_origins=["*"] with credentials _[OWASP:A05]_
_Stack:_ fastapi · pydantic-ai · supabase · stripe · vite-react
_Checks run:_ 41 · _Skipped (N/A for this stack):_ 6 · _Scanners not installed:_ trivy, gitleaks
Quickstart
pipx install ai-agent-security
agentsec audit /path/to/your/repo # prioritized report, exits non-zero on high+ (your CI gate)
That's the whole loop. The dependency-free guards run immediately; add the optional scanners for full depth with one command:
agentsec setup /path/to/your/repo # stack-aware, installs only what your stack needs, no PATH edits
agentsec audit /path/to/your/repo # …now runs at full depth
Run it in CI
One step in any GitHub Actions job, after actions/checkout. It runs from the action's own checkout, so
there is nothing to install and your code never leaves your runner; you get a job summary, inline PR
annotations, a SARIF artifact and the gate:
- uses: Zard-Lab/ai-agent-security@<40-hex-commit-sha> # v0.22.x, pin by SHA
with:
fail-on: high # critical | high | medium
mode: gate # or advisory: report and warn, never fail the job
Inputs, outputs, permissions and the private-repo setup: user guide §16.
Why agentsec
- Runs only what applies (the N/A rule). No Stripe → payments checks don't fire; no frontend → React checks are N/A. A clean report means "nothing applicable found," not "nothing checked" — and the report says exactly what ran and what was skipped.
- Leads with the exploitable few. Findings are ranked by severity × reachability (product code over tests/migrations) × confidence (proven over surfacing), so "Fix these first" is the short list that matters — the antidote to alert fatigue.
- Covers the LLM/agentic layer. Beyond the usual SAST: LLM-output-to-sink, the lethal trifecta, RAG trust boundaries, agent tool over-permission, MCP trust, prompt/secret leakage.
- Zero runtime dependencies. Pure-Python stdlib; the guards always run. External scanners are optional and degrade gracefully (reported as skipped, never fatal). The audit CLI makes no network calls.
- Honest by construction. A liveness canary fails CI if any guard silently stops firing; every
coveredchecklist item must cite a real planted-violation test; exceptions expire (no forever-ignores). - One report model → SARIF + markdown. Guards, scanners, the AI layer, and ingested third-party reports
all become the same
Finding, merged into one severity-ordered report.
What it checks
493 guards across the FastAPI + React + Postgres + LLM/RAG stack, plus 11 optional scanners
(bandit, semgrep, pip-audit, node-audit, eslint, react-doctor, gitleaks, trivy, hadolint,
scorecard, go-osv-hygiene), mapped to OWASP Top 10 · OWASP LLM Top 10 (2025) · CIS · CWE.
| Stack layer (detected feature) | Example guards |
|---|---|
LLM / agentic (llm) |
lethal-trifecta · llm-output-to-sink · rag-trust-boundary · agent-tool-overpermission · mcp-tool-unverified · system-prompt-leak |
Frontend / browser (frontend) |
frontend-xss · dom-xss-sinks · token-in-localstorage · jsx-href-scheme · vite-client-secret |
Postgres / RLS (sql / supabase) |
public-table-rls · rls-permissive-policy · rls-update-privileged-column · pg-function-search-path |
Supabase (supabase) |
service-role-key · auth-users-not-exposed-via-view · supabase-storage-public |
Payments / Stripe (payments) |
stripe-payments · checkout-price-from-server · no-pan-stored · webhook-idempotency |
Supply chain (python / frontend) |
python-supply-chain · js-supply-chain · npm-ignore-scripts · dependency-version-floor |
Auth / API (fastapi) |
jwt-alg · bola · mass-assignment · cors-wildcard · security-headers · rate-limit-no-user-key |
Run agentsec coverage . for the full per-section score card (covered / partial / manual / N-A) against
your stack.
Install
# CLI (recommended), from PyPI:
pipx install ai-agent-security
# Or from a clone, or a release tag straight from git:
pipx install .
pipx install "git+https://github.com/Zard-Lab/ai-agent-security@vX.Y.Z"
# Development:
pip install -e ".[dev]" # adds pytest, ruff, mypy, pyright, pyyaml
Requires Python ≥3.12, zero runtime dependencies. Optional scanners install via agentsec setup,
or, where that can't run (air-gapped / policy-restricted), by hand;
agentsec doctor shows what's present.
Installing from
@mainis not signature-verified.pip/pipxdo no signature checking, andmainis a moving, unsigned ref, so an install from it carries no proof of provenance. Release tags are signed (v0.21.14onward), but installing from a tag does not verify it either: pip discards the git metadata, so the installed package holds nothing to check. Verification is a deliberate, separate step, documented in SECURITY.md.
Common commands
| command | what it does |
|---|---|
agentsec scan <repo> |
one-shot: detect + audit → agentsec-out/{detect.txt, audit.md, audit.sarif} |
agentsec audit <repo> |
the core scan + CI gate (--format sarif, --fail-on, --guards-only, --baseline, --changed-files-only) |
agentsec drift <repo> |
compare current findings against a saved snapshot — catch regressions in CI, including a superseded SQL finding that comes back live |
agentsec detect <repo> |
fingerprint the stack (what everything keys off) |
agentsec coverage <repo> |
checklist score card for your stack |
agentsec ai-bom <repo> |
AI Bill of Materials — models, providers, MCP servers, vector stores, AI deps (JSON / CycloneDX / markdown) |
agentsec suggest-excludes <repo> |
advise non-product dirs to exclude/demote (advisory; --write to opt into .agentsec/config.json) |
agentsec live <repo> |
audit + running-target scanners (ZAP DAST, Splinter, Schemathesis, jwt_tool) |
agentsec harden-host |
opt-in live-host hardening audit (SSH/UFW/fail2ban/auto-updates/listeners; read-only, sudo for root-only probes) |
agentsec trifecta <repo> |
agentic-AI "lethal trifecta" architecture review |
agentsec fix <repo> |
apply allowlisted mechanical fixes (dry-run by default; --write) |
agentsec doctor |
which optional scanners are installed (--canary, --sandbox, --efficacy self-tests) |
agentsec setup <repo> |
install the scanner toolchain (stack-aware, no PATH edits) |
agentsec ci add <id> <repo> |
install a production-derived CI gate (13 components) |
agentsec harden-python / harden-js |
fix dependency config to the supply-chain standard |
agentsec report-gap <stack> |
flag a stack we don't cover yet (offline; opens a prefilled issue) |
Which command should I run?
- First look / attach to a PR →
agentsec scan . - CI gate →
agentsec audit . --fail-on high(or--format sariffor code-scanning) - Is my stack detected right? →
agentsec detect . - What's my coverage / to-do list? →
agentsec coverage . - Fast PR check (changed files only) →
agentsec audit . --changed-files-only origin/main - Track regressions over time →
agentsec drift . --save(once), thenagentsec drift .on each run. A snapshot saved by an older agentsec does not record which findings were superseded history; re-save it sodriftand the--baseline-snapshotratchet also fail when one of them comes back live - Repo-specific false positives → add them to
.agentsec/suppress.json(merged with the global baseline) - Silence one finding in place → a
# security: allow-<guard-id>comment (comments only, never a string — user guide §14) - Which guards are firing vs silent? →
agentsec doctor --efficacy . - Scan a running deployment (DAST, DB lint, fuzzing) →
agentsec live . --target-url … - LLM/agent architecture review →
agentsec trifecta .
Full reference for every command and flag: docs/user-guide.md.
How it works
detect → select applicable checks → run (guards + scanners + AI layer) → prioritize → one report → gate on severity
detect.py fingerprints the repo into a StackProfile; registry.py selects only the checks whose stack
feature is present; every source produces the same Finding; the report is one severity-ordered list led by
"Fix these first," gated by --fail-on (default high).
Two classes of finding are reported but do not gate: ones you baselined (--write-baseline, until their
review_by lapses) and schema-state findings superseded by an authoritative schema dump the repo ships —
the old migration's copy of a policy the dump already carries live. A dump counts only when its name looks like
one (schema.sql, schema-snapshot.sql, *.dump.sql, …) and its head carries pg_dump's session preamble
or banner, and it governs only the .sql files in its own directory subtree; a hand-written schema.sql
supersedes nothing. Both classes are counted and named on the CI line
(agentsec: … , N superseded (non-gating) — PASS), never dropped from the report. Everything else gates.
Delivery channels
- CLI —
pipx-installable; the commands above. - CI/CD — a composite GitHub Action (
action.yml) for the audit, an à-la-carte component library (agentsec ci add, 13 components) of production-derived, secret-stripped gates, and a pre-commit hook (.pre-commit-hooks.yaml) for the local guard run. See the user guide. - Claude Code skills —
/security,/security-prime,/security-review,/security-audit,/security-fix,/security-scan-url(no repo needed — just a live URL),/add-ci,/harden-python,/harden-js(dropclaude-skills/*into.claude/skills/).
Documentation
- User Guide — every command, flag, exception/baseline schema, CI wiring, reading the report, troubleshooting.
- wiki/ — the methodology + threat research the guards are designed against.
- Contributing a guard — how to add a guard, the quality gates, conventions.
Standards covered
OWASP Top 10 · OWASP LLM Top 10 (2025) · CIS Benchmarks · OWASP Agentic AI (Threats & Mitigations) · CWE · the "lethal trifecta" model.
Contributing
Adding a guard is a small, well-defined recipe (module + test + design doc + canary plant + checklist
mapping). See CONTRIBUTING-GUARDS.md. Quality gates: ruff + mypy --strict + pyright +
pytest + agentsec doctor --canary must all pass. Outside contributors sign the
Contributor License Agreement once, on their first pull request (a bot asks).
Security
Found a vulnerability in agentsec itself? Please report it privately — see SECURITY.md. Don't open a public issue for a security report.
License
Metadata
Release files for ai-agent-security 0.22.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_agent_security-0.22.2.tar.gz | 2.4 MB | With provenance | Details for ai_agent_security-0.22.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_agent_security-0.22.2-py3-none-any.whl | Python 3 | none | any | Details for ai_agent_security-0.22.2-py3-none-any.whl |
Total release size: 5.5 MB
Release files / ai_agent_security-0.22.2.tar.gz
| Download URL | ai_agent_security-0.22.2.tar.gz |
|---|---|
| Size | 2.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a01256ed710abd1fbd4c5b61a4e0cb065e41c82fe2fc760d8002bc40ed210ea3
|
|
BLAKE2b-256 checksum How to use checksums |
149ce046f73d8eaf83084cb48b5443bbd2daaa2304b4c2046afe7703aed80756
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / ai_agent_security-0.22.2-py3-none-any.whl
| Download URL | ai_agent_security-0.22.2-py3-none-any.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aca11a356d825df33070d5d7bb7f20079d9272db6f4d077beb416ac1fdc76185
|
|
BLAKE2b-256 checksum How to use checksums |
6d4f4cf284dd73c3a345e62181716aca69e267a134871a7b934db2c65ea24586
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for ai-agent-security 0.22.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ai_agent_security-0.22.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.