agentsec
is a security auditing CLI for AI agent skills. It scans every skill installed in a project against the OWASP Agentic Skills Top 10 and reports vulnerabilities, misconfigurations, and governance gaps.
When to Use
Use
when the user asks to:
- Audit, scan, or check agent skills for security issues
- Verify installed skills are safe before running them
- Check OWASP compliance of an agent setup
- Gate a CI/CD pipeline on skill security
- Generate a security report for stakeholders
Quick Start
The fastest path to a result — no install, no flags:
This scans every default skills directory on the machine — grouped by platform — plus any
folder in the current project (up to two levels deep), and audits each installed skill against the OWASP Agentic Skills Top 10. Always try this first.
Auto-discovery locations
| Platform | Paths scanned |
|---|
| Claude Code | , , ~/.claude/plugins/*/skills/*
|
| OpenClaw / ClawHub | ~/.openclaw/workspace/skills
~/.openclaw/workspace-*/skills
|
| Codex / skills.sh | , , , |
| Other (generic) | Any directory found within the current project, up to two levels deep |
Core Commands
Every workflow starts from one of four commands. Run them with
— no install needed.
bash
# Full audit (scan + policy evaluation). Default command.
npx agentsec
# Scan only (no policy evaluation)
npx agentsec scan
# Generate a report from a previously saved audit JSON
npx agentsec report audit.json
# Manage and inspect policy presets
npx agentsec policy list
Installation
needs no install. For repeated use, install globally:
bash
# bun (recommended)
bun add -g agentsec
# npm
npm install -g agentsec
# pnpm
pnpm add -g agentsec
# yarn
yarn global add agentsec
bash
agentsec
agentsec scan --path ./my-skills
Flags
All flags work with any command.
| Flag | Short | Values | Default | Purpose |
|---|
| | , , , | | Output format |
| | path | stdout | Write report to file |
| | preset name or path | | Apply a policy preset |
| | , , | auto | Narrow to one agent platform |
| | path | auto | Custom skill directory to scan |
| | , , | | Rule profile. auto-detects Web3 skills; forces the annex on every skill |
| | | off | Show detailed findings |
| | | off | Disable colored output |
| | | | Show help |
| | | | Print version |
Common Recipes
Show detailed findings and remediation
Scan a specific directory
bash
npx agentsec scan --path ./my-skills
Target a specific agent platform
bash
npx agentsec --platform claude
npx agentsec --platform codex
Audit with a strict policy and save JSON
bash
npx agentsec --policy strict --format json --output audit.json
Generate an HTML report for stakeholders
bash
npx agentsec --format html --output report.html
Generate a SARIF report for IDE / code-scanning integration
bash
npx agentsec --format sarif --output report.sarif
List available policy presets
Inspect the rules in a preset
bash
npx agentsec policy show strict
Validate a custom policy config file
bash
npx agentsec policy validate ./my-policy.json
Replay a previous audit as an HTML report
bash
npx agentsec report audit.json --format html --output report.html
Policy Presets
| Name | Use Case |
|---|
| Balanced policy. Blocks critical findings. |
| Enterprise-grade. Blocks high and critical findings, enforces tests. |
| Lenient. Only blocks critical CVEs. Good for development. |
| Built directly from the OWASP Agentic Skills Top 10. |
Configuration File
auto-loads
,
, or
from the current directory (or any parent):
json
{
"format": "text",
"output": null,
"policy": "strict",
"verbose": false
}
CLI flags always override config file values. Omit
and
to keep the default auto-discovery behavior — agentsec will scan every known platform's default locations.
OWASP Agentic Skills Top 10
Every audit checks all ten risk categories:
| ID | Risk |
|---|
| AST01 | Malicious Skills |
| AST02 | Supply Chain Compromise |
| AST03 | Over-Privileged Skills |
| AST04 | Insecure Metadata |
| AST05 | Unsafe Deserialization |
| AST06 | Weak Isolation |
| AST07 | Update Drift |
| AST08 | Poor Scanning |
| AST09 | No Governance |
| AST10 | Cross-Platform Reuse |
AST-10 Web3 Annex (auto-detected)
Web3-touching skills are detected automatically and audited against twelve additional rules — no flag required. A skill is detected as Web3 when its manifest declares a
block, when its source imports a Web3 client library (
,
,
,
,
,
,
,
,
), when it references a Web3 RPC method (
,
,
,
), or when it ships a
file. Detected skills are tagged
in the output:
text
✔ scoped-trader v1.4.0 [Web3] C (62)
✔ helpful-summarizer v1.2.0 A (95)
is still available — it forces the annex onto every skill regardless of detection (useful for cross-team CI consistency):
bash
npx agentsec audit --profile web3 --path ./my-skills
| ID | Risk |
|---|
| AST-W01 | Unbounded Signing Authority |
| AST-W02 | Implicit Permit / Permit2 Signature Capture |
| AST-W03 | Delegation Hijack via EIP-7702 |
| AST-W04 | Blind / Opaque Signing Surface |
| AST-W05 | RPC Endpoint Substitution & Mempool Leakage |
| AST-W06 | Unverified Contract Call Targets |
| AST-W07 | Cross-Chain / Bridge Action Replay |
| AST-W08 | MCP Chain-Tool Drift / Capability Smuggling |
| AST-W09 | Session-Key / Permission-Caveat Erosion |
| AST-W10 | Slippage / Oracle Manipulation by Agent Loop |
| AST-W11 | Key Material in Agent Memory / Logs |
| AST-W12 | No On-Chain Action Audit / Kill-Switch |
Skills can declare a
block in their manifest (chains, signers, policy caps, session-key scopes, MCP server pinning, audit sink, kill-switch) so the annex can verify scoping without flagging well-bounded skills. See
docs/plans/ast10-web3-annex-rules.md
for full per-rule detection signals.
Understanding the Output
Default output is compact: each skill shows its grade and score, followed by a one-line finding summary and a PASS/WARN/FAIL status.
✔ Found 6 skills
✔ fetch-data v1.0.0 D (42)
✔ deploy-helper v2.3.0 C (68)
✔ code-review v1.1.0 A (95)
6 skills scanned • avg score 78 • 4 certified
Findings: 2 critical, 1 high, 2 medium
⚠ WARN 3 high/critical finding(s) detected
Use
for score breakdowns, rule IDs, file/line locations, and remediation for each finding.
Exit Codes
- — audit passed the active policy
- — policy violation or fatal error
Use the exit code directly to gate CI pipelines — no special flag required:
bash
npx agentsec --policy strict || exit 1
Tips
- Start with — no install, no flags. Iterate from there.
- Add whenever you need to act on specific findings.
- Pipe into or a custom script for programmatic handling.
- is the most common preset for production repositories.
- Browse the agent skills ecosystem at skills.sh.