git-security-tool 0.1.0__tar.gz

git_security_tool-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # for the SARIF upload
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: pip install -e ".[scanners,dev]"
+
+      - name: Install gitleaks
+        run: |
+          url=$(curl -s https://api.github.com/repos/gitleaks/gitleaks/releases/latest \
+            | grep -o 'https://[^"]*linux_x64\.tar\.gz' | head -1)
+          curl -sL "$url" | tar xz -C /usr/local/bin gitleaks
+          gitleaks version
+
+      - name: Lint
+        run: |
+          ruff check src tests
+          ruff format --check src tests
+
+      - name: Test
+        run: pytest -q
+
+      - name: Self-scan (full repo)
+        run: git-security-tool scan --all
+
+      - name: SARIF report
+        if: always()
+        run: git-security-tool scan --all --format sarif > results.sarif || true
+
+      - name: Upload SARIF to code scanning
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif

git_security_tool-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: release
+
+# Publishes to PyPI on a version tag (v*), using PyPI Trusted Publishing
+# (OIDC) - no API token stored as a secret.
+#
+# One-time setup on pypi.org:
+#   Project "git-security-tool" -> Publishing -> add a trusted publisher:
+#     owner: MustafaBasit521 · repo: commit-guard
+#     workflow: release.yml · environment: pypi
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

git_security_tool-0.1.0/.github/workflows/scan.reusable.yml

@@ -0,0 +1,46 @@
+name: git-security-tool scan
+
+# Reusable workflow. Other repos call it with:
+#
+#   jobs:
+#     security:
+#       uses: MustafaBasit521/commit-guard/.github/workflows/scan.reusable.yml@main
+#
+# Pin @v0.1.0 (or a commit SHA) instead of @main once the tool is tagged, so a
+# change to the tool can't unexpectedly break a downstream project's CI.
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: "git-security-tool version, branch, or SHA to install"
+        type: string
+        default: main
+      python-version:
+        type: string
+        default: "3.12"
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Install git-security-tool
+        run: >
+          pip install "git-security-tool[scanners] @
+          git+https://github.com/MustafaBasit521/commit-guard.git@${{ inputs.ref }}"
+
+      - name: Install gitleaks
+        run: |
+          url=$(curl -s https://api.github.com/repos/gitleaks/gitleaks/releases/latest \
+            | grep -o 'https://[^"]*linux_x64\.tar\.gz' | head -1)
+          curl -sL "$url" | tar xz -C /usr/local/bin gitleaks
+          gitleaks version
+
+      - name: Scan
+        run: git-security-tool scan --all

git_security_tool-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.pyc
+
+# Virtual environments
+.venv/
+venv/
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.git-security-tool.toml

