Security Recipes

security-recipes.ai

搜索 CVE。使用 AI Agent 修复漏洞。 事实均有来源，修复范围明确，每项计划都附带验证、回滚和停止条件——这是网站的承诺，也是本仓库的承诺。

security-recipes.ai 是一个 Eleventy 网站，提供有来源依据的 CVE 情报和经证据门控的漏洞修复内容，供 AI Agent 使用，同时不赋予它们部署或生产环境权限。

本项目有意聚焦于以下内容：

• 持续更新的完整中危／高危／严重级别 CVE 数据库，
• 经证据验证的规范 CVE 修复记录，
• 实用的安全修复方案，
• 提示词和规则文件示例，
• Agent 设置指南，
• MCP 集成模式，
• 一个可选的只读 MCP 服务，用于搜索方案和获取经批准的上游 MCP 上下文，
• 一个可复用的 GitHub Action，可将这些指南转化为可切换的 CI 健康检查。

它不是扫描器、工单系统、SOAR 平台、部署工具或定制安全工具包。现有安全工具应负责生成发现结果；本网站帮助 Agent 使用恰当的修复上下文，并在适当的时候停止。

如需查找具体漏洞，请从在线的 CVE Database 开始；如需了解从证据到补丁的工作流，请查看 AI Vulnerability Remediation Playbooks。针对特定 Agent 的指南涵盖 Codex、Claude Code、Cursor、GitHub Copilot、Devin、Shiba Studio、Hermes Desktop 和 OpenClaw。 Visual Guide 展示了从来源验证和搜索发现，到有界计划、验证、回滚和人工审查的完整流程。 如果要解决的是保护 Agent 系统的身份、工具、连接器、上下文、记忆、运行时和恢复控制这一不同问题，请使用 AI Agent Security。

当前产品和工作流

合格搜索发现

完整目录仍可搜索，而公开的规范 CVE 页面仅收录经过审核或符合证据要求的记录。这些页面提供唯一的搜索元数据、服务器渲染的核心事实和受影响版本证据、一项修复权威来源（优先采用稳定且经过审核的指导，否则采用完整且关联来源的 AI 补充内容）、一条须经批准的简短 AI 实施提示词、规范 URL、面包屑，以及 Article/TechArticle 结构化数据。CVE 数据库将目录描述为 Dataset；修复支柱则将其可见的七步工作流标记为 HowTo。按年份划分的 CVE 站点地图仅包含可编入索引的规范路由；若站点地图一致性、规范归属、爬取可达性、元数据限制或同源链接发生偏差，构建就会失败。

批量模板化的方案子页面也不会被编入索引。72 个开发代码卫生方案和 39 个生成式合规框架方案仍可从其规范中心浏览，并设置 noindex,follow，因为它们采用相同的方法。受限的渲染正文相似度门槛会阻止子页面重新进入站点地图，除非其证据、示例和测试存在实质性差异。中心仍可编入索引，并提供共享的发现背景信息。

发布包含 SEO 内容的版本后，公开修订版本必须与合并提交一致，之后才能提交站点地图或检查 URL。 Caddy 部署指南 介绍了经 DNS 验证的 Search Console 移交流程、优先级实时 URL 检查、站点地图提交、索引请求和查询监控。提交内容仅用于提示搜索引擎发现内容，并不保证内容会被编入索引或获得特定排名。

修复支柱还记录了一个公开的代码仓库示例： brace-expansion 中的 CVE-2026-13149。 它将仅涉及依赖项的更改与 经审核的拉取请求、 测试、公告证据和恢复路径关联起来，同时明确区分同一 PR 中无关的 Fail2Ban 工作。

从 CVE 搜索到规范记录	从 CVE 证据到有界 Agent 计划
证明与人工审核	只读 MCP 上下文

本项目的用途

AI 编码 Agent 可以帮助解决安全问题，但其工作范围必须明确： 一个问题、一项方案、一份经审核的输出。

security-recipes.ai 帮助团队解答以下问题：

• 哪项方案适用于这个问题？
• Agent 应使用哪条提示词？
• 我应将 Copilot、Claude、Cursor、Codex 或 Devin 的指令放在哪里？
• Agent 应读取哪些 MCP 服务，以获取公告、扫描器、代码仓库或运行手册上下文？
• 在审查者信任 PR 或分诊说明之前，其中应包含什么？

交付内容

