AlloyPlane/gitguard

gitguard — Git 安全上传防护 / Git Security Upload Guard

中英双语 · Bilingual  |  MIT License
灵感来自 AI 编程助手（如 Qoder）推广的 L1/L2/L3 分层安全理念。

gitguard 让本机所有 git 仓库在提交/推送前自动做安全扫描，并支持 LLM 深度安全审查。
gitguard 在你机器上的每次 git 提交 / 推送前自动进行安全扫描，
并可选配 LLM 驱动的深度安全审查（L2/L3）。

✨ 特性 / Features

| 中文 | EN |
|---|---|
| L1 规则扫描（自动） — pre-commit / pre-push 钩子按 security-patterns.yaml（14 条规则：密钥/AWS/私钥/SQL注入/eval…）扫描暂存区/全库，命中拦截 | L1 rule scan (automatic) — pre-commit / pre-push hooks scan staged/all files against security-patterns.yaml (14 rules: API keys, AWS, private keys, SQL-injection, eval, …) and block risky commits/pushes |
| L2/L3 LLM 审查（手动） — review 用任意 OpenAI 兼容模型审查 diff / 提交范围 / 全仓库，输出严重级别+修复建议 | L2/L3 LLM review (manual) — review reviews diff / commit range / whole repo with any OpenAI-compatible model, outputting severity + fix advice |
| 全局生效 — core.hooksPath 使本机所有仓库自动防护 | Global — core.hooksPath protects every repo on the machine |
| 零依赖 — 纯 Python 标准库，跨平台 | Zero dependency — pure Python stdlib, cross-platform |
| 交互选模型 — ① 用你当前正在用的模型 ② 自定义（地址/Key/模型三要素） | Interactive model choice — 1) current model from your config, 2) custom (address / key / model) |

📦 安装 / Install

git clone https://github.com/AlloyPlane/gitguard.git
cd gitguard
python gitguard.py install        # installs global hooks (core.hooksPath → ~/.gitguard)

或安装为命令 / Or install as a command:
pip install .        # provides the gitguard command
gitguard install

🚀 使用 / Usage

运行 review 时选择模型模式 / Run review and choose a model mode:

gitguard security review mode:
[1] Use your current model (deepseek-v4-pro)     ← 用你正在用的模型，回车即用
[2] Custom model (address / API key / model)     ← 自定义，填三要素

gitguard scan                    # scan all tracked files (also run by pre-push hook)
gitguard scan --staged           # scan staged files (also run by pre-commit hook)
gitguard review --diff           # L2: review uncommitted changes (LLM)
gitguard review --commits A..B   # L3: review a commit range
gitguard review --all            # L3: review whole repo (sampled)
gitguard config                  # save custom model settings (address/key/model)
gitguard status                  # show hook & rule status
gitguard uninstall               # remove global hooks

🔑 API Key（用于 L2/L3）

优先级 / Priority: CLI args > env (DEEPSEEK_API_KEY / OPENAI_API_KEY) > ~/.gitguard/config.json > ~/.kic-ai/config.json (your current model)。

⚙️ 原理 / How it works

安装时把 pre-commit / pre-push 钩子装到 ~/.gitguard 并设置全局 core.hooksPath，
钩子调用 gitguard scan，命中规则即阻止提交/推送。
install copies pre-commit / pre-push hooks to ~/.gitguard and sets the global
core.hooksPath. Hooks call gitguard scan; rule hits block the commit/push.

🛡 安全说明 / Security notes
- 规则位于 security-patterns.yaml（可自行编辑添加；立即生效）。规则可自行增改，改完即生效。
- API 密钥存储在本地（config.json）；请保持文件权限严格。密钥仅存本机，注意文件权限。
- 扫描基于模式匹配；LLM 审查增加逻辑层面的分析（每次调用花费几分钱）。扫描=模式匹配；LLM 审查=逻辑分析（每次几分钱）。

🤝 贡献 / 参与

欢迎提交 PR。本项目自身的提交/推送由 gitguard 自身保护（自举）。欢迎 PR，本项目自己的提交也受 gitguard 保护（自举）。

📄 许可证

MIT — 参见 LICENSE。

🙏 致谢

- 灵感来自 Qoder 推广的分层安全审查理念（仅为设计灵感；未使用其代码）。
灵感来自 Qoder 的分层安全审查思路（仅思路借鉴，未使用其代码）。
- 属于 DeepSeek Harness 生态系统的一部分（可作为 Harness 技能使用）。同时以 Harness 技能形式接入 DeepSeek Harness 生态。