git-security-tool 0.1.0__py3-none-any.whl

git_security/__init__.py

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

git_security/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m git_security`."""
+
+from git_security.cli import main
+
+raise SystemExit(main())

git_security/baseline.py

@@ -0,0 +1,67 @@
+"""Suppress findings already recorded in a baseline file.
+
+A baseline lets a repository adopt the tool without fixing every pre-existing
+issue first: ``git-security-tool baseline`` records the current findings into
+``.git-security-tool-baseline.json``, and later scans hide anything already
+on that list. Newly introduced issues still surface and still block.
+
+Fingerprint is ``(tool, rule, file, message)`` - deliberately line-independent
+so unrelated edits to a file don't resurface a baselined finding. Regenerate
+the baseline after large refactors.
+"""
+
+import json
+from pathlib import Path
+
+from git_security.models.finding import Finding
+
+BASELINE_FILENAME = ".git-security-tool-baseline.json"
+_VERSION = 1
+
+Fingerprint = tuple[str, str, str, str]
+
+
+def _fingerprint(finding: Finding) -> Fingerprint:
+    return (finding.tool, finding.rule, finding.file, finding.message)
+
+
+def load_baseline(repo_root: Path) -> set[Fingerprint]:
+    """Fingerprints recorded in the baseline file, or an empty set."""
+    path = repo_root / BASELINE_FILENAME
+    if not path.is_file():
+        return set()
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return set()
+    return {
+        (
+            entry.get("tool", ""),
+            entry.get("rule", ""),
+            entry.get("file", ""),
+            entry.get("message", ""),
+        )
+        for entry in data.get("findings", [])
+    }
+
+
+def apply_baseline(
+    findings: list[Finding], baseline: set[Fingerprint]
+) -> tuple[list[Finding], int]:
+    """Return (findings not in the baseline, count suppressed)."""
+    kept = [f for f in findings if _fingerprint(f) not in baseline]
+    return kept, len(findings) - len(kept)
+
+
+def write_baseline(repo_root: Path, findings: list[Finding]) -> Path:
+    """Write *findings* to the baseline file and return its path."""
+    entries = sorted({_fingerprint(f) for f in findings})
+    payload = {
+        "version": _VERSION,
+        "findings": [
+            {"tool": t, "rule": r, "file": f, "message": m} for (t, r, f, m) in entries
+        ],
+    }
+    path = repo_root / BASELINE_FILENAME
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+    return path

git_security/cli.py

@@ -0,0 +1,87 @@
+"""Command-line interface for git-security-tool.
+
+Thin layer: parse arguments, dispatch to an action, return an exit code.
+All real work lives in the modules this calls. argparse (stdlib) is enough
+for the handful of subcommands we have - no CLI framework needed yet.
+"""
+
+import argparse
+
+from git_security import __version__
+from git_security.installer.git_hook import install, status, uninstall
+from git_security.scan import run_scan, write_baseline_file
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="git-security-tool",
+        description="Local Git security & code-quality gate (pre-commit).",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan_parser = subparsers.add_parser(
+        "scan",
+        help="scan staged changes (or --all tracked files); non-zero if blocked",
+    )
+    scan_parser.add_argument(
+        "--all",
+        action="store_true",
+        dest="scan_all",
+        help="scan every tracked file in the working tree (for CI / audits)",
+    )
+    scan_parser.add_argument(
+        "--format",
+        choices=("text", "sarif"),
+        default="text",
+        dest="output_format",
+        help="output format (sarif goes to stdout for GitHub code scanning)",
+    )
+
+    subparsers.add_parser(
+        "baseline",
+        help="record current findings so future scans ignore them",
+    )
+
+    install_parser = subparsers.add_parser(
+        "install", help="install the pre-commit hook into this repository"
+    )
+    install_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="replace an existing hook not managed by git-security-tool",
+    )
+
+    subparsers.add_parser(
+        "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("version", help="print the version and exit")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "scan":
+        return run_scan(
+            scope="all" if args.scan_all else "staged",
+            output_format=args.output_format,
+        )
+    if args.command == "baseline":
+        return write_baseline_file()
+    if args.command == "install":
+        return install(force=args.force)
+    if args.command == "uninstall":
+        return uninstall()
+    if args.command == "check":
+        return status()
+    if args.command == "version":
+        print(f"git-security-tool {__version__}")
+        return 0
+
+    # argparse enforces `required=True`, so this is unreachable.
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

git_security/config/loader.py

@@ -0,0 +1,127 @@
+"""Load repo-level configuration from ``.git-security-tool.toml``.
+
+The file is optional. When it is absent - or a key within it is missing -
+the built-in defaults apply. Parsing uses ``tomllib`` from the standard
+library (Python 3.11+), so this adds no dependency.
+
+A malformed file raises :class:`ConfigError`; callers turn that into a clean
+message rather than a traceback.
+
+Example ``.git-security-tool.toml`` at the repo root::
+
+    [policy]
+    block_threshold = "CRITICAL"   # INFO | LOW | MEDIUM | HIGH | CRITICAL
+
+    [scanners]
+    gitleaks = false               # disable a scanner
+
+    [ignore]
+    paths = ["tests/fixtures/", "*.generated.py"]
+
+    [ai]
+    enabled = true                 # off by default
+    provider = "gemini"            # "anthropic" | "gemini"
+    model = ""                     # blank = the provider's default model
+    max_findings = 3
+"""
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from git_security.models.finding import Severity
+from git_security.policy.engine import PolicyConfig
+
+CONFIG_FILENAME = ".git-security-tool.toml"
+
+_ALL_SCANNERS = ("ruff", "gitleaks", "semgrep")
+_AI_PROVIDERS = ("anthropic", "gemini")
+
+
+class ConfigError(Exception):
+    """Raised when ``.git-security-tool.toml`` is present but malformed."""
+
+
+@dataclass(frozen=True)
+class AIConfig:
+    enabled: bool = False
+    provider: str = "anthropic"
+    model: str = ""  # blank = provider default
+    max_findings: int = 3
+
+
+@dataclass(frozen=True)
+class Config:
+    policy: PolicyConfig = field(default_factory=PolicyConfig)
+    enabled_scanners: frozenset[str] = frozenset(_ALL_SCANNERS)
+    ignore_paths: tuple[str, ...] = ()
+    ai: AIConfig = field(default_factory=AIConfig)
+
+
+def load_config(repo_root: Path) -> Config:
+    """Read ``.git-security-tool.toml`` from *repo_root*, or return defaults."""
+    path = repo_root / CONFIG_FILENAME
+    if not path.is_file():
+        return Config()
+
+    try:
+        with path.open("rb") as handle:
+            raw = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"could not read {CONFIG_FILENAME}: {exc}") from exc
+
+    return Config(
+        policy=_load_policy(raw.get("policy", {})),
+        enabled_scanners=_load_scanners(raw.get("scanners", {})),
+        ignore_paths=_load_ignore(raw.get("ignore", {})),
+        ai=_load_ai(raw.get("ai", {})),
+    )
+
+
+def _load_policy(section: dict) -> PolicyConfig:
+    name = section.get("block_threshold")
+    if name is None:
+        return PolicyConfig()
+    try:
+        threshold = Severity[name.upper()]
+    except (KeyError, AttributeError):
+        valid = ", ".join(s.name for s in Severity)
+        raise ConfigError(
+            f"invalid policy.block_threshold: {name!r} (expected one of {valid})"
+        ) from None
+    return PolicyConfig(block_threshold=threshold)
+
+
+def _load_scanners(section: dict) -> frozenset[str]:
+    enabled = set(_ALL_SCANNERS)
+    for name in _ALL_SCANNERS:
+        if section.get(name) is False:
+            enabled.discard(name)
+    return frozenset(enabled)
+
+
+def _load_ignore(section: dict) -> tuple[str, ...]:
+    paths = section.get("paths", [])
+    if not isinstance(paths, list) or not all(isinstance(p, str) for p in paths):
+        raise ConfigError("ignore.paths must be a list of strings")
+    return tuple(paths)
+
+
+def _load_ai(section: dict) -> AIConfig:
+    provider = section.get("provider", "anthropic")
+    model = section.get("model", "")
+    max_findings = section.get("max_findings", 3)
+    if provider not in _AI_PROVIDERS:
+        raise ConfigError(f"ai.provider must be one of {', '.join(_AI_PROVIDERS)}")
+    if not isinstance(model, str):
+        raise ConfigError("ai.model must be a string")
+    if isinstance(max_findings, bool) or not isinstance(max_findings, int):
+        raise ConfigError("ai.max_findings must be an integer")
+    if max_findings < 1:
+        raise ConfigError("ai.max_findings must be >= 1")
+    return AIConfig(
+        enabled=section.get("enabled", False) is True,
+        provider=provider,
+        model=model,
+        max_findings=max_findings,
+    )

git_security/git/diff.py

@@ -0,0 +1,50 @@
+"""Read what is currently staged for the next commit.
+
+Thin queries on top of :func:`git_security.git.repository.run_git`, plus
+:func:`materialize_staged` which writes the exact staged content to disk so
+scanners analyse what will be committed rather than the working tree.
+"""
+
+from pathlib import Path
+
+from git_security.git.repository import run_git
+
+
+def get_staged_files() -> list[str]:
+    """Return the paths staged for the next commit.
+
+    ``--diff-filter=ACM`` keeps Added / Copied / Modified files and drops
+    deletions, since there is nothing to scan in a file being removed.
+    """
+    output = run_git(["diff", "--cached", "--name-only", "--diff-filter=ACM"])
+    return [line for line in output.splitlines() if line]
+
+
+def get_staged_diff() -> str:
+    """Return the full unified diff of everything staged for the next commit."""
+    return run_git(["diff", "--cached"])
+
+
+def get_staged_file_content(path: str) -> str:
+    """Return the staged (index) content of a single file as text."""
+    return run_git(["show", f":{path}"])
+
+
+def get_tracked_files() -> list[str]:
+    """Every file tracked by Git in this repository (for a full-repo scan)."""
+    return [line for line in run_git(["ls-files"]).splitlines() if line]
+
+
+def materialize_staged(files: list[str], dest: Path) -> None:
+    """Write the staged (index) content of *files* under *dest*.
+
+    Relative paths are preserved and missing sub-directories are created.
+    This is the staged blob - the exact bytes that will be committed - not
+    the working-tree copy, which may have diverged since ``git add``.
+    *dest* must already exist.
+    """
+    if not files:
+        return
+    # --prefix is prepended literally, so it must end with a separator.
+    prefix = f"{dest}/"
+    run_git(["checkout-index", f"--prefix={prefix}", "--", *files])

git_security/git/hooks.py

@@ -0,0 +1,25 @@
+"""Locate this repository's hooks directory and its pre-commit hook.
+
+Git's hooks directory is usually ``.git/hooks`` but can be moved with the
+``core.hooksPath`` config or differ inside worktrees. ``git rev-parse
+--git-path hooks`` resolves all of that for us.
+"""
+
+from pathlib import Path
+
+from git_security.git.repository import run_git
+
+
+def hooks_dir() -> Path:
+    """Absolute path to the hooks directory Git will actually use."""
+    raw = run_git(["rev-parse", "--git-path", "hooks"]).strip()
+    path = Path(raw)
+    if not path.is_absolute():
+        top = run_git(["rev-parse", "--show-toplevel"]).strip()
+        path = Path(top) / path
+    return path
+
+
+def pre_commit_hook() -> Path:
+    """Absolute path to this repository's ``pre-commit`` hook file."""
+    return hooks_dir() / "pre-commit"

git_security/git/repository.py

@@ -0,0 +1,38 @@
+"""Low-level access to the current Git repository.
+
+Every call that shells out to ``git`` goes through :func:`run_git` here.
+Higher-level modules (``diff.py``) build on it.
+"""
+
+import subprocess
+from pathlib import Path
+
+
+def run_git(args: list[str]) -> str:
+    """Run ``git <args>`` and return stdout as text.
+
+    Argument list, no shell - nothing to quote, no injection risk. Raises
+    ``RuntimeError`` with git's own stderr if git is missing or exits
+    non-zero, so callers never get a silent empty result.
+    """
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        raise RuntimeError("git executable not found on PATH")
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"git {' '.join(args)} failed (exit {result.returncode}): "
+            f"{result.stderr.strip()}"
+        )
+    return result.stdout
+
+
+def get_repo_root() -> Path:
+    """Absolute path to the top level of the current working tree."""
+    return Path(run_git(["rev-parse", "--show-toplevel"]).strip())

git_security/ignore.py

@@ -0,0 +1,27 @@
+"""Skip staged paths that match the config's ignore patterns.
+
+Patterns are matched against repo-relative POSIX paths:
+
+* ``tests/fixtures/``  - trailing slash means "anything under this directory"
+* ``*.generated.py``   - fnmatch glob (``*`` also spans ``/``)
+* ``migrations``       - a plain name matches that path and everything under it
+"""
+
+from fnmatch import fnmatch
+
+
+def _matches(path: str, pattern: str) -> bool:
+    pattern = pattern.rstrip("/")
+    if not pattern:
+        return False
+    return fnmatch(path, pattern) or fnmatch(path, f"{pattern}/*")
+
+
+def is_ignored(path: str, patterns: tuple[str, ...]) -> bool:
+    return any(_matches(path, pattern) for pattern in patterns)
+
+
+def filter_ignored(files: list[str], patterns: tuple[str, ...]) -> list[str]:
+    if not patterns:
+        return list(files)
+    return [f for f in files if not is_ignored(f, patterns)]

git_security/installer/dependencies.py

@@ -0,0 +1,14 @@
+"""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/installer/git_hook.py

@@ -0,0 +1,122 @@
+"""Install, remove, and report on the git-security-tool pre-commit hook.
+
+The hook itself is tiny and lives in ``.git/hooks/`` (not version-controlled),
+so every repo needs this command to set it up. We only ever touch a hook we
+created - identified by MARKER - unless the user passes --force.
+"""
+
+import stat
+from pathlib import Path
+
+from git_security.git.hooks import pre_commit_hook
+from git_security.git.repository import run_git
+from git_security.installer.dependencies import check_dependencies
+
+_PREFIX = "[git-security-tool]"
+
+MARKER = "git-security-tool managed hook"
+
+HOOK_CONTENT = f"""\
+#!/bin/sh
+# {MARKER} - do not edit; regenerate with `git-security-tool install`
+if ! command -v git-security-tool >/dev/null 2>&1; then
+    echo "git-security-tool not on PATH - skipping scan (is your venv active?)" >&2
+    exit 0
+fi
+exec git-security-tool scan
+"""
+
+_EXEC_BITS = stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+
+
+def _inside_work_tree() -> bool:
+    try:
+        return run_git(["rev-parse", "--is-inside-work-tree"]).strip() == "true"
+    except RuntimeError:
+        return False
+
+
+def _is_ours(path: Path) -> bool:
+    try:
+        return path.is_file() and MARKER in path.read_text()
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+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()):
+        print(
+            f"{_PREFIX} missing scanners are skipped at scan time; "
+            "install them for full coverage"
+        )
+
+
+def install(force: bool = False) -> int:
+    if not _inside_work_tree():
+        print(f"{_PREFIX} not inside a Git repository")
+        return 1
+
+    hook = pre_commit_hook()
+    hook.parent.mkdir(parents=True, exist_ok=True)
+
+    if hook.exists() and not _is_ours(hook) and not force:
+        print(
+            f"{_PREFIX} a pre-commit hook already exists at {hook} and was not "
+            f"created by git-security-tool.\n"
+            f"{_PREFIX} re-run with --force to replace it."
+        )
+        return 1
+
+    hook.write_text(HOOK_CONTENT)
+    hook.chmod(hook.stat().st_mode | _EXEC_BITS)
+    print(f"{_PREFIX} installed pre-commit hook at {hook}")
+    _print_dependencies()
+    return 0
+
+
+def uninstall() -> int:
+    if not _inside_work_tree():
+        print(f"{_PREFIX} not inside a Git repository")
+        return 1
+
+    hook = pre_commit_hook()
+    if not hook.exists():
+        print(f"{_PREFIX} no pre-commit hook to remove")
+        return 0
+    if not _is_ours(hook):
+        print(
+            f"{_PREFIX} pre-commit hook at {hook} was not created by "
+            "git-security-tool - leaving it alone"
+        )
+        return 1
+
+    hook.unlink()
+    print(f"{_PREFIX} removed pre-commit hook at {hook}")
+    return 0
+
+
+def status() -> int:
+    if not _inside_work_tree():
+        print(f"{_PREFIX} not inside a Git repository")
+        return 1
+
+    hook = pre_commit_hook()
+    if _is_ours(hook):
+        print(f"{_PREFIX} pre-commit hook: installed ({hook})")
+        installed = True
+    elif hook.exists():
+        print(
+            f"{_PREFIX} pre-commit hook: present but not managed by "
+            f"git-security-tool ({hook})"
+        )
+        installed = False
+    else:
+        print(f"{_PREFIX} pre-commit hook: not installed")
+        installed = False
+
+    print(f"{_PREFIX} scanners:")
+    _print_dependencies()
+    return 0 if installed else 1

git_security/models/finding.py

@@ -0,0 +1,33 @@
+"""The normalized finding model.
+
+Every scanner converts its tool's native output into ``Finding`` objects.
+From here on, the rest of git-security-tool (policy, reporting) deals only
+with ``Finding`` - never a raw tool dict.
+"""
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class Severity(IntEnum):
+    """Ordered severity levels.
+
+    Subclassing ``IntEnum`` means the members compare like numbers, so policy
+    can ask ``finding.severity >= Severity.HIGH`` directly. Higher = worse.
+    """
+
+    INFO = 1
+    LOW = 2
+    MEDIUM = 3
+    HIGH = 4
+    CRITICAL = 5
+
+
+@dataclass(frozen=True)
+class Finding:
+    tool: str  # scanner that produced it: "ruff", "gitleaks", ...
+    rule: str  # tool-specific rule id: "F401", "aws-access-token", ...
+    severity: Severity
+    file: str  # repo-relative path
+    line: int  # 1-based line number; 0 when the tool reports none
+    message: str  # human-readable description

git_security/policy/engine.py

@@ -0,0 +1,38 @@
+"""Turn a list of findings into an allow/block decision.
+
+The policy layer is the *only* place that decides whether the commit should
+proceed. Scanners just report; ``main()`` just obeys the returned Decision.
+Keeping the rule here means we can change blocking behaviour without touching
+any scanner.
+"""
+
+from dataclasses import dataclass, field
+
+from git_security.models.finding import Finding, Severity
+
+# Severities that abort the commit. Anything below this is shown as a warning
+# but does not block. Made configurable from a file in a later milestone.
+DEFAULT_BLOCK_THRESHOLD = Severity.HIGH
+
+
+@dataclass(frozen=True)
+class PolicyConfig:
+    block_threshold: Severity = DEFAULT_BLOCK_THRESHOLD
+
+
+@dataclass
+class Decision:
+    blocked: bool
+    blocking: list[Finding] = field(default_factory=list)
+    warnings: list[Finding] = field(default_factory=list)
+
+
+def evaluate(findings: list[Finding], config: PolicyConfig) -> Decision:
+    """Split findings into blocking vs warning by severity threshold."""
+    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=blocking,
+        warnings=warnings,
+    )