• Eleventy 文档站点（静态构建速度快，无需 Go 工具链）。
• 以 CVE 为先的观测站主页和以数据为先的 CVE 数据库。
• 依赖项、SAST、敏感数据、基础镜像、CVE 和默认加固修复方案的指南中心。
• CVE 情报接收策略、提示词、测试样例和评估器，用于在 Agent 打补丁前对公告信号进行路由。
• 完整的滚动十年 Medium/High/Critical CVE 目录，由通过完整性验证的 NVD JSON 2.0 Feed、CISA KEV 元数据和所有适用的 vetted 修复方案原型构成。只有经审核的 stable Markdown 页面会覆盖这一保守基线。
• 经过完整性哈希验证的搜索许可名单，仅为经审核的 stable Markdown 页面或通过确定性“可用于配方”证据契约的 AI 增强内容发布规范的 CVE 页面。即使某条记录不符合搜索索引条件，仍可搜索完整数据库。
• 面向目录中每个 CVE 的版本化七阶段 Agentic 变更契约：发现、评估、缓解、修复、验证、回滚和分诊。每项操作都会声明可能涉及的文件目标、变更和审批边界、所需证据、输出及失败行为，不会猜测补丁或固定版本。
• 涵盖 39 种安全、隐私、保障、韧性和软件供应链框架的结构化合规库，不复现受许可保护的控制文本。框架中心是搜索入口；模板化的子评估页面在内容有所区分之前保持 noindex,follow。
• 包含 72 个代码卫生配方的库，涵盖跨语言及特定生态系统的审计、修复、验证和停止条件工作流。其开发子页面在正文共用生成模板期间保持 noindex,follow。
• 保留现有提示词集合的配方。
• 面向 GitHub Copilot、Claude、Cursor、Codex 和 Devin 的 Agent 设置指南。
• 面向公共安全数据源和组织批准的安全数据源的 MCP 集成指南。
• 位于 mcp_server.py 的可选只读 FastMCP 服务，支持配方搜索、检索和选择加入的上游 MCP 上下文。
• 用于本地或 droplet 托管的 Docker 和 Docker Compose 配置。
• 用于站点维护、验证、导入和部署的辅助脚本。

仓库结构

路径	用途
content/	配方、文档、修复指南和 Agent 设置页面。
eleventy.config.js	站点构建配置（永久链接、Feed、标签页面）。
_includes/	页面布局：文档界面和独立主页。
lib/	构建模块：短代码移植、JSON Feed 构建器、SEO head。
assets/	站点 CSS 和 JavaScript，用于配方浏览器、导航和辅助工具。
static/	图像、徽标、架构和静态资源。
static/api/cve-catalog/	完整的分片式 CVE 目录、按年份分区的机器索引、压缩的浏览器搜索索引、来源清单和原型。
data/cve/	人工审核的修复方案原型、确定性 AI 增强缓存和生成配方所有权台账。
data/compliance-frameworks/	结构化合规框架目录和来源注册表。
data/code-hygiene/	结构化代码卫生目录、来源注册表和路由测试样例。
docs/	仓库文档和旧版截图资源；当前 README 和视觉指南图像位于 static/images/。
mcp_server.py	可选只读 MCP 服务，用于配方搜索和经批准的上游 MCP 上下文。
mcp-server.toml.example	MCP 服务配置模板。
Dockerfile	站点镜像。
Dockerfile.mcp-server	可选 MCP 服务镜像。
docker-compose.yml	生产风格的本地栈。
scripts/	用于维护和部署的辅助脚本。

核心内容领域

• CVE Database：来源可靠的 CVE 情报、受影响版本证据和权威修复记录。
• AI Vulnerability Remediation： 通过证据门控的操作手册，帮助从单条发现到经过审查的补丁或分诊说明。
• AI Agent Security： 面向 AI Agent 系统自身的威胁建模、生产基线、来源边界、控制路由、 证据和事件响应准备。
• Quick Start：从单条发现到一份 经过审查的 PR 或分诊说明。
• AI Agent Comparison：针对 Copilot、Claude Code、Cursor、Codex 和 Devin，介绍经过验证的 运行模式、原生指令、预期产物、先决条件和审查关卡。
• Recipes：可复用的提示词、 指令、规则、技能和审查清单。
• MCP Integration：如何安全地连接 安全上下文。
• Visual Guide：通过五张图示，展示合格的 搜索发现、CVE 到计划、验证、回滚、审查和只读 MCP 流程。
• Docs：网站使用方法、Agent 使用模式 和贡献指南。

Python 修复工具

Python 工具套件是文档的可选执行伴侣。它可以检查范围受限的工作区，选择 75 个修复操作手册中的任意一个，创建持久化运行数据包，记录带完整性哈希的证据，并在交接给 Agent 或审查者之前验证数据包。它始终在本地运行且保持谨慎：不会自行合并代码、部署更改或调用外部系统。

python scripts/security_recipes_remediation_suite.py playbook list
python scripts/security_recipes_remediation_suite.py playbook inspect \
  --playbook vulnerable-dependencies --workspace .
python scripts/security_recipes_remediation_suite.py playbook start \
  --playbook vulnerable-dependencies --workspace . \
  --finding finding.json --run-dir .security-recipes/runs/dependency-fix
python scripts/security_recipes_remediation_suite.py playbook verify \
  --run-dir .security-recipes/runs/dependency-fix

