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

git_security/reporter/sarif.py

@@ -0,0 +1,72 @@
+"""SARIF 2.1.0 output, for CI / GitHub code scanning.
+
+``git-security-tool scan --all --format sarif`` prints this to stdout; upload
+it with the ``github/codeql-action/upload-sarif`` step to populate the
+repository's Security tab.
+"""
+
+import json
+
+from git_security.models.finding import Finding, Severity
+
+_INFO_URI = "https://github.com/MustafaBasit521/commit-guard"
+
+_LEVEL = {
+    Severity.INFO: "note",
+    Severity.LOW: "note",
+    Severity.MEDIUM: "warning",
+    Severity.HIGH: "error",
+    Severity.CRITICAL: "error",
+}
+
+
+def to_sarif(findings: list[Finding]) -> str:
+    rules: dict[str, dict] = {}
+    results: list[dict] = []
+
+    for finding in findings:
+        rule_id = f"{finding.tool}.{finding.rule}"
+        rules.setdefault(
+            rule_id,
+            {
+                "id": rule_id,
+                "name": finding.rule or finding.tool,
+                "shortDescription": {"text": finding.rule or finding.tool},
+            },
+        )
+        results.append(
+            {
+                "ruleId": rule_id,
+                "level": _LEVEL.get(finding.severity, "warning"),
+                "message": {"text": finding.message},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": finding.file},
+                            "region": {"startLine": max(finding.line, 1)},
+                        }
+                    }
+                ],
+            }
+        )
+
+    doc = {
+        "version": "2.1.0",
+        "$schema": (
+            "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/"
+            "Schemata/sarif-schema-2.1.0.json"
+        ),
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "git-security-tool",
+                        "informationUri": _INFO_URI,
+                        "rules": list(rules.values()),
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+    return json.dumps(doc, indent=2)

git_security/reporter/terminal.py

@@ -0,0 +1,46 @@
+"""Turn a policy Decision into human-readable terminal output.
+
+All the "how do we present findings" logic lives here, so ``main()`` only
+has to orchestrate and pick an exit code. A JSON / SARIF reporter for CI can
+be added alongside this without touching ``main()``.
+"""
+
+from git_security.models.finding import Finding
+from git_security.policy.engine import Decision
+
+_PREFIX = "[git-security-tool]"
+_MESSAGE_LIMIT = 120
+
+
+def report(decision: Decision) -> None:
+    """Print warnings, then blocking findings, then a one-line summary."""
+    if not decision.warnings and not decision.blocking:
+        print(f"{_PREFIX} no findings")
+        return
+
+    if decision.warnings:
+        _section("warning(s), do not block", decision.warnings)
+    if decision.blocking:
+        _section("blocking finding(s)", decision.blocking)
+
+    print(
+        f"{_PREFIX} summary: {len(decision.blocking)} blocking, "
+        f"{len(decision.warnings)} warning(s)"
+    )
+
+
+def _section(title: str, findings: list[Finding]) -> None:
+    print(f"{_PREFIX} {len(findings)} {title}:")
+    for f in sorted(findings, key=lambda x: (x.file, x.line, x.tool)):
+        print(
+            f"  [{f.severity.name}] {f.tool}:{f.rule} "
+            f"{f.file}:{f.line} - {_one_line(f.message)}"
+        )
+
+
+def _one_line(message: str, limit: int = _MESSAGE_LIMIT) -> str:
+    """Collapse whitespace/newlines and truncate long messages."""
+    message = " ".join(message.split())
+    if len(message) <= limit:
+        return message
+    return message[: limit - 1] + "…"

git_security/rules/semgrep/crypto_tls.yml

@@ -0,0 +1,37 @@
+# Weak cryptography and disabled transport security.
+rules:
+  - id: python-weak-hash
+    languages: [python]
+    severity: WARNING
+    message: >
+      MD5 and SHA-1 are broken for security use (practical collisions). Use
+      SHA-256 or stronger. For a non-security checksum, pass
+      usedforsecurity=False to make the intent explicit.
+    patterns:
+      - pattern-either:
+          - pattern: hashlib.md5(...)
+          - pattern: hashlib.sha1(...)
+      - pattern-not: hashlib.md5(..., usedforsecurity=False)
+      - pattern-not: hashlib.sha1(..., usedforsecurity=False)
+
+  - id: python-tls-verification-disabled
+    languages: [python]
+    severity: ERROR
+    message: >
+      TLS certificate verification is disabled (verify=False), which exposes
+      the connection to man-in-the-middle attacks. Remove it, or pin a CA
+      bundle with verify="/path/to/ca.pem".
+    pattern-either:
+      - pattern: requests.$M(..., verify=False, ...)
+      - pattern: httpx.$M(..., verify=False, ...)
+      - pattern: httpx.Client(..., verify=False, ...)
+
+  - id: python-ssl-unverified-context
+    languages: [python]
+    severity: ERROR
+    message: >
+      ssl._create_unverified_context() / _create_stdlib_context disables
+      certificate validation for every connection that uses it.
+    pattern-either:
+      - pattern: ssl._create_unverified_context(...)
+      - pattern: ssl._create_stdlib_context(...)

git_security/rules/semgrep/deserialization.yml

@@ -0,0 +1,38 @@
+# Deserialization of untrusted data -> arbitrary object construction / RCE.
+rules:
+  - id: python-pickle-load
+    languages: [python]
+    severity: ERROR
+    message: >
+      pickle can execute arbitrary code while deserializing. Never unpickle
+      data you do not fully trust; use JSON or a schema-validated format.
+    pattern-either:
+      - pattern: pickle.load(...)
+      - pattern: pickle.loads(...)
+      - pattern: cPickle.load(...)
+      - pattern: cPickle.loads(...)
+
+  - id: python-yaml-unsafe-load
+    languages: [python]
+    severity: ERROR
+    message: >
+      yaml.load() without a safe loader can construct arbitrary Python objects
+      from the input. Use yaml.safe_load(...) or pass Loader=yaml.SafeLoader.
+    patterns:
+      - pattern: yaml.load(...)
+      - pattern-not: yaml.load(..., Loader=yaml.SafeLoader)
+      - pattern-not: yaml.load(..., Loader=yaml.CSafeLoader)
+
+  - id: python-insecure-xml-parser
+    languages: [python]
+    severity: WARNING
+    message: >
+      Parsing XML with the standard library is exposed to entity-expansion
+      ("billion laughs") and, with some parsers, external-entity attacks. Use
+      the defusedxml package for untrusted input.
+    pattern-either:
+      - pattern: xml.etree.ElementTree.parse(...)
+      - pattern: xml.etree.ElementTree.fromstring(...)
+      - pattern: xml.dom.minidom.parse(...)
+      - pattern: xml.dom.minidom.parseString(...)
+      - pattern: xml.sax.parse(...)

git_security/rules/semgrep/filesystem_net.yml

@@ -0,0 +1,38 @@
+# Filesystem and network hygiene.
+rules:
+  - id: python-archive-extractall
+    languages: [python]
+    severity: ERROR
+    message: >
+      extractall()/extract() on an untrusted archive can write files outside
+      the target directory (path traversal - Zip Slip, CVE-2007-4559).
+      Validate each member's path before extracting.
+    pattern-either:
+      - pattern: $ARCHIVE.extractall(...)
+      - pattern: $ARCHIVE.extract(...)
+
+  - id: python-tempfile-mktemp
+    languages: [python]
+    severity: WARNING
+    message: >
+      tempfile.mktemp() only returns a name - there is a race between that and
+      creating the file. Use tempfile.mkstemp() or NamedTemporaryFile().
+    pattern: tempfile.mktemp(...)
+
+  - id: python-requests-no-timeout
+    languages: [python]
+    severity: WARNING
+    message: >
+      A requests call with no timeout can hang forever, which is a
+      denial-of-service risk. Pass timeout=<seconds>.
+    patterns:
+      - pattern-either:
+          - pattern: requests.get(...)
+          - pattern: requests.post(...)
+          - pattern: requests.put(...)
+          - pattern: requests.patch(...)
+          - pattern: requests.delete(...)
+          - pattern: requests.head(...)
+          - pattern: requests.options(...)
+          - pattern: requests.request(...)
+      - pattern-not: requests.$M(..., timeout=$T)

git_security/rules/semgrep/injection.yml

@@ -0,0 +1,43 @@
+# Command / code injection: input reaching an interpreter or a shell.
+rules:
+  - id: python-dangerous-eval
+    languages: [python]
+    severity: ERROR
+    message: >
+      eval() executes arbitrary code from its argument. If the input is ever
+      attacker-influenced this is remote code execution. Parse or dispatch
+      explicitly instead.
+    pattern: eval(...)
+
+  - id: python-dangerous-exec
+    languages: [python]
+    severity: ERROR
+    message: >
+      exec() runs arbitrary code. Avoid it; use explicit logic or a narrow
+      dispatch table.
+    pattern: exec(...)
+
+  - id: python-os-system
+    languages: [python]
+    severity: ERROR
+    message: >
+      os.system() runs its argument through the shell - command injection if
+      any part is dynamic. Use subprocess.run([...]) with an argument list.
+    pattern: os.system(...)
+
+  - id: python-os-popen
+    languages: [python]
+    severity: ERROR
+    message: >
+      os.popen() runs its argument through the shell. Use subprocess with an
+      argument list instead.
+    pattern: os.popen(...)
+
+  - id: python-subprocess-shell-true
+    languages: [python]
+    severity: WARNING
+    message: >
+      subprocess called with shell=True runs the command through a shell,
+      enabling shell injection if any argument is dynamic. Pass an argument
+      list and omit shell=True.
+    pattern: subprocess.$FUNC(..., shell=True, ...)

git_security/rules/semgrep/web.yml

@@ -0,0 +1,32 @@
+# Web-framework footguns: debug servers and disabled output escaping.
+rules:
+  - id: python-flask-debug-true
+    languages: [python]
+    severity: ERROR
+    message: >
+      Running a web app with debug=True exposes the Werkzeug interactive
+      debugger, which allows remote code execution. Never enable it outside
+      local development.
+    pattern: $APP.run(..., debug=True, ...)
+
+  - id: python-jinja-autoescape-disabled
+    languages: [python]
+    severity: WARNING
+    message: >
+      A Jinja2 Environment without autoescaping does not HTML-escape template
+      output, risking XSS. Pass autoescape=True or
+      autoescape=select_autoescape(...).
+    patterns:
+      - pattern: jinja2.Environment(...)
+      - pattern-not: jinja2.Environment(..., autoescape=True)
+      - pattern-not: jinja2.Environment(..., autoescape=select_autoescape(...))
+
+  - id: python-django-mark-safe
+    languages: [python]
+    severity: WARNING
+    message: >
+      mark_safe() turns off Django's HTML autoescaping for this value. If any
+      part of it is user-controlled, this is an XSS sink.
+    pattern-either:
+      - pattern: mark_safe(...)
+      - pattern: django.utils.safestring.mark_safe(...)

git_security/scan.py

@@ -0,0 +1,245 @@
+"""The scan pipeline.
+
+Gather the files to check, run every scanner, evaluate policy, report, and
+return an exit code.
+
+* ``run_scan("staged")`` - the pre-commit path: scans the exact staged blob
+  content and can offer AI suggestions.
+* ``run_scan("all")`` - the CI / audit path: scans every tracked file in the
+  working tree; supports ``--format sarif``.
+* ``write_baseline_file()`` - records the current findings so a repo can
+  adopt the tool without fixing everything first.
+
+Escape hatch (staged mode only): set GIT_SECURITY_NO_BLOCK=1 to report
+findings but never block.
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+from collections.abc import Callable
+from importlib.resources import files
+from pathlib import Path
+
+from git_security.baseline import apply_baseline, load_baseline, write_baseline
+from git_security.config.loader import AIConfig, Config, ConfigError, load_config
+from git_security.git.diff import (
+    get_staged_file_content,
+    get_staged_files,
+    get_tracked_files,
+    materialize_staged,
+)
+from git_security.git.repository import get_repo_root
+from git_security.ignore import filter_ignored, is_ignored
+from git_security.models.finding import Finding
+from git_security.policy.engine import evaluate
+from git_security.reporter.sarif import to_sarif
+from git_security.reporter.terminal import report
+from git_security.scanners.gitleaks import run_gitleaks
+from git_security.scanners.ruff import run_ruff, run_ruff_format
+from git_security.scanners.semgrep import run_semgrep
+
+_PREFIX = "[git-security-tool]"
+
+# Config files a scanner may look for when deciding how to lint a project.
+_PROJECT_CONFIG_FILES = ("pyproject.toml", "ruff.toml", ".ruff.toml", "setup.cfg")
+
+
+def _copy_project_config(repo_root: Path, dest: Path) -> None:
+    """Place the repo's lint config at the root of the materialized tree.
+
+    Scanners resolve their configuration by walking up from each file. The
+    throwaway directory has none, so without this Ruff (etc.) would silently
+    use built-in defaults instead of the project's settings.
+    """
+    for name in _PROJECT_CONFIG_FILES:
+        src = repo_root / name
+        if src.is_file():
+            shutil.copy2(src, dest / name)
+
+
+def _safe_scan(name: str, run: Callable[[], list[Finding]], log) -> list[Finding]:
+    """Run one scanner, turning a crash into a clear message + empty result."""
+    try:
+        return run()
+    except RuntimeError as exc:
+        log(f"{_PREFIX} {name} failed to run - skipping it: {exc}")
+        return []
+
+
+def _run_file_scanners(
+    paths: list[str], root: Path, rules_dir: Path, enabled: frozenset[str], log
+) -> list[Finding]:
+    findings: list[Finding] = []
+    if "ruff" in enabled:
+        findings += _safe_scan("ruff", lambda: run_ruff(paths, root), log)
+        findings += _safe_scan("ruff format", lambda: run_ruff_format(paths, root), log)
+    if "semgrep" in enabled:
+        findings += _safe_scan(
+            "semgrep", lambda: run_semgrep(paths, root, rules_dir), log
+        )
+    return findings
+
+
+def _semgrep_rules_dir() -> Path:
+    """Directory of bundled Semgrep rules (shipped inside the package)."""
+    return Path(str(files("git_security") / "rules" / "semgrep"))
+
+
+def _collect_findings(scope: str, log) -> tuple[list[Finding], Path, Config]:
+    """Run every enabled scanner for *scope*. Raises ConfigError."""
+    staged = scope == "staged"
+    repo_root = get_repo_root()
+    config = load_config(repo_root)
+
+    candidates = get_staged_files() if staged else get_tracked_files()
+    scannable = filter_ignored(candidates, config.ignore_paths)
+
+    if not scannable:
+        if not candidates:
+            log(
+                f"{_PREFIX} "
+                + ("nothing staged" if staged else "no tracked files to scan")
+            )
+        else:
+            log(f"{_PREFIX} nothing to scan after ignores")
+        return [], repo_root, config
+
+    ignored = len(candidates) - len(scannable)
+    suffix = f" ({ignored} ignored by config)" if ignored else ""
+    log(f"{_PREFIX} {len(scannable)} file(s) to scan{suffix}")
+
+    rules_dir = _semgrep_rules_dir()
+    enabled = config.enabled_scanners
+    findings: list[Finding] = []
+
+    if staged:
+        # Scan the exact staged blob content, not the working tree.
+        with tempfile.TemporaryDirectory(prefix="git-security-tool-") as tmp:
+            root = Path(tmp)
+            materialize_staged(scannable, root)
+            _copy_project_config(repo_root, root)
+            paths = [str(root / f) for f in scannable]
+            findings += _run_file_scanners(paths, root, rules_dir, enabled, log)
+    else:
+        paths = [str(repo_root / f) for f in scannable]
+        findings += _run_file_scanners(paths, repo_root, rules_dir, enabled, log)
+
+    if "gitleaks" in enabled:
+        leaks = _safe_scan("gitleaks", lambda: run_gitleaks(staged=staged), log)
+        findings += [f for f in leaks if not is_ignored(f.file, config.ignore_paths)]
+
+    return findings, repo_root, config
+
+
+# --- AI suggestions ---------------------------------------------------------
+
+
+def _staged_snippet(finding: Finding, context: int = 5) -> str:
+    """A few lines of the staged file around the finding, with line numbers."""
+    try:
+        lines = get_staged_file_content(finding.file).splitlines()
+    except RuntimeError:
+        return ""
+    if finding.line <= 0:
+        window = lines[: 2 * context + 1]
+        start = 1
+    else:
+        start = max(1, finding.line - context)
+        window = lines[start - 1 : finding.line + context]
+    return "\n".join(f"{start + i}: {text}" for i, text in enumerate(window))
+
+
+def _run_ai_suggestions(
+    blocking: list[Finding], all_findings: list[Finding], ai: AIConfig
+) -> None:
+    from git_security.suggestions.llm import explain, suggestions_available
+
+    if not suggestions_available(ai.provider):
+        print(
+            f"{_PREFIX} AI suggestions are enabled but the '{ai.provider}' "
+            "provider is unavailable - check its API key "
+            "(ANTHROPIC_API_KEY / GEMINI_API_KEY)"
+        )
+        return
+
+    # Never send secret-bearing code off the machine: skip Gitleaks findings
+    # and skip any file that Gitleaks flagged.
+    secret_files = {f.file for f in all_findings if f.tool == "gitleaks"}
+    targets = [
+        f for f in blocking if f.tool != "gitleaks" and f.file not in secret_files
+    ][: ai.max_findings]
+
+    if not targets:
+        print(
+            f"{_PREFIX} no findings eligible for AI suggestions "
+            "(secret-bearing code is never sent)"
+        )
+        return
+    explain([(f, _staged_snippet(f)) for f in targets], ai)
+
+
+# --- entry points ----------------------------------------------------------
+
+
+def run_scan(scope: str = "staged", output_format: str = "text") -> int:
+    staged = scope == "staged"
+    sarif = output_format == "sarif"
+    # In sarif mode stdout must be pure JSON, so progress goes to stderr.
+    log: Callable[[str], None] = (
+        (lambda m: print(m, file=sys.stderr)) if sarif else print
+    )
+    log(
+        f"{_PREFIX} " + ("pre-commit security scan" if staged else "full security scan")
+    )
+
+    try:
+        findings, repo_root, config = _collect_findings(scope, log)
+    except ConfigError as exc:
+        log(f"{_PREFIX} config error: {exc}")
+        return 1
+
+    baseline = load_baseline(repo_root)
+    if baseline:
+        findings, suppressed = apply_baseline(findings, baseline)
+        if suppressed:
+            log(f"{_PREFIX} {suppressed} finding(s) suppressed by baseline")
+
+    decision = evaluate(findings, config.policy)
+
+    if sarif:
+        print(to_sarif(decision.blocking + decision.warnings))
+    else:
+        report(decision)
+
+    if staged and config.ai.enabled and decision.blocking:
+        _run_ai_suggestions(decision.blocking, findings, config.ai)
+
+    passed = "commit allowed" if staged else "scan passed"
+    blocked = "commit blocked" if staged else "scan failed"
+
+    if not decision.blocked:
+        log(f"{_PREFIX} {passed}")
+        return 0
+
+    if staged and os.environ.get("GIT_SECURITY_NO_BLOCK") == "1":
+        log(f"{_PREFIX} would block, but GIT_SECURITY_NO_BLOCK=1 is set - {passed}")
+        return 0
+
+    override = ", or set GIT_SECURITY_NO_BLOCK=1 to override" if staged else ""
+    log(f"{_PREFIX} {blocked} - fix the blocking findings above{override}")
+    return 1
+
+
+def write_baseline_file() -> int:
+    """Record the current full-repo findings into the baseline file."""
+    try:
+        findings, repo_root, _ = _collect_findings("all", print)
+    except ConfigError as exc:
+        print(f"{_PREFIX} config error: {exc}")
+        return 1
+    path = write_baseline(repo_root, findings)
+    print(f"{_PREFIX} recorded {len(findings)} finding(s) in {path.name}")
+    print(f"{_PREFIX} commit this file; future scans will ignore those findings")
+    return 0

git_security/scanners/base.py

@@ -0,0 +1,34 @@
+"""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

git_security/scanners/gitleaks.py

@@ -0,0 +1,59 @@
+"""Gitleaks wrapper: staged changes (or the whole tree) -> list[Finding].
+
+Gitleaks is Git-aware, so this wrapper takes no file list:
+
+* ``staged=True``  -> ``gitleaks git --staged`` (the staged diff, pre-commit)
+* ``staged=False`` -> ``gitleaks dir .``        (every file on disk, CI / audit)
+
+It maps Gitleaks' JSON to the normalized ``Finding`` model and nothing else.
+"""
+
+import json
+
+from git_security.models.finding import Finding, Severity
+from git_security.scanners.base import run_tool
+
+_NOT_FOUND_MSG = (
+    "[git-security-tool] gitleaks not found on PATH - skipping "
+    "(https://github.com/gitleaks/gitleaks#installing)"
+)
+
+
+def run_gitleaks(staged: bool = True) -> list[Finding]:
+    """Scan for secrets and return normalized findings."""
+    mode = ["git", "--staged"] if staged else ["dir", "."]
+    proc = run_tool(
+        [
+            "gitleaks",
+            *mode,
+            "--report-format",
+            "json",
+            "--report-path",
+            "-",  # write the JSON report to stdout
+            "--redact",  # never echo the actual secret value
+            "--no-banner",
+        ]
+    )
+    if proc is None:
+        print(_NOT_FOUND_MSG)
+        return []
+
+    # Gitleaks exit codes: 0 = no leaks, 1 = leaks found, other = error.
+    if proc.returncode not in (0, 1):
+        raise RuntimeError(f"gitleaks failed: {proc.stderr.strip()}")
+
+    if not proc.stdout.strip():
+        return []
+
+    return [_to_finding(item) for item in json.loads(proc.stdout)]
+
+
+def _to_finding(item: dict) -> Finding:
+    return Finding(
+        tool="gitleaks",
+        rule=item.get("RuleID") or "",
+        severity=Severity.CRITICAL,  # a committed secret always blocks
+        file=item.get("File") or "",  # Gitleaks paths are already repo-relative
+        line=item.get("StartLine") or 0,
+        message=item.get("Description") or "",
+    )