agentsec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agentsec

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.

agentsec

是一款针对AI Agent技能的安全审计CLI工具。它会扫描项目中已安装的所有技能，对照OWASP Agentic Skills Top 10检测漏洞、配置错误以及治理缺口。

When to Use

适用场景

Use

agentsec

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

当用户有以下需求时，可使用

agentsec

：

审计、扫描或检查Agent技能的安全问题
在运行已安装的技能前验证其安全性
检查Agent配置是否符合OWASP合规要求
基于技能安全性管控CI/CD流水线
为相关方生成安全审计报告

Quick Start

快速开始

The fastest path to a result — no install, no flags:

bash

npx agentsec

This scans every default skills directory on the machine — grouped by platform — plus any

./skills

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.

无需安装、无需参数，最快获得扫描结果：

bash

npx agentsec

该命令会扫描机器上所有默认技能目录（按平台分组），以及当前项目中所有

./skills

文件夹（最多两层深度），并对照OWASP Agentic Skills Top 10审计每个已安装的技能。建议首先尝试此命令。

Auto-discovery locations

自动发现路径

Platform	Paths scanned
Claude Code	`~/.claude/skills` , `./.claude/skills` , `~/.claude/plugins//skills/` , `~/.claude/commands` , `./.claude/commands`
OpenClaw / ClawHub	`~/.openclaw/workspace/skills` , `~/.openclaw/workspace-*/skills` (profiles via `OPENCLAW_PROFILE` ), `~/.openclaw/skills`
Codex / skills.sh	`~/.agents/skills` , `./.agents/skills` , `../.agents/skills` , `/etc/codex/skills`
Other (generic)	Any `skills/` directory found within the current project, up to two levels deep

平台	扫描路径
Claude Code	`~/.claude/skills` , `./.claude/skills` , `~/.claude/plugins//skills/` , `~/.claude/commands` , `./.claude/commands`
OpenClaw / ClawHub	`~/.openclaw/workspace/skills` , `~/.openclaw/workspace-*/skills` （通过 `OPENCLAW_PROFILE` 指定配置文件）, `~/.openclaw/skills`
Codex / skills.sh	`~/.agents/skills` , `./.agents/skills` , `../.agents/skills` , `/etc/codex/skills`
其他（通用）	当前项目中找到的所有 `skills/` 目录，最多两层深度

Core Commands

核心命令

Every workflow starts from one of four commands. Run them with

npx agentsec

— no install needed.

bash

undefined

所有工作流均从以下四个命令开始。无需安装，直接通过

npx agentsec

运行。

bash

undefined

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

从已保存的审计JSON文件生成报告

npx agentsec report audit.json

Manage and inspect policy presets

管理和查看策略预设

npx agentsec policy list

undefined

npx agentsec policy list

undefined

Installation

安装方式

npx agentsec

needs no install. For repeated use, install globally:

bash

undefined

npx agentsec

无需安装即可使用。如需重复使用，可全局安装：

bash

undefined

bun (recommended)

bun（推荐）

bun add -g agentsec

npm

npm install -g agentsec

pnpm

pnpm add -g agentsec

yarn

yarn global add agentsec


Then drop the `npx` prefix:

