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

中英双语 · Bilingual | MIT License Inspired by the L1/L2/L3 layered security idea popularized by AI coding assistants (e.g. Qoder).

gitguard 让本机所有 git 仓库在提交/推送前自动做安全扫描，并支持 LLM 深度安全审查。 gitguard adds an automatic security scan before every git commit / push on your machine, plus optional LLM-powered deep security review (L2/L3).

---

✨ Features / 特性

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

📦 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 / 使用

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

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 (for 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 / 原理

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. 安装时把 pre-commit / pre-push 钩子装到 ~/.gitguard 并设置全局 core.hooksPath， 钩子调用 gitguard scan，命中规则即阻止提交/推送。

🛡 Security notes / 安全说明

• Rules live in security-patterns.yaml (edit to add your own; take effect immediately). 规则可自行增改，改完即生效。
• API keys are stored locally (config.json); keep the file permission-tight. 密钥仅存本机，注意文件权限。
• The scan is pattern-based; LLM review adds logic-level analysis (costs a few cents per call). 扫描=模式匹配；LLM 审查=逻辑分析（每次几分钱）。

🤝 Contributing / 参与

PRs welcome. This project's own commits/pushes are protected by gitguard itself (dogfooding). 欢迎 PR，本项目自己的提交也受 gitguard 保护（自举）。

📄 License

MIT — see LICENSE.

🙏 Credits

• Inspired by the layered security-review concept popularized by Qoder (design inspiration only; no code used). 灵感来自 Qoder 的分层安全审查思路（仅思路借鉴，未使用其代码）。
• Part of the DeepSeek Harness ecosystem (available as a Harness skill). 同时以 Harness 技能形式接入 DeepSeek Harness 生态。