在进行行为变更之前，请参阅 OVERVIEW.md 以了解该仓库的用途、组件和范围的高层描述。
一个修复编排器，以 MCP 服务器形式暴露。连接一个 MCP 客户端（Claude Desktop、Claude Code 或类似工具）并提交一个自然语言请求，例如：
登录主机 a.b.c，检查已安装的软件包，查找 CVE，并建议修复方案——如果可能的话使用 Ansible，并告诉我它映射到哪些合规控制项。
prescryb 提供基础原语（SSH 清单、CVE 匹配、实时公告查询、合规主题映射、Ansible playbook 渲染）。连接的模型负责推理：哪些发现重要、要深入调查哪些 CVE、要生成哪个 playbook。prescryb 从不对目标主机应用任何更改——每个工具对目标主机都是只读的，或者是纯文本/数据生成。
| 工具 | 功能 |
|---|---|
inventory_host(host, user="", port=22, hostname="", identity_file="", trust_unknown_host=False) | 通过 SSH 登录，检测发行版，列出已安装的软件包及其版本。 |
check_cves(system, packages) | 使用 OSV.dev 的生态系统感知版本比较（而非仅名称匹配）批量匹配软件包版本。每个匹配项都会附带一个 EPSS 利用概率评分。 |
fetch_advisory(cve_id) | 实时获取某个 CVE 的当前 NVD 记录——描述、CVSS、CWE、参考链接——而非来自训练数据。 |
fetch_epss(cve_ids) | 批量获取尚未被 check_cves 覆盖的 CVE ID 的 EPSS 利用概率评分（例如来自 fetch_advisory 或网络搜索的 CVE ID）。 |
map_compliance(area) | 将自由文本主题（"ssh"、"sudo"、"kernel modules" 等）映射到 CIS/DISA STIG 主题领域，以及（如果 konstruktoid.hardening GitHub 仓库中存在）匹配的角色——外加该领域所应对的 MITRE ATT&CK 技术和缓解措施。 |
lookup_cce(target, keyword, cce_id) | 查询某个平台（例如 "rhel8"）的 NIST CCE（通用配置枚举）条目，数据来源于 konstruktoid/cce-web 的社区 JSON 转换。 |
list_cce_targets() | 列出 lookup_cce 可以查询的所有平台。 |
list_local_docs() | 列出本地、被 gitignore 的 LOCAL_DOCS_DIR 下找到的文档（Markdown/文本/PDF）。 |
search_local_docs(query, top_k=5) | 对这些本地文档进行 RAG 风格的语义搜索，完全在机器上嵌入。 |
generate_playbook(system, cve_matches, compliance_areas, hosts_alias) | 渲染一个仅建议的 Ansible playbook：CVE 修复变为软件包升级任务，合规领域变为 roles: 引用。 |
典型流程：inventory_host，然后对返回的软件包执行 check_cves，接着可选地对感兴趣的 CVE 执行 fetch_advisory，然后对注意到的任何不安全配置领域执行 map_compliance（以及 lookup_cce），接着可选地执行 search_local_docs 以获取相关的内部运行手册/策略上下文，最后执行 generate_playbook 以生成可供审查的内容。
flowchart TD
U["Operator: natural-language request"] --> M["Connected model\n(Claude Desktop / Claude Code)"]
M --> A["inventory_host\nSSH in, list packages"]
A --> B["check_cves\nOSV.dev match + EPSS score"]
B --> C{"Interesting\nCVE?"}
C -->|yes| D["fetch_advisory\nNVD detail for one CVE"]
C -->|no| E
D --> E["map_compliance / lookup_cce\nCIS/DISA STIG + ATT&CK mapping"]
E --> F["search_local_docs\ninternal runbooks (optional)"]
F --> G["generate_playbook\nsuggest-only Ansible playbook"]
G --> H["Model reasons over the results\nand presents findings + playbook"]
H --> R["Operator reviews\n(ansible-playbook --check --diff)\nand applies manually"]
style R fill:#f9f,stroke:#333,stroke-width:1px
只有工具框属于 prescryb：inventory_host、check_cves、
fetch_advisory、map_compliance/lookup_cce、search_local_docs 和
generate_playbook——每一个都是只读查询或纯文本/数据生成
调用。操作员和所连接的模型不属于 prescryb，并且
这条链中除了 inventory_host 的
只读 SSH 会话之外，没有任何内容触及目标主机——应用生成的 playbook 是操作员在 prescryb 之外
采取的、有意的独立步骤。
uv sync
Claude Code：
claude mcp add prescryb -- uv --directory /path/to/prescryb run prescryb
Claude Desktop（claude_desktop_config.json）：
{
"mcpServers": {
"prescryb": {
"command": "uv",
"args": ["--directory", "/path/to/prescryb", "run", "prescryb"]
}
}
}
inventory_host 从不接受密码参数。MCP 工具调用参数可能被客户端记录，并且对已连接的模型可见，因此凭据绝不能通过这些参数传递。认证方式与你亲自运行 ssh host 完全一致：
~/.ssh/config 解析。inventory_host 的 hostname/identity_file 参数会直接覆盖解析出的地址/密钥路径，适用于你不想添加到 ~/.ssh/config 的主机（仅传递路径，绝不传递密钥内容）。trust_unknown_host=True
ssh host 来固定该密钥。qemu/vm.sh 在 QEMU 下启动云镜像（almalinux10、trixie、resolute），带有 cloud-init seed，并在 127.0.0.1 上做 SSH 端口转发（2201、2202、2203）。它需要 qemu-system-x86_64、qemu-img、cloud-localds（cloud-image-utils）、curl 和 ssh；当 /dev/kvm 可写时会使用 KVM。镜像会经过校验和验证并缓存到 qemu/.state/。
qemu/vm.sh up trixie
qemu/vm.sh ssh trixie true # retry until the guest answers
claude 'inventory 127.0.0.1 port 2202 user prescryb with identity file
qemu/.state/id_ed25519 (trust_unknown_host is fine, it is a throwaway VM),
check any vulnerabilities and suggest a fix, include compliance mapping if
possible, write the playbook suggestion to /tmp/ and print the file location'
qemu/vm.sh destroy trixie
对于已经可以通过 ssh 访问的主机（通过 ~/.ssh/config、agent 密钥或默认身份文件解析），直接指定主机名即可；无需配置端口或身份文件：
清点 prod-web-01，检查已安装的软件包，查找 CVE，并建议修复方案——如果可能的话使用 Ansible，并告诉我它对应哪些合规控制项。
如果该主机尚未出现在 ~/.ssh/config 中，可以添加一个 Host 块，或者直接将 user/port/hostname/identity_file 传给 inventory_host 以进行一次性连接——与下面的 molecule 示例相同。
molecule converge -s default
从该场景的 molecule.yml 平台条目中找到 ssh_port/ssh_user（例如 almalinux10 平台的 ssh_port: 22201、ssh_user: almalinux），以及 molecule login 用于连接的私钥——要么向 ~/.ssh/config 添加一个 Host 块，要么完全跳过该文件，直接将它们传给 inventory_host，以建立一次性的临时连接：
Inventory 127.0.0.1，端口 22201，用户 almalinux，identity_file /path/to/molecule's/generated/key，检查已安装的软件包，查找 CVE， 并建议修复方案——如果可能的话用 Ansible，并告诉我它映射到哪些合规 控制项。
完成后运行 molecule destroy -s default；prescryb 不会替你执行此操作，也不会在读取实例之外对其做任何改动。
map_compliance 会列出主题领域（例如“SSH Server Configuration”），并且如果在 konstruktoid/ansible-collection-hardening GitHub 仓库中找到，还会给出实现该领域的 Ansible 角色的链接。
默认情况下，它会针对 konstruktoid/ansible-collection-hardening 查询 GitHub API。
可通过以下方式覆盖：
export HARDENING_COLLECTION_REPO=owner/repo
将 GITHUB_TOKEN 设置为提高（否则较低的）未认证 GitHub API 速率限制。如果在仓库中未找到某个角色，map_compliance 仍会返回主题/框架/角色名称，以便你知道需要安装什么（ansible-galaxy collection install konstruktoid.hardening）。
lookup_cce 用于查询 NIST 通用配置枚举条目——即单个配置检查的唯一标识符，与上文按主题领域划分的 CIS/DISA STIG 映射不同。NIST 仅以电子表格形式发布 CCE，因此此功能读取由社区项目 konstruktoid/cce-web 托管的预转换 JSON 导出文件，而非解析 Excel。
覆盖范围按平台划分，而非按主题划分，且对于本项目的目标发行版而言较为有限：只有 RHEL 系列（rhel6/rhel7/rhel8——AlmaLinux/Rocky 使用对应的上游 RHEL 版本号）和 SUSE（SLES12-DISA-STIG/SLES15-DISA-STIG/SLES15-PCI-DSS）拥有可用数据。Debian、Ubuntu、Alpine 和 Arch 在上游完全没有 CCE 数据。少数较旧的 cce-web 导出文件（例如 rhel4、rhel5、apache-httpd2.2）在上游 Excel 转 JSON 转换过程中丢失了列标题；这些会被报告为不支持，而不是返回乱码字段。调用 list_cce_targets 可查看所有已发布的平台，包括非 Linux 平台（firefox、win2k8r2 等）。
通过以下方式覆盖源仓库：
export CCE_REPO=owner/repo
除 CIS/DISA STIG 之外，map_compliance 和 generate_playbook 还会引用某个主题领域的加固所缓解的 MITRE ATT&CK 技术（例如 "ssh" 映射到 T1110 Brute Force 和 T1021.004 Remote Services: SSH），并在 ATT&CK 定义了相应缓解措施时引用该措施（例如 M1032 Multi-factor Authentication），同时附上指向 attack.mitre.org 的链接。与 CIS/DISA STIG 规则编号不同，ATT&CK 技术和缓解措施 ID 属于 MITRE 自己的公开目录，因此可以直接引用，而无需查询需要授权的基准。此映射是静态的（内置于 attack.py），并非实时获取。
{name, ecosystem, version}，因此匹配结果反映的是确切安装的版本，而不是"任何提及此包名的 CVE"。对 Debian、Ubuntu、Alpine 的覆盖已成熟；对 RHEL 系（AlmaLinux、Rocky）和 SUSE 覆盖较薄弱。check_cves 会返回一个 warning 字段，标记覆盖较薄弱的生态系统，而对于完全没有生态系统映射的发行版则返回空（而非猜测）——此处的空结果意味着"未检查"，而非"干净"。fetch_advisory）仅用于丰富你已拥有 ID 的 CVE。设置 NVD_API_KEY 可提高（原本较低的）未认证速率限制。check_cves 匹配结果上的 epss_score/epss_percentile，或对来自其他来源的 CVE ID 使用 fetch_epss）估算未来 30 天内被利用的概率——它独立于 CVSS/严重性，并是有用的补充：一个 LOW 严重性的 CVE 可能具有高 EPSS 分数，反之亦然。这使得发现结果可以按 cve_id、severity 或 epss_score 排序/过滤。无需 API 密钥。没有 EPSS 记录的 CVE（非常新、保留或已拒绝的 ID）只是 epss_score 未设置——并非错误。FIRST.org 服务中断会以 check_cves 上的 warning 形式出现，而不会导致 CVE 匹配本身失败。cvss_vector），而非预先计算的标签。仅当来源明确标注时才会填充 severity；否则为 "UNKNOWN"，向量留给你（或模型）自行解读，而非猜测。