```bash
agentsec
agentsec scan --path ./my-skills

yarn global add agentsec


安装后即可省略`npx`前缀：

```bash
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`	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

所有参数可搭配任意命令使用。

参数	简写	可选值	默认值	用途
`--format`	`-f`	`text` , `json` , `sarif` , `html`	`text`	输出格式
`--output`	`-o`	文件路径	标准输出	将报告写入文件
`--policy`	`-p`	预设名称或文件路径	`default`	应用策略预设
`--platform`		`openclaw` , `claude` , `codex`	自动检测	限定扫描单个Agent平台
`--path`		目录路径	自动检测	指定要扫描的自定义技能目录
`--profile`		`default` , `web3` , `strict`	`default`	规则配置文件。 `default` 会自动检测Web3技能； `web3` 会对所有技能强制应用附加规则
`--verbose`	`-v`		关闭	显示详细检测结果
`--no-color`			关闭	禁用彩色输出
`--help`	`-h`			显示帮助信息
`--version`	`-V`			输出版本号

Common Recipes

常用操作示例

Show detailed findings and remediation

显示详细检测结果与修复建议

bash

npx agentsec --verbose

bash

npx agentsec --verbose

Scan a specific directory

扫描指定目录

bash

npx agentsec scan --path ./my-skills

bash

npx agentsec scan --path ./my-skills

Target a specific agent platform

针对特定Agent平台扫描

bash

npx agentsec --platform claude
npx agentsec --platform codex

bash

npx agentsec --platform claude
npx agentsec --platform codex

Audit with a strict policy and save JSON

使用严格策略审计并保存为JSON文件

bash

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

bash

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

Generate an HTML report for stakeholders

为相关方生成HTML报告

bash

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

bash

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

Generate a SARIF report for IDE / code-scanning integration

生成SARIF报告用于IDE/代码扫描集成

bash

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

bash

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

List available policy presets

查看可用的策略预设

bash

npx agentsec policy list

bash

npx agentsec policy list

Inspect the rules in a preset

查看预设中的规则

bash

npx agentsec policy show strict

bash

npx agentsec policy show strict

Validate a custom policy config file

验证自定义策略配置文件

bash

npx agentsec policy validate ./my-policy.json

bash

npx agentsec policy validate ./my-policy.json

Replay a previous audit as an HTML report

从之前的审计JSON文件重新生成HTML报告

bash

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

bash

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.

名称	适用场景
`default`	平衡策略，阻止严重级别的检测结果。
`strict`	企业级策略，阻止高风险和严重级别的检测结果，并强制要求测试。
`permissive`	宽松策略，仅阻止严重级别的CVE漏洞。适用于开发环境。
`owasp-agent-top-10`	完全基于OWASP Agentic Skills Top 10构建。

Configuration File

配置文件

agentsec

auto-loads

.agentsecrc

.agentsecrc.json

, or

agentsec.config.json

from the current directory (or any parent):

json

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

CLI flags always override config file values. Omit

"platform"

and

"path"

to keep the default auto-discovery behavior — agentsec will scan every known platform's default locations.

agentsec

.agentsecrc

、

.agentsecrc.json

或

agentsec.config.json

配置文件：

json

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

CLI参数优先级始终高于配置文件。省略

"platform"

和

"path"

可保留默认自动发现行为——agentsec会扫描所有已知平台的默认路径。

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

每次审计都会检查以下十大风险类别：

ID	风险类型
AST01	恶意技能
AST02	供应链攻击
AST03	权限过度的技能
AST04	不安全的元数据
AST05	不安全的反序列化
AST06	隔离性薄弱
AST07	更新偏差
AST08	扫描不充分
AST09	缺乏治理
AST10	跨平台复用

AST-10 Web3 Annex (auto-detected)

AST-10 Web3附加规则（自动检测）

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

web3:

block, when its source imports a Web3 client library (

viem

ethers

web3

wagmi

@solana/web3.js

@coinbase/onchainkit

@privy-io

@biconomy

@zerodev

), when it references a Web3 RPC method (

eth_*

wallet_*

personal_sign

signTypedData

), or when it ships a

.sol

file. Detected skills are tagged

[Web3]

in the output:

text

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

--profile web3

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

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

docs/plans/ast10-web3-annex-rules.md

for full per-rule detection signals.

工具会自动检测涉及Web3的技能，并针对额外12条规则进行审计——无需额外参数。当技能的清单文件中声明了

web3:

块、源码中导入了Web3客户端库（

viem

、

ethers

、

web3

、

wagmi

、

@solana/web3.js

、

@coinbase/onchainkit

、

@privy-io

、

@biconomy

、

@zerodev

）、引用了Web3 RPC方法（

eth_*

、

wallet_*

、

personal_sign

、

signTypedData

），或包含

.sol

文件时，会被判定为Web3技能。检测到的技能会在输出中标记为

[Web3]

：

text

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

仍可使用

--profile web3

参数——它会对所有技能强制应用附加规则，无论是否检测到Web3属性（有助于跨团队CI流程的一致性）：

bash

npx agentsec audit --profile web3 --path ./my-skills

ID	风险类型
AST-W01	无限制的签名权限
AST-W02	隐式Permit/Permit2签名捕获
AST-W03	通过EIP-7702劫持授权
AST-W04	盲签/不透明签名界面
AST-W05	RPC端点替换与内存池泄露
AST-W06	未验证的合约调用目标
AST-W07	跨链/桥接操作重放
AST-W08	MCP链工具偏差/能力走私
AST-W09	会话密钥/权限约束弱化
AST-W10	Agent循环导致滑点/预言机操纵
AST-W11	密钥材料存储在Agent内存/日志中
AST-W12	无链上操作审计/终止开关

技能可在清单文件中声明

web3

块（包含链信息、签名者、策略限制、会话密钥范围、MCP服务器固定、审计接收端、终止开关），以便附加规则验证其范围，不会误判边界清晰的技能。完整的规则检测信号可查看

docs/plans/ast10-web3-annex-rules.md

。

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.

默认输出为紧凑格式：每个技能显示等级和分数，随后是一行检测结果摘要以及PASS/WARN/FAIL状态。

✔ 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

使用

--verbose

参数可查看分数明细、规则ID、文件/行位置以及每个检测结果的修复建议。

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:

bash

npx agentsec --policy strict || exit 1

```
0
```
— 审计符合当前策略要求
```
1
```
— 违反策略或发生致命错误

可直接使用退出码管控CI流水线——无需额外参数：

bash

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.

从
```
npx agentsec
```
开始——无需安装、无需参数，在此基础上逐步调整。
当需要针对具体检测结果采取行动时，添加
```
--verbose
```
参数。
将
```
--format json
```
的输出通过管道传递给
```
jq
```
或自定义脚本，实现程序化处理。
```
strict
```
是生产环境仓库最常用的策略预设。
可访问skills.sh浏览Agent技能生态。