Metadata-Version: 2.4
Name: dsh-gitguard
Version: 0.1.0
Summary: Git security upload guard: auto scan before commit/push (L1 rules) + LLM deep review (L2/L3)
Author: AlloyPlane
License: MIT
Keywords: git,security,secret-scan,pre-commit,hook
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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 / 安装

```bash
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 / 或安装为命令:
```bash
pip install .        # provides the `gitguard` command
gitguard install
```

## 🚀 Usage / 使用

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

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

```bash
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](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 生态。