仓库还包含面向特定领域的生成器和评估器，用于需要更丰富证据包或运行时策略决策的操作手册。即使没有 Python，网站和 JSON 注册表依然有用；这些工具则让 CI、编排器和获准的编码 Agent 可以直接执行同一套工作流约定。

值得了解的部署辅助工具：

• scripts/setup_digitalocean_droplet.sh：Ubuntu Droplet 引导设置，包含 Docker、主机加固，以及可选的由 Caddy 管理的 HTTPS。
• scripts/configure_nginx_letsencrypt.sh：为希望使用 nginx 而非 Caddy 配置 Let's Encrypt 的团队设置主机 nginx 反向代理。
• README.nginx-letsencrypt.md：面向运维人员的 nginx 部署路径指南。

推荐的运行模式：

1. 让现有的 SCA、SAST、机密信息、CI、云和工单系统生成发现结果。
2. 附上匹配的 security-recipes.ai 操作手册和提示词。
3. 仅允许 Agent 读取处理该发现所需的文件和 MCP 上下文。
4. 合并前要求进行测试和人工审查。
5. 初期流程中不要加入广泛自动化、写入权限和部署操作。

指南手册与执行工具

该网站是修复工作的指南手册，包含操作手册、提示词、Agent 设置、MCP/API 集成说明和审查模式。运行时自动化应放在用户获准的 Agent 宿主、CI 系统、工单工作流或扫描器平台中，而不是由网站托管的聊天机器人中。

scripts/、tools/ 和 mcp_server.py 中的 Python 工具为维护者和可自托管用户提供支持，包括操作手册执行数据包、证据验证、特定领域的评估与生成、验证、公告导入、配方搜索，以及可选的只读 MCP 访问。

可选 MCP 服务

MCP 服务默认只读。其基本作用是让兼容 MCP 的 Agent 搜索和检索操作手册。可自托管部署也可以将其配置为获准的上游 MCP 服务的上下文中枢，而无需将这些凭据放入公开网站。 检索到的上下文不会授予变更权限。任何能够更改代码仓库、工单、密钥、部署或生产系统的连接器，都必须由调用方主机单独配置并批准。

常用工具：

• recipes_search
• recipes_list
• recipes_get
• recipes_cve_catalog_info
• recipes_cve_search
• recipes_cve_get
• recipes_match_finding
• recipes_playbooks_list
• recipes_playbook_get
• recipes_playbook_plan
• recipes_mcp_upstream_servers
• recipes_mcp_upstream_tools
• recipes_mcp_upstream_call
• recipes_mcp_upstream_context

MCP 服务同时支持以下两种生成的配方数据源：

• /api/recipes.json 是首选的 Agent 数据源，包含类别、严重性、CVE/GHSA、生态系统和交接元数据。
• /recipes-index.json 仍受支持，供旧版使用者使用。
• /recipes-browser.json 是精简的交互式库数据源。/recipes/ 页面会在服务端渲染 18 张可供爬取的配方卡片及完全匹配的水合种子数据，然后仅在访客聚焦搜索框、筛选、排序、访问经过筛选的 URL 或加载更多内容时请求完整数据源。

完整的 CVE 目录也可在不使用 MCP 的情况下获取：

• /api/cve-catalog/manifest.json 声明精确的日期和严重性策略、源哈希、覆盖数量及分片清单。
• /api/cve-catalog/runtime-summary.json 是小型浏览器引导文件，包含覆盖总量，以及每个运行时资源基于内容生成的缓存版本。
• /api/cve-catalog/index.json 是 /api/cve-catalog/indexes/ 下完整发布年份分区的小型清单。离线使用方可以只获取所需年份；浏览器页面加载和精确 MCP 查询都不会解析这些分区。
• /api/cve-catalog/search 是受限的同源广泛搜索端点。它固定使用 runtime-summary.json 中声明的分片集修订版本，由 nginx 限速，最多返回 100 条预览。生产 MCP 镜像通过只读 SQLite FTS 数据库提供该端点；该数据库根据同一份清单构建，并经过整文件验证。仅输入 Focus 或不完整的 CVE-YYYY-NNNN 标识符时，不会发起搜索请求。
• /api/cve-catalog/records/{cve} 是受限的同源精确记录端点。每个请求都会固定使用分片集修订版本，且 MCP 服务只验证并打开包含该 CVE 的单个确定性分片。当前浏览器使用此端点，而不是获取分片命名空间。
• 当较旧的运行时摘要未声明搜索和记录 API 时，/api/cve-catalog/browser-index.json.gz 仍会保留一个兼容窗口。当前浏览器在已声明这些 API 时不会下载此文件，因此访问者不再承担完整语料的传输或内存开销。
• 规范 CVE 页面会在服务器端渲染其概览、受影响版本证据、选定的修复权威来源、AI 实施与验证交接信息、来源、溯源信息、引用和架构。页面不会嵌入或水合目录应用。页面仍提供指向精确 gzip JSON Lines 分片的精简链接，以便机器读取溯源信息，同时不增加浏览器请求。
• /api/cve-catalog/search-indexable.json 是一份经过完整性哈希校验的精简允许列表，用于规范 CVE 页面、相关 CVE 链接和搜索发现。其策略仅接受经过审核的稳定 Markdown，或通过确定性配方就绪证据契约的完整 AI 增补内容。每条浏览器搜索结果都会链接到本地 /cve/<ID>/ 记录。允许列表中的记录会生成为可供索引的静态页面；其他所有记录则使用受限的运行时渲染器，设置 noindex,follow，并在记录中保留其官方 CVE.org 来源。
• /api/cve-catalog/archetypes.json 包含经过审核的修复契约，用于为每条目录记录组合保守的修复方案。它还包含版本化的 Agentic 操作架构，以及浏览器和 MCP 服务共用的生态系统特定文件目标提示。
• 每个分区都将范围内的所有 CVE 映射到经过完整性哈希校验的压缩 JSONL 分片。分片记录包含 CVSS、CWE、受限 CPE、引用及 KEV 溯源信息，供精确 CVE 查询使用。
• 为限制记录大小，每个分片最多存储 12 行存在漏洞的 CPE/版本信息，同时提供来源匹配总数和明确的截断标志；设置该标志时，使用方必须参阅 NVD/供应商证据。

