security-recipes.ai

搜索 CVE。使用 AI 代理修复漏洞。 有来源的事实保持有来源，修复保持有边界，每个计划都带有验证、回滚和停止条件——这是实时站点的契约，也是本仓库的契约。

security-recipes.ai 是一个 Eleventy 站点，用于提供有来源的 CVE 情报和基于证据的漏洞修复，AI 代理可以消费这些内容，而不会继承部署或生产权限。

该项目刻意保持范围狭窄：

• 一个完整的滚动式 Medium/High/Critical CVE 数据库，

• 经过证据限定的规范 CVE 修复记录，

• 实用的安全修复配方，

• 提示词和规则文件示例，

• 代理设置指南，

• MCP 集成模式，

• 一个可选的只读 MCP 服务器，用于配方搜索和经批准的上游 MCP 上下文，

• 一个可复用的 GitHub Action，可将这些指导转化为可切换的 CI 健康检查。

它不是扫描器、工单系统、SOAR 平台、部署工具或自定义安全工具包。现有的安全工具应产生发现结果；本站点帮助代理使用正确的修复上下文并在正确的时间停止。

从实时 CVE 数据库 开始查找特定漏洞，或使用 AI 漏洞修复手册 了解从证据到补丁的工作流程。针对特定代理的指南涵盖 Codex、Claude Code、Cursor、GitHub Copilot、Devin、Shiba Studio、Hermes Desktop 和 OpenClaw。视觉指南 展示了从来源限定和搜索发现到有界计划、证明、回滚和人工审查的完整路径。对于保护代理系统的身份、工具、连接器、上下文、内存、运行时和恢复控制这一独特问题，请使用 AI 代理安全。

当前产品和工作流程

限定搜索发现

完整目录保持可搜索，而公开的规范 CVE 页面仅限于已审查或证据限定的记录。这些页面提供独特的搜索元数据、服务端渲染的核心事实和受影响版本证据、一个修复权威（优先使用稳定的已审查指导，否则使用完整的来源链接 AI 增强）、一个简短的审批门控 AI 实现提示词、规范 URL、面包屑以及 Article/TechArticle 结构化数据。CVE 数据库将目录描述为 Dataset；修复支柱将其可见的七步工作流程暴露为 HowTo。按年份分区的 CVE 站点地图仅包含可索引的规范路由，当站点地图一致性、规范所有权、爬取可达性、元数据限制或同源链接漂移时，构建会失败。

索引性也从大规模模板化的配方子页面中移除。72 个开发代码卫生配方和 39 个生成的合规框架配方保持可从其规范中心浏览，带有 noindex,follow，同时它们共享一种通用方法。一个有界的渲染主体相似性门控可防止子页面重新进入站点地图，直到其证据、示例和测试在实质上不同。中心保持可索引并携带共享的发现上下文。

在具有 SEO 影响的发布之后，公共修订版必须在站点地图提交或 URL 检查之前与合并提交匹配。Caddy 部署指南 记录了经过 DNS 验证的 Search Console 交接、优先实时 URL 检查、站点地图提交、索引请求和查询监控。提交是一个发现提示；它不保证索引或特定排名。

修复支柱还记录了 CVE-2026-13149 in brace-expansion 的公共仓库示例。它将仅依赖变更与已审查的拉取请求、测试、公告证据和恢复路径联系起来，同时明确区分同一 PR 中无关的 Fail2Ban 工作。

Related MCP server: CVE Intelligence MCP Server

本项目的用途

AI 编码代理可以在其工作有界时帮助关闭安全发现：一个发现、一个配方、一个已审查的输出。

security-recipes.ai 帮助团队回答：

• 哪个配方匹配此发现？

• 代理应使用哪个提示词？

• 我应该将 Copilot、Claude、Cursor、Codex 或 Devin 的指令放在哪里？

• 代理应读取哪些 MCP 服务器以获取公告、扫描器、仓库或运行手册上下文？

• 在审查者信任之前，PR 或分诊说明应包含什么？

交付内容

• Eleventy 文档站点（快速静态构建，无需 Go 工具链）。

• CVE 优先的观测站首页和数据优先的 CVE 数据库。

• 针对依赖、SAST、敏感数据、基础镜像、CVE 和默认加固修复的配方中心。

• CVE 情报接收策略、提示词、固定装置和评估器，用于在代理修补之前路由公告信号。

• 一个完整的滚动式十年 Medium/High/Critical CVE 目录，由完整性验证的 NVD JSON 2.0 源、CISA KEV 元数据和每个适用的经过审查的修复原型组成。只有已审查的 stable Markdown 页面会覆盖该保守基线。

