rdzehtsiar/agent-skill-auditor

# Agent Skill 审计员 [](https://github.com/rdzehtsiar/agent-skill-auditor/actions/workflows/tests.yml) [](https://codecov.io/gh/rdzehtsiar/agent-skill-auditor) [](https://sonarcloud.io/summary/new_code?id=rdzehtsiar_agent-skill-auditor) 面向 AI Agent 技能的离线安全与兼容性审计工具。 Agent Skill Auditor 旨在帮助解答一个实际的信任问题： 它不是一个通用的 Markdown 或 YAML Linter。它的目标用户是在安装、发布或审批 Agent 技能包之前，需要对其进行检查的维护者、安全审查人员和团队。 ## 状态 Agent Skill Auditor 目前为技能包提供了一个本地 CLI 扫描器。 v0.6.0 的 CLI 可以发现 `SKILL.md` manifest，解析 frontmatter 和 Markdown 内容，提取规范化的包元数据，评估基于元数据的确定性规则，评估本地宿主兼容性配置，盘点本地供应链证据，加载明确的审计配置，应用已文档化的抑制规则，并生成总结报告、JSON、SARIF 和独立的离线 HTML 报告。它完全在离线状态下运行，且不会执行技能脚本。 v0.5.0 的供应链功能可以报告关于许可证、信任 manifest、外部 URL、远程依赖、依赖 manifest、包管理器文件、lockfiles、可执行与二进制制品、校验和、观察到的权限以及离线审计就绪情况的本地证据。离线审计就绪情况是基于本地证据的审计信号；它不能证明该技能可以在离线环境下运行。它不会联系代码库或注册表，不会验证代码库的所有权，也不会证明远程来源是值得信任的。 v0.7.0 的集成工作记录了适用于本地 Cargo 构建、已提交的 GitHub Action、本地 Docker 镜像、npm 包装器、Homebrew tap formula 模板和 mise/asdf 指南的 CI-ready 安装和工作流路径。在相应的发布标签、资产、注册表、taps、插件仓库和凭证实际存在之前，外部发布渠道不会激活。 v0.7.5 的公开审计强化工作为 v0.8 的公开生态系统审计做好了准备，其方式是记录方法学元数据、稳定的发现与组指纹、公开安全的数据集输出、置信度标签、规范的发现分组以及观察到的生态系统模式报告。策略包仍在规划中。 ## 快速开始 构建并测试工作区： ``` cargo build cargo test ``` 将本地代码库安装到 `PATH`： ``` cargo install --locked --path crates/agent-audit-cli agent-audit scan . ``` 或者构建一个 release 二进制文件，但不进行安装： ``` cargo build --locked --release -p agent-audit-cli --bin agent-audit ./target/release/agent-audit scan . ``` 对基础 fixture 运行一次总结性扫描： ``` cargo run -q -p agent-audit-cli -- scan fixtures/spec/basic ``` 有关 v0.7.0 发布渠道的指导，请参阅[安装与工作流路径](./docs/release/install.md)，涵盖 Cargo、GitHub Actions、Docker、npm、Homebrew、mise 和 asdf。在这些外部渠道正式发布之前，Docker 镜像、npm 包、Homebrew tap、mise 插件、asdf 插件和 crates.io 安装路径仅作为发布模板存在。 ## CLI 用法 ``` agent-audit scan [PATH] [--format FORMAT] [--mode MODE] [--output PATH] [--open] [--config PATH] [--fail-on SEVERITY] [--profile PROFILE] [--supply-chain] [--strict-supply-chain] [--corpus-name NAME] [--corpus-entry-id ID] [--methodology-version VERSION] [--inclusion-tag TAG] [--repo-classification CLASSIFICATION] [--scan-batch-id ID] ``` - `PATH` 默认为 `.`。 - `--format` 默认为 `summary`。 - 支持的格式有 `summary`、`json`、`public-json`、`sarif` 和 `html`。 - `--mode` 默认为 `default`。支持的模式有 `default`、`verbose`、`research` 和 `ci`。 - 人类可读的 summary 和 HTML 输出使用 `--mode` 来控制密度：分组默认输出、展开的 verbose 发现、带有规范化键的分组 research 证据，或紧凑的 CI 日志。Default、research、HTML 和 JSON 报告使用相同的规范发现组和组指纹；CI 模式显示经过过滤的顶层组子集，并将其标记为已过滤以控制日志大小。JSON 和 SARIF 保留完整的发现集，包括发现置信度。 - `--output PATH` 将选定的报告格式写入文件，而不是标准输出。当生成的输出路径已知时，CI 总结会包含该路径。 - `--open` 在 HTML 报告写入后将其打开。它仅在指定了 `--format html --output PATH` 的情况下适用，并且仅在 `fail_on` 检查通过之后才会执行。 - `--config PATH` 在扫描之前显式读取并验证 YAML 审计配置。 - `--fail-on SEVERITY` 在呈现报告后，如果有任何未被抑制的发现完全匹配该严重级别，则以失败退出。重复使用此选项可匹配多个严重级别。 - 支持的严重级别有 `info`、`low`、`medium`、`high` 和 `critical`。 - `--profile PROFILE` 选择兼容性配置。可以重复使用或使用逗号分隔的值。使用 `--profile all` 包含所有支持的配置。 - 接受 `--supply-chain` 是为了与聚焦供应链的工作流保持兼容；盘点和供应链规则默认已经在运行。 - `--strict-supply-chain` 要求提供本地的信任 manifest 和许可证证据，并会添加默认扫描故意回避的缺失元数据发现。 - 可选的方法学标志（`--corpus-name`、`--corpus-entry-id`、`--methodology-version`、`--inclusion-tag`、`--repo-classification` 和 `--scan-batch-id`）将 v0.8 公开审计上下文附加到 JSON、public JSON 和 HTML 报告中。在未设置时，它们在常规扫描中会被省略。 示例： ``` agent-audit scan agent-audit scan fixtures/spec/basic agent-audit scan fixtures/compatibility/valid/spec-basic --profile all agent-audit scan fixtures/compatibility/host/mixed-profile-metadata --profile codex,github-copilot agent-audit scan fixtures/compatibility/host/mixed-profile-metadata --profile codex --profile github-copilot agent-audit scan fixtures/spec/basic --format json agent-audit scan fixtures/spec/basic --format public-json agent-audit scan fixtures/spec/basic --format sarif agent-audit scan fixtures/spec/basic --format html agent-audit scan fixtures/spec/basic --mode verbose agent-audit scan fixtures/spec/basic --mode ci agent-audit scan fixtures/spec/basic --format html --output report.html agent-audit scan fixtures/spec/basic --format html --output report.html --open agent-audit scan fixtures/supply-chain/trust-manifest-valid --format json agent-audit scan fixtures/spec/basic --strict-supply-chain agent-audit scan fixtures/spec/basic --config .agent-audit.yaml agent-audit scan fixtures/spec/basic --fail-on medium --fail-on high agent-audit scan fixtures/spec/basic --config .agent-audit.yaml --fail-on high agent-audit scan ./skills --config .agent-audit.yaml --format public-json --output reports/public-audit-001/dataset.json --corpus-name "v0.8 public audit" --corpus-entry-id repo-001 --methodology-version 2026-05 --inclusion-tag public,executable --repo-classification oss-skill-repo --scan-batch-id batch-2026-05 ``` 配置加载是显式的。当省略 `--config` 时，扫描器不会自动发现 `.agent-audit.yaml`。 当同时提供了配置中的 `fail_on` 和 CLI 的 `--fail-on` 值时，以 CLI 值为准。例如，一个在 `low` 级别失败的配置，可以通过在某次运行中指定 `--fail-on high` 来缩小失败范围。 CI 模式保持输出简短且面向操作。它报告精确的 `fail_on` 严重级别、阻塞性规范发现组、非阻塞性规范发现组、顶层阻塞组、生成的输出路径或 `stdout`，以及退出码行为。`fail_on` 依然是精确的严重级别匹配：当存在任何具有配置严重级别的未被抑制发现时，CLI 在呈现完毕后会返回非零退出码；除非扫描或报告写入失败，否则返回零。 当在配置或 CLI 中未选择任何配置时，扫描器会按注册顺序评估所有支持的兼容性配置：`agent-skills-spec`、`claude-code`、`codex`、`github-copilot`、`vscode-copilot` 和 `generic`。CLI 的 `--profile` 值会覆盖配置中的 `profiles`。 抑制规则是通过 `ignore` 条目配置的。精确抑制匹配一个活动规则 ID 和一个相对于被扫描项目的规范化路径；它们不使用 glob 匹配。模式抑制可以使用 `match` 来匹配规范化的分组证据键，例如，在许多生成的技能中抑制已审查过的 `requires` frontmatter 字段的 `SKILL040`。 ``` profiles: - codex - github-copilot fail_on: - medium - high ignore: - rule: SKILL010 path: skills/internal-search/SKILL.md reason: False positive: references/api.md is generated and packaged by the release process. - rule: SKILL040 match: requires reason: Accepted risk: generated requires metadata is reviewed by the platform team. ``` JSON 输出包含被抑制的发现，而 SARIF 报告仅包含活动发现。在这两种格式中，被抑制的发现都不会触发 `fail_on`。每条发现都包含附加的 `confidence` 元数据（`low`、`medium` 或 `high`），用于将证据确定性与严重级别区分开来。 配置 `profiles` 和兼容性抑制在[配置](./docs/config.md)中进行了说明。 ## 报告格式 Summary 输出适用于本地审查和 CI 日志： ``` cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/valid/spec-basic --profile all ``` Summary 输出包含一个紧凑的兼容性部分： ``` Compatibility: Profiles: agent-skills-spec, claude-code, codex, github-copilot, vscode-copilot, generic Status totals: pass=2 warn=0 fail=0 unknown=4 untested=0 Rows: - SKILL.md (spec-basic): agent-skills-spec=pass, claude-code=unknown, codex=unknown, github-copilot=unknown, vscode-copilot=unknown, generic=pass ``` JSON 输出适用于确定性的机器处理： ``` cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/host/mixed-profile-metadata --profile codex,github-copilot --format json cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/host/mixed-profile-metadata --profile codex,github-copilot --format json > report.json ``` 发现对象包括 `fingerprint`、`severity`、`confidence`、`category`、位置、理由、补救措施和抑制指南。`severity` 是策略影响；`confidence` 是扫描器的证据确定性。发现组根据规则和规范化证据维度将重复的发现聚集在一起，包含 `group_fingerprint`，并一致地用于默认 summary、research summary、HTML 和 JSON 输出。JSON 还包含一个结构化的 `patterns` 数组，当聚合证据支持时，包含简明的生态系统级观察、计数和受影响的包百分比。省略了 `confidence` 或 fingerprint 字段的旧版报告在反序列化时仍会保留默认值。 在生成可重用的公共审计数据集时，请使用 `--format public-json`。Public JSON 保留审计元数据、可选的方法学元数据、代码库元数据、包标识符、发现、发现组、指纹、指标、模式和有界的证据片段，但默认会省略完整的 `SKILL.md` 正文、代码块主体、行内代码主体和其他大型 manifest 内容。这是用于可复现报告的公开安全投影，而不是完整的内部扫描模型。公开数据集投影记录在 `docs/report.schema.json` 的 `$defs.publicDataset` 中。 JSON 报告包含稳定的兼容性矩阵数据： ``` "compatibility": { "profiles": ["codex", "github-copilot"], "matrix": [ { "path": ".agents/skills/mixed-profile-metadata/SKILL.md", "name": "mixed-profile-metadata", "profiles": [ { "profile": "codex", "status": "warn", "finding_ids": ["SKILL050"] }, { "profile": "github-copilot", "status": "unknown", "finding_ids": [] } ] } ] } ``` JSON 报告还包含一个稳定的 `supply_chain` 部分。该部分是本地证据的清单，而不是信任声明： ``` "supply_chain": { "licenses": [], "trust_manifests": [], "external_urls": [], "external_url_domains": [], "remote_dependencies": [], "dependency_manifests": [], "package_managers": [], "lockfiles": [], "executables": [], "binaries": [], "checksums": [], "permissions": [], "offline_readiness": [] } ``` `external_url_domains` 按域名对 `external_urls` 进行汇总，包括总 URL 数、可变 URL 数、示例 URL、受影响的包以及粗略的分类，如 `github-raw`、`docs`、`api`、`package-registry` 或 `unknown`。原始的每个 URL 的证据仍保留在 `external_urls` 中，以便进行详细审查和生成可复现的数据集。 `offline_readiness[].status`、`score` 和 `reasons` 描述了静态的离线可审计性。可选的 `runtime_offline_capability`、`external_service_dependency` 和 `remote_fetch_dependency` 字段是独立的，因此报告不会仅仅基于可审计性证据就暗示运行时的离线行为。 Summary 输出包含简明的供应链计数、当存在 URL 证据时的主要外部域名、离线审计就绪状态，以及适用的观察到的生态系统模式。SARIF 将供应链规则发现作为常规结果包含在内；完整的清单则保留在 JSON 中。 SARIF 输出适用于接受 SARIF 的代码扫描集成： ``` cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/host/mixed-profile-metadata --profile codex --profile github-copilot --format sarif cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/host/mixed-profile-metadata --profile codex --profile github-copilot --format sarif > report.sarif ``` HTML 输出适用于独立且易于阅读的报告： ``` cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/host/mixed-profile-metadata --profile codex --format html cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/host/mixed-profile-metadata --profile codex --format html --output report.html cargo run -q -p agent-audit-cli -- scan fixtures/compatibility/host/mixed-profile-metadata --profile codex --format html --output report.html --open ``` SARIF 在运行属性下存储兼容性矩阵数据，将配置上下文添加到兼容性发现中，并包含发现置信度、规则帮助文本、规则文档 URI、类别/配置标签、审计元数据和稳定的指纹。SARIF 级别对代码扫描进行了保守映射：`critical` 和 `high` 级别的发现映射为 `error`，`medium` 级别的发现映射为 `warning`，`low` 或 `info` 级别的发现映射为 `note`。HTML 报告是单一文件，不使用任何外部托管的资产，可以在离线状态下查看。外部 URL 呈现为文本以供审查，而不是被获取或嵌入。 HTML 报告呈现的内容包括：执行摘要、观察到的生态系统模式、风险分布、宿主支持、高风险技能、损坏的引用、外部 URL、机密使用情况、离线审计就绪情况、包、发现以及每个技能的详情部分。机密使用情况区分了实际的机密证据（如类似机密的环境变量访问）与提及暴露机密的提示风险文本。`--open` 仅限于显式的 HTML 文件输出：CLI 会首先写入报告，评估 `fail_on`，并仅在扫描结果通过时才打开文件。 ## 公共审计方法学 对于公开审计批次，建议使用带有方法学元数据的 `--format public-json`，以便下游读者能够识别语料库、条目、包含标签、代码库分类、方法学版本和扫描批次。Public JSON 被设计为公开安全的数据集：它保留了稳定的包标识符、发现、发现组、指纹、指标、观察到的生态系统模式和有界的证据片段，同时省略了完整的 manifest 主体和代码主体。 当规则、路径、位置和消息保持不变时，发现指纹可在多次运行中识别单个发现。组指纹可识别重复的问题家族，例如在生成的包中出现的相同宿主特定或无法识别的元数据字段。这些指纹支持生态系统模式报告，而不会暴露完整的私有源语料库。 ## 当前检查 当前的扫描器支持： - 递归发现 `SKILL.md`。 - Frontmatter 和 Markdown 解析。 - 提取 name、description、tools 和 permissions。 - 提取 Markdown 标题、链接、行内代码和围栏代码块。 - 提取相对文件引用。 - 对 `scripts/`、`references/` 和 `assets/` 的技能制品盘点。 - 针对本地许可证、信任 manifest、外部 URL、依赖 manifest、包管理器、lockfiles、可执行文件、二进制制品、校验和、观察到的权限以及离线审计就绪情况的供应链证据盘点。 - 用于初始结构性、规范和兼容性检查的、基于元数据的确定性规则引擎- 针对 `agent-skills-spec`、`claude-code`、`codex`、`github-copilot`、`vscode-copilot` 和 `generic` 的离线确定性兼容性矩阵。 - 确定性发现包括： - `SKILL001`：缺少必要的 name。 - `SKILL002`：缺少必要的 description。 - `SKILL010`：损坏的相对引用。 - `SKILL020`：manifest 过大。 - `SKILL030`：重复的技能名称。 - `SKILL040`：宿主特定或无法识别的元数据字段。 - `SKILL041`：格式错误的 frontmatter。 - `SKILL050`：被忽略的宿主特定元数据。 - 活动的 `SUPPLY` 规则：规则注册表中记录的已选定的 v0.5.0 供应链和来源检查。 规则元数据定义了每个规则的 ID、状态、严重级别、类别、解释、补救措施和安全的抑制指南。规则状态是显式的：`active` 规则可以发出发现并且可以被抑制，而 `reserved` 规则用于记录已规划的规则 ID，不会发出或在抑制配置中被接受。有关生成的规则注册表，请参见[规则文档](./docs/rules/README.md)。 `SKILL050` 是针对宿主特定元数据的活动元数据，这些元数据很可能会被选定的配置忽略。一些宿主特定或无法识别的 frontmatter 会被报告为 `SKILL040`。 配置在[配置](./docs/config.md)中进行了说明。当前的重要行为包括： - 配置加载通过 `--config PATH` 显式进行；`.agent-audit.yaml` 是首选的文件名，但不会被自动发现。 - `fail_on` 使用精确的严重级别匹配，而不是阈值匹配。例如，`fail_on: [medium]` 仅在未被抑制的 `medium` 发现时失败，而不是在 `high` 或 `critical` 时失败。 - `profiles` 值选择兼容性评估和矩阵渲染。省略或清空 `profiles` 将评估所有支持的配置。 - `supply_chain.policy: strict` 要求本地的信任 manifest 和许可证证据。默认策略只记录证据，而不会将缺失的可选元数据转化为发现。 - CLI 的 `--profile` 值会覆盖配置中的 `profiles`。 - CLI 的 `--strict-supply-chain` 会将该次扫描的配置供应链策略覆盖为 strict。 - 抑制需要活动的规则 ID、明确的原因，以及精确的规范化路径或分组的证据 `match` 值（包括兼容性发现）。 ## 安全模型 Agent Skill Auditor 旨在将不受信任的或第三方的技能包安装到 AI Agent 环境之前对其进行检查。 当前的 CLI： - 默认完全离线运行。 - 不收集遥测数据。 - 不需要托管后端。 - 不需要 AI API。 - 不执行不受信任的技能代码。 - 生成确定性的、可解释的结构性、兼容性、安全性和供应链发现。 - 适用于本地审查和 CI 冒烟测试。 静态分析无法证明技能是安全的。供应链检查仅使用本地文件和声明；它们不会验证远程身份、代码库所有权、注册表状态、签名，也不会验证引用的 URL 当前是否提供相同的字节。发现应被视为审查证据，而不是完整的安全保证。 ## 支持的技能内容 扫描器目前侧重于本地技能包内容： - `SKILL.md` - 技能目录。 - `scripts/` - `references/` - `assets/` 它解析 manifest 内容并盘点已知的制品目录，但不执行脚本或验证行为 fixture。 未来可能会扩展对其他 Agent 相关元数据和行为 fixture 的支持。 ## 宿主兼容性 宿主兼容性配置从本地扫描事实生成离线确定性矩阵。扫描器不会联系宿主、执行脚本或证明宿主会在运行时接受包。`pass` 表示已实施的检查验证了该配置当前建模的要求。 支持的配置包括： - `agent-skills-spec` - `claude-code` - `codex` - `github-copilot` - `vscode-copilot` - `generic` 矩阵单元格使用 `pass`、`warn`、`fail`、`unknown` 或 `untested`。除非有发现或明确的配置规则支持，否则仅限矩阵的警告情况（如非首选路径、脚本或权限元数据）均为 `unknown`。兼容性发现解释了发生了什么、发生在哪里、为什么重要、如何修复以及如何安全地抑制它。有关配置假设、选定路径约定、已知限制和状态含义，请参见[宿主配置](./docs/host-profiles.md)。 ## 路线图 | 领域 | 状态 | | --- | --- | | CLI 扫描器和包发现 | Phase 1 已实现。 | | 规范化的内部模型 | Phase 1 的包元数据已实现。 | | 确定性结构规则引擎 | 初始的 `SKILL001` 至 `SKILL041` 规则已实现。 | | JSON 输出 | 已实现。 | | 终端摘要 | 已实现。 | | SARIF 和 HTML 输出 | 已实现，包括 v0.6.0 独立的离线 HTML 报告。 | | Fixture 和快照式测试 | 针对当前的扫描器和报告行为已实现。 | | 宿主兼容性配置 | 初始的离线矩阵已实现。 | | 静态脚本安全分析器 | 针对选定的脚本和制品风险已实现初始的离线检查。 | | 供应链清单和规则 | 初始的 v0.5.0 本地证据管道已实现。 | | 规则文档生成 | 已通过规则元数据实现。 | | 策略和抑制配置 | 已实现显式配置加载、精确的 fail-on 严重级别匹配、严格的供应链策略和路径范围的抑制。 | | CI-ready 安装和工作流文档 | 针对 v0.7.0 本地 Cargo、已提交的 GitHub Action、本地 Docker 镜像、npm 包装器、Homebrew tap formula 模板和 mise/asdf 指南进行了记录。在真实的发布渠道存在之前，外部发布将保持推迟。 | ## 许可证 基于 Apache License, Version 2.0 许可。 参见 [LICENSE](./LICENSE.txt)。

标签：AI安全, Chat Copilot, DevSecOps, DNS 反向解析, HTML报告, IP 地址批量处理, Markdown解析, SARIF, SBOM, 上游代理, 云安全监控, 人工智能, 依赖管理, 兼容性检测, 前端元数据, 可视化界面, 多模态安全, 安全合规, 安全审查, 开源维护者, 技能审计, 文档结构分析, 用户模式Hook绕过, 硬件无关, 离线扫描, 网络代理, 跌倒检测, 软件物料清单, 通知系统, 静态分析