规范 CVE 页面使用同一组主参考来源来生成可见的来源列表和结构化数据引用。原始生成的记录允许包含 NVD、CVE.org、范围明确的 CISA KEV 记录，以及附有来源链接的供应商公告、补丁、发行说明或缓解措施；失效链接、仅第三方来源、仅利用漏洞的信息，以及通用漏洞数据库链接不会自动提升为参考来源。经过审核的稳定 Markdown 可以在其 References 部分有意引用其他 HTTPS 证据。当修复涉及多个受支持的分支或产品系列时，展示的操作会保留所有可信的修复版本声明，而不会将指导简化为一项不完整的升级。 在纯静态构建中，开发阶段及目录维护的稳定版 CVE Markdown 不会生成独立页面，也不会纳入 Eleventy 和通用配方/搜索源、标签页、RSS 或站点地图。目录建立前的 3 个历史稳定版配方仍会作为普通内容渲染。 生产环境可通过 nginx 和 MCP 支持的落地页服务，将旧版配方 URL 保留为指向规范 CVE 路由的重定向。要进行完整发现，请使用专用目录或 recipes_cve_* MCP 工具。

浏览器的精确 ID 路径和固定修订版本的搜索 API 涵盖清单声明的所有范围内 Medium、High 和 Critical 记录。MCP 服务通过 recipes_cve_search 提供同样由 SQLite 支持的覆盖范围；成功调用 recipes_cve_get 后，会返回规范化的源记录、源标识符和引用、适用的原型、组合式修复合约，以及独立完整的 agentic_change_plan。该计划会将每项缓解措施和修复指示扩展为有序的代码/文件操作，并附上验证、回滚、证据、审批和分类要求。当源匹配集超出有界记录的范围时，计划也会保留明确的 CPE 截断元数据。

每日 CVE 同步与可选 AI 丰富处理

.github/workflows/cve-catalog-sync.yml 每天在 09:23 UTC 运行，也可手动触发。它会验证并合并 NVD JSON 2.0 年度源文件和 CISA KEV 目录，重新生成所有目录索引/分片，验证结果，按依赖顺序刷新从配方派生的确定性证据，运行目录测试，并向默认分支创建或更新 automation/cve-catalog-sync 拉取请求。 首次发布拉取请求前，仓库的 Settings > Actions > General > Workflow permissions 必须允许 GitHub Actions 创建拉取请求。

将 CVE_AUTO_MERGE_ENABLED=true 设为启用后，安全审批通过的目录拉取请求会在其确切头部修订版本通过专用验证工作流后发布。配置 CVE_AUTOMATION_APP_CLIENT_ID 和 CVE_AUTOMATION_APP_PRIVATE_KEY 密钥后，工作流会优先使用该 GitHub App 身份，以便正常触发拉取请求和主分支上的 Build 运行。没有 App 凭据时，工作流仍会自动运行：通过保护措施完成 GITHUB_TOKEN 合并后，它会验证返回的合并 SHA 仍是当前 main，然后以该确切 SHA 分派实际的 build.yml 工作流。生产部署门禁只认可符合 CVE 条件的 Build 分派，因此定时监控和无关的手动工作流既不会造成死锁，也无法满足发布条件。

源同步不需要密钥。目录丰富处理默认通过现有的 XAI_API_KEY Actions 密钥使用 xAI grok-4.7。一个仓库变量 CVE_ENRICH_MODEL 用于选择提供商和模型。剩余黄金数据审查、内容刷新、AI 维护、AI 问题维护，以及此仓库的安全健康操作仍通过 XAI_API_KEY 使用 Grok。

gh secret set XAI_API_KEY --repo stevologic/security-recipes.ai
gh secret set OPENAI_API_KEY --repo stevologic/security-recipes.ai

