Agentsec

---
name: agentsec
description: Audit AI agent skills for security vulnerabilities. Use when scanning installed skills against the OWASP Agentic Skills Top 10, checking skills before running them, gating CI/CD on skill safety, or generating audit reports (text, JSON, SARIF, HTML) for stakeholders.
version: 0.3.3
license: MIT
homepage: https://agentsec.sh
author: markeljan
credits: original author semiotic-ai
permissions:
  - filesystem:read
metadata:
  agentsec:
    profile: meta
  openclaw:
    emoji: "🛡️"
    homepage: https://agentsec.sh
    requires:
      anyBins:
        - agentsec
        - npx
        - bunx
    install:
      - kind: node
        package: agentsec
        bins:
          - agentsec
        label: Install agentsec (npm)
---

# agentsec

## intent

audit your installed AI agent skills against the OWASP Agentic Skills Top 10 to catch security vulnerabilities, misconfigurations, and governance gaps before they run. use agentsec when you need to verify skills are safe, gate CI/CD pipelines on skill security, check compliance across platforms (Claude, OpenClaw, Codex, Hermes), or generate audit reports (text, JSON, SARIF, HTML) for stakeholders. runs zero-config with auto-discovery across platform default locations, or target specific directories and policy presets.

## inputs

**required**

- agentsec binary or access to npm/bun/pnpm package manager for `npx agentsec` (no global install needed)

**optional**

- custom skill directory path (default: auto-discovers from platform locations listed below)
- policy preset name: `default`, `strict`, `permissive`, or `owasp-agent-top-10` (default: `default`)
- output format: `text`, `json`, `sarif`, or `html` (default: `text`)
- output file path for report (default: stdout)
- platform filter: `openclaw`, `claude`, `codex`, `hermes`, or auto-detect (default: auto)
- profile: `default`, `web3`, or `strict` (default: `default`, auto-detects Web3 skills)

**auto-discovery locations** (scanned by default, no flag required)

| Platform | Paths |
| -------- | ----- |
| Claude Code | `~/.claude/skills`, `./.claude/skills`, `~/.claude/plugins/*/skills/*`, `~/.claude/commands`, `./.claude/commands` |
| OpenClaw/ClawHub | `~/.openclaw/workspace/skills`, `~/.openclaw/workspace-*/skills` (respects `OPENCLAW_PROFILE` env var), `~/.openclaw/skills` |
| Codex/skills.sh | `~/.agents/skills`, `./.agents/skills`, `../.agents/skills`, `/etc/codex/skills` |
| Hermes | `~/.hermes/skills`, `~/.hermes/skills/*` (bundled categories), `./.hermes/skills` |
| Generic | any `skills/` directory in current project, up to two levels deep |

**optional config file** (auto-loaded from cwd or parent)

agentsec auto-discovers `.agentsecrc`, `.agentsecrc.json`, or `agentsec.config.json`. CLI flags override config file values.

