agentsec

intent

agentsec audits installed ai agent skills against the owasp agentic skills top 10 security framework, checking for malicious code, supply chain compromise, over-privileged access, unsafe deserialization, weak isolation, outdated deps, poor governance, and cross-platform reuse risks. use it when you need to verify skill safety before running them, gate ci/cd pipelines on security compliance, generate audit reports for stakeholders (text, json, sarif, html formats), or validate web3-enabled skills against additional signing and transaction scoping rules.

inputs

required:

• agentsec binary or npx/bunx available in PATH (auto-discovers npm installation)
• filesystem read access to skill directories (permissions:read)

platform auto-discovery 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
• Generic: any skills/ directory in current project (up to two levels deep)

optional flags:

• --path : override auto-discovery, scan specific directory only
• --platform : narrow scan to one platform (openclaw, claude, codex)
• --policy <preset|path>: apply policy preset (default, strict, permissive, owasp-agent-top-10) or path to custom policy json
• --profile : rule profile (default auto-detects web3; web3 forces web3 annex on all skills; default is default)
• --format : output format (text, json, sarif, html; default: text)
• --output : write report to file instead of stdout
• --verbose: show detailed findings, rule ids, file/line locations, remediation
• --no-color: strip ansi colors from output
• --help: print help
• --version: print version

external connections: none required; no api keys, oauth, or credentials needed.

procedure

1. invoke audit command with npx agentsec (or agentsec if installed globally). no flags runs full audit with default policy against all auto-discovered skill paths. input: user invocation with optional flags. output: audit object queued for processing.

2. scan skills against owasp agentic skills top 10 rules (ast01-ast10). parse each skill's manifest (name, version, permissions, imports, declared web3 config), source code, and dependency tree. for each skill, emit findings keyed by owasp category (malicious skills, supply chain, over-privilege, insecure metadata, unsafe deserialization, weak isolation, update drift, poor scanning, no governance, cross-platform reuse). input: skill metadata, source, deps. output: raw findings list (one entry per vulnerability detected, including severity level: critical, high, medium, low).

3. detect web3 skills (auto, unless --profile default explicitly). a skill is tagged web3 if it declares web3: block in manifest, imports a web3 library (viem, ethers, web3, wagmi, @solana/web3.js, @coinbase/onchainkit, @privy-io, @biconomy, @zerodev), references web3 rpc methods (eth_*, wallet_*, personal_sign, signTypedData), or ships a .sol file. input: manifest, imports, rpc calls, file list. output: boolean web3 flag on skill record.

4. audit web3 skills against annex if detected (ast-w01 through ast-w12). check signing authority bounds, permit/permit2 capture, eip-7702 delegation, blind signing surfaces, rpc endpoint substitution, unverified contract calls, cross-chain replay, mcp drift, session-key erosion, slippage/oracle manipulation, key material in memory, on-chain audit trail. input: web3 config from manifest, source inspection. output: web3-specific findings.

5. compute grade and score per skill. aggregate findings by severity (critical counts as -30, high -20, medium -10, low -5). score ranges 0-100; grade is derived (a 90+, b 80-89, c 70-79, d 60-69, f <60). input: findings list. output: single score and letter grade per skill.

6. apply policy (step runs after all skills scored). load policy preset or custom config file. policy defines pass/fail rules (e.g., "fail if any critical or high finding", "fail if avg score <70", "fail if no tests declared"). evaluate each skill and the aggregate against policy rules. input: scores, findings, policy object. output: pass/warn/fail status for each skill and audit as a whole.

7. format output according to --format flag. text: human readable summary (skill list with grades, aggregate stats, exit status). json: structured findings object suitable for piping to jq or custom scripts. sarif: static analysis results interchange format for ide integration. html: styled html report for stakeholder review. input: audit state (skills, findings, scores, grades, policy result). output: formatted string or file written to --output path (or stdout if no --output).

8. exit with code 0 if policy passed, 1 if policy violated or fatal error. input: policy evaluation result. output: exit code to shell.

decision points

if user does not specify --path or --platform: scan all auto-discovery locations for all known agent platforms (claude, openclaw, codex, generic). this is the default and recommended path for most audits.

if user specifies --path: only scan that directory; skip auto-discovery entirely.

if user specifies --platform: only scan auto-discovery paths for that platform (claude, openclaw, or codex); ignore other platform paths.

if skill is detected as web3 (auto-detect or --profile web3): apply ast-w01 through ast-w12 annex rules in addition to core ast01-ast10. if skill has a web3: block in manifest declaring scopes (chains, signers, policy caps, session-key scopes), verify that findings align with declared bounds before flagging. unscoped web3 skills trigger failures under strict/owasp-agent-top-10 policies.

if user supplies --policy : use that preset (default, strict, permissive, owasp-agent-top-10). if user supplies --policy :** load custom policy from file.

