sudoworks-lab/repo-health-doctor

# repo-health-doctor [](https://github.com/sudoworks-lab/repo-health-doctor/actions/workflows/ci.yml)    repo-health-doctor 是一个本地优先的执行前安全门控，专为人类和 AI agent 在处理不熟悉的代码库时使用。 它不能证明安全。 它防止虚假的自信。 在 agent 或开发者运行 `npm install`、`pip install`、`pytest`、 `make` 或生成的脚本之前，repo-health-doctor 会收集有限的证据， 暴露局限性，并防止缺失或降级的证据变成 “绿灯”。 ## 谁应该使用它 当你想要在接触一个你不完全信任的代码库之前，设置一个小巧且易于审查的 gate 时，请使用 repo-health-doctor： - 审查 AI 生成或外部代码库更改的维护者 - 首次浏览陌生本地检出代码的开发者 - 需要执行故障关闭（fail-closed）执行前检查的 coding agent - 需要脱敏的 PASS / WARN / BLOCK 报告的 CI 工作流 ## 5 分钟演示 在本地检出的代码中运行这些命令。它们不会安装 Gitleaks、OSV-Scanner 或 任何其他主机扫描器，也不会连接网络。 1. 检查在检出的代码中是否可以使用该命令： ``` env PYTHONPATH=src python3 -m repo_health_doctor --help ``` 2. 运行无发现但降级的演示，并阅读 opt-in 的 gate 摘要： ``` env PYTHONPATH=src python3 -m repo_health_doctor examples/demo-no-finding-but-degraded \ --public-safety \ --gate-summary \ --format json \ --output /tmp/rhd-demo-no-finding.v3.json \ --gate-decision-output /tmp/rhd-demo-no-finding.gate.json python3 -m json.tool /tmp/rhd-demo-no-finding.gate.json ``` 3. 运行合成供应链演示： ``` env PYTHONPATH=src python3 -m repo_health_doctor examples/demo-synthetic-supply-chain \ --public-safety \ --gate-summary \ --format json \ --output /tmp/rhd-demo-supply-chain.v3.json \ --gate-decision-output /tmp/rhd-demo-supply-chain.gate.json python3 -m json.tool /tmp/rhd-demo-supply-chain.gate.json ``` 终端摘要是演示的主要读数：静态健康状况可以是 `PASS` 而 gate 决策仍然是 `UNKNOWN`、`WARN`、`QUARANTINE`、`BLOCK` 或 受限状态。它还会保持 `execution_authorized=false` 并解释“没有扫描器发现”并不等于安全证明。无发现演示会指出缺失 或降级的观察者证据；合成供应链演示会指出 postinstall、凭据/环境、出站目标、工作流和类 eval 信号。当你想要检查 实验性 gate 详情时，可以使用 sidecar JSON。 `--gate-summary` 是 opt-in 的，旨在作为人类可读的演示 / 审查辅助工具。 它不会改变默认的 v3 报告契约。Gate 决策 sidecar、 人类可读的解释和上下文措辞都是实验性的。即使 `allow_limited` 也不是安全证明或不受限制的执行许可。 更多详情请参见 [docs/quickstart.md](docs/quickstart.md) 和 [docs/demo-runbook.md](docs/demo-runbook.md)。 ## 这不是什么 repo-health-doctor 不是： - Gitleaks、TruffleHog、OSV-Scanner、Grype、Syft、zizmor、 actionlint、Falco、Tracee 或 EDR 的替代品 - 一个完整的恶意软件沙箱 - 一个依赖漏洞数据库 - 代码库安全的证明 - 运行派生自代码库的命令的许可 这个边界是刻意设定的。干净的扫描器结果仅仅是范围有限的证据。 扫描失败不是 PASS。降级的观察者不等于信心。外部 扫描器证据可以提高风险，但它不能授权实时执行。 ## 稳定性与公开契约 默认的 v3 报告仍然是兼容稳定的输出。默认的 CLI 行为、脱敏原则、无发现的局限性、决策与 授权分离、gate 决策 `execution_authorized=false` 以及 呈现的局限性都是稳定的公开契约。 证据 schema、gate 决策 sidecar、`--gate-summary`、人类可读的 gate 解释、导入的证据适配器、样本输出和执行 授权工件在此版本中均为实验性功能。与真实输出兼容的 fixture 覆盖率和 Docker 集成 CI 路径也是实验性的，并且 仅限于文档中记录的 fixture、版本和 CI 范围。 请参见 [docs/public-contracts.md](docs/public-contracts.md) 和 [docs/versioning.md](docs/versioning.md)。 ## 安全审查状态 尚未进行第三方安全审查。内部测试、公共安全检查、 策略验证、schema 检查和兼容性 fixture 不能 替代外部审查。欢迎进行安全模型审查；请对非敏感审查使用 公开模板，并避免使用原始的敏感数据。 请参见 [docs/security-review-needed.md](docs/security-review-needed.md) 和 [docs/threat-model.md](docs/threat-model.md)。 ## 本地快速检查 对于本地开发，请在仓库根目录下使用 `PYTHONPATH=src` 运行离线本地验证： ``` env PYTHONPATH=src python3 -m unittest discover -s tests -v env PYTHONPATH=src python3 -m repo_health_doctor --version env PYTHONPATH=src python3 -m repo_health_doctor . --fail-on block --public-safety env PYTHONPATH=src python3 -m repo_health_doctor validate-policy . env PYTHONPATH=src python3 -m repo_health_doctor . --public-safety --format json --output /tmp/repo-health-doctor-result.json python3 -m json.tool /tmp/repo-health-doctor-result.json >/dev/null ``` 可编辑安装是可选的，属于打包验证的一部分。在网络受限的环境中，在解析构建系统依赖项之前它可能会停止， 因此请将离线本地验证保留为本地基线，并在 CI 或构建依赖已解决的环境中维护打包验证。 ``` python3 -m venv .venv . .venv/bin/activate python3 -m pip install -e . repo-health-doctor --version repo-health-doctor . --fail-on block --public-safety ``` ## 核心命令 ``` repo-health-doctor . repo-health-doctor . --public-safety repo-health-doctor . --fail-on warn --public-safety repo-health-doctor . --public-safety --format json --output /tmp/repo-health-doctor-public-safety.json repo-health-doctor . --public-safety --format markdown --output /tmp/repo-health-doctor-public-safety.md repo-health-doctor validate-policy . repo-health-doctor list-allows . repo-health-doctor list-allows . --fail-on expiring-soon repo-health-doctor diff-reports before.json after.json repo-health-doctor release-check . repo-health-doctor sandbox . ``` 命令详情特意保留在文档中： - [docs/quickstart.md](docs/quickstart.md)：5 分钟演示和 gate 决策 - [docs/demo-runbook.md](docs/demo-runbook.md)：安全的合成演示代码库 - [docs/policy.md](docs/policy.md)：策略和 `validate-policy` - [docs/ci-integration.md](docs/ci-integration.md)：CI 和 GitHub Step Summary - [docs/maintainer-guide.md](docs/maintainer-guide.md)：维护者工作流 - [docs/agent-guide.md](docs/agent-guide.md)：agent 工作流 ## 输出与脱敏 当前稳定的扫描输出使用 `schema_version: 1.1` 并报告： - `PASS`：当前检查范围内没有阻碍性发现 - `WARN`：在依赖结果之前需要进行审查 - `BLOCK`：在处理发现或缺失的证据之前不要继续 报告不得打印原始密钥、原始扫描器输出、原始 stdout 或 stderr、 主机私有路径、凭据或原始策略值。公共安全发现 将作为中性类别报告，而不是原始检测值。 此紧凑的策略 JSON 样本与 golden fixture 保持同步： ``` { "tool": "repo-health-doctor", "version": "0.1.0", "schema_version": "1.1", "repo_path": "", "overall_status": "pass", "summary": { "pass": 1, "warn": 0, "block": 0 }, "checks": [ { "name": "policy", "status": "pass", "summary": "Policy configuration loaded.", "details": { "findings": [], "policy_sources": [ "repo" ], "ignore_path_count": 1, "allow_finding_count": 0 } } ] } ``` 此文本样本显示了脱敏的公共安全报告结构： ``` Repo Health Doctor: PASS Target: Schema: 1.1 Summary: 12 pass, 0 warn, 0 block Status: PASS ok, WARN review, BLOCK release blocker Checks: - [PASS] readme: README found. found: README.md - [PASS] license: License file found. found: LICENSE - [PASS] gitignore: .gitignore found. found: .gitignore, .git/info/exclude - [PASS] ci: Workflow file found. found: .github/workflows/ci.yml - [PASS] tests: Test directory found. found: tests - [PASS] docs: Docs directory found. found: docs - [PASS] scripts: Scripts directory found. found: scripts - [PASS] secrets_scan: No obvious unallowed secrets detected. scanned_files: 6 - [PASS] large_files: No unallowed large files detected. threshold_bytes: 10485760 - [PASS] public_text_safety: No obvious public-facing text issues detected. scanned_files: 6 scan_scope: tracked - [PASS] tracked_artifacts: Tracked generated or environment files were not detected. scan_scope: tracked - [PASS] policy: Policy configuration loaded. policy_sources: repo ignore_path_count: 1 allow_finding_count: 0 ``` 当前 v3 输出向未来证据/gate 模型转变的差距记录在 [docs/v3-output-to-evidence-gate-gap-audit.md](docs/v3-output-to-evidence-gate-gap-audit.md) 中。 机器可读的 schema 和 golden 样本由测试覆盖。 ## 与现有工具的关系 repo-health-doctor 是一个证据标准化器和执行前 gate。在 策略允许的情况下，它可以 使用或关联来自专用工具的证据，但 它不会取代它们。 角色分工记录在 [docs/competitor-positioning.md](docs/competitor-positioning.md) 中。 ## 局限性 - 它不能证明代码库是安全的。 - 它不能取代专门的密钥、漏洞、SBOM、CI/CD、EDR 或 runtime 检测工具。 - 它不能消除 Docker、扫描器二进制文件、观察者、fixture 或版本 的盲点。 - 当前稳定的 JSON 输出是面向检查的报告，而不是未来的 证据/gate 模型。 - 与真实输出兼容的覆盖范围仅限于文档记录的 fixture、版本 和适配器范围。 - 尚未进行第三方安全审查，这仍然是外部的必要工作。 ## 详细文档 - [docs/README.md](docs/README.md)：完整文档索引 - [docs/security-model.md](docs/security-model.md)：脱敏和安全边界 - [docs/evaluation-model.md](docs/evaluation-model.md)：测试、fixture 和 golden 输出 - [docs/public-contracts.md](docs/public-contracts.md)：稳定 / 实验性 / 非契约接口 - [docs/security-review-needed.md](docs/security-review-needed.md)：第三方审查状态 - [docs/compatibility-regeneration.md](docs/compatibility-regeneration.md)：安全的兼容性 fixture 重生成 - [docs/release-notes/v0.1.0.md](docs/release-notes/v0.1.0.md)：发布说明 - [CHANGELOG.md](CHANGELOG.md)：更新日志

标签：AI代理安全, IP 地址批量处理, LNA, Python, RDFlib, 云安全监控, 代码审查, 文档安全, 无后门, 本地优先, 请求拦截, 逆向工具, 配置审计, 静态分析