AgentSec Triage
September 1, 2026 · View on GitHub
|
Florian BRUNIAUX · AI Founding Engineer @ Méthode Aristote 13 years from developer to CTO / VP Eng · Blog ↗ · Projects ↗ |
Turn sourced threat intelligence into deterministic checks for local repositories. AgentSec scans one explicit root, reports what it inspected, and fails closed when applicable evidence cannot be read reliably.
Scans are read-only and offline by default. AgentSec does not certify that a repository, workstation, dependency set, or account is clean.
AgentSec is a public source repository in alpha. Install it from a checked-out copy; no package or tagged release is authorized yet.
Start here
| Goal | Command or guide | Result |
|---|---|---|
| Install from source | Installation guide | Local agentsec command and runtime verification |
| Check the installation | agentsec doctor | Database, schema, and packaged-resource status |
| Scan one repository | agentsec scan /path/to/repo --progress --verbose --redact | Human verdict with phase and bounded progress details on stderr |
| Produce machine output | agentsec scan /path/to/repo --format json --redact | Versioned scan-result v2 JSON |
| Export for code scanning | agentsec scan /path/to/repo --format sarif --redact > agentsec.sarif | SARIF 2.1.0 with completion and coverage metadata |
| Explain one detector | agentsec detectors explain shai-hulud-keyv | Rules, inputs, sources, limits, and not_scanned capabilities |
| Scan an explicit list | agentsec batch /repo/a /repo/b --format json --redact | Ordered batch result with aggregate exit status |
Read the examples and verdict guide before automating the
result. Exit code 2 means incomplete coverage, not success.
When to use AgentSec
Use AgentSec before trusting a repository with a coding agent, after a tracked campaign disclosure, or in CI when you need repository-local evidence tied to reviewed threat intelligence.
| Need | Use AgentSec? |
|---|---|
| Check supported lockfiles, package metadata, payload hashes, hooks, or skill instructions against an implemented campaign detector | Yes |
| Know which applicable inputs were inspected, skipped, unsupported, or unreadable | Yes |
| Find general application vulnerabilities, secrets, or every vulnerable dependency | No. Add SAST, secret scanning, and SCA tools. |
| Inspect running processes, network traffic, credentials, persistence, live MCP servers, or registry history | No. Use host and runtime controls. |
AgentSec differs from broad repository and agent scanners through traceability: each active rule links a reviewed source, campaign evidence, a deterministic fixture, a finding, stated coverage, and response guidance. Its current breadth is smaller than several alternatives, so it should complement rather than replace general security tooling. See when to use AgentSec and how it compares and the dated scanner ecosystem study.
AgentSec grew from the threat database behind the Claude Code Guide security page. A scan does not query that website: it uses a validated, versioned database bundled with the installed source, then reports the database version in its output. AgentSec exports reviewed metadata back to the guide and landing page, and CI rejects feed drift. The page tracks more intelligence than the two detector families currently implemented by the scanner.
What it checks today
AgentSec currently ships two detector families. The wider intelligence catalogue contains research that has not been promoted into executable checks.
| Detector | Repository evidence | Main inputs |
|---|---|---|
shai-hulud-keyv | Documented compromised package versions, payload hashes, lifecycle scripts, and repository startup hooks associated with the Shai-Hulud/Keyv campaign | Supported npm, pnpm, Yarn, and text Bun lockfiles; installed package metadata; .claude settings; VS Code tasks; regular-file SHA-256 |
clawhavoc-skill | Exact bundled campaign domains in SKILL.md or explicitly delegated same-skill setup instructions | Repository-local SKILL.md and referenced Markdown setup files |
Run agentsec detectors explain DETECTOR_ID --format json for the current
coverage contract. Binary bun.lockb, Git history, remote repositories,
registry history, remote payloads, runtime behavior, host credentials, and host
processes are not inspected.
Concrete examples
These examples come from inert test fixtures shipped with AgentSec.
| What AgentSec surfaces | Example | What it means |
|---|---|---|
| Compromised dependency version | critical / confirmed / package-lock.json / keyv@6.0.0 | The exact package-version pair matches bundled campaign intelligence. It proves the resolved version is present, not that its payload executed. |
| Campaign-correlated startup hook | high / high / .claude/settings.json / SessionStart: node setup.mjs | Opening the repository with the affected agent configuration may invoke a command associated with the campaign. Inspect the referenced file and investigate possible prior execution. |
| Suspicious but unconfirmed hook | medium / review / .claude/settings.json / SessionStart: echo repository-ready | A repository hook can execute automatically, but this command has no campaign correlation. Confirm its owner and purpose before changing it. |
| Delegated skill instruction | high / high / setup-installation.md:3 / openclawcli.vercel.app | SKILL.md delegates setup to a local file containing an exact campaign domain. Do not follow the instruction; verify the skill's origin and version. |
| Incomplete coverage | error / bun.lockb / Unsupported binary Bun lockfile format | This is a diagnostic, not a finding. AgentSec returns exit code 2 because it cannot inspect an applicable authoritative input. |
See complete finding examples for full output, every active rule, false-positive boundaries, and diagnostic classes.
Read the result
| Exit code | Meaning |
|---|---|
0 | Applicable checks completed and produced no finding. This is not a clean-system certificate. |
1 | At least one finding requires action or review. |
2 | The scan failed or applicable coverage is incomplete. Findings already collected remain in the report. |
Reports keep findings, diagnostics, discovery exclusions, per-detector coverage, and unsupported capabilities separate. This prevents a skipped input from being presented as a successful check.
Versioned response playbooks separate evidence collection, manual containment, remediation, and verification. AgentSec does not perform destructive remediation.
Scope and safety
The default source scope excludes installed dependencies, generated trees,
caches, binary assets, and VCS metadata while retaining supported lockfiles.
Choose a broader scope explicitly when the investigation needs it:
agentsec scan /path/to/repo --scope dependencies
agentsec scan /path/to/repo --scope repository
AgentSec does not execute target content, invoke Git on the target repository, request the network during a scan, or follow filesystem indirection outside the scan root. Unreadable, changed, unsupported, or budget-exceeding applicable inputs make the result incomplete.
AgentSec is not an antivirus, EDR, general SAST, dependency scanner, or secret scanner. Its result covers only the implemented detectors and supported inputs reported by that run.
Outputs and automation
- Human output for local review.
- Scan-result v2 JSON and batch-result v1 JSON.
- SARIF 2.1.0 with AgentSec completion, coverage, diagnostic, and exclusion properties.
- A repository-local GitHub Action that runs checked-out source, validates SARIF, and preserves exit codes.
- A versioned public security feed mirrored into the Claude Code Ultimate Guide and its landing page, with drift rejected in CI.
Remote Action use remains blocked until a release is authorized. See the project overview for the data flow, product surfaces, sources of truth, and integration boundaries.
Documentation
| Need | Document |
|---|---|
| Install and run the first scan | Installation |
| Interpret human, JSON, SARIF, and incomplete results | Examples and verdicts |
| Understand architecture and canonical files | Project overview |
| Decide when to use AgentSec or another control | Usage and comparison guide |
| Respond to a finding | Response playbooks |
| Review sources and dated events | Security intelligence and timeline |
| Add a source, event, IOC, or detector | Intelligence authoring |
| Give the task to an LLM | Copy-ready prompt and LLM index |
| Review priorities and shipped work | Roadmap and changelog |
| Report a vulnerability or incorrect result | Security policy |
| Contribute code or intelligence | Contributing |
The related educational security page is https://cc.bruniaux.com/security/.
Explore the ecosystem
These projects extend the workflow without duplicating this tool:
- Learn with Claude Code Ultimate Guide: the guide already consumes the scanner's versioned security feed.
- Validate with ctxharness: cover configuration security and context integrity together.
- Automate with claude-code-plugins: pair specialist triage with the security-suite workflows.
Browse the complete open-source galaxy
License status
Project-owned code and original documentation use the MIT License. The paths listed in LICENSE-DATA.md remain unavailable for public redistribution while their separate rights and CC BY-SA 4.0 review is open.
Public visibility does not authorize a package, tag, source archive, GitHub Release, or redistribution of gated data. The blocking decisions are recorded in LICENSE-DECISION.md.