目录工作流默认使用 grok-4.7，且每次运行最多处理 20 条新增或源数据已更改的记录。定时队列根据受版本控制的 NVD/CISA 目录生成：候选记录必须包含有效且带标签的供应商公告、补丁、发行说明或缓解措施 URL。源数据完整的记录仍符合条件，因为这些记录仍需要基于来源合成修复方案；在每个 KEV 和严重性区间内，这类记录优先于存在确定性来源缺口的记录，其后依次按受影响产品/版本证据和新近程度排序。这会使用现有的每日请求额度，无需额外手动运行。 模型和数量上限可通过可选的 Actions 变量更改；丰富处理数量硬性限制在 0 到 50 之间：

gh variable set CVE_ENRICH_MODEL --body "grok-4.7" --repo stevologic/security-recipes.ai
gh variable set CVE_ENRICHMENT_LIMIT --body "20" --repo stevologic/security-recipes.ai

CVE_ENRICH_MODEL 是唯一的开关。grok-* 使用 xAI 和 XAI_API_KEY。 gpt-* 使用 OpenAI 和 OPENAI_API_KEY。以后切换到 Daybreak 时，只需将该 变量改为 gpt-6-sol+daybreak_blue。workflow_dispatch 输入项 daybreak_probe=true 会为当前配置的提供方发起一次探测调用，并跳过目录同步。

AI 输出是补充信息，并会明确标注。它使用严格的结构化输出，只引用 Responses API 网络搜索来源记录中实际返回的 URL，并以可复现的方式存储在 data/cve/ai-enrichments.json 中。只有当单独的审核关卡确认，受影响产品、暴露情况、修复措施和验证方面的每项声明都有与某个已标记可信公告参考的确切 URL 关联的证据时，完整的增强结果才会成为特定 CVE 的 Markdown 草稿。每项必需声明都必须单独满足该规则，并且每份生成的修复方案都必须包含有引用依据的、明确的修复版本声明。

缓存的增强结果会重新评估，而不会永久沿用：达到可生成修复方案条件的条目在 30 天后成为刷新候选项，KEV 条目在 60 天后成为刷新候选项，其他完整但不够具体或证据不足的条目在 180 天后成为刷新候选项。手动优先处理的 CVE 会在现有请求上限内强制刷新。如果刷新失败，上一次有效的缓存结果仍会保留；来源指纹无效时则会继续按失败关闭处理。同步报告和自动化健康摘要会显示待刷新的条目数以及手动优先处理的条目数。

符合条件的草稿会写入 maturity: development 文件，文件名为 content/recipes/cve/ai-enrichment-cve-*.md。这些文件不会被通用修复方案发现流程纳入，也不会覆盖稳定的已审核修复方案。人工审核者可以将 ai_enrichment_review_status: human-reviewed-development-draft 设为保留其他方面已符合证据要求、但不应公开作为修复依据的增强结果，也可以将 ai_enrichment_review_status: approved-for-ai-authority 设为批准其用于此目的。未添加标注的生成器拥有的草稿仍受自动证据关卡约束，而稳定 Markdown 始终优先。data/cve/ai-generated-recipes.json 中的所有权记录会记录每个生成文件的哈希值；自动化只能刷新或删除哈希匹配且未被修改的草稿。人工编辑，或同一 CVE 已存在任何人工编写的开发版或稳定版修复方案，都会使该 Markdown 文件归人工所有，并阻止自动替换。AI 生成不会更改来源 CVSS/KEV 事实、受影响版本数据、原型选择或已审核的稳定 Markdown。缺少密钥、API 拒绝、超时或速率限制不会阻止 NVD/CISA 刷新；连续失败达到三次或运行预算达到 15 分钟后，调用即会停止，并保留有效的缓存增强结果。手动运行可以优先处理指定的 CVE，但这些 ID 会占用该次运行现有上限内的名额，且绝不会绕过修复方案就绪所需的证据关卡：

gh workflow run cve-catalog-sync.yml --ref main \
  -f ai_enrichment_limit=20 \
  -f priority_cve_ids="CVE-2026-58644,CVE-2026-56164"

手动调度会额外触发一次工作流运行，因此可能产生额外请求；每日确定性队列无需手动运行。在非默认分支上手动运行时，会将增强缓存、所有权记录和生成的草稿作为短期工作流构件上传，以便审核。

.github/workflows/leftover-review.yml 每天在 13:17 UTC 运行，并根据 GitHub Advisories 和 NVD 对 leftover-gold CVE 项目中的遗漏项进行实时验证。优先处理 leftover-gold 中的严重和高危项。处理完这些项目后，每次运行最多审核 25 个 leftover-gold 中危和低危页面，将已完成的 ID 记录在 data/cve/leftover-review-state.json 中，并创建带标签的自动合并 PR。leftover-review 作业使用 Grok Build CLI 和 XAI_API_KEY；如果缺少该密钥或 leftover-gold 队列为空，则不执行任何操作。