• 一个完整性哈希的搜索允许列表，仅发布已审查的稳定 Markdown 或通过确定性配方就绪证据契约的 AI 增强的规范 CVE 页面。即使记录不符合搜索索引条件，完整数据库仍保持可搜索。

• 针对每个目录 CVE 的版本化七阶段代理变更契约：发现、评估、缓解、修复、验证、回滚和分诊。每个操作声明可能的文件目标、变更和批准边界、所需证据、输出和失败行为，而不猜测补丁或固定版本。

• 一个结构化合规库，涵盖 39 个安全、隐私、保证、弹性和软件供应链框架，而不复制许可的控制文本。其框架中心是搜索表面；模板化的子评估保持 noindex,follow，直到差异化。

• 一个 72 配方的代码卫生库，涵盖跨语言和生态系统特定的审计、修复、验证和停止条件工作流程。其开发子页面保持 noindex,follow，而它们的正文共享生成的模板。

• 保留现有提示词集合的配方。

• 针对 GitHub Copilot、Claude、Cursor、Codex 和 Devin 的代理设置指南。

• 针对公共和组织批准的安全数据源的 MCP 集成指导。

• 可选的只读 FastMCP 服务器，位于 mcp_server.py，用于配方搜索、检索和可选的上游 MCP 上下文。

• 用于本地或 droplet 托管的 Docker 和 Docker Compose 配置。

• 用于站点维护、验证、导入和部署的辅助脚本。

仓库地图

核心内容区域

• CVE 数据库：来源可靠的 CVE 情报、受影响版本证据和规范修复记录。

• AI 漏洞修复： 从一条发现到经审核的补丁或分类说明的循证剧本。

• AI 代理安全： 针对 AI 代理系统本身的威胁建模、生产基线、来源边界、控制路由、 证据和事件就绪。

• 快速入门：从一条发现到 一个经审核的 PR 或分类说明。

• AI 代理对比：针对 Copilot、Claude Code、Cursor、Codex 和 Devin 的 已验证操作模式、原生指令、预期产物、前提条件和 审核门禁。

• 配方：可复用的提示词、 指令、规则、技能和审核清单。

• MCP 集成：如何安全地连接 安全上下文。

• 视觉指南：通过五张图展示 合格的搜索发现、CVE 到计划、证明、回滚、审核和只读 MCP 流程。

• 文档：站点使用、代理消费 模式和贡献指南。

Python 修复工具

Python 套件是文档的可选执行伴侣。它 可以检查有界工作区、选择 75 个修复剧本中的任意一个、 创建持久化的运行数据包、记录完整性哈希证据，并在 代理或审核者交接前验证数据包。它保持本地化和保守性：它 不会自行合并代码、部署更改或调用外部系统。

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

仓库还包含针对需要更丰富证据包或运行时策略决策的剧本的 领域特定生成器和评估器。 站点和 JSON 注册表在没有 Python 的情况下仍然有用；这些工具使 相同的工作流契约可直接由 CI、编排器和经批准的编码代理执行。

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

• scripts/setup_digitalocean_droplet.sh：Ubuntu droplet 引导，包含 Docker、主机加固和可选的 Caddy 管理的 HTTPS。

• scripts/configure_nginx_letsencrypt.sh：主机 nginx 反向代理设置，适用于 希望在 nginx 上使用 Let's Encrypt 而非 Caddy 的团队。

• README.nginx-letsencrypt.md：面向运维人员的 nginx 部署路径操作指南。

推荐的操作模式：

1. 让现有的 SCA、SAST、密钥、CI、云和工单系统产生 发现。

2. 附加一个匹配的 security-recipes.ai 配方和提示词。

3. 让代理只读取该发现所需的文件和 MCP 上下文。

4. 在合并前要求测试和人工审核。

5. 将广泛的自动化、写访问和部署排除在第一个循环之外。

指南和执行工具

该站点是修复工作的指南：配方、提示词、代理设置、 MCP/API 集成说明和审核模式。运行时自动化属于 用户经批准的代理主机、CI 系统、工单工作流或扫描器 平台，而不是站点托管的聊天机器人。

scripts/、tools/ 和 mcp_server.py 中的 Python 工具通过 剧本执行数据包、证据验证、 领域特定评估和生成、验证、公告导入、 配方搜索和可选的只读 MCP 访问来支持维护者和自托管者。

可选的 MCP 服务器

MCP 服务器默认是只读的。其基线角色是让 MCP 兼容代理搜索和检索配方。自托管部署也可以 将其配置为经批准的上游 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 是首选的代理订阅源，包含类别、严重性、 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 数据库提供该服务，该数据库基于同一清单构建并经过 整文件验证。仅聚焦和不完整的 CVE-YYYY-NNNN 标识符不会发起搜索请求。

