scadastrangelove/agent-audit
GitHub: scadastrangelove/agent-audit
针对本地 AI 编码代理的取证审计工具和代码仓库指令表面扫描器，通过 296 条内置规则检测提示注入、工具投毒等已知威胁模式并生成结构化安全报告。
Stars: 5 | Forks: 1
B["Surface discovery
& parsing"] B --> C["Native + imported detectors"] C --> D["Normalization
clustering / aggregation / severity mapping"] D --> E["Outputs
reports / sidecars / security profile / verification"] ``` ## 安装 ``` git clone git@github.com:scadastrangelove/agent-audit.git cd agent-audit python3 -m venv .venv source .venv/bin/activate pip install -e . ``` 健全性检查： ``` agent-audit --help agent-audit packs ``` ## 使用方法 `agent-audit` 有两种主要的操作模式。 ### 模式 1：本地代理环境的取证审计 当您想检查本地代理主目录、会话日志、配置、 hooks 和跟踪记录以查找已知的不良行为时，请使用此模式。 典型场景： - 在可疑运行后审查 Claude Code 或 Codex 环境 - 检查代理是否写入了危险的配置、触及了机密，或 滑向了不安全的自主行为 - 生成经过验证的事件风格报告包 示例： ``` # 自动发现本地 agent 主目录并在读取前请求同意 agent-audit scan # 生成完整的报告 bundle agent-audit scan --output ./reports/forensic-run -y # 在扫描过程中请求 verifier 审查 agent-audit scan --output ./reports/forensic-run --verify -y # 显示可用的 detector packs / 捆绑规则 agent-audit packs agent-audit packs --all ``` 您将获得： - 来自日志、配置和指令文件的原始发现 - 用于审查和共享的优先验证报告包 - 可选的配置补丁建议 - 使用已配置的 LLM 后端进行的可选验证器重新检查 ### 模式 2：项目 / 代码库表面扫描 当您想审计包含 `SKILL.md`、`AGENTS.md`、 `CLAUDE.md`、插件清单、MCP 清单、工具描述或类似 指令表面的代码库时，请使用此模式。 典型场景： - 发布前审计您自己的技能代码库 - 复用前对第三方代理代码库进行分诊 - 出于研究、基准测试或回归 跟踪的目的扫描大量代码库 示例： ``` # 扫描单个 repo agent-audit scan-project ~/code/my-agent-repo # 扫描 repo 目录并写入输出 artifacts agent-audit scan-project ~/code/corpus --output ./reports/project-scan -y # 聚焦于单个导入的 pack agent-audit scan-project ~/code/corpus --tool atr agent-audit scan-project ~/code/corpus --tool cisco-promptguard # 降低噪声并仅保留较强的 findings agent-audit scan-project ~/code/corpus --min-severity high # 单独查看每个重复的 finding，而非集合级别的 rollup agent-audit scan-project ~/code/corpus --no-aggregate ``` 您将获得： - `project-findings.json` 和 `project-findings.md` - `clustered-findings.json` - `security-profile.json` - `files-of-concern.json` - `report-profiles.json` - 针对重复技能/模板模式的集合级聚合 `scan-project --output ./reports/project-scan` 的示例输出目录： ``` reports/project-scan/ project-findings.json project-findings.md clustered-findings.json security-profile.json files-of-concern.json report-profiles.json ``` ## 典型工作流程 针对维护者： 1. 发布前在您的代码库上运行 `scan-project`。 2. 检查 `project-findings.md` 和 `security-profile.json`。 3. 首先修复或缩窄最宽泛的指令表面。 4. 使用 `--min-severity high` 重新运行，作为更严格的发布关卡。 针对评估第三方代码库的用户： 1. 在您计划复用的代码库或语料库上运行 `scan-project`。 2. 首先查看聚类发现和集合级模式。 3. 将宽泛的外部操作、自主循环和信任边界扩展 发现作为审查优先级。 4. 如果代码库看起来可疑，请在安装/使用后 对实际的本地代理环境执行后续的 `scan`。 针对研究 / 语料库： 1. 使用 `scan-project` 扫描包含多个代码库的目录。 2. 将原始、聚类和聚合输出分开保存。 3. 使用 `corpus-lab` 进行回归快照和稳定性检查。 ## 签名来源 `agent-audit` 目前结合了： - **原生 ASAMM 检测器**，用于特定于代理的结构性缺陷，例如 未经批准的广泛外部操作、带有写入操作的自主循环，以及 持久性身份重写。 - **ATR (Agent Threat Rules)**，用于提示注入、代理操纵、 过度自主、技能妥协、工具投毒、上下文 渗透以及相关的以代理为中心的攻击模式。 - **Aguara 派生规则**，用于外部下载/安装信任边界 扩展、第三方内容摄取、SSRF-cloud 以及相关的远程 输入 / 远程执行表面。 - **Cisco PromptGuard 风格的规则**，用于 PII 收集、秘密模式、 markdown/data-URI 渗透以及相关的提示/输出滥用模式。 目前的内置数量为： - `233` 条 ATR 规则 - `37` 条 Aguara 派生规则 - `26` 条 Cisco PromptGuard 派生规则 - 在此基础上还有原生 ASAMM 检测器和项目特定的后处理 有关来源和 许可证详细信息，请参阅 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md)。 ## 为什么不直接运行一个上游包 使用多个来源很重要，但更大的价值在于 `agent-audit` 在它们周围所做的事情： - **感知表面的应用。** `scan-project` 不会盲目地对每个 文件进行正则匹配。它会对指令表面进行分类，例如 `SKILL.md`、`AGENTS.md`、 插件清单、MCP 清单、工具描述和任务 YAML，然后 仅应用相关的规则。 - **感知字段的过滤。** 旨在用于实时会话事件的规则不会 盲目地复用于扁平的代码库文本。这消除了在脱离上下文应用面向会话的包时 出现的大量误报类别。 - **原生特定于代理的逻辑。** 一些重要的问题是基于缺失或 结构性的，而不仅仅是词法上的。“未经批准的广泛操作”和 “持久性身份重写”就是这样的例子，在这些情况下，原生检测器增加了 原始导入签名无法很好提供的信号。 - **规范聚类和去重。** 不同的包通常描述 同一危险表面的不同方面。`agent-audit` 将原始的 规则命中聚类为由构件支持的问题实例，而不是将每次 触发视为单独的安全事实。 - **集合级聚合。** 当一个复制的技能模板触发 数百次时，该工具可以将其折叠为一个集合级 模式，而不是用几乎相同的发现淹没操作员。 - **严重性规范化和报告。** 导入的严重性和原生 检测器输出被规范化到一个报告层，然后以 原始、聚类和聚合视图的形式公开。 - **可选验证。** 可以使用外部或 本地 LLM 后端对发现进行重新检查，这在原始模式匹配存在噪声或 依赖于上下文时非常有用。 简而言之：上游签名提供成分；`agent-audit` 提供 使这些成分得以运作所需的、特定于代理代码库的执行模型、过滤、聚类和审查 工作流。 没有主动防御——每一步都带有同意提示的只读分析。 生成随时可供审查的配置补丁，但从不自动应用它们。 有关即将推出的内容，请参阅 [ROADMAP.md](ROADMAP.md)。 有关技术架构，请参阅 [docs/architecture.md](docs/architecture.md) ——流水线阶段、模块布局、如何添加检测器/ 表面/规则。如果您正在接手该项目，请从这里开始。 有关分阶段的 AST / tree-sitter / Rego 应用计划（v0.12 → v1.0）， 请参阅 [docs/ast-precision-plan.md](docs/ast-precision-plan.md)。 ## 发布历史 有关当前的发行说明，请参阅 [CHANGELOG.md](CHANGELOG.md)； 有关详细的研究阶段迭代历史，请参阅 [docs/HISTORICAL_CHANGELOG.md](docs/HISTORICAL_CHANGELOG.md)。
& parsing"] B --> C["Native + imported detectors"] C --> D["Normalization
clustering / aggregation / severity mapping"] D --> E["Outputs
reports / sidecars / security profile / verification"] ``` ## 安装 ``` git clone git@github.com:scadastrangelove/agent-audit.git cd agent-audit python3 -m venv .venv source .venv/bin/activate pip install -e . ``` 健全性检查： ``` agent-audit --help agent-audit packs ``` ## 使用方法 `agent-audit` 有两种主要的操作模式。 ### 模式 1：本地代理环境的取证审计 当您想检查本地代理主目录、会话日志、配置、 hooks 和跟踪记录以查找已知的不良行为时，请使用此模式。 典型场景： - 在可疑运行后审查 Claude Code 或 Codex 环境 - 检查代理是否写入了危险的配置、触及了机密，或 滑向了不安全的自主行为 - 生成经过验证的事件风格报告包 示例： ``` # 自动发现本地 agent 主目录并在读取前请求同意 agent-audit scan # 生成完整的报告 bundle agent-audit scan --output ./reports/forensic-run -y # 在扫描过程中请求 verifier 审查 agent-audit scan --output ./reports/forensic-run --verify -y # 显示可用的 detector packs / 捆绑规则 agent-audit packs agent-audit packs --all ``` 您将获得： - 来自日志、配置和指令文件的原始发现 - 用于审查和共享的优先验证报告包 - 可选的配置补丁建议 - 使用已配置的 LLM 后端进行的可选验证器重新检查 ### 模式 2：项目 / 代码库表面扫描 当您想审计包含 `SKILL.md`、`AGENTS.md`、 `CLAUDE.md`、插件清单、MCP 清单、工具描述或类似 指令表面的代码库时，请使用此模式。 典型场景： - 发布前审计您自己的技能代码库 - 复用前对第三方代理代码库进行分诊 - 出于研究、基准测试或回归 跟踪的目的扫描大量代码库 示例： ``` # 扫描单个 repo agent-audit scan-project ~/code/my-agent-repo # 扫描 repo 目录并写入输出 artifacts agent-audit scan-project ~/code/corpus --output ./reports/project-scan -y # 聚焦于单个导入的 pack agent-audit scan-project ~/code/corpus --tool atr agent-audit scan-project ~/code/corpus --tool cisco-promptguard # 降低噪声并仅保留较强的 findings agent-audit scan-project ~/code/corpus --min-severity high # 单独查看每个重复的 finding，而非集合级别的 rollup agent-audit scan-project ~/code/corpus --no-aggregate ``` 您将获得： - `project-findings.json` 和 `project-findings.md` - `clustered-findings.json` - `security-profile.json` - `files-of-concern.json` - `report-profiles.json` - 针对重复技能/模板模式的集合级聚合 `scan-project --output ./reports/project-scan` 的示例输出目录： ``` reports/project-scan/ project-findings.json project-findings.md clustered-findings.json security-profile.json files-of-concern.json report-profiles.json ``` ## 典型工作流程 针对维护者： 1. 发布前在您的代码库上运行 `scan-project`。 2. 检查 `project-findings.md` 和 `security-profile.json`。 3. 首先修复或缩窄最宽泛的指令表面。 4. 使用 `--min-severity high` 重新运行，作为更严格的发布关卡。 针对评估第三方代码库的用户： 1. 在您计划复用的代码库或语料库上运行 `scan-project`。 2. 首先查看聚类发现和集合级模式。 3. 将宽泛的外部操作、自主循环和信任边界扩展 发现作为审查优先级。 4. 如果代码库看起来可疑，请在安装/使用后 对实际的本地代理环境执行后续的 `scan`。 针对研究 / 语料库： 1. 使用 `scan-project` 扫描包含多个代码库的目录。 2. 将原始、聚类和聚合输出分开保存。 3. 使用 `corpus-lab` 进行回归快照和稳定性检查。 ## 签名来源 `agent-audit` 目前结合了： - **原生 ASAMM 检测器**，用于特定于代理的结构性缺陷，例如 未经批准的广泛外部操作、带有写入操作的自主循环，以及 持久性身份重写。 - **ATR (Agent Threat Rules)**，用于提示注入、代理操纵、 过度自主、技能妥协、工具投毒、上下文 渗透以及相关的以代理为中心的攻击模式。 - **Aguara 派生规则**，用于外部下载/安装信任边界 扩展、第三方内容摄取、SSRF-cloud 以及相关的远程 输入 / 远程执行表面。 - **Cisco PromptGuard 风格的规则**，用于 PII 收集、秘密模式、 markdown/data-URI 渗透以及相关的提示/输出滥用模式。 目前的内置数量为： - `233` 条 ATR 规则 - `37` 条 Aguara 派生规则 - `26` 条 Cisco PromptGuard 派生规则 - 在此基础上还有原生 ASAMM 检测器和项目特定的后处理 有关来源和 许可证详细信息，请参阅 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md)。 ## 为什么不直接运行一个上游包 使用多个来源很重要，但更大的价值在于 `agent-audit` 在它们周围所做的事情： - **感知表面的应用。** `scan-project` 不会盲目地对每个 文件进行正则匹配。它会对指令表面进行分类，例如 `SKILL.md`、`AGENTS.md`、 插件清单、MCP 清单、工具描述和任务 YAML，然后 仅应用相关的规则。 - **感知字段的过滤。** 旨在用于实时会话事件的规则不会 盲目地复用于扁平的代码库文本。这消除了在脱离上下文应用面向会话的包时 出现的大量误报类别。 - **原生特定于代理的逻辑。** 一些重要的问题是基于缺失或 结构性的，而不仅仅是词法上的。“未经批准的广泛操作”和 “持久性身份重写”就是这样的例子，在这些情况下，原生检测器增加了 原始导入签名无法很好提供的信号。 - **规范聚类和去重。** 不同的包通常描述 同一危险表面的不同方面。`agent-audit` 将原始的 规则命中聚类为由构件支持的问题实例，而不是将每次 触发视为单独的安全事实。 - **集合级聚合。** 当一个复制的技能模板触发 数百次时，该工具可以将其折叠为一个集合级 模式，而不是用几乎相同的发现淹没操作员。 - **严重性规范化和报告。** 导入的严重性和原生 检测器输出被规范化到一个报告层，然后以 原始、聚类和聚合视图的形式公开。 - **可选验证。** 可以使用外部或 本地 LLM 后端对发现进行重新检查，这在原始模式匹配存在噪声或 依赖于上下文时非常有用。 简而言之：上游签名提供成分；`agent-audit` 提供 使这些成分得以运作所需的、特定于代理代码库的执行模型、过滤、聚类和审查 工作流。 没有主动防御——每一步都带有同意提示的只读分析。 生成随时可供审查的配置补丁，但从不自动应用它们。 有关即将推出的内容，请参阅 [ROADMAP.md](ROADMAP.md)。 有关技术架构，请参阅 [docs/architecture.md](docs/architecture.md) ——流水线阶段、模块布局、如何添加检测器/ 表面/规则。如果您正在接手该项目，请从这里开始。 有关分阶段的 AST / tree-sitter / Rego 应用计划（v0.12 → v1.0）， 请参阅 [docs/ast-precision-plan.md](docs/ast-precision-plan.md)。 ## 发布历史 有关当前的发行说明，请参阅 [CHANGELOG.md](CHANGELOG.md)； 有关详细的研究阶段迭代历史，请参阅 [docs/HISTORICAL_CHANGELOG.md](docs/HISTORICAL_CHANGELOG.md)。
标签：AI Agent安全, AI代码审计, AMSI绕过, CISA项目, Claude Code, Codex CLI, DevSecOps, Go语言工具, GraphQL安全矩阵, IP 地址批量处理, MCP协议, OpenClaw, SCADA安全, TLS, 上游代理, 云计算, 人工智能安全, 代码安全, 合规性, 威胁检测, 安全合规, 安全扫描器, 恶意模式检测, 提示词注入检测, 文档结构分析, 本地大模型, 机器行为, 漏洞枚举, 算法安全, 网络代理, 网络安全, 规则引擎, 跨平台API, 逆向工具, 错误基检测, 防御工具, 隐私保护, 零日漏洞检测, 静态代码分析