运行时路径经过刻意限制，以应对目录规模的流量：

• hub 从精简版运行时摘要启动；精确查询调用固定版本的同源记录 API；只有在明确表达搜索意图后，才会调用搜索 API 搜索标题、产品、厂商和筛选条件；
• 广泛搜索最多从不可变、只读的 SQLite 中返回 100 条预览，HTTP 边界为 3 秒，并且绝不会在访客进程或浏览器主线程中解码完整目录；
• 精确记录服务每个请求验证并打开一个分片；MCP 精确检索使用相同的仅分片路径，而非精确文本搜索则通过专用执行器、有界准入队列、查询截止时间和 nginx 速率限制，使用由清单固定的 SQLite 数据库；
• 不可变的浏览器缓存键来自声明的记录／搜索契约、原型哈希和分片集修订版本，而不是上游时间戳。

已实现的构建边界、精确分片交付模型、基于证据的 SEO 策略、SQLite 搜索运行时，以及尚待完成的制品发布迁移，均记录在 CVE scale architecture 中。

生产镜像会在其缓存镜像层中构建一次 SQLite 制品，记录独立的 SHA-256 校验和旁文件，并在启动时验证架构、目录修订版本、记录数、清单摘要、文件摘要及代表性 FTS 索引条目。RECIPES_MCP_EAGER_CVE_SEARCH 现在仅适用于未配置 SQLite 路径时的旧版本地回退。对于持续的搜索流量，请运行多组配对的 MCP 实例；精确分片读取仍与有界文本搜索执行器及队列隔离。

更改站点标识后，运行 npm run icons。该命令会重新生成不透明的 Apple 触控图标，以及生产性能门禁所检查的 192／512／可遮罩安装应用资源。

生产构建会预压缩大型 JSON／XML 订阅源，以供 nginx gzip_static 使用；同时验证稳定版／草稿版发现边界，并通过 npm run check:performance 强制执行负载／文件数量预算。

使用 Docker 运行：

docker build -f Dockerfile.mcp-server -t security-recipes-mcp .
docker run --rm -p 8123:80 security-recipes-mcp

将 MCP 客户端连接到：

http://localhost:8123/mcp

使用 Python 在本地运行：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-mcp-server.txt
python mcp_server.py

Windows PowerShell 激活：

.\.venv\Scripts\Activate.ps1
python mcp_server.py

在本地运行站点

先决条件：

• Node.js >= 20
• Python >= 3.10，并已安装 requirements-mcp-server.txt，用于生产环境 npm run build 的 CVE 预渲染步骤
• Git

python -m pip install -r requirements-mcp-server.txt
npm install
npm run serve

打开：

http://localhost:8080

npm run serve 会监视更改并增量构建。一次性生产构建命令为 npm run build（输出写入 public/）。构建会先执行 Python／依赖预检，再删除现有输出，随后使用与 MCP 运行时相同的 CVE 渲染器。Eleventy 不会通过 passthrough 复制 static/api/cve-catalog/：页面生成后，有界的构建后步骤会检查链接、孤立文件、不安全路径，以及清单字节数／哈希是否匹配，之后才会安装该目录子树。目录之外的静态资源（包括根目录点文件）仍按常规 passthrough 方式处理。

如需单独构建目录，请将 SECURITY_RECIPES_CVE_CATALOG_ROOT 设置为其绝对发布目录。Eleventy 数据、限定页面生成以及经过验证的目录复制都会使用同一根目录。npm run serve 不会重新运行页面生成器或目录复制，因此若要在开发服务器中获取规范的 /cve/<ID>/ 页面和目录 API 树，请先运行一次 npm run build；后续增量构建会保留这些构建后生成的输出。

Docker Compose

创建环境文件：

cp .env.example .env

启动整套服务：

docker compose up -d --build

使用 Docker Compose v2 插件（docker compose）。此服务栈不支持旧版 Python docker-compose v1 软件包；在较新的 Docker Engine 版本中，查看日志时它可能因 KeyError: 'id' 崩溃，或在重新创建容器时因 KeyError: 'ContainerConfig' 崩溃。

在 Ubuntu/Debian 主机上，安装 Compose v2 和兼容性垫片：

sudo bash scripts/install_docker_compose_v2.sh

默认路由：

site: http://127.0.0.1:8080/
agent recipe feed: /api/recipes.json
MCP endpoint: /mcp

Compose 服务栈将公共站点及其动态 CVE/MCP 渲染器配成对应的蓝绿组合：

• security-recipes / mcp-server-blue：蓝色站点和渲染器。
• security-recipes-green / mcp-server-green：绿色站点和渲染器。
• mcp-server：过渡期单例，保留用于首次成对部署以及向后兼容的手动 Compose 工作流。它读取本地构建的站点数据源 http://security-recipes/api/recipes.json，因此分支或 Droplet 会提供自身的食谱，而不依赖公共生产索引。