• /api/cve-catalog/records/{cve} 是有界、同源的精确记录 端点。每个请求都固定分片集修订版，MCP 服务 验证并只打开包含该 CVE 的确定性分片。 当前浏览器使用此端点，而不是学习分片命名空间。

• /api/cve-catalog/browser-index.json.gz 在一个兼容窗口期内保留， 用于较旧的运行时摘要未声明搜索和记录 API 的情况。当 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 包含经审核的修复 契约，用于为每个目录记录组合保守的配方。 它还包含版本化的代理操作模式和生态系统特定的 文件目标提示，供浏览器和 MCP 服务器共享。

• 每个分区将每个范围内的 CVE 映射到其完整性哈希的压缩 JSONL 分片。分片记录包含 CVSS、CWE、有界 CPE、引用和 KEV 出处，用于精确 CVE 检索。

• 为保持记录有界，分片最多存储 12 行易受攻击的 CPE/版本 行，以及来源匹配总数和显式截断标志； 当该标志被设置时，消费者必须遵循 NVD/供应商证据。

规范化的 CVE 页面使用一组主引用集来呈现可见来源列表和结构化数据引用。原始生成的记录允许 NVD、CVE.org、范围内的 CISA KEV 记录，以及来源关联的厂商公告、补丁、发布说明或缓解措施；损坏的、仅第三方、仅漏洞利用和通用漏洞数据库链接不会自动提升。稳定的已审阅 Markdown 可以在其 References 部分有意引用额外的 HTTPS 证据。当修复措施涉及多个受支持分支或产品系列时，显示的操作会保留每一条可信的已修复版本声明，而不是将指导压缩为一条不完整的升级。

开发版和目录拥有的稳定 CVE Markdown 在纯静态构建中不生成独立页面，并被排除在 Eleventy 和通用配方/搜索源、标签页、RSS 和站点地图之外。三个目录前历史稳定配方仍作为普通渲染内容保留。

生产环境可以通过 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 创建拉取请求，以便首次运行时发布 PR。

设置 CVE_AUTO_MERGE_ENABLED=true 可在目录 PR 的精确头部修订通过专用验证工作流后交付经安全批准的目录 PR。当配置了 CVE_AUTOMATION_APP_CLIENT_ID 和 CVE_AUTOMATION_APP_PRIVATE_KEY 密钥时，工作流优先使用该 GitHub App 身份，以便普通 PR 和主分支 Build 运行自然触发。没有 App 凭据时，工作流仍保持自动化：在受保护的 GITHUB_TOKEN 合并后，它验证返回的合并 SHA 仍是当前的 main，然后以该精确 SHA 触发真正的 build.yml 工作流。生产部署门仅识别这些 CVE 限定的 Build 触发，因此计划监控器和无关的手动工作流无法死锁或满足发布条件。

源同步不需要密钥。遗留黄金审阅、内容刷新、AI 维护、AI 问题维护以及此仓库的安全健康操作也使用 Grok。添加一个名为 XAI_API_KEY 的 Actions 密钥（官方 xAI 环境变量；不要使用 GROK_API_KEY）：

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

工作流默认使用 xAI 的 grok-4.6 Responses API 模型，每次运行最多处理 20 条新增或来源变更的记录。计划队列源自跟踪的 NVD/CISA 目录：候选记录必须具有有效的带标签厂商公告、补丁、发布说明或缓解 URL。来源完整的记录仍然符合条件，因为它们仍需要来源化的修复综合；在每个 KEV 和严重性带内，它们排在具有确定性来源缺口的记录之前，其次是受影响产品/版本证据和时效性。这使用现有的每日请求预算，不需要额外的手动运行。模型和限制都可以通过可选的 Actions 变量更改；增强限制硬性限定在 0 到 50 之间：

gh variable set XAI_MODEL --body "grok-4.6" --repo stevologic/security-recipes.ai
gh variable set XAI_ENRICHMENT_LIMIT --body "20" --repo stevologic/security-recipes.ai

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 实时验证遗留黄金 CVE 遗留项。遗留黄金的 Critical 和 High 优先处理。这些关闭后，每次运行审阅最多 100 个遗留黄金 Medium 和 Low 页面，在 data/cve/leftover-review-state.json 中记录已完成的 ID，并打开带标签的自动合并 PR。遗留审阅作业使用带有 XAI_API_KEY 的 Grok Build CLI，当该密钥缺失或遗留黄金队列为空时无操作。

运行时路径有意为目录规模流量做了有界设计：

• 中心从紧凑的运行时摘要引导，精确查找调用修订固定的同源记录 API，标题/产品/厂商/筛选搜索仅在明确的搜索意图后才调用搜索 API；