```json
{
  "format": "text",
  "output": null,
  "policy": "strict",
  "verbose": false
}

procedure

1. invoke agentsec with desired command and flags

   • input: command (empty for full audit, scan, report, policy)
   • input: flags (--format, --output, --policy, --path, --platform, --profile, --verbose, --no-color, --help, --version)
   • output: audit process starts

2. agentsec auto-discovers skill directories (unless --path or --platform override)

   • input: file system paths from inputs section above
   • output: list of found skills in SKILL.md format, grouped by platform
   • note: scans up to two levels deep in generic skills/ directories

3. agentsec audits each skill against OWASP Agentic Skills Top 10 rules

   • input: SKILL.md manifest for each skill (metadata, permissions, inputs, procedure, etc.)
   • input: policy preset rules (default, strict, permissive, or owasp-agent-top-10)
   • output: per-skill grade (A-F scale), numeric score (0-100), risk category tags
   • note: detects Web3 skills automatically via manifest blocks, imports, RPC method refs, or .sol files; applies AST-W01 through AST-W12 web3 annex rules if detected

4. agentsec applies policy gate

   • input: active policy preset (from --policy flag or config file)
   • input: audit findings (critical, high, medium, low severity)
   • output: PASS or WARN/FAIL status; determines exit code
   • note: strict blocks high and critical findings; default blocks critical; permissive only blocks critical CVEs

5. agentsec formats and outputs report

   • input: format flag (text, json, sarif, html)
   • input: output path (--output flag or stdout)
   • output: formatted audit report written to file or console
   • note: json format useful for piping into jq or custom scripts; sarif integrates with IDE/code-scanning tools; html for stakeholder viewing

decision points

• if user specifies --path: scan only that directory, skip auto-discovery
• if user specifies --platform: scan only that platform's locations (claude, openclaw, codex, hermes), ignore others
• if Web3 skills detected (manifest has web3: block, imports viem/ethers/web3/wagmi/solana, references eth_*/wallet_*/personal_sign/signTypedData, or ships .sol file): apply AST-W01 through AST-W12 web3 annex rules automatically, unless --profile web3 is set (which forces annex on every skill regardless)
• if policy violation detected: return exit code 1 and WARN/FAIL status; exit code 0 only if audit passes the active policy
• if --format json requested: also save raw audit JSON for later replay with agentsec report
• if no skills found: still return exit code 0 with zero-skills summary (not a fatal error)
• if config file present: use it as baseline; all CLI flags override config values
• if --verbose flag set: include score breakdowns, rule IDs, file/line locations, and remediation text per finding; else show one-line summary only

output contract

text format (default)

✔ 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

json format

• structured JSON object with skills array, each containing: name, version, grade, score, findings array (id, severity, title, file, line, remediation)
• top-level summary: total skills, avg score, certified count, finding counts by severity

sarif format

• SARIF 2.1.0 compliant output suitable for GitHub code scanning, IDE integration
• one result per finding with ruleId, level, message, location (file, line)

html format

• interactive HTML report with skill grades, finding details, charts, and remediation guidance
• suitable for stakeholder or audit review

exit codes

• 0: audit passed the active policy (no high/critical findings under policy constraints)
• 1: policy violation or fatal error (missing binary, invalid config, parse error)

file location (if --output specified)

• report written to specified path; parent directories created if needed
• stdout used if --output omitted

outcome signal

• run command completes with exit code 0 or 1 visible in shell
• report appears on screen (text, json, html preview, or sarif) or in specified output file
• web3-tagged skills appear with [Web3] suffix in output if detected
• verbose mode shows per-rule details, file paths, and remediation steps
• policy gate status (PASS, WARN, FAIL) clearly displayed at end of report
• npx agentsec policy list and npx agentsec policy show <preset> confirm available rules and presets loaded correctly
• npx agentsec report audit.json --format html successfully replays a saved audit as a new report

---

quick start

fastest path: no install, no flags.

npx agentsec

this auto-discovers every skill across all known platforms and audits against the OWASP Agentic Skills Top 10. always try this first.

core commands

every workflow starts from one of four commands. run with npx agentsec (no install needed) or just agentsec if globally installed.

# 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

npx agentsec needs no install. for repeated use, install globally:

# bun (recommended)
bun add -g agentsec

# npm
npm install -g agentsec

# pnpm
pnpm add -g agentsec

# yarn
yarn global add agentsec

then drop the npx prefix:

agentsec
agentsec scan --path ./my-skills

flags

all flags work with any command.

flag	short	values	default	purpose
--format	-f	text, json, sarif, html	text	output format
--output	-o	path	stdout	write report to file
--policy	-p	preset name or path	default	apply a policy preset
--platform		openclaw, claude, codex, hermes	auto	narrow to one agent platform
--path		path	auto	custom skill directory to scan
--profile		default, web3, strict	default	rule profile. default auto-detects Web3 skills; web3 forces the annex on every skill
--verbose	-v		off	show detailed findings
--no-color			off	disable colored output
--help	-h			show help
--version	-V			print version

common recipes

show detailed findings and remediation:

npx agentsec --verbose

scan a specific directory:

npx agentsec scan --path ./my-skills

target a specific agent platform:

npx agentsec --platform claude
npx agentsec --platform codex
npx agentsec --platform hermes
npx agentsec --platform openclaw

audit with a strict policy and save JSON:

npx agentsec --policy strict --format json --output audit.json

generate an HTML report for stakeholders:

npx agentsec --format html --output report.html

generate a SARIF report for IDE / code-scanning integration:

npx agentsec --format sarif --output report.sarif

list available policy presets:

npx agentsec policy list

inspect the rules in a preset:

npx agentsec policy show strict

validate a custom policy config file:

npx agentsec policy validate ./my-policy.json

replay a previous audit as an HTML report:

npx agentsec report audit.json --format html --output report.html

policy presets

name	use case
default	balanced policy. blocks critical findings.
strict	enterprise-grade. blocks high and critical findings, enforces tests.
permissive	lenient. only blocks critical CVEs. good for development.
owasp-agent-top-10	built directly from the OWASP Agentic Skills Top 10.

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:

• manifest declares a web3: block
• source imports a Web3 client library (viem, ethers, web3, wagmi, @solana/web3.js, @coinbase/onchainkit, @privy-io, @biconomy, @zerodev)
• references a Web3 RPC method (eth_*, wallet_*, personal_sign, signTypedData)
• ships a .sol file

detected skills are tagged [Web3] in the output:

✔ scoped-trader v1.4.0  [Web3]  C (62)
✔ helpful-summarizer v1.2.0     A (95)

--profile web3 forces the annex onto every skill regardless of detection (useful for cross-team CI consistency):

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 web3 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.

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 --verbose for score breakdowns, rule IDs, file/line locations, and remediation for each finding.

exit codes

• 0: audit passed the active policy
• 1: policy violation or fatal error

use the exit code directly to gate CI pipelines, no special flag required:

npx agentsec --policy strict || exit 1

tips

• start with npx agentsec , no install, no flags. iterate from there.
• add --verbose whenever you need to act on specific findings.
• pipe --format json into jq or a custom script for programmatic handling.
• strict is the most common preset for production repositories.
• browse the agent skills ecosystem at skills.sh.