deploy.sh 会先启动已撤出流量的槽位中的 MCP 容器并验证其版本，再启动该槽位的站点容器；它会直接验证一个规范 CVE，之后才将这一对服务接入 Caddy。手动启动 Compose 时仍默认使用单例，以确保首次部署与之前安装的脚本兼容。

如果使用 nginx 或 Caddy 反向代理并通过 Let's Encrypt 获取证书，请让 Docker 仅绑定回环地址，并由代理占用公共端口 80 和 443：

SECURITY_RECIPES_HTTP_PORT=127.0.0.1:8080

然后将代理指向：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

如果你想使用一套开箱即用的主机 nginx + Let's Encrypt 配置，请运行：

sudo bash scripts/configure_nginx_letsencrypt.sh \
  --domain security-recipes.ai \
  --email [email protected]

完整的运维指南见 README.nginx-letsencrypt.md。

DigitalOcean Droplet

对于全新的 Ubuntu Droplet，请使用辅助脚本：

sudo bash scripts/setup_digitalocean_droplet.sh \
  --domain security-recipes.ai \
  --email [email protected]

该脚本会安装 Docker/Compose、配置受限的应用用户、启用基本的主机加固、启动 Compose 服务栈，并可在前端配置 Caddy 以启用 HTTPS。它还会启用一个适配 Caddy 的 Fail2Ban 监狱：同一客户端在五秒内针对高置信度漏洞探测路径（例如 .env、Git、WordPress、phpMyAdmin 或 PHPUnit 探测）收到五个最终 HTTP 404 响应后，其地址将被封禁，无法访问该站点的 TCP 和 HTTP/3 端口，封禁一小时后会自动恢复访问。普通的缺失页面、类似 CVE 的无匹配项和归档分页无匹配项不会计入封禁额度。

设置前，请将 apex 和 www 两条 DNS 记录都指向 Droplet。托管的 Caddy 会为这两个名称获取证书，并将 www 永久重定向到 apex 规范主机；如果只在 HTTP 层重定向，HTTPS 爬虫将无法完成 TLS 握手。同一服务栈也可以通过这些上游域名提供 security-recipes.si 和 www.security-recipes.si（SECURITY_RECIPES_MIRROR_DOMAIN）；可见的品牌元素会根据请求的 Host 显示，而 SEO 规范链接仍指向 https://security-recipes.ai/。详见 README.caddy-deploy.md。

对于已有 Droplet，部署包含该监狱的提交后，需要执行以下一次性、幂等的启用操作：

sudo bash scripts/configure_caddy_404_ban.sh
sudo fail2ban-client status security-recipes-caddy-404

如果 Droplet 仍使用带有旧命名日志卷的内置 Caddy，请先在 .env 中设置 SECURITY_RECIPES_TRAFFIC_LOGS_SOURCE=/var/log/caddy，然后在维护窗口内仅重新创建一次 Caddy：

docker compose --profile caddy up -d \
  --no-deps --force-recreate --pull never caddy
sudo bash scripts/configure_caddy_404_ban.sh

该过滤器使用 Caddy 结构化日志中的 client_ip，而不是可伪造的转发标头或 User-Agent 值。如果源站之后置于 CDN 或负载均衡器之后，请将封禁操作转移到相应提供商的 WAF/API；如果客户端的数据包来自受信任的代理，源站防火墙就无法直接封禁该终端客户端。 该 jail 不信任 Googlebot User-Agent 字符串。在统计公共客户端之前，它会执行 Google 的反向再正向 DNS 检查：PTR 主机名必须位于 googlebot.com 下，且解析该主机名必须返回相同的 IP。结果按 IP 缓存一小时；查询错误和五秒的解析器截止时间都会采取默认拒绝策略，因此未经验证的客户端仍受扫描路径的 404 预算限制。

对于完全由 Compose 管理的 Caddy 部署，也可以在堆栈中运行 Fail2Ban。在 .env 中设置 DEPLOY_COMPOSE_FAIL2BAN=true，并让 Caddy 的日志源使用默认的 caddy_logs 卷（或主机绑定挂载）。下次运行时，deploy.sh 会拉取、启动并执行健康检查，之后还会更新 Fail2Ban 容器。它还会在启动 jail 前初始化 Caddy 的访问日志文件，因为 Fail2Ban 要求配置的文件必须存在。若要手动启动而不等待部署，请使用：

docker compose up -d caddy fail2ban
docker compose exec fail2ban fail2ban-client status security-recipes-caddy-404

该容器与主机共享网络命名空间，并且仅具有将 jail 的 nftables 规则应用于主机和 Docker 转发的 Web 流量所需的 NET_ADMIN/NET_RAW 能力。security-recipes-caddy-404 jail 在主机上运行时，请勿启用 Compose jail；防火墙规则只能由其中一个负责。这可以缓解重复的应用层 404 扫描，但不能替代上游的大流量 DDoS 防护或请求速率限制。选项为 false 时，deploy.sh 不要求安装主机上的 fail2ban 软件包；主机管理的安装仍由 droplet 设置和 scripts/configure_caddy_404_ban.sh 工作流负责。