if no policy supplied: default policy is applied (blocks critical findings, warns on high).

if --format json supplied: output raw audit object regardless of policy result. if --format sarif supplied:** map findings to sarif severities (critical/high to error, medium to warning, low to note). if --format html supplied:** generate styled report with grade badges, score breakdown, and remediation links.

if --output supplied: write formatted output to file and suppress stdout. if no --output:** print to stdout.

if skill scan fails (parse error, permission denied, network timeout): emit fatal error for that skill, continue scanning others, report error count in summary, exit 1.

if no skills found: emit zero-skills-found message, exit 0 (this is not an error).

if policy evaluation results in warn status: print ⚠ warning to stderr, exit 0 (audit ran, but policy flag was soft). if fail status: print ✗ failure to stderr, exit 1.

if --verbose flag: expand output to include rule ids (ast01, ast-w05, etc.), file paths and line numbers where vulnerability detected, remediation guidance for each finding. omit verbose details if --verbose absent.

if --no-color flag: strip ansi escape codes from text output (no impact on json, sarif, html).

if custom .agentsecrc, .agentsecrc.json, or agentsec.config.json found in current or parent directory: load as base config. cli flags override config file values. omit "platform" and "path" keys in config to preserve auto-discovery behavior.

if network error (timeout, dns failure, unreachable registry) during dependency check: note finding as "dep check timeout" with severity medium or low, continue audit, exit 0 unless policy mandates failure on incomplete scans.

output contract

text format (default):

✔ Found N skills

✔ skill-name   v1.0.0  [Web3]  A (95)
⚠ skill-name   v2.0.0          C (68)
✗ skill-name   v1.5.0          F (35)

N skills scanned  •  avg score M  •  X certified
Findings: C critical, H high, D medium, L low

[PASS|WARN|FAIL]  message

• each skill shows: status icon, name, version, optional [Web3] tag, letter grade, numeric score (0-100).
• summary line includes skill count, average score, certified count (passing default policy).
• findings aggregate counts by severity.
• final status line shows policy result.

json format:

{
  "audit_id": "uuid",
  "timestamp": "iso8601",
  "policy_used": "strict",
  "platform_scanned": ["openclaw", "claude"],
  "skills": [
    {
      "name": "skill-name",
      "version": "1.0.0",
      "web3": false,
      "score": 95,
      "grade": "A",
      "findings": [
        {
          "id": "ast02",
          "severity": "high",
          "title": "outdated dependency",
          "file": "package.json",
          "line": 12,
          "remediation": "update lodash to ^4.17.21"
        }
      ]
    }
  ],
  "aggregate": {
    "total_skills": 6,
    "avg_score": 78,
    "critical": 2,
    "high": 1,
    "medium": 2,
    "low": 0
  },
  "policy_result": "WARN"
}

sarif format: standard sarif 2.1.0 output suitable for ingestion by github code scanning, gitlab sast, ide plugins. each finding mapped to owasp agentic skills top 10 rule id as ruleId, severity as level (error/warning/note), file/line as locations.

html format: single self-contained html file with:

• header: audit timestamp, policy used, platform scanned.
• skill cards: name, version, grade badge, score gauge, web3 tag if present.
• findings table: rule id, severity color, title, remediation link.
• aggregate stats: pie chart of severity distribution, avg score, pass/fail status.

file output: if --output specified, write formatted output to that path. all formats support --output. if file exists, overwrite. create parent directories if needed. emit file path to stderr on success.

exit code: 0 if audit completed successfully and policy passed. 1 if policy failed, fatal error, or no skills found and strict policy applied.

outcome signal

user sees audit result immediately in terminal or in written report file:

• text mode: colored summary printed to stdout showing skill grades, aggregate stats, and pass/fail banner. user can read results instantly and act on findings.

• json mode: structured audit object printed to stdout (or written to file with --output). user can pipe to jq, import into a dashboard, or parse programmatically to gate ci/cd.

• sarif mode: sarif json file written to --output path. user uploads to github/gitlab; vulnerabilities appear in code-scanning ui and pr comments.

• html mode: html file written to --output path. user opens in browser; executive or team lead sees styled report with remediation guidance.

• exit code: shell sees exit code 0 (pass) or 1 (fail). ci pipeline can branch on exit code: agentsec --policy strict || exit 1 stops the build if policy fails.

• verbose output: user sees rule ids (ast05, ast-w03, etc.), exact file paths and line numbers, specific remediation steps. user knows which skill, which rule, where to fix.

success criteria:

• all auto-discovered skills scanned without fatal errors.
• findings categorized and scored consistently.
• policy evaluation deterministic and reproducible.
• output format matches specified flag (text/json/sarif/html).
• exit code reflects policy result (0 pass, 1 fail).
• if --verbose: remediation text present for each finding.
• if --output: file created and readable; no data lost.