git_security_tool-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,279 @@
+# git-security-tool — Architecture
+
+This is the as-built reference. It also doubles as a design retrospective:
+each section explains **what** a piece does and **why** it ended up that way.
+For usage, see `README.md`.
+
+---
+
+## 1. What it is
+
+A local Git **pre-commit gate** for Linux. On `git commit` it scans the
+*staged* changes; if policy says a finding is serious enough, the commit is
+aborted (`exit 1`). The same engine runs in CI over the whole repo.
+
+It is an **orchestration layer**, not a scanner. Detection is delegated to
+three mature tools; this project decides what to scan, runs them, normalizes
+their output, applies policy, and reports.
+
+```
+git commit
+  └─► .git/hooks/pre-commit  (3-line shell shim)
+       └─► git-security-tool scan
+            ├─ ruff check         → lint            (LOW  → warn)
+            ├─ ruff format --check → formatting     (LOW  → warn)
+            ├─ semgrep + 17 rules → insecure code   (HIGH/MEDIUM)
+            └─ gitleaks           → secrets         (CRITICAL → block)
+                 └─► policy.evaluate() → Decision
+                      └─► exit 0 (allow) | exit 1 (block)
+```
+
+Core design rule, held throughout: **the exit code is the entire control
+mechanism.** Everything else is logic for choosing between `0` and `1`.
+
+---
+
+## 2. Package layout
+
+```
+src/git_security/
+├── __main__.py         python -m git_security  → cli.main()
+├── cli.py              argparse; dispatch to an action; return an exit code
+├── scan.py             the pipeline: gather → scan → policy → report → exit
+│
+├── git/
+│   ├── repository.py   run_git() — the ONLY place that shells to git
+│   ├── diff.py         staged files, staged diff, materialize_staged, ls-files
+│   └── hooks.py        resolve this repo's hooks dir / pre-commit path
+│
+├── scanners/
+│   ├── base.py         run_tool() (missing-tool tolerant), to_repo_relative()
+│   ├── ruff.py         run_ruff (lint) + run_ruff_format  → list[Finding]
+│   ├── gitleaks.py     run_gitleaks(staged=…)             → list[Finding]
+│   └── semgrep.py      run_semgrep(files, root, rules_dir) → list[Finding]
+│
+├── models/finding.py   Severity (IntEnum) + Finding (frozen dataclass)
+├── policy/engine.py    PolicyConfig, Decision, evaluate()
+├── config/loader.py    .git-security-tool.toml → Config (+ ConfigError)
+├── ignore.py           glob/prefix path-ignore matching
+├── baseline.py         suppress findings already recorded in a baseline file
+│
+├── reporter/
+│   ├── terminal.py     Decision → human text
+│   └── sarif.py        findings → SARIF 2.1.0 JSON (for CI code scanning)
+│
+├── installer/
+│   ├── git_hook.py     install / uninstall / status; the managed hook text
+│   └── dependencies.py which scanners are on PATH
+│
+├── suggestions/
+│   ├── llm.py          optional AI explanation of blocking findings
+│   └── providers.py    AnthropicProvider, GeminiProvider (same 4 methods)
+│
+└── rules/semgrep/*.yml  17 bundled rules, shipped as package data
+```
+
+**Why a package and not one file:** every module has one job and one reason
+to change. `cli.py` reads like a table of contents; `scan.py` is pure
+orchestration; each scanner owns exactly one tool's quirks. Adding a
+capability is usually one new module + one line in `scan.py`.
+
+---
+
+## 3. The data flow
+
+### 3.1 Get the files
+
+`git/diff.py` provides three sources:
+
+| function | used by | returns |
+|---|---|---|
+| `get_staged_files()` | pre-commit (`scan`) | staged paths, `--diff-filter=ACM` (no deletions) |
+| `get_tracked_files()` | CI (`scan --all`) | `git ls-files` |
+| `materialize_staged(files, dest)` | pre-commit only | writes the **index** blob content into a temp dir via `git checkout-index` |
+
+**Why `materialize_staged`:** a commit is built from the *index*, not the
+working tree. Stage `x.py`, edit it again, and a working-tree scan would
+flag code that isn't being committed *and* miss code that is — the dangerous
+direction for a security gate. So `scan` (staged mode) copies the exact
+staged bytes to a throwaway dir and scans that. `scan --all` has no "staged"
+concept, so it scans the working tree in place. Gitleaks is Git-aware and
+scans the index itself (`gitleaks git --staged`), so it never needs the
+temp dir.
+
+`_copy_project_config()` also drops the repo's `pyproject.toml` / `ruff.toml`
+into the temp dir — scanners resolve config by walking up from each file, and
+a bare temp dir would make Ruff silently use built-in defaults.
+
+### 3.2 Run the scanners
+
+`scan._collect_findings(scope)` runs each enabled scanner through
+`_safe_scan()` — a wrapper that turns a scanner crash (`RuntimeError`) into
+a printed message + empty list, so one broken tool doesn't take down the
+commit with a traceback. A scanner that isn't installed is skipped silently
+by `base.run_tool()` returning `None`.
+
+### 3.3 Normalize — the `Finding` model
+
+```python
+@dataclass(frozen=True)
+class Finding:
+    tool: str; rule: str; severity: Severity
+    file: str; line: int; message: str
+```
+
+Each scanner's `_to_finding()` converts its tool's native JSON into this.
+The three tools emit wildly different shapes:
+
+| | Ruff | Gitleaks | Semgrep |
+|---|---|---|---|
+| path key | `filename` (absolute) | `File` (relative) | `path` |
+| line | `location.row` | `StartLine` | `start.line` |
+| rule | `code` (can be null) | `RuleID` | `check_id` (path-namespaced) |
+| severity | *(none — assigned)* | *(none — CRITICAL)* | `extra.severity` (ERROR/WARNING/INFO) |
+
+Absorbing that asymmetry in one place per scanner is the whole point — from
+here on, policy and reporting see only `Finding`.
+
+`Severity` is an `IntEnum` so policy can write `f.severity >= threshold`
+directly (it's `4 >= 3` underneath) while still being a typo-proof named
+constant.
+
+### 3.4 Baseline + ignores
+
+Before policy:
+
+- `ignore.filter_ignored()` drops files matching `[ignore] paths` patterns
+  (`tests/fixtures/`, `*.generated.py`, …). Gitleaks findings are filtered
+  after the fact since it scans everything.
+- `baseline.apply_baseline()` removes findings whose
+  `(tool, rule, file, message)` fingerprint is already in
+  `.git-security-tool-baseline.json`. This lets an established repo adopt the
+  tool without a big-bang cleanup: existing issues are grandfathered, new
+  ones still block. The fingerprint deliberately excludes line number so
+  unrelated edits don't resurface a baselined finding.
+
+### 3.5 Policy
+
+```python
+def evaluate(findings, config) -> Decision:
+    blocking = [f for f in findings if f.severity >= config.block_threshold]
+    warnings = [f for f in findings if f.severity <  config.block_threshold]
+    return Decision(blocked=bool(blocking), blocking=..., warnings=...)
+```
+
+One pure function. No printing, no `sys.exit`, no subprocess — which is why
+it's trivially unit-tested with fake `Finding`s. `block_threshold` defaults
+to `HIGH` (secrets + RCE-class patterns block; style warns) and is
+overridable per repo.
+
+**Why a whole module for ten lines:** it is the single place blocking
+behaviour is defined. Per-directory thresholds, per-rule allowlists,
+"never block on Fridays" — all of that would land here, and scanners /
+`scan.py` wouldn't change.
+
+### 3.6 Report + exit
+
+- text mode → `reporter/terminal.py` groups warnings then blocking findings,
+  sorted by `(file, line, tool)`, long messages collapsed to one line.
+- sarif mode (`--format sarif`) → `reporter/sarif.py` prints SARIF 2.1.0 to
+  **stdout** (progress goes to stderr so the JSON is clean); CI uploads it
+  to GitHub code scanning.
+
+Then `run_scan` returns `0` or `1`. In staged mode, `GIT_SECURITY_NO_BLOCK=1`
+forces `0` while still reporting — the dev escape hatch (distinct from
+`git commit --no-verify`, which skips the hook entirely).
+
+---
+
+## 4. The other entry points
+
+- **`git-security-tool install`** — `installer/git_hook.py` writes a 3-line
+  shell shim to this repo's hooks dir (resolved via
+  `git rev-parse --git-path hooks`, so `core.hooksPath` / worktrees work).
+  The shim carries a marker comment; `install` refuses to overwrite a hook
+  it didn't write unless `--force`, and `uninstall` only removes its own.
+- **`git-security-tool baseline`** — runs a full-repo scan and writes every
+  current finding to the baseline file.
+- **`git-security-tool check`** — is the hook installed, which scanners are
+  present.
+
+---
+
+## 5. Optional AI suggestions
+
+Off by default. Enabled only when `[ai] enabled = true` **and** the provider's
+API key is set. `providers.py` has `AnthropicProvider` and `GeminiProvider`
+behind one 4-method shape (`name`, `default_model`, `available()`,
+`complete()`); `[ai] provider` picks one. Gemini uses stdlib `urllib` (no
+dependency); Anthropic needs `pip install ".[ai]"`.
+
+Guarantees: it never changes the block decision, never writes files,
+announces before sending code to the API, and **never sends a file Gitleaks
+flagged** (a secret could be in the surrounding snippet).
+
+---
+
+## 6. Two defense layers
+
+| | local | CI |
+|---|---|---|
+| trigger | `git commit` | `git push` / PR |
+| command | `git-security-tool scan` (staged) | `git-security-tool scan --all` |
+| bypass | `--no-verify`, or not installed | none |
+| purpose | fast feedback, before it's in history | enforcement nobody can skip |
+
+`.github/workflows/scan.reusable.yml` is a `workflow_call` reusable workflow
+so downstream repos reference it in three lines instead of copy-pasting.
+
+---
+
+## 7. Build history — milestone by milestone
+
+Each milestone was: explain the concept → smallest implementation → explain
+the code → test → next. The lesson each one carried:
+
+| # | Milestone | What it established |
+|---|---|---|
+| 1 | Hook runs a Python program | Git finds an executable `pre-commit`; exit 0/non-zero is the whole gate; hooks aren't version-controlled |
+| 2 | `subprocess` captures staged changes | argument lists (never `shell=True`); `git diff --cached` ≠ `git diff`; `CompletedProcess` |
+| 3 | Ruff wrapper | linter exit codes (1 = "found issues" is normal, not failure); JSON output over text scraping |
+| 4 | Gitleaks wrapper | a second tool with a different invocation model and a different JSON shape → motivates normalization |
+| 5 | `Finding` model + `scanners/base.py` | two concrete tool outputs = the right time to design the common one; extract the shared helper, keep the per-tool quirks |
+| 6 | Semgrep | source → AST → pattern match → structured finding; first tool with real severities; offline (`--metrics=off`) |
+| 7 | Policy engine | `Severity` becomes an ordered `IntEnum`; `evaluate()` is pure; **the exit code finally means something** |
+| 8 | Reporter module + pytest | pull presentation out of `main`; the pure policy/mapper code begs for tests |
+| 9 | Packaging | `pyproject.toml` (hatchling), `[project.scripts]` creates the command, rules ship as package data, `-e` editable install |
+| 10 | `install` / `uninstall` / `check` | the hook must be written per-repo; only ever touch a hook we created (marker + `--force`) |
+| 11 | Config file | `tomllib` (stdlib, 3.11+); reuse `PolicyConfig`; malformed config = clean message, not traceback |
+| 12 | Scan the staged blob | the accuracy bug: index vs working tree; `git checkout-index` to a temp dir; copy project config so scanners keep their settings |
+| 13 | Path ignores | `fnmatch` glob + directory prefix; filter Gitleaks findings after the fact |
+| 14 | `ruff format --check` | linting ≠ formatting; the tool must pass its own checks (reformatted the codebase) |
+| 15 | Optional AI | advisory only; opt-in; announce before sending; never send secret-bearing files |
+| — | Gemini provider | provider-pluggable behind one shape; stdlib `urllib` keeps core zero-dependency |
+| — | `scan --all` + CI | CI has no "staged" — scan tracked files in place; the second, unbypassable layer |
+| — | 17 Semgrep rules | injection / deserialization / crypto-TLS / web / filesystem-net; validated in CI |
+| — | Baseline + SARIF | adopt-on-a-dirty-repo; GitHub code-scanning integration |
+| — | Hardening | `ConfigError` handling, per-scanner isolation (`_safe_scan`), AI secret-leak guard, fixed Gitleaks 8.30 (`protect`/`detect` removed → `git --staged` / `dir`) |
+
+### Mistakes worth remembering
+
+- **`git reset --hard` on a commit that held real work** wiped milestone 7;
+  recovered from reflog. `--hard` discards commits *and* uncommitted changes.
+- **Staging a scratch file alongside real work** made the "undo the probe"
+  step also undo the milestone. Test with the probe unstaged, or `git add`
+  only the real files.
+- **`--amend` after pushing** diverged local/remote; fixed with
+  `push --force-with-lease` (safe here — solo repo).
+- **Ruff's shifting defaults** kept flagging our own code (`PLW1510`,
+  `TRY004`); fixed by pinning `[tool.ruff.lint] select`.
+
+---
+
+## 8. Scope boundaries
+
+Not in scope: dependency-CVE scanning, license checks, SBOM, IaC/container
+scanning, non-Python static analysis. The bundled Semgrep set is curated and
+small — not a replacement for the Semgrep registry or a full SAST platform.
+Kubernetes / microservices / a database were explicitly ruled out from day
+one and never needed.