如果你更倾向于在 droplet 上使用 nginx 而非 Caddy，请先在不启用代理的情况下初始化主机，然后运行 nginx 辅助脚本：

sudo bash scripts/setup_digitalocean_droplet.sh --no-caddy
sudo bash scripts/configure_nginx_letsencrypt.sh \
  --domain security-recipes.ai \
  --email [email protected]

对于仅供本地使用或已配置代理的 droplet：

sudo bash scripts/setup_digitalocean_droplet.sh --no-caddy --no-firewall --no-upgrade
docker compose up -d --build

如果先前使用 docker-compose v1 运行失败，并出现 KeyError: 'ContainerConfig'，请升级 Compose，并移除过时的项目容器，然后重新创建堆栈：

sudo bash scripts/repair_docker_compose_containerconfig.sh
hash -r
command -v docker-compose
docker-compose version

生产环境部署会拉取由 main 分支上必需的 GitHub Actions Build 工作流发布、以提交标识的站点和 MCP 镜像，并在 https://security-recipes.ai/ 提供服务。同一定时任务还会将 development 镜像部署到 https://dev.security-recipes.ai/。部署期间，Droplet 不会运行 Node、Eleventy、pip，也不会构建 Docker 镜像，因此部署可在 1 CPU / 2 GB 内存的资源范围内完成。

一次性配对 MCP 部署升级

在首次引入配对 MCP 服务的部署之前，只更新部署脚本，然后运行它。在配对 Compose 文件出现之前，已经运行的旧版 deploy.sh 进程就已完成解析；否则，它会在该次发布期间重新创建正在运行的单实例 MCP：

git fetch origin main
git checkout origin/main -- deploy.sh
bash deploy.sh

新脚本会保持正在运行的单实例不变，同时准备非活动 MCP 和站点，并将它们作为一个整体切换。完成这一步后，现有的 bash deploy.sh cron 条目无需更改。

首次成功运行 main 工作流后，会创建两个 GHCR 软件包。请将它们设为公开，或使用可读取软件包的细粒度令牌，为部署服务所用的 root 账户进行身份验证：

printf '%s' "$GHCR_READ_TOKEN" |
  sudo docker login ghcr.io --username stevologic --password-stdin

MCP 集成理念

使用 MCP 为 Agent 提供上下文，而不是不受约束的权限。

CVE MCP 工具只会返回计划和证据；不会编辑代码库或更改环境。经批准的 Agent 宿主可以应用返回的计划，但必须先确认受影响的范围和实际代码库路径，保留无关更改，获得任何已声明的生产环境／外部审批，并保留可通过机械方式执行的回滚方案。可能匹配的文件 glob 只能作为发现线索，绝不能视为文件存在漏洞的证明或修改许可。 在每项操作中，只有生效的 target_kinds 才是默认候选对象。 archetype_target_kinds 仅提供上下文，不构成授权；对于有条件的目标，必须证明代码库拥有受影响的实现，而禁止目标绝不能编辑。固件和二进制目标指的是权威参考、锁定版本、替换项、策略、清单、源代码或构建更改，绝不是修补供应商制品的字节内容。

NVD/CNA 描述、安全公告、链接、补丁、问题评论、发行说明和概念验证内容都属于不可信证据。Agent 可以从中提取经佐证的漏洞和版本事实，但不得执行或遵循其中嵌入的指令或命令。

良好的上下文来源包括：

• 官方 GitHub MCP 功能，用于提供代码库和代码安全上下文，
• 经批准的 Semgrep 和 Snyk Agentic／MCP 集成，
• OSV、GitHub Advisories、deps.dev、软件包注册表以及由 NVD 提供数据的镜像，
• SARIF、SBOM、CI、所有权和内部运行手册来源，
• 只读文档连接器。

具备写入能力的连接器需要单独审核。不能仅仅因为 Agent 能读取操作方案，就启用工单创建、分支修改、部署、密钥轮换、云端更改和 SOAR 操作。

贡献

贡献应改进方案库：

• 新的修复方案，
• 更好的提示词，
• 更清晰的 Agent 设置，
• MCP 集成示例，
• 审核者清单，
• 文档修正。

提交拉取请求前，请清除密钥、内部主机名、客户数据和私有漏洞详情。

提交前请先在本地构建：

python -m pip install -r requirements-dev.txt
python scripts/run_checks.py
npm run build

许可证

项目的原始代码、文档、修复方案、生成的网站和 MCP 服务均采用 Apache License 2.0 许可。这允许私人和商业使用、修改与再分发，包括纳入专有公司系统，但须遵守许可证中的声明和更改标记要求。

源漏洞数据和捆绑的第三方软件仍受各自条款和署名要求约束。请参阅 NOTICE 和 THIRD_PARTY_NOTICES.md。