MaintainerGuard

证据优先的 AI 维护者助手，用于合并、安全、Issue 和发布就绪评估。

MaintainerGuard 帮助开源维护者将 pull request 元数据、 更改的文件、扫描器输出、仓库策略、Issue 报告和发布 信息流转化为一份简明的维护者报告。 它回答了维护者真正关心的审查问题： MaintainerGuard 在没有 AI 的情况下也很有用。确定性证据引擎是 事实来源。可选的 AI 仅在保留的每项声明 链接到已知证据后，才能改善措辞。 ## 为什么优先考虑证据？ 维护者已经需要同时处理 diff、CI、CodeQL、依赖扫描器、secret 扫描器、发布说明和本地项目规则。困难的部分不在于看到 又一个警报。困难的部分在于知道什么重要、为什么重要，以及 在合并前需要检查什么。 MaintainerGuard 将这种审查噪音缩减为一份报告，包含： - 结论、风险等级、置信度和决策指导； - 安全敏感、依赖项、供应链、测试、文档和发布信号； - 将扫描器发现转化为维护者易懂的语言； - 仓库策略检查； - 维护者检查清单； - 针对重要声明的证据表。 ## MaintainerGuard 不是什么 MaintainerGuard 不是： - 人工审查的替代品； - 安全代码的保证； - 能发现所有漏洞的漏洞扫描器； - 自动合并机器人； - CodeQL、OSV、Semgrep、Gitleaks 或人工安全审查的替代品； - 发布嘈杂的内联 AI 评论的系统。 MaintainerGuard 是： - 证据优先的审查助手； - 合并就绪报告器； - 扫描器结果解释器； - 维护者检查清单生成器； - 无垃圾信息的 GitHub workflow 助手。 ## 核心功能 - 以 Markdown 或 JSON 格式生成确定性的合并就绪报告 - 决策指导，例如 `Request tests` 或 `Block until scanner finding is resolved` - 安全敏感变更检测，不会对漏洞过度预警 - 依赖项和供应链敏感文件检测 - 适用于通用 JSON、类 SARIF/code scanning、类 OSV 公告、secret scanner 结果、类 Semgrep 静态分析以及 workflow 策略输出的扫描器适配器 - 具有安全默认值的特定仓库策略 - 带有对潜在私人安全报告进行安全处理的 Issue 分类 - 包含发布结论、检查清单和发布说明草稿的发布就绪报告 - 可选的 OpenAI Responses API 丰富功能，带有脱敏和证据验证 - GitHub dry-run 模式和受保护的 update-one-comment 发布 - 用于 GitHub Action 的一流 `action.yml` 元数据 - 无第三方运行时依赖 ## 快速开始 MaintainerGuard 需要 Python 3.11 或更高版本。 在仓库发布后使用 `pipx` 安装： ``` pipx install git+https://github.com/xxxquide/MaintainerGuard.git mg demo mg init mg presets mg scanners mg doctor ``` 从检出的代码进行本地开发： ``` git clone https://github.com/xxxquide/MaintainerGuard.git cd MaintainerGuard python3 -m pip install -e . mg verify mg demo ``` 安装后的包同时暴露 `mg` 和 `maintainerguard`。从源码 检出中，无需安装即可运行 `./mg demo`。调试时仍可使用模块形式： ``` python3 -m maintainerguard demo --scenario high-risk-auth ``` 有关命令参考和故障排除，请参阅 [CLI 指南](docs/cli.md)。 GitHub Marketplace：[MaintainerGuard](https://github.com/marketplace/actions/maintainerguard)。 ## 本地演示场景 运行默认的高风险身份验证演示： ``` mg demo ``` - `high-risk-auth`：没有相关测试的身份验证/session 更改 - `dependency-advisory`：带有阻止性公告扫描器结果的依赖项更新 - `ci-workflow-risk`：带有供应链扫描器证据的发布 workflow 权限更改 - `secret-finding`：测试夹具以及提供的 secret scanner 发现 - `docs-only`：低风险的纯文档更改 - `test-only`：低风险的纯测试更改 - `medium-risk-config`：配置行为更改 - `release-impact`：带有 changelog/test 文件的破坏性 CLI 风格更改 示例报告： - [高风险身份验证报告](examples/reports/high-risk-auth.md) - [依赖项公告报告](examples/reports/dependency-advisory.md) - [CI workflow 风险报告](examples/reports/ci-workflow-risk.md) - [Secret finding 报告](examples/reports/secret-finding.md) - [纯文档低风险报告](examples/reports/docs-only-low-risk.md) - [纯测试低风险报告](examples/reports/test-only-low-risk.md) - [发布就绪报告](examples/reports/release-readiness.md) - [Issue 分类报告](examples/reports/issue-triage.md) ## 合并报告示例结构 ``` # MaintainerGuard 合并就绪报告 **Verdict:** Tests required **Overall risk:** High **Confidence:** Medium ## 执行摘要 "Change session token validation" affects Security-sensitive code. ## 决策指南 **Recommended maintainer action:** Request tests **Reason:** A maintainer should act on this recommendation because security-sensitive areas were touched and related tests were not supplied. ## 证据 | ID | Claim | Evidence | Confidence | |---|---|---|---| | `ev-...` | src/auth/session.py changed | changed_file: src/auth/session.py | High | ``` 完整报告还包括已更改的区域、风险原因、扫描器发现、 依赖项和供应链影响、测试影响、文档影响、发布 影响、策略检查、维护者检查清单和局限性。 ## GitHub Action 用法 包含的 [action.yml](action.yml) 默认是安全的。它以 dry-run 模式 运行，除非您明确禁用 dry-run 并启用评论发布。以下示例 保持 AI 关闭且评论关闭，除非明确展示了评论发布。 ### Dry-run PR 分析 ``` name: MaintainerGuard on: pull_request: types: [opened, synchronize, reopened, ready_for_review] permissions: contents: read pull-requests: read jobs: analyze: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/setup-python@v6 with: python-version: "3.11" - uses: xxxquide/MaintainerGuard@v0.3.1 with: mode: analyze-pr dry-run: "true" post-comment: "false" fail-on-risk: none ``` 外部仓库应使用已发布的 Action： ``` uses: xxxquide/MaintainerGuard@v0.3.1 ``` 该 Action 从 `$GITHUB_ACTION_PATH` 导入其 Python 包，同时将 工作目录保持为调用者仓库，因此 `.maintainerguard.toml` 和 扫描器路径在被分析的项目中解析。 本地开发注意事项：在发布前，在此仓库内测试更改时，请将 Action 步骤替换为： ``` uses: ./ ``` ### 常见 Action 变体 仅在出现严重风险时使 workflow 失败，同时保持 dry-run 模式： ``` - uses: xxxquide/MaintainerGuard@v0.3.1 with: mode: analyze-pr dry-run: "true" post-comment: "false" fail-on-risk: critical ``` 验证 `.maintainerguard.toml`，而不分析 PR 或发布任何内容： ``` - uses: xxxquide/MaintainerGuard@v0.3.1 with: mode: validate-config dry-run: "true" post-comment: "false" ``` 使用示例数据运行捆绑的演示，且不发布 PR 评论： ``` - uses: xxxquide/MaintainerGuard@v0.3.1 with: mode: demo scenario-or-sample-input-path: high-risk-auth dry-run: "true" post-comment: "false" ``` ### 明确发布一条 PR 评论 评论发布仅为可选。在 dry-run 报告看起来有用后启用它， 并且仅授予读取内容和编写 PR/Issue 评论所需的权限。 `GITHUB_TOKEN` 通过 `env` 传递；没有 `token` 输入。 ``` permissions: contents: read pull-requests: write issues: write steps: - uses: actions/checkout@v6 - uses: actions/setup-python@v6 with: python-version: "3.11" - uses: xxxquide/MaintainerGuard@v0.3.1 env: GITHUB_TOKEN: ${{ github.token }} with: mode: analyze-pr dry-run: "false" post-comment: "true" update-existing-comment: "true" fail-on-risk: none ``` MaintainerGuard 使用一个隐藏的评论标记，更新现有的标记 评论，并跳过相同的报告。它不会自动合并。 请参阅 [GitHub 自动化](docs/github-automation.md)。 ## 配置 MaintainerGuard 从当前目录或显式指定的 `--config` 路径读取 `.maintainerguard.toml`。默认值是有意设为安全的： - 启用 dry-run； - 禁用 AI； - 禁用评论发布； - 禁用草稿和机器人编写的 PR 评论； - 限制输入大小和文件数量； - 跳过标签包括 `no-ai`、`skip-ai` 和 `skip-maintainerguard`。 ``` mg config mg presets mg scanners mg doctor mg validate-config ``` 请参阅[配置参考](docs/configuration.md)和 [维护者策略](docs/maintainer-policies.md)。 从 v0.3.0 开始，`mg init --preset minimal|security|strict|docs` 可以将 标准策略配置写入 `.maintainerguard.toml`。自定义 `[[policy]]` 条目仍受支持，并在存在时替换所选的预设。 ## 扫描器集成 MaintainerGuard 会解释扫描器输出。它不会取代扫描器或 独立确认每一个发现。 ``` mg pr examples/sample-data/prs/dependency-update.json \ --scanner examples/sample-data/scanners/dependency-advisory.json \ --scanner examples/sample-data/scanners/static-analysis.sarif.json ``` 受支持的 MVP 输入包括通用 JSON、类 SARIF 的 code scanning、类 OSV 的 依赖项公告、secret scanner 结果、类 Semgrep 的静态分析和 workflow 策略警告。请参阅[扫描器输入](docs/scanner-inputs.md)。 列出捆绑示例和测试涵盖的扫描器夹具系列： ``` mg scanners ``` ## 可选 AI AI 默认是关闭的。启用后，MaintainerGuard 仅将有限的、 经过脱敏处理的结构化报告发送到配置的 OpenAI Responses API endpoint，并设置 `store: false`。不受支持的 AI 声明将被丢弃，并且 AI 无法更改 确定性结论、风险等级或阻止性扫描器决策。 请参阅[隐私和安全](docs/privacy-and-security.md)。 ## 开发 ``` python3 -m unittest discover -s tests -v python3 -m compileall -q maintainerguard python3 -m pip wheel . --no-deps mg verify ``` 贡献者文档： - [文档索引](docs/README.md) - [示例指南](examples/README.md) - [开发指南](docs/development.md) - [架构说明](docs/architecture.md) - [发布材料](docs/launch.md) - [公开发布检查清单](docs/public-launch-checklist.md) - [公开发版检查清单](docs/public-release-checklist.md) - [贡献指南](CONTRIBUTING.md) - [支持](SUPPORT.md) - [安全策略](SECURITY.md) 只要专注且有证据支持，欢迎提供良好的首次贡献： - [良好的首次 Issue](https://github.com/xxxquide/MaintainerGuard/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22) - [维护者反馈讨论](https://github.com/xxxquide/MaintainerGuard/discussions) - [扫描器适配器请求](https://github.com/xxxquide/MaintainerGuard/issues/new/choose) ## 项目状态和局限性 这是一个本地优先的开源工具。它分析提供的元数据、更改的 文件路径、有限的 patch 文本、扫描器输出和策略配置。它 不执行不受信任的仓库代码，不证明安全性，不进行未经授权的扫描 仓库，不自动合并更改，也不提供托管服务。 GitHub 支持涵盖事件分析、有限的 PR 文件检索、dry-run 输出 和受保护的 update-one-comment 发布。发布和 Issue 输入在此版本中是本地的 JSON feed。 请参阅[路线图](docs/roadmap.md)。 ## 许可证 Apache-2.0。MaintainerGuard 是人类维护者的辅助工具。其报告可能 不完整或有误，绝不能视为安全保证或自动 合并决策。

标签：AI辅助, DevSecOps, Python, Python安全, 上游代理, 云安全监控, 代码审查, 开源项目维护, 无后门, 静态分析