git_security_tool-0.1.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# git-security-tool — Claude Code instructions
+
+A local Git **pre-commit gate** (Linux) that scans staged changes and blocks
+the commit on serious findings. It is an **orchestration layer** over Ruff,
+Semgrep, and Gitleaks — never reimplement what those tools do. Full design:
+`./ARCHITECTURE.md`. Usage: `./README.md`.
+
+## Status
+
+Built and working (milestone 15 + extras). Installed and dogfooded on a real
+project. Not yet tagged / published to PyPI.
+
+## Dev commands
+
+```bash
+pip install -e ".[scanners,dev]"          # tool + ruff + semgrep + pytest
+pytest                                     # ~50s (semgrep subprocess tests)
+ruff check src tests && ruff format --check src tests
+git-security-tool scan --all               # run the tool on this repo
+```
+
+Python 3.11+. Package import name `git_security`; CLI / PyPI name
+`git-security-tool`.
+
+## Hard rules (the tool must obey its own advice)
+
+- **Scan staged content, not the working tree** — `scan` materializes the
+  index into a temp dir. `git diff --cached`, never `git diff`.
+- **subprocess: argument lists only.** Never `shell=True`, never build a
+  command from untrusted input. `git/repository.py::run_git` is the only
+  place that shells to git.
+- **The exit code is the gate.** `run_scan` returns 0 (allow) or 1 (block);
+  nothing else decides.
+- **Policy lives in `policy/engine.py`.** Scanners assign a severity and stop;
+  they never decide blocking.
+- **AI is advisory** — off by default, opt-in, never changes the decision,
+  never writes files, never sends a Gitleaks-flagged file to the API.
+- **Never print/log secret values** (Gitleaks runs with `--redact`).
+- Keep `ruff check` and `ruff format --check` green on `src/` and `tests/`.
+
+## Conventions
+
+- One module, one job. New capability = new module + one line in `scan.py`.
+- Each scanner owns its tool's CLI flags, exit-code meaning, and JSON→Finding
+  mapping. Shared plumbing (`run_tool`, `to_repo_relative`) is in
+  `scanners/base.py`.
+- Config errors raise `ConfigError` → caught in `run_scan` → clean message,
+  no traceback.
+- A scanner crash is caught per-scanner (`_safe_scan`) — report it, continue.
+- Tests: pure logic (policy, mappers, config, ignore, baseline, sarif) has no
+  I/O; end-to-end tests use a real temp git repo; semgrep/gitleaks tests skip
+  if the tool isn't installed.
+
+## Out of scope
+
+Dependency-CVE scanning, license/SBOM, IaC/container scanning, non-Python
+static analysis, Kubernetes/microservices/databases. The bundled Semgrep set
+is intentionally small.
+
+## Working style (learning project)
+
+Incremental. For a new concept: explain what/why/how it fits → implement the
+smallest version → explain the key code → test → next. Surface any decision
+that affects architecture before acting. No large unexplained code dumps.

