git-security-tool 0.1.1__tar.gz → 0.2.0__tar.gz

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/.gitignore

@@ -15,3 +15,6 @@ dist/
 .pytest_cache/
 .ruff_cache/
 .git-security-tool.toml
+CLAUDE.md
+LEARNING.md
+CONCEPTS.md

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/ARCHITECTURE.md

@@ -195,9 +195,19 @@ forces `0` while still reporting — the dev escape hatch (distinct from
   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 fetch-gitleaks`** — `installer/fetch.py` downloads the
+  Gitleaks release for this OS/arch, verifies its SHA-256 against the release
+  checksums file, and installs it in `MANAGED_BIN_DIR`
+  (`~/.local/share/git-security-tool/bin/`). Gitleaks is a Go binary, so pip
+  can't ship it.
 - **`git-security-tool check`** — is the hook installed, which scanners are
   present.
 
+**Scanner resolution** (`scanners/base.py::resolve_scanner`) — each wrapper
+calls a tool by bare name; `run_tool` resolves it in order: `MANAGED_BIN_DIR`
+→ next to `sys.executable` (so `ruff`/`semgrep` from the `[scanners]` extra
+are found even inside a pipx-isolated venv that isn't on `PATH`) → `PATH`.
+
 ---
 
 ## 5. Optional AI suggestions

git_security_tool-0.2.0/INSTALL.md

@@ -0,0 +1,295 @@
+# Installing and using git-security-tool
+
+A detailed, step-by-step guide. If you just want the short version, see the
+["Add it to a project"](README.md#add-it-to-a-project) section of the README.
+
+Two commands to set up your machine, then one command per repository:
+
+1. `pipx install "git-security-tool[scanners]"` — the tool + Ruff + Semgrep.
+2. `git-security-tool fetch-gitleaks` — downloads the Gitleaks binary for
+   secret detection.
+3. `git-security-tool install` — run once inside each Git repo you want
+   protected.
+
+---
+
+## Step 0 — Check the prerequisites
+
+You need **Python 3.11 or newer** and **Git**. Check:
+
+```bash
+python3 --version      # must be 3.11.x or higher
+git --version
+```
+
+If Python is older than 3.11, install a newer one (`sudo apt install
+python3.12` on Ubuntu, or use [pyenv](https://github.com/pyenv/pyenv)).
+
+---
+
+## Step 1 — Install the tool
+
+The pre-commit hook calls `git-security-tool` by name, so it must be on your
+`PATH` permanently. **pipx** does this cleanly — it installs the tool in its
+own isolated environment and exposes just the command.
+
+### Recommended — pipx
+
+```bash
+# install pipx itself, once
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+# close and reopen your terminal so PATH updates
+
+# install the tool - the [scanners] extra also brings Ruff + Semgrep
+pipx install "git-security-tool[scanners]"
+```
+
+You do **not** need to install Ruff or Semgrep separately. They come with the
+`[scanners]` extra, and the tool finds them next to its own interpreter even
+though the pipx environment isn't on your `PATH`.
+
+### Alternative — pip into an always-active virtualenv
+
+```bash
+python3 -m venv ~/.venvs/tools && source ~/.venvs/tools/bin/activate
+pip install "git-security-tool[scanners]"
+```
+
+Only use this if that venv is active in every shell where you run `git
+commit` (add the `source` line to `~/.bashrc`).
+
+### Verify
+
+```bash
+git-security-tool version      # e.g. git-security-tool 0.2.0
+```
+
+If you get `command not found`, reopen your terminal (pipx just changed
+`PATH`), or run `python3 -m pipx ensurepath` again.
+
+---
+
+## Step 2 — Get Gitleaks (for secret detection)
+
+Gitleaks is a Go binary, not a Python package. One command downloads it:
+
+```bash
+git-security-tool fetch-gitleaks
+```
+
+This detects your OS and CPU, downloads the matching release from GitHub,
+**verifies its SHA-256 checksum**, and installs it in
+`~/.local/share/git-security-tool/bin/`. Output:
+
+```
+[git-security-tool] downloading gitleaks_8.30.1_linux_x64.tar.gz ...
+[git-security-tool] sha-256 verified
+[git-security-tool] installed gitleaks 8.30.1 -> ~/.local/share/git-security-tool/bin/gitleaks
+[git-security-tool] secret scanning is now active
+```
+
+The tool works without Gitleaks — it just can't catch leaked API keys /
+tokens then.
+
+### Verify everything is visible
+
+```bash
+git-security-tool check
+```
+
+You'll see which scanners are present:
+
+```
+[git-security-tool] pre-commit hook: not installed
+[git-security-tool] scanners:
+  ruff: ok
+  gitleaks: ok
+  semgrep: ok
+```
+
+Any `missing` here just means that check is skipped — install it if you want
+that coverage.
+
+---
+
+## Step 3 — Turn on the hook in a repository
+
+Do this **once per repo** (the hook lives in `.git/hooks/`, which is not
+committed, so a fresh `git clone` needs this again).
+
+```bash
+cd ~/path/to/your-project
+git-security-tool install
+```
+
+Output:
+
+```
+[git-security-tool] installed pre-commit hook at .../.git/hooks/pre-commit
+  ruff: ok
+  gitleaks: ok
+  semgrep: ok
+```
+
+If the repo already has a pre-commit hook that this tool didn't create, it
+will refuse and tell you to re-run with `--force` (which replaces it).
+
+---
+
+## Step 4 — See it work
+
+Now every `git commit` runs the scan first.
+
+```bash
+# make a file with an obvious problem
+printf 'eval(input())\n' > _probe.py
+git add _probe.py
+git commit -m "test"
+```
+
+Expected — the commit is **blocked**:
+
+```
+[git-security-tool] pre-commit security scan
+[git-security-tool] 1 file(s) to scan
+[git-security-tool] 1 blocking finding(s):
+  [HIGH] semgrep:python-dangerous-eval _probe.py:1 - eval() executes arbitrary
+  code from its argument ...
+[git-security-tool] commit blocked - fix the blocking findings above, or set
+GIT_SECURITY_NO_BLOCK=1 to override
+```
+
+Clean up the probe:
+
+```bash
+git restore --staged _probe.py && rm _probe.py
+```
+
+A normal commit with no problems just passes through with
+`commit allowed`.
+
+---
+
+## Step 5 — Adopting an existing project (optional but recommended)
+
+An older codebase probably has findings already. You don't want to be blocked
+on day one for issues you didn't just write.
+
+```bash
+cd ~/path/to/your-project
+
+# 1. see what's there
+git-security-tool scan --all
+
+# 2. if there's a lot, record it as a "baseline" - those get grandfathered
+git-security-tool baseline
+
+# 3. commit the baseline file
+git add .git-security-tool-baseline.json
+git commit -m "add git-security-tool baseline"
+```
+
+From now on, **new** problems block; the recorded ones are ignored. As you
+fix them, regenerate the baseline (`git-security-tool baseline` again) to
+shrink it.
+
+---
+
+## Step 6 — Configuration (optional)
+
+Create `.git-security-tool.toml` in the repo root:
+
+```toml
+[policy]
+# what severity blocks a commit. HIGH (default) blocks secrets + RCE-class
+# code. Use "CRITICAL" to only block secrets while you get used to it.
+block_threshold = "HIGH"
+
+[scanners]
+# turn a scanner off entirely
+# gitleaks = false
+
+[ignore]
+# skip generated code, migrations, vendored libraries, fixtures
+paths = ["migrations/", "vendor/", "tests/fixtures/", "*.generated.py"]
+
+[ai]
+# optional: ask an LLM to explain and suggest a fix for blocking findings.
+# off by default. also needs an API key in your environment.
+enabled = false
+provider = "gemini"          # or "anthropic"
+```
+
+Commit this file — it's meant to be shared across the team.
+
+---
+
+## Step 7 — Add the CI check
+
+The local hook can be skipped (`git commit --no-verify`) or simply not
+installed on a teammate's machine. CI is the layer nobody can bypass.
+
+Create `.github/workflows/security.yml` in your project:
+
+```yaml
+name: security
+on: [push, pull_request]
+
+jobs:
+  security:
+    uses: MustafaBasit521/commit-guard/.github/workflows/scan.reusable.yml@main
+```
+
+Commit and push it. GitHub will run `git-security-tool scan --all` over the
+whole repo on every push and pull request, and the check fails if there's a
+blocking finding.
+
+---
+
+## Troubleshooting
+
+**`git commit` doesn't run any scan / no `[git-security-tool]` output**
+The hook isn't installed, or the tool isn't on `PATH` in that shell. Run
+`git-security-tool check` and `which git-security-tool`. If `check` says
+"not installed", run `git-security-tool install`.
+
+**Hook prints "git-security-tool not on PATH - skipping scan"**
+The hook ran but couldn't find the command itself. This happens if you
+installed into a virtualenv that isn't active, or `~/.local/bin` isn't on
+`PATH`. Use pipx (Step 1), or add the install location to `~/.bashrc`.
+
+**`check` says `ruff: missing` or `semgrep: missing` after installing**
+You installed without the `[scanners]` extra. Reinstall:
+`pipx install --force "git-security-tool[scanners]"`. You should *not* need
+to install Ruff or Semgrep separately — the tool locates them next to its
+own interpreter.
+
+**`check` says `gitleaks: missing`**
+Run `git-security-tool fetch-gitleaks`.
+
+**Committing from VS Code / a Git GUI does nothing**
+GUI apps sometimes don't inherit your shell `PATH`. Install with pipx so the
+command lives in `~/.local/bin`, restart the app, and make sure that
+directory is on the system `PATH`.
+
+**`command not found: git-security-tool` right after installing**
+Reopen your terminal (pipx updates `PATH` in a way the current shell hasn't
+picked up), or run `python3 -m pipx ensurepath` again.
+
+**A commit is blocked and I need to commit anyway (emergency)**
+```bash
+GIT_SECURITY_NO_BLOCK=1 git commit -m "..."   # runs the scan, reports, doesn't block
+git commit --no-verify -m "..."               # skips the hook entirely
+```
+Use these sparingly — CI will still catch it.
+
+**Remove the tool from a repo**
+```bash
+git-security-tool uninstall
+```
+
+**Uninstall completely**
+```bash
+pipx uninstall git-security-tool     # or: pip uninstall git-security-tool
+```

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-security-tool
-Version: 0.1.1
+Version: 0.2.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
@@ -72,26 +72,78 @@ $ git commit -m "add config loader"
 GIT_SECURITY_NO_BLOCK=1 to override
 ```
 
-## Install
+## Add it to a project
+
+> New to this? [**INSTALL.md**](INSTALL.md) is a slower, detailed walkthrough
+> with expected output and troubleshooting. The steps below are the short
+> version.
+
+### 1. Install (once per machine)
+
+```bash
+pipx install "git-security-tool[scanners]"   # the tool + ruff + semgrep, bundled
+git-security-tool fetch-gitleaks             # downloads the Gitleaks binary (SHA-256 verified)
+git-security-tool check                      # confirm all three scanners show "ok"
+```
+
+[pipx](https://pipx.pypa.io/) keeps the command on your `PATH` in an isolated
+environment. `pip install "git-security-tool[scanners]"` into an
+always-active virtualenv works too. `ruff` and `semgrep` come with the
+`[scanners]` extra and the tool finds them automatically — even inside the
+pipx venv. Gitleaks is a Go binary, so `fetch-gitleaks` pulls it into
+`~/.local/share/git-security-tool/bin/`; the scan skips it if you don't.
+
+### 2. Turn on the hook (once per repo)
 
 ```bash
-pip install "git-security-tool[scanners]"     # tool + ruff + semgrep
 cd your-repo
-git-security-tool install                     # writes .git/hooks/pre-commit
+git-security-tool install               # writes .git/hooks/pre-commit
+```
+
+`.git/hooks/` is not version-controlled, so every clone / machine runs this
+once. `git-security-tool uninstall` removes it; `--force` replaces a hook
+you didn't create.
+
+### 3. (existing repo) Baseline what's already there
+
+```bash
+git-security-tool scan --all            # see what it finds first
+git-security-tool baseline              # grandfather those findings
+git add .git-security-tool-baseline.json && git commit -m "add security baseline"
+```
+
+New issues still block — only the pre-existing ones are ignored.
+
+### 4. Add the CI check
+
+Local hooks can be skipped (`--no-verify`) or missing on a teammate's
+machine, so CI is the real enforcement. Create
+`.github/workflows/security.yml`:
+
+```yaml
+name: security
+on: [push, pull_request]
+jobs:
+  security:
+    uses: MustafaBasit521/commit-guard/.github/workflows/scan.reusable.yml@main
 ```
 
-Gitleaks is a Go binary — [install it](https://github.com/gitleaks/gitleaks#installing)
-separately for secret detection (the scan skips any tool that isn't on `PATH`).
+That reusable workflow installs the tool + Gitleaks and runs
+`git-security-tool scan --all` over the whole repo.
 
-Commands: `scan [--all] [--format sarif]`, `baseline`, `install [--force]`,
-`uninstall`, `check`, `version`.
+### 5. (optional) Tune it — `.git-security-tool.toml`
+
+See [Configuration](#configuration--git-security-tooltoml-optional-repo-root)
+below: severity threshold, disable a scanner, ignore paths, AI suggestions.
+
+---
+
+**Commands:** `scan [--all] [--format sarif]`, `baseline`, `fetch-gitleaks`,
+`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 an existing repo can adopt the tool without fixing everything first;
-  new issues still block
 
 Verify the ruleset end to end: `./scripts/probe.sh` (checks all 17 rules +
 secret detection in a throwaway repo).
@@ -142,21 +194,6 @@ to the API, and secret-bearing files are never sent.
 | `gemini` | `GEMINI_API_KEY` | none (stdlib HTTP) |
 | `anthropic` | `ANTHROPIC_API_KEY` | `pip install "git-security-tool[ai]"` |
 
-## CI (the second layer)
-
-Local hooks can be skipped (`--no-verify`) or simply not installed on a
-teammate's machine, so CI is the enforcement layer. This repo ships a
-reusable workflow:
-
-```yaml
-# .github/workflows/security.yml in your project
-name: security
-on: [push, pull_request]
-jobs:
-  security:
-    uses: MustafaBasit521/commit-guard/.github/workflows/scan.reusable.yml@main
-```
-
 ## Overrides
 
 - `GIT_SECURITY_NO_BLOCK=1 git commit …` — run the scan, report, never block.

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/README.md

@@ -43,26 +43,78 @@ $ git commit -m "add config loader"
 GIT_SECURITY_NO_BLOCK=1 to override
 ```
 
-## Install
+## Add it to a project
+
+> New to this? [**INSTALL.md**](INSTALL.md) is a slower, detailed walkthrough
+> with expected output and troubleshooting. The steps below are the short
+> version.
+
+### 1. Install (once per machine)
+
+```bash
+pipx install "git-security-tool[scanners]"   # the tool + ruff + semgrep, bundled
+git-security-tool fetch-gitleaks             # downloads the Gitleaks binary (SHA-256 verified)
+git-security-tool check                      # confirm all three scanners show "ok"
+```
+
+[pipx](https://pipx.pypa.io/) keeps the command on your `PATH` in an isolated
+environment. `pip install "git-security-tool[scanners]"` into an
+always-active virtualenv works too. `ruff` and `semgrep` come with the
+`[scanners]` extra and the tool finds them automatically — even inside the
+pipx venv. Gitleaks is a Go binary, so `fetch-gitleaks` pulls it into
+`~/.local/share/git-security-tool/bin/`; the scan skips it if you don't.
+
+### 2. Turn on the hook (once per repo)
 
 ```bash
-pip install "git-security-tool[scanners]"     # tool + ruff + semgrep
 cd your-repo
-git-security-tool install                     # writes .git/hooks/pre-commit
+git-security-tool install               # writes .git/hooks/pre-commit
+```
+
+`.git/hooks/` is not version-controlled, so every clone / machine runs this
+once. `git-security-tool uninstall` removes it; `--force` replaces a hook
+you didn't create.
+
+### 3. (existing repo) Baseline what's already there
+
+```bash
+git-security-tool scan --all            # see what it finds first
+git-security-tool baseline              # grandfather those findings
+git add .git-security-tool-baseline.json && git commit -m "add security baseline"
+```
+
+New issues still block — only the pre-existing ones are ignored.
+
+### 4. Add the CI check
+
+Local hooks can be skipped (`--no-verify`) or missing on a teammate's
+machine, so CI is the real enforcement. Create
+`.github/workflows/security.yml`:
+
+```yaml
+name: security
+on: [push, pull_request]
+jobs:
+  security:
+    uses: MustafaBasit521/commit-guard/.github/workflows/scan.reusable.yml@main
 ```
 
-Gitleaks is a Go binary — [install it](https://github.com/gitleaks/gitleaks#installing)
-separately for secret detection (the scan skips any tool that isn't on `PATH`).
+That reusable workflow installs the tool + Gitleaks and runs
+`git-security-tool scan --all` over the whole repo.
 
-Commands: `scan [--all] [--format sarif]`, `baseline`, `install [--force]`,
-`uninstall`, `check`, `version`.
+### 5. (optional) Tune it — `.git-security-tool.toml`
+
+See [Configuration](#configuration--git-security-tooltoml-optional-repo-root)
+below: severity threshold, disable a scanner, ignore paths, AI suggestions.
+
+---
+
+**Commands:** `scan [--all] [--format sarif]`, `baseline`, `fetch-gitleaks`,
+`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 an existing repo can adopt the tool without fixing everything first;
-  new issues still block
 
 Verify the ruleset end to end: `./scripts/probe.sh` (checks all 17 rules +
 secret detection in a throwaway repo).
@@ -113,21 +165,6 @@ to the API, and secret-bearing files are never sent.
 | `gemini` | `GEMINI_API_KEY` | none (stdlib HTTP) |
 | `anthropic` | `ANTHROPIC_API_KEY` | `pip install "git-security-tool[ai]"` |
 
-## CI (the second layer)
-
-Local hooks can be skipped (`--no-verify`) or simply not installed on a
-teammate's machine, so CI is the enforcement layer. This repo ships a
-reusable workflow:
-
-```yaml
-# .github/workflows/security.yml in your project
-name: security
-on: [push, pull_request]
-jobs:
-  security:
-    uses: MustafaBasit521/commit-guard/.github/workflows/scan.reusable.yml@main
-```
-
 ## Overrides
 
 - `GIT_SECURITY_NO_BLOCK=1 git commit …` — run the scan, report, never block.

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/src/git_security/__init__.py

@@ -1,3 +1,3 @@
 """git-security-tool: a local Git security and code-quality gate."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/src/git_security/cli.py

@@ -8,6 +8,7 @@ for the handful of subcommands we have - no CLI framework needed yet.
 import argparse
 
 from git_security import __version__
+from git_security.installer.fetch import fetch_gitleaks
 from git_security.installer.git_hook import install, status, uninstall
 from git_security.scan import run_scan, write_baseline_file
 
@@ -55,6 +56,10 @@ def build_parser() -> argparse.ArgumentParser:
         "uninstall", help="remove the pre-commit hook from this repository"
     )
     subparsers.add_parser("check", help="report pre-commit hook and scanner status")
+    subparsers.add_parser(
+        "fetch-gitleaks",
+        help="download the Gitleaks binary (checksum-verified) for secret scanning",
+    )
     subparsers.add_parser("version", help="print the version and exit")
     return parser
 
@@ -75,6 +80,8 @@ def main(argv: list[str] | None = None) -> int:
         return uninstall()
     if args.command == "check":
         return status()
+    if args.command == "fetch-gitleaks":
+        return fetch_gitleaks()
     if args.command == "version":
         print(f"git-security-tool {__version__}")
         return 0

git_security_tool-0.2.0/src/git_security/installer/dependencies.py

@@ -0,0 +1,15 @@
+"""Check which external scanners are available.
+
+A scanner counts as available if it is in the tool's managed bin directory,
+next to the running interpreter, or on PATH (see ``resolve_scanner``).
+Missing scanners are skipped at scan time.
+"""
+
+from git_security.scanners.base import resolve_scanner
+
+SCANNERS = ("ruff", "gitleaks", "semgrep")
+
+
+def check_dependencies() -> dict[str, bool]:
+    """Map each scanner name to whether its executable can be found."""
+    return {name: resolve_scanner(name) is not None for name in SCANNERS}

git_security_tool-0.2.0/src/git_security/installer/fetch.py

@@ -0,0 +1,99 @@
+"""Download the Gitleaks binary into the tool's managed bin directory.
+
+Gitleaks is a Go program, not a Python package, so ``pip install`` can't
+pull it. ``git-security-tool fetch-gitleaks`` grabs the matching release
+from GitHub, verifies its SHA-256 against the release checksums file, and
+installs it where the scanner wrappers already look (``MANAGED_BIN_DIR``).
+"""
+
+import hashlib
+import io
+import platform
+import tarfile
+import urllib.error
+import urllib.request
+
+from git_security.scanners.base import MANAGED_BIN_DIR
+
+_PREFIX = "[git-security-tool]"
+_VERSION = "8.30.1"
+_BASE = f"https://github.com/gitleaks/gitleaks/releases/download/v{_VERSION}"
+
+_ARCH = {
+    "x86_64": "x64",
+    "amd64": "x64",
+    "aarch64": "arm64",
+    "arm64": "arm64",
+    "armv7l": "armv7",
+}
+_OS = {"Linux": "linux", "Darwin": "darwin"}
+
+
+def _asset_name() -> str:
+    system = platform.system()
+    machine = platform.machine().lower()
+    if system not in _OS:
+        raise RuntimeError(
+            f"fetch-gitleaks supports Linux and macOS, not {system!r} - "
+            "on Windows use WSL, or install gitleaks manually"
+        )
+    if machine not in _ARCH:
+        raise RuntimeError(
+            f"no gitleaks build for architecture {machine!r} - install it from "
+            "https://github.com/gitleaks/gitleaks/releases"
+        )
+    return f"gitleaks_{_VERSION}_{_OS[system]}_{_ARCH[machine]}.tar.gz"
+
+
+def _download(url: str) -> bytes:
+    try:
+        with urllib.request.urlopen(url, timeout=60) as resp:  # noqa: S310 - pinned https
+            return resp.read()
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise RuntimeError(f"download failed ({url}): {exc}") from exc
+
+
+def _expected_sha(checksums: bytes, asset: str) -> str:
+    for line in checksums.decode().splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == asset:
+            return parts[0]
+    raise RuntimeError(f"{asset} is not listed in the release checksums file")
+
+
+def _extract_binary(tarball: bytes) -> bytes:
+    with tarfile.open(fileobj=io.BytesIO(tarball), mode="r:gz") as archive:
+        member = archive.extractfile("gitleaks")  # one named file, no extractall
+        if member is None:
+            raise RuntimeError("archive did not contain a 'gitleaks' file")
+        return member.read()
+
+
+def fetch_gitleaks() -> int:
+    try:
+        asset = _asset_name()
+        print(f"{_PREFIX} downloading {asset} ...")
+        tarball = _download(f"{_BASE}/{asset}")
+        checksums = _download(f"{_BASE}/gitleaks_{_VERSION}_checksums.txt")
+
+        expected = _expected_sha(checksums, asset)
+        actual = hashlib.sha256(tarball).hexdigest()
+        if actual != expected:
+            raise RuntimeError(
+                f"checksum mismatch for {asset}\n"
+                f"  expected {expected}\n  got      {actual}"
+            )
+        print(f"{_PREFIX} sha-256 verified")
+
+        binary = _extract_binary(tarball)
+    except RuntimeError as exc:
+        print(f"{_PREFIX} fetch-gitleaks failed: {exc}")
+        return 1
+
+    MANAGED_BIN_DIR.mkdir(parents=True, exist_ok=True)
+    dest = MANAGED_BIN_DIR / "gitleaks"
+    dest.write_bytes(binary)
+    dest.chmod(0o755)
+    print(f"{_PREFIX} installed gitleaks {_VERSION} -> {dest}")
+    print(f"{_PREFIX} secret scanning is now active")
+    return 0

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/src/git_security/installer/git_hook.py

@@ -47,10 +47,12 @@ def _print_dependencies() -> None:
     deps = check_dependencies()
     for name, present in deps.items():
         print(f"  {name}: {'ok' if present else 'missing'}")
-    if not all(deps.values()):
+    if not deps.get("gitleaks", True):
+        print(f"{_PREFIX} run `git-security-tool fetch-gitleaks` to enable secrets")
+    if not deps.get("ruff", True) or not deps.get("semgrep", True):
         print(
-            f"{_PREFIX} missing scanners are skipped at scan time; "
-            "install them for full coverage"
+            f"{_PREFIX} for ruff/semgrep, reinstall with: "
+            'pipx install "git-security-tool[scanners]"'
         )
 
 

git_security_tool-0.2.0/src/git_security/scanners/base.py

@@ -0,0 +1,67 @@
+"""Shared plumbing for scanner wrappers.
+
+Each scanner module owns the tool-specific knowledge: which command to run,
+how to read its exit codes, how to map its output to ``Finding``. What every
+scanner shares - find the executable, run it, cope if it isn't installed, and
+report paths consistently - lives here.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Where `git-security-tool fetch-gitleaks` puts the binary it downloads.
+_XDG_DATA = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+MANAGED_BIN_DIR = Path(_XDG_DATA) / "git-security-tool" / "bin"
+
+
+def resolve_scanner(name: str) -> str | None:
+    """Locate a scanner executable, or ``None`` if it isn't anywhere we look.
+
+    Order:
+    1. ``MANAGED_BIN_DIR`` - binaries this tool downloaded itself.
+    2. Next to the running interpreter - ``ruff`` / ``semgrep`` installed as
+       dependencies land in the same ``bin/`` as our Python, even inside a
+       pipx-isolated venv that isn't on the user's PATH.
+    3. The user's ``PATH``.
+    """
+    exe = MANAGED_BIN_DIR / name
+    if exe.is_file() and os.access(exe, os.X_OK):
+        return str(exe)
+
+    sibling = Path(sys.executable).parent / name
+    if sibling.is_file() and os.access(sibling, os.X_OK):
+        return str(sibling)
+
+    return shutil.which(name)
+
+
+def run_tool(cmd: list[str]) -> subprocess.CompletedProcess | None:
+    """Run an external tool with stdout/stderr captured.
+
+    ``cmd[0]`` may be a bare name or an absolute path. Returns the
+    ``CompletedProcess`` for any exit code, or ``None`` if the executable
+    cannot be found - so callers skip a missing tool cleanly.
+    """
+    resolved = resolve_scanner(cmd[0]) if not Path(cmd[0]).is_absolute() else cmd[0]
+    if resolved is None:
+        return None
+    try:
+        return subprocess.run(
+            [resolved, *cmd[1:]], capture_output=True, text=True, check=False
+        )
+    except FileNotFoundError:
+        return None
+
+
+def to_repo_relative(path: str, repo_root: Path) -> str:
+    """Make an absolute path repo-relative; leave anything else untouched."""
+    p = Path(path)
+    if not p.is_absolute():
+        return path
+    try:
+        return str(p.relative_to(repo_root))
+    except ValueError:
+        return path

git_security_tool-0.2.0/tests/test_base.py

@@ -0,0 +1,61 @@
+"""Tests for scanner resolution (managed dir > next-to-python > PATH)."""
+
+import os
+
+from git_security.scanners import base
+from git_security.scanners.base import resolve_scanner, run_tool
+
+
+def _make_exe(path):
+    path.write_text("#!/bin/sh\necho hi\n")
+    path.chmod(0o755)
+
+
+def test_prefers_managed_bin_dir(tmp_path, monkeypatch):
+    managed = tmp_path / "managed"
+    managed.mkdir()
+    _make_exe(managed / "ruff")
+    monkeypatch.setattr(base, "MANAGED_BIN_DIR", managed)
+
+    assert resolve_scanner("ruff") == str(managed / "ruff")
+
+
+def test_falls_back_to_next_to_interpreter(tmp_path, monkeypatch):
+    monkeypatch.setattr(base, "MANAGED_BIN_DIR", tmp_path / "empty")
+    fake_bin = tmp_path / "venv" / "bin"
+    fake_bin.mkdir(parents=True)
+    _make_exe(fake_bin / "semgrep")
+    monkeypatch.setattr(base.sys, "executable", str(fake_bin / "python"))
+
+    assert resolve_scanner("semgrep") == str(fake_bin / "semgrep")
+
+
+def test_returns_none_when_nowhere(tmp_path, monkeypatch):
+    monkeypatch.setattr(base, "MANAGED_BIN_DIR", tmp_path / "empty")
+    monkeypatch.setattr(base.sys, "executable", str(tmp_path / "nope" / "python"))
+    monkeypatch.setattr(base.shutil, "which", lambda _name: None)
+
+    assert resolve_scanner("definitely-not-a-real-tool") is None
+
+
+def test_run_tool_returns_none_for_missing(monkeypatch):
+    monkeypatch.setattr(base, "resolve_scanner", lambda _name: None)
+    assert run_tool(["ghost-tool", "--version"]) is None
+
+
+def test_run_tool_runs_resolved(tmp_path, monkeypatch):
+    exe = tmp_path / "echoer"
+    exe.write_text("#!/bin/sh\nprintf ok\n")
+    exe.chmod(0o755)
+    monkeypatch.setattr(base, "resolve_scanner", lambda _name: str(exe))
+
+    proc = run_tool(["echoer"])
+    assert proc is not None
+    assert proc.stdout == "ok"
+
+
+def test_managed_dir_respects_xdg(monkeypatch):
+    # sanity: the module constant is under a data dir, not the repo
+    assert base.MANAGED_BIN_DIR.name == "bin"
+    assert "git-security-tool" in str(base.MANAGED_BIN_DIR)
+    assert os.path.isabs(base.MANAGED_BIN_DIR)

{git_security_tool-0.1.1 → git_security_tool-0.2.0}/tests/test_cli.py

@@ -43,6 +43,11 @@ def test_baseline_subcommand_parses():
     assert args.command == "baseline"
 
 
+def test_fetch_gitleaks_subcommand_parses():
+    args = build_parser().parse_args(["fetch-gitleaks"])
+    assert args.command == "fetch-gitleaks"
+
+
 def test_install_parses_force_flag():
     args = build_parser().parse_args(["install", "--force"])
     assert args.command == "install"

git_security_tool-0.2.0/tests/test_fetch.py

@@ -0,0 +1,95 @@
+"""Tests for `git-security-tool fetch-gitleaks` (no real network)."""
+
+import hashlib
+import io
+import tarfile
+
+import pytest
+
+from git_security.installer import fetch
+
+
+def _make_tarball(binary: bytes = b"#!/bin/sh\necho gitleaks\n") -> bytes:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        info = tarfile.TarInfo(name="gitleaks")
+        info.size = len(binary)
+        tf.addfile(info, io.BytesIO(binary))
+    return buf.getvalue()
+
+
+# --- helpers ---------------------------------------------------------------
+
+
+def test_asset_name_linux_x64(monkeypatch):
+    monkeypatch.setattr(fetch.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(fetch.platform, "machine", lambda: "x86_64")
+    assert fetch._asset_name() == f"gitleaks_{fetch._VERSION}_linux_x64.tar.gz"
+
+
+def test_asset_name_mac_arm(monkeypatch):
+    monkeypatch.setattr(fetch.platform, "system", lambda: "Darwin")
+    monkeypatch.setattr(fetch.platform, "machine", lambda: "arm64")
+    assert fetch._asset_name() == f"gitleaks_{fetch._VERSION}_darwin_arm64.tar.gz"
+
+
+def test_asset_name_rejects_windows(monkeypatch):
+    monkeypatch.setattr(fetch.platform, "system", lambda: "Windows")
+    monkeypatch.setattr(fetch.platform, "machine", lambda: "AMD64")
+    with pytest.raises(RuntimeError, match="WSL"):
+        fetch._asset_name()
+
+
+def test_expected_sha_parsing():
+    blob = b"abc123  gitleaks_x_linux_x64.tar.gz\ndef456  other.tar.gz\n"
+    assert fetch._expected_sha(blob, "gitleaks_x_linux_x64.tar.gz") == "abc123"
+
+
+def test_expected_sha_missing_asset():
+    with pytest.raises(RuntimeError, match="checksums"):
+        fetch._expected_sha(b"abc  something-else.tar.gz\n", "wanted.tar.gz")
+
+
+def test_extract_binary_roundtrip():
+    assert fetch._extract_binary(_make_tarball(b"BODY")) == b"BODY"
+
+
+# --- full flow (network mocked) -----------------------------------------------
+
+
+@pytest.fixture
+def offline(monkeypatch, tmp_path):
+    monkeypatch.setattr(fetch, "MANAGED_BIN_DIR", tmp_path / "bin")
+    monkeypatch.setattr(fetch.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(fetch.platform, "machine", lambda: "x86_64")
+    return tmp_path
+
+
+def test_fetch_installs_verified_binary(offline, monkeypatch, capsys):
+    tarball = _make_tarball(b"the-real-binary")
+    asset = f"gitleaks_{fetch._VERSION}_linux_x64.tar.gz"
+    checksums = f"{hashlib.sha256(tarball).hexdigest()}  {asset}\n".encode()
+
+    monkeypatch.setattr(
+        fetch, "_download", lambda url: checksums if "checksums" in url else tarball
+    )
+
+    assert fetch.fetch_gitleaks() == 0
+    installed = offline / "bin" / "gitleaks"
+    assert installed.read_bytes() == b"the-real-binary"
+    assert installed.stat().st_mode & 0o111
+    assert "sha-256 verified" in capsys.readouterr().out
+
+
+def test_fetch_rejects_bad_checksum(offline, monkeypatch, capsys):
+    tarball = _make_tarball()
+    asset = f"gitleaks_{fetch._VERSION}_linux_x64.tar.gz"
+    monkeypatch.setattr(
+        fetch,
+        "_download",
+        lambda url: f"0000  {asset}\n".encode() if "checksums" in url else tarball,
+    )
+
+    assert fetch.fetch_gitleaks() == 1
+    assert "checksum mismatch" in capsys.readouterr().out
+    assert not (offline / "bin" / "gitleaks").exists()

git_security_tool-0.1.1/CLAUDE.md

@@ -1,64 +0,0 @@
-# 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.1/src/git_security/installer/dependencies.py

@@ -1,14 +0,0 @@
-"""Check which external scanners are available on PATH.
-
-The tool never installs anything itself - it just tells the user what is
-present and what is missing. Missing scanners are skipped at scan time.
-"""
-
-import shutil
-
-SCANNERS = ("ruff", "gitleaks", "semgrep")
-
-
-def check_dependencies() -> dict[str, bool]:
-    """Map each scanner name to whether its executable is on PATH."""
-    return {name: shutil.which(name) is not None for name in SCANNERS}

git_security_tool-0.1.1/src/git_security/scanners/base.py

@@ -1,34 +0,0 @@
-"""Shared plumbing for scanner wrappers.
-
-Each scanner module owns the tool-specific knowledge: which command to run,
-how to read its exit codes, how to map its output to ``Finding``. What every
-scanner shares - run an external process, cope if it isn't installed, and
-report paths consistently - lives here.
-"""
-
-import subprocess
-from pathlib import Path
-
-
-def run_tool(cmd: list[str]) -> subprocess.CompletedProcess | None:
-    """Run an external tool with stdout/stderr captured.
-
-    Returns the ``CompletedProcess`` for any exit code, or ``None`` if the
-    executable is not on PATH - so callers can skip a missing tool cleanly
-    instead of crashing the commit.
-    """
-    try:
-        return subprocess.run(cmd, capture_output=True, text=True, check=False)
-    except FileNotFoundError:
-        return None
-
-
-def to_repo_relative(path: str, repo_root: Path) -> str:
-    """Make an absolute path repo-relative; leave anything else untouched."""
-    p = Path(path)
-    if not p.is_absolute():
-        return path
-    try:
-        return str(p.relative_to(repo_root))
-    except ValueError:
-        return path