matthiasrohr/appsec-advisor

# appsec-advisor [](#) [](LICENSE) [](https://docs.claude.com/en/docs/claude-code) [](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) [](https://codecov.io/gh/matthiasrohr/appsec-advisor) `appsec-advisor` 是一款专为 AppSec 团队设计的 Claude Code 插件，以代码锚定威胁建模为核心。它将代码库转化为安全架构模型，识别信任边界和数据流，应用 STRIDE 方法论，并生成结构化的分析结果。 在相同的基础架构上，它还支持需求审计和开发者辅助工具（变更审查、pre-commit 指导、CI 门禁）。团队可以直接开箱即用，也可以根据自身需求进行定制，包括自定义需求、威胁上下文、预设配置、安全护栏以及带有公司品牌标识的打包方案。 ## 问题背景 威胁建模通常仍在研讨会、设计评审、发布门禁或审计中进行。这些评审活动非常有价值，但一旦具体实现发生变更，其结论很快就会过时。 大多数自动化安全工具侧重于实现层面的问题，例如存在漏洞的依赖项、不安全的代码模式、密钥泄露以及配置不当。它们极少能解释架构层面的风险：缺失信任边界控制、隐式的服务间信任、未认证的内部数据路径，或者控制权责不清晰。 这在代码扫描和手动架构审查之间留下了空白。威胁建模器正是 `appsec-advisor` 为填补这一空白而提供的解决方案。 ## 实现方法 威胁建模器将代码库作为安全架构审查的主要证据来源。 * **代码锚定的架构模型：** 架构、信任边界和数据流均从当前代码中读取，无需手动维护同步图表。 * **分阶段 Agent pipeline：** 专业的 Agent 将侦察、分析、分类和 QA 作为独立阶段运行，并受到共享 schema、契约和模板的约束。其输出是结构化且可验证的，而非自由格式的 LLM 文本。 * **基于目录的上下文：** 您的需求、历史威胁和相邻服务将作为分析的输入，因此分析结果会引用您实际配置的控制措施，而非通用的检查清单。 * **基于 Diff 的重跑：** 分析结果在多次运行中保持稳定的 ID，因此重新扫描能准确显示自上次运行以来发生的实际变更。 * **架构级审查：** 分析结果聚焦于信任边界、服务信任和未认证路径：这些正是代码扫描器容易遗漏的架构风险。 最终成果是一个可重复、具备代码感知能力的审查起点。它辅助进行架构层面的判断，但并不作为最终定论。需求审计和开发者辅助工具复用了相同的目录和 Agent 基础设施，将这一能力延伸至日常开发中。 ## 预期用途 `appsec-advisor` 专用于内部企业安全审查工作流。 AppSec 和安全架构团队负责管理插件配置、默认值、模板和审查策略。工程团队在设计工作、评审准备、重大变更或发布就绪检查期间运行威胁建模，并使用需求审计和开发者辅助工具进行持续的合规性检查和代码变更审查。 在威胁模型分析结果被用于指导发布决策、修复承诺、例外情况或正式的风险接受之前，必须由 AppSec 工程师或安全架构师进行验证。 ## 安全说明 **哪些数据会离开您的设备。** 仅限受分析组件的源代码、清单文件和配置，绝不包含整个代码库。在侦察输出中发现的密钥将被掩码处理。该插件需要访问 `api.anthropic.com`，无法在物理隔离（air-gapped）环境中运行；缓存的 prompt 片段将存储在 Anthropic 基础设施中，直至缓存 TTL 到期。 **报告如何生成。** 报告由确定性的 Python (Jinja) 脚本而非模型渲染生成，因此相同的输入必定产生相同的报告。中间产物均经过 schema 验证，并且在发布前拦截或掩码处理密钥，因此 `publish-threat-model` 绝不会暴露未经掩码的密钥。 ## 目录 - [快速入门](#quick-start) - [威胁建模器](#threat-modeler) - [需求审计](#requirements-audit) - [其他开发者工具](#additional-developer-tools) - [CI 集成](#ci-integration) - [插件开发检查](#plugin-development-checks) - [企业级部署](#enterprise-rollout) - [路线图](#roadmap) - [相关项目](#related-projects) - [贡献指南](#contributing) ## 快速入门 以下步骤将引导您生成首个威胁模型（即插件的核心工具）。需求审计和开发者辅助工具使用相同的设置流程，具体说明将在下文各自的章节中介绍。 本插件需要 [Claude Code](https://docs.claude.com/en/docs/claude-code)、Python 3.10+ 以及 `PATH` 路径下的 `git`。可选的 Node 依赖（`jsdom` + `mermaid`）可启用语法级别的 Mermaid QA 检查。请参阅 [威胁建模器](#threat-modeler) 文档。 插件只需注册一次，之后即可从您需要评估的代码库中调用。 目前，安装过程使用本地检出，而非打包发布的版本。这使得插件文件、prompts、schema 和脚本易于检查、修补或锁定版本，这对于仍处于测试阶段的项目非常实用。 ### 1. 注册本地插件检出 克隆此代码库，并在启用插件目录的情况下启动 Claude Code： ``` git clone https://github.com/matthiasrohr/appsec-advisor.git /path/to/appsec-advisor claude --plugin-dir /path/to/appsec-advisor ``` 在 Claude Code 中，输入： ``` /appsec-advisor: ``` 您应该会看到已注册的技能。 ### 2. 配置权限 首次运行威胁建模器之前，请合并插件所需的 Claude Code 权限： ``` /appsec-advisor:check-permissions --update ``` 此操作会检查并更新威胁建模 pipeline 使用的 Bash、Read、Write 和 Edit 操作的白名单，从而避免在较长时间分析的过程中出现频繁的权限提示。 ### 3. 运行您的首个威胁模型 在您需要分析的代码库中打开 Claude Code 并运行： ``` /appsec-advisor:create-threat-model ``` 威胁建模器会分析当前的 Git 代码库并将输出写入 `docs/security/`。由于报告可能包含漏洞详情，因此默认会被 git 忽略。 有关评估深度、成本控制、针对性扫描、参与者（actor）配置、代码库本地及跨代码库上下文的详细信息，请参阅 [docs/threat-modeler.md](docs/threat-modeler.md)。 ### 4. 可选步骤：发布威胁模型 生成的报告不会被自动提交。如果仅需本地评审，您可以在评估完成后直接停止操作。如果您的团队有意在 git 中跟踪经过审核的威胁模型，请运行发布辅助工具： ``` /appsec-advisor:publish-threat-model ``` ## 威胁建模器 `/appsec-advisor:create-threat-model` 从代码库中推导架构模型，并进行 STRIDE 分析以生成结构化的安全审查报告。 一次评估生成的报告将涵盖架构观察、信任边界、STRIDE 分析结果、风险分级威胁、受影响的组件、修复指南以及生成的架构图表。默认输出文件为 `threat-model.md` 和 `threat-model.yaml`；可选的导出格式包括 PDF、HTML、SARIF 和渗透测试任务列表。 **示例：** 针对采用 thorough（彻底）模式对 [OWASP Juice Shop](https://owasp.org/www-project-juice-shop/) 进行的扫描共产生 78 项发现，涵盖了 9 个组件（10 个严重，40 个高危，22 个中危，6 个低危），包含架构图、滥用案例链以及完整的缓解措施清单。 → [阅读完整示例报告](examples/threat-modeler/threat-model-juice-shop-thorough.md)  **→ 完整参考文档：[docs/threat-modeler.md](docs/threat-modeler.md)** 涵盖内容：输出格式、侦察阶段检查项、所有使用示例、评估深度与成本控制、代码库本地上下文（业务上下文、已知威胁）、跨代码库上下文、pipeline 架构，以及工作流命令（发布、导出、健康检查、运行恢复）。 ## 需求审计 `/appsec-advisor:audit-security-requirements` 根据内部的 AppSec 需求目录对代码库进行评估。它的速度比完整的威胁建模更快，适用于 PR 门禁、合规仪表板和审计准备。 ``` # 使用已配置的 catalog 运行 /appsec-advisor:audit-security-requirements # 使用 URL 独立运行（无需更改 config） /appsec-advisor:audit-security-requirements --requirements https://URL/appsec-requirements.yaml ``` `audit-security-requirements` 和 `create-threat-model` 的需求评估阶段均从 `skills/audit-security-requirements/config.json` 中的同一个 `requirements_yaml_url` 读取配置：只需配置一次，这两个命令即可自动生效。 还没有需求目录？您可以从内置的基线文件（`data/appsec-requirements-fallback.yaml`）开始，并根据您所在组织的标准进行编辑调整。一旦您拥有了在线需求页面（如 Confluence、Antora、静态 HTML），`scripts/harvest_requirements.py` 即可自动生成并更新 YAML 文件。 → [docs/harvester.md](docs/harvester.md) **→ 完整参考文档：[docs/security-requirements-audit-skill.md](docs/security-requirements-audit-skill.md)** 涵盖内容：状态值、目录设置、建立目录的三种途径、所有 flags，以及分析结果如何与威胁模型进行关联。 ## 插件配置 根目录下的 `config.json` 是用于安全默认值的已提交运行时配置。请使用 `config.local.json` 进行本地或内部覆盖；该文件会被 git 忽略，并在支持的情况下优先于 `config.json` 加载。 支持的根配置块包括 `external_context`（可选的 REST 业务上下文）、`pricing`（token 成本计算）、`logging`（详细的 hook 输出和日志轮转）以及 `organization_profile`（打包的组织配置文件指针）。在修改插件配置文件后，请运行 `python3 scripts/validate_config.py .` 进行检查。 ## 其他开发者工具 需求审计（`audit-security-requirements`）是一个由 AppSec 团队管理的合规门禁：它根据需求目录对代码库快照进行评分，并为仪表板、审计和发布门禁生成结构化报告。 下面列出的工具用途不同：它们是面向开发者的辅助工具，旨在为开发者在编写代码或处理未完成 diff 的过程中提供安全反馈。它们并不是审计制品。与需求审计类似，它们将配置好的需求目录作为当前标准；如果未配置，则回退到内置的基线标准。 | 工具 | 类型 | 范围 | 入口 | 适用场景 | |---|---|---|---|---| | [Security Coach hook](docs/dev-security-helper-usage.md#security-coach-hook) (*实验性*) | Hook | Prompt 阶段指导 | `APPSEC_COACH=1 claude --plugin-dir /path/to/appsec-advisor` | 在您编写安全敏感代码时，向 Claude 的上下文中添加安全指导。 | | [appsec-reviewer](docs/dev-security-helper-usage.md#appsec-reviewer-agent) (*实验性*) | Agent | 代码变更审查引擎 | `appsec-reviewer` | 将审查器嵌入到 Claude Code 或 Agent SDK 工作流中。 | | [verify-requirements](docs/dev-security-helper-usage.md#verify-requirements-skill) (*实验性*) | Skill | 交互式 diff 审查 | `/appsec-advisor:verify-requirements` | 从交互式的 Claude Code 会话中审查当前的、已暂存的或基础参考的变更。 | | [appsec-reviewer-cli](docs/dev-security-helper-usage.md#appsec-reviewer-cli) (*实验性*) | CLI | CI diff 审查 | `appsec-reviewer-cli review --diff origin/main --output security-review.md` | 在 CI 或其他自动化流程中，以无头模式运行相同的需求审查。 | 完整指南：[`docs/dev-security-helper-usage.md`](docs/dev-security-helper-usage.md) · 需求目录设置：[`docs/harvester.md`](docs/harvester.md) · Security Coach：[`docs/security-coach-skill.md`](docs/security-coach-skill.md)。 ### 报告 pipeline 错误 如果运行失败，请构建一份**已匿名化的**诊断数据包发送给维护者。 普通插件用户（非本地检出）请在失败的会话中运行该技能： ``` /appsec-advisor:report-error ``` 具有本地检出的开发者可以使用 Make 目标： ``` make diagnostic-bundle RUN=/docs/security # → appsec-diag-.tgz ``` 该数据包仅包含工具/插件版本、运行状态（达到的阶段、耗时统计、聚合计数）、仅限元数据的文件清单以及经过脱敏处理的日志。 它**绝不**包含威胁模型的结果、分析发现、证据或任何 源代码 —— 发送前请使用 `make inspect-bundle BUNDLE=appsec-diag-.tgz` 进行核查。 ## CI 集成 `scripts/run-headless.sh` 可在受评估代码库的 CI/CD pipeline 中 以非交互方式运行 `appsec-advisor`。它会调用与交互式运行相同的 Claude Code 插件技能，并透传退出状态码，以便后续 步骤能够基于此结果设置门禁。 ``` ./scripts/run-headless.sh --incremental --max-duration 1800 --max-budget 5 --sarif ``` 如需仅针对需求的更快的 CI 任务： ``` ./scripts/run-headless.sh --audit-requirements --save-report --max-budget 3 ``` 有关 GitHub Actions、GitLab、Jenkins 和 PR 门禁的示例，请参阅 [`docs/headless-mode`](docs/headless-mode.md)。 ## 插件开发检查 对于本插件代码库的变更，确定性测试套件是每个 PR 的安全保障。已提交的 GitHub Actions 工作流会在 Python 3.10、3.11 和 3.12 环境下运行配置验证、ruff 检查和 pytest。在本地，`Makefile` 封装了相同的检查逻辑： ``` make test # standard pytest suite with coverage (no LLM) make lint # ruff check + format check make check # continuous gate: lint, format, config validation, fragment-registry/drift, full test suite make release-check # release-boundary gate: `check` + version/tag/changelog consistency ``` 在对渲染器、schema、阶段 prompts、hooks 或 pipeline 控制流进行重大更改之后，请运行手动的完整端到端 (E2E) 检查： ``` make e2e-full # quick: pipeline, schemas, full deterministic QA, oracle make e2e-full-standard # also exercises Stage-3 QA make e2e-full-thorough # also exercises Stage-4 architect review make e2e-full-eval # fresh quick run plus adversarial semantic-quality gate make e2e-fixture-suite # all six external language/architecture recall oracles ``` 若需针对外部测试夹具套件进行本地回归测试，请使用手动测试夹具驱动程序： ``` ./scripts/e2e_fixture.sh --fixture python-threat-fixture --depth quick --clean-output ./scripts/e2e_cross_repo_fixture.sh --depth quick --clean-output ``` 通用的单一代码库驱动程序支持来自同级代码库 [`appsec-advisor-fixtures`](https://github.com/matthiasrohr/appsec-advisor-fixtures) 检出的 Spring、Python、Rust、Go、Node.js/TypeScript 和 Python/LangChain 测试夹具。这些 E2E 运行均为手动触发且为可选行为，因为它们会调用 Claude Code 并消耗 LLM 配额。请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)、[`docs/internal/runbooks/e2e-fixtures.md`](docs/internal/runbooks/e2e-fixtures.md) 以及 [`docs/internal/runbooks/e2e-cross-repo-fixture.md`](docs/internal/runbooks/e2e-cross-repo-fixture.md)。 ## 企业级部署 针对 AppSec 和平台团队：可将 `appsec-advisor` 视为上游的分析核心，将其封装在公司品牌的插件中，并推送给开发者。开发者只需运行一条命令，即可自动加载您的需求目录、预设和防护措施，无需开发者进行任何额外配置。 相较于通用插件，组织配置文件可为您提供以下优势： - 分析发现和审计评分将引用您内部的控制 ID 和严重性定义，而非通用的基线。 - **固定的成本限制。** Token 预算和最长持续时间已内置锁定，因此开发者不会意外执行不受限制的分析。 - 服务分类、监管范围和风险偏好由中央统一设定，而非每次运行单独设置。 - **一致的预设：** 评估深度、输出格式和 SARIF 导出项只需为整个组织配置一次。 - `package-policy.yaml` 锁定了可用功能范围，屏蔽了未经批准在内部使用的实验性技能或 hooks。 下图展示了以“Acme”作为您所在组织占位符的打包和分发流程。  初始化程序将引导您完成组织特定的必要设置，并创建一个可直接使用的打包代码库。 ``` $ bash <(curl -fsSL https://raw.githubusercontent.com/matthiasrohr/appsec-advisor-org-packaging-template/main/scripts/init-org-repo.sh) appsec-advisor — org packaging repo setup ──────────────────────────────────────────── This script creates a ready-to-use packaging repo for appsec-advisor. You will need: git, python3 (3.10+), make Organization name (e.g. Acme Corp): Secodis Organization id (short lowercase abbreviation, e.g. 'acme', 'hl' — used in plugin name) [s]: secodis Plugin name (Claude Code command prefix) [secodis-appsec]: Team owner (e.g. AppSec Team) [Secodis AppSec Team]: Target directory [./secodis-appsec-advisor]: Include demo content (example requirements + filled org profile)? [y/N]: ==> Cloning template from GitHub … Done. Your packaging repo is ready at: ./secodis-appsec-advisor ``` - 操作手册：[internal-plugin-packaging.md](docs/internal-plugin-packaging.md) · 配置文件：[org-profiles.md](docs/org-profiles.md) - 可运行的 CI 起始模板：[GitLab CI](examples/internal-packaging-gitlab) · [GitHub Actions](examples/internal-packaging-github) · 本地构建：[快速入门](docs/internal-plugin-packaging.md#quick-start) - 完整的打包代码库示例：[github.com/matthiasrohr/appsec-advisor-packaging-template](https://github.com/matthiasrohr/appsec-advisor-packaging-template) ## 路线图 已计划和正在进行的工作： - **针对真实应用进行验证。** 该插件正在越来越多的应用程序中进行测试——涵盖不同的技术栈、架构和部署模式——旨在强化 prompt 行为，提高输出一致性，并发现合成测试夹具无法覆盖的边缘情况。 - **将实验性技能升级为受支持状态。** 目前标记为*实验性*的开发者工具（`verify-requirements`、`appsec-reviewer`、`appsec-reviewer-cli`、Security Coach hook）正在进行加强，并将逐步过渡到受支持的生产就绪状态。 - **更好的打包与配置。** 提供更多方式来根据组织特定需求调整插件的技能。 - **更强的威胁聚焦。** 报告目前依然混合了架构观察、合规信号和 STRIDE 发现。即将到来的迭代将进一步强化威胁叙事，更清晰地区分威胁、弱点以及架构风险。 - **更丰富的上下文输入。** 目前 pipeline 几乎完全依赖于代码库本身。我们的目标是允许产品团队将更多上下文输入到评估中——目前仅支持 `docs/business-context.md`、`docs/known-threats.yaml` 和 `docs/related-repos.yaml`。 - **扩展以适应组件密集型代码库。** 分析功能涵盖了每一个组件，但组件数量超过约 8 到 10 个时，运行速度会变慢且成本增加。目前不会丢弃任何暴露的组件；正在进行的工作是如何提升大型代码库的分析速度。 - **多代码库扫描。** 按代码库扫描适用于 monorepo，但对于跨多个代码库的应用（如 API、IaC 等）则显得捉襟见肘。目前只能通过 `docs/related-repos.yaml` 进行部分覆盖。 - **引入现有的威胁模型（构想）。** 检测现有的模型（如 Threat Dragon 的 `threat-model.json`）并将其作为非权威上下文使用。 - **市场发布（构想）。** 一旦脱离测试阶段，计划将插件发布到 Claude Code 插件市场，实现一键安装。 ## 相关项目 - **[matthiasrohr/appsec-advisor-packaging-template](https://github.com/matthiasrohr/appsec-advisor-packaging-template)**：配套的模板代码库，用于构建包含您所在组织默认设置、需求目录和成本防护措施的内部 `appsec-advisor` 插件。 - **[davidmatousek/tachi](https://github.com/davidmatousek/tachi)**：软件项目的威胁建模辅助工具。它使用专门的 Agent 分析架构描述，并生成诸如 STRIDE 结果、攻击树、SARIF、风险评分数据、叙述性报告以及 PDF 报告等输出内容。 - **[mrwadams/stride-gpt](https://github.com/mrwadams/stride-gpt)**：一款 Streamlit 应用程序，可通过文本形式的系统或应用描述生成 STRIDE 威胁模型。它主要用于早期的设计探讨，也可生成缓解措施、攻击树、风险评分、测试用例以及 Markdown 输出。 - **[Claude Security](https://support.claude.com/en/articles/14661296-use-claude-security)** (Anthropic 推出，面向 Enterprise 套餐的公开测试版)：内置于 claude.ai 的漏洞扫描器，可扫描 GitHub 代码库中可利用的弱点，通过多阶段验证结果以减少误报，并将每个发现的结果链接到 Claude Code 会话以便进行补丁审查。它与 `appsec-advisor` 互为补充：Claude Security 更侧重于漏洞发现和修复工作流，而 `appsec-advisor` 则是一个更广泛的 AppSec 审查助手，涵盖代码库分析、威胁建模、架构观察、弱点识别和建议。 ## 贡献指南 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何提议变更、开发规范、测试套件、目标测试清单以及手动端到端测试。在可能的情况下，请在发送 pull request 之前开启一个 issue 以讨论您的想法。

标签：Claude Code插件, 云安全监控, 代码审查, 威胁建模, 安全架构, 网络安全研究, 逆向工具, 静态分析