git_security_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Mustafa Basit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_security_tool-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: git-security-tool
+Version: 0.1.0
+Summary: Local Git security and code-quality gate that runs on pre-commit.
+Project-URL: Homepage, https://github.com/MustafaBasit521/commit-guard
+Project-URL: Issues, https://github.com/MustafaBasit521/commit-guard/issues
+Author: Muhammad Mustafa Basit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: git,gitleaks,pre-commit,sast,secrets,security,semgrep
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Provides-Extra: ai
+Requires-Dist: anthropic; extra == 'ai'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: scanners
+Requires-Dist: ruff; extra == 'scanners'
+Requires-Dist: semgrep; extra == 'scanners'
+Description-Content-Type: text/markdown
+
+# git-security-tool
+
+[![CI](https://github.com/MustafaBasit521/commit-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/MustafaBasit521/commit-guard/actions/workflows/ci.yml)
+
+A local Git **pre-commit gate** for Linux. It scans your *staged* changes and
+blocks the commit when it finds something serious — secrets, dangerous code
+patterns — while surfacing quality and formatting issues as warnings.
+
+It is an **orchestration layer**, not a new scanner: it runs
+[Gitleaks](https://github.com/gitleaks/gitleaks),
+[Semgrep](https://semgrep.dev/), and [Ruff](https://docs.astral.sh/ruff/),
+normalizes their output, applies your policy, and decides pass/block.
+
+```
+git commit
+   └─► .git/hooks/pre-commit
+        └─► git-security-tool scan
+             ├─ gitleaks   → secrets            (CRITICAL → blocks)
+             ├─ semgrep    → security patterns  (HIGH → blocks)
+             ├─ ruff check → lint               (LOW → warns)
+             └─ ruff format --check → format    (LOW → warns)
+                  └─► PASS (exit 0) / BLOCK (exit 1)
+```
+
+## Install
+
+```bash
+pip install "git-security-tool[scanners]"     # tool + ruff + semgrep
+cd your-repo
+git-security-tool install                     # writes .git/hooks/pre-commit
+```
+
+Latest unreleased version, straight from the repo:
+
+```bash
+pip install "git-security-tool[scanners] @ git+https://github.com/MustafaBasit521/commit-guard.git"
+```
+
+Gitleaks is a Go binary — install it separately if you want secret detection
+(the scan skips any tool that isn't on `PATH`).
+
+Commands: `scan [--all] [--format sarif]`, `baseline`, `install [--force]`,
+`uninstall`, `check`, `version`.
+
+- `scan` — staged changes (pre-commit)
+- `scan --all` — every tracked file (CI / audit); `--format sarif` emits SARIF
+  on stdout for GitHub code scanning
+- `baseline` — records current findings to `.git-security-tool-baseline.json`
+  so a repo can adopt the tool without fixing everything first; new issues
+  still block
+
+## What it checks
+
+| category | tool | severity | blocks by default |
+|---|---|---|---|
+| Secrets / credentials | Gitleaks (staged diff) | CRITICAL | yes |
+| Insecure code patterns (17 rules) | Semgrep + bundled rules | HIGH / MEDIUM | HIGH yes |
+| Lint (unused imports, undefined names, …) | `ruff check` | LOW | no |
+| Formatting | `ruff format --check` | LOW | no |
+
+The bundled Semgrep rules (`src/git_security/rules/semgrep/`) cover code/command
+injection (`eval`, `exec`, `os.system`, `shell=True`), unsafe deserialization
+(`pickle`, `yaml.load`, insecure XML), weak crypto & disabled TLS verification,
+web footguns (Flask `debug=True`, Jinja autoescape off, `mark_safe`), and
+filesystem/network hygiene (`extractall`, `mktemp`, `requests` without timeout).
+
+Semgrep/Ruff analysis is **Python only**; Gitleaks is language-agnostic.
+Scanners see the exact **staged** content, not your working tree.
+
+## Configuration — `.git-security-tool.toml` (optional, repo root)
+
+```toml
+[policy]
+block_threshold = "HIGH"          # INFO | LOW | MEDIUM | HIGH | CRITICAL
+
+[scanners]
+gitleaks = false                  # disable a scanner
+
+[ignore]
+paths = ["tests/fixtures/", "*.generated.py"]
+
+[ai]
+enabled = false                   # optional LLM remediation suggestions
+provider = "gemini"               # "anthropic" | "gemini"
+model = ""                        # blank = provider default
+max_findings = 3
+```
+
+**AI suggestions** are off by default and advisory only — they never affect
+the pass/block decision or modify files, they announce before sending code
+to the API, and secret-bearing files are never sent.
+
+| provider | key env var | extra install |
+|---|---|---|
+| `gemini` | `GEMINI_API_KEY` | none (stdlib HTTP) |
+| `anthropic` | `ANTHROPIC_API_KEY` | `pip install ".[ai]"` |
+
+## Overrides
+
+- `GIT_SECURITY_NO_BLOCK=1 git commit …` — run the scan, report, never block.
+- `git commit --no-verify` — skip the hook entirely (Git built-in).
+
+## Development
+
+```bash
+pip install -e ".[scanners,dev]"
+pytest
+ruff check src tests && ruff format --check src tests
+```
+
+## Scope / non-goals
+
+No dependency-CVE scanning, no license checks, no SBOM, no IaC/container
+scanning, no non-Python static analysis. The bundled Semgrep ruleset is
+curated and intentionally small — not a replacement for a full SAST platform
+or the Semgrep registry.
+
+## License
+
+MIT — see [LICENSE](LICENSE).