• 广泛搜索从不可变的只读 SQLite 返回最多 100 条预览，具有三秒 HTTP 边界，并且绝不在访客进程或浏览器主线程中解码完整目录；

• 精确记录服务每次请求验证并打开一个分片；MCP 精确检索使用相同的仅分片路径，而非精确文本搜索使用清单固定的 SQLite 数据库，由专用执行器、有界准入队列、查询截止时间和 nginx 速率限制支持；

• 不可变浏览器缓存键来自声明的记录/搜索契约、原型哈希和分片集修订，而不是上游时间戳。

已实现的构建边界、精确分片交付模型、证据门控 SEO 策略、SQLite 搜索运行时和剩余的工件发布迁移记录在 CVE scale architecture 中。

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

更改站点标记后运行 npm run icons。它会重新生成不透明的 Apple touch 图标以及生产性能门检查的 192/512/maskable 已安装应用资源。

生产构建预压缩大型 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-copy 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 启动保留单例默认值， 因此首次发布仍与先前安装的脚本兼容。

对于使用 Let's Encrypt 的 nginx 或 Caddy 反向代理，请让 Docker 绑定到 loopback，并让代理拥有公共端口 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 admin@security-recipes.ai

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

DigitalOcean droplet

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

sudo bash scripts/setup_digitalocean_droplet.sh \
  --domain security-recipes.ai \
  --email admin@security-recipes.ai

该脚本安装 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 握手。

现有 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；源站 防火墙无法直接阻止其数据包来自 受信任代理的最终客户端。

该监狱不信任 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 容器。它还会在启动监狱之前初始化 Caddy 的访问日志文件， 因为 Fail2Ban 要求配置文件已存在。要手动启动它 而无需等待部署，请使用：

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

该容器共享主机网络命名空间，仅具有 应用监狱的 nftables 规则到主机和 Docker 转发 Web 流量所需的 NET_ADMIN/NET_RAW 能力。当主机 security-recipes-caddy-404 监狱处于活动状态时，请勿启用 Compose 监狱；请为 防火墙规则选择一个所有者。这可以缓解重复的应用层 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 admin@security-recipes.ai

对于仅本地或预代理的 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

生产部署拉取由所需的 GitHub Actions Build 工作流在 main 上发布的 提交寻址的站点和 MCP 镜像，并在 https://security-recipes.ai/ 上提供服务。同一计时器还将 development 镜像部署到 https://dev.security-recipes.ai/。Droplet 在部署期间 不运行 Node、Eleventy、pip 或 Docker 镜像构建，这使部署 保持在 1 CPU / 2 GB 内存的范围内。

一次性配对 MCP 部署升级

在引入配对 MCP 服务的首次部署之前，仅更新 部署脚本然后运行它。一个已在运行的较旧 deploy.sh 进程是在配对 Compose 文件存在之前解析的，否则 会在那一次发布期间重新创建实时单例 MCP：

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

新脚本保持实时单例不变，一起准备非活动 MCP 和站点，并将它们作为一个单元切换。完成此一次性步骤后， 现有的 bash deploy.sh cron 条目无需更改。

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

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

MCP 集成理念

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

CVE MCP 工具仅返回计划和证据；它们不编辑仓库 或更改环境。经批准的代理主机可以应用返回的计划， 但它必须首先证明受影响的表面和实际的仓库路径， 保留无关的更改，获得任何声明的生产/外部批准， 并保留可机械使用的回滚。可能的文件通配符是发现 提示，绝不是文件易受攻击或允许修改它的证明。 在每个操作中，只有有效的 target_kinds 是默认候选。 archetype_target_kinds 是上下文，不是授权；条件目标 要求证明仓库拥有受影响的实现，而 禁止的目标绝不能编辑。固件和二进制目标意味着 权威参考、固定、替换、策略、清单、源代码或构建 更改——绝不是修补供应商工件字节。

NVD/CNA 描述、公告、链接、补丁、问题评论、发布 说明和概念验证内容是不可信的证据。代理可以从它们中提取 经过证实的漏洞和版本事实，但绝不能执行或遵循 其中嵌入的指令或命令。

良好的上下文来源包括：

• 用于仓库和代码安全上下文的官方 GitHub MCP 能力，

• 经批准情况下的 Semgrep 和 Snyk 代理/MCP 集成，

• OSV、GitHub Advisories、deps.dev、软件包注册表和 NVD 支持的镜像，

• SARIF、SBOM、CI、所有权和内部 runbook 来源，

• 只读文档连接器。

可写连接器值得单独审查。工单创建、分支 变更、部署、密钥轮换、云更改和 SOAR 操作不应 仅仅因为代理可以读取配方就启用。

贡献

贡献应改进配方库：

• 新的修复配方，

• 更好的提示词，

• 更清晰的代理设置，

• 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。