zak-guard 0.1.0__tar.gz

zak_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zak Molloy
+
+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.

zak_guard-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: zak-guard
+Version: 0.1.0
+Summary: Pre-commit secret scanner: catches AWS keys, GitHub PATs, Stripe tokens, private keys, and more before they hit your repo
+Author-email: Zak Molloy <zakguard@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/molloyzak13/zak-guard
+Project-URL: Repository, https://github.com/molloyzak13/zak-guard
+Project-URL: Issues, https://github.com/molloyzak13/zak-guard/issues
+Keywords: pre-commit,security,secrets,git,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# zak-guard
+
+A pre-commit secret scanner. Catches AWS keys, GitHub PATs, Stripe tokens, private keys, and other credentials before they land in your repo.
+
+Works standalone as a CLI tool and as a hook in the [pre-commit](https://pre-commit.com) framework.
+
+---
+
+## What it catches
+
+| Rule | Examples |
+|---|---|
+| AWS access key ID | `AKIA...` (20-char, high entropy) |
+| AWS secret access key | `AWS_SECRET_ACCESS_KEY=...` env var assignments |
+| GitHub PATs (classic + fine-grained) | `ghp_...`, `github_pat_...` |
+| GitHub OAuth / Actions / refresh tokens | `gho_`, `ghs_`, `ghr_` |
+| OpenAI keys (legacy + project) | `sk-...`, `sk-proj-...` |
+| Anthropic keys | `sk-ant-...` |
+| DeepSeek / generic `sk-` keys | `sk-` prefix with high entropy |
+| Stripe live keys | `sk_live_...`, `rk_live_...` |
+| Slack tokens | `xoxb-`, `xoxp-`, `xoxa-` |
+| Google API keys | `AIza...` |
+| PEM private key blocks | `-----BEGIN ... PRIVATE KEY-----` |
+| JWTs | Three base64url segments |
+| Generic `.env` assignments | `PASSWORD=...`, `SECRET=...`, `TOKEN=...` with high entropy |
+
+Every finding shows `file:line`, the rule name, and a redacted match (`AKIA...Y01`). The full value is never printed.
+
+---
+
+## Install
+
+```sh
+pip install zak-guard
+# or
+pipx install zak-guard
+```
+
+---
+
+## Use as a CLI
+
+Scan staged changes (what you're about to commit):
+
+```sh
+zak-guard --staged
+```
+
+Scan everything in the current directory:
+
+```sh
+zak-guard --all
+```
+
+Scan a specific path:
+
+```sh
+zak-guard --all ./src
+```
+
+Suppress known false positives with an allowlist:
+
+```sh
+zak-guard --staged --allowlist .zak-guard-allowlist
+```
+
+Wire it as a git pre-commit hook:
+
+```sh
+zak-guard install
+```
+
+---
+
+## Use with the pre-commit framework
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/molloyzak13/zak-guard
+    rev: v0.1.0
+    hooks:
+      - id: zak-guard
+```
+
+Then install:
+
+```sh
+pre-commit install
+```
+
+---
+
+## Allowlist
+
+Create a text file with one entry per line. Any detected value that contains an allowlist entry is suppressed. Lines starting with `#` are comments.
+
+```
+# .zak-guard-allowlist
+AKIAEXAMPLE         # known-fake key in test fixtures
+sk_live_test_       # Stripe test mode prefix used in integration tests
+```
+
+Pass it with `--allowlist <file>` or set the `ZAK_GUARD_ALLOWLIST` environment variable.
+
+---
+
+## How detectors work
+
+Each rule combines a regex pattern with a Shannon entropy minimum. The entropy gate cuts false positives on placeholder values like `YOUR_API_KEY_HERE` or `xxxxxxxxxxxx` that match the pattern shape but are obviously not real credentials.
+
+The staged scanner (`--staged`) parses `git diff --cached` and flags only added lines. It won't block you for secrets that were already in the repo before your change.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Clean, no findings |
+| 1 | One or more secrets detected |
+| 2 | Error (not inside a git repo, git not found, etc.) |
+
+---
+
+## Development
+
+```sh
+git clone https://github.com/molloyzak13/zak-guard
+cd zak-guard
+pip install -e ".[dev]"
+pytest -v
+```
+
+---
+
+## License
+
+MIT

zak_guard-0.1.0/README.md

@@ -0,0 +1,140 @@
+# zak-guard
+
+A pre-commit secret scanner. Catches AWS keys, GitHub PATs, Stripe tokens, private keys, and other credentials before they land in your repo.
+
+Works standalone as a CLI tool and as a hook in the [pre-commit](https://pre-commit.com) framework.
+
+---
+
+## What it catches
+
+| Rule | Examples |
+|---|---|
+| AWS access key ID | `AKIA...` (20-char, high entropy) |
+| AWS secret access key | `AWS_SECRET_ACCESS_KEY=...` env var assignments |
+| GitHub PATs (classic + fine-grained) | `ghp_...`, `github_pat_...` |
+| GitHub OAuth / Actions / refresh tokens | `gho_`, `ghs_`, `ghr_` |
+| OpenAI keys (legacy + project) | `sk-...`, `sk-proj-...` |
+| Anthropic keys | `sk-ant-...` |
+| DeepSeek / generic `sk-` keys | `sk-` prefix with high entropy |
+| Stripe live keys | `sk_live_...`, `rk_live_...` |
+| Slack tokens | `xoxb-`, `xoxp-`, `xoxa-` |
+| Google API keys | `AIza...` |
+| PEM private key blocks | `-----BEGIN ... PRIVATE KEY-----` |
+| JWTs | Three base64url segments |
+| Generic `.env` assignments | `PASSWORD=...`, `SECRET=...`, `TOKEN=...` with high entropy |
+
+Every finding shows `file:line`, the rule name, and a redacted match (`AKIA...Y01`). The full value is never printed.
+
+---
+
+## Install
+
+```sh
+pip install zak-guard
+# or
+pipx install zak-guard
+```
+
+---
+
+## Use as a CLI
+
+Scan staged changes (what you're about to commit):
+
+```sh
+zak-guard --staged
+```
+
+Scan everything in the current directory:
+
+```sh
+zak-guard --all
+```
+
+Scan a specific path:
+
+```sh
+zak-guard --all ./src
+```
+
+Suppress known false positives with an allowlist:
+
+```sh
+zak-guard --staged --allowlist .zak-guard-allowlist
+```
+
+Wire it as a git pre-commit hook:
+
+```sh
+zak-guard install
+```
+
+---
+
+## Use with the pre-commit framework
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/molloyzak13/zak-guard
+    rev: v0.1.0
+    hooks:
+      - id: zak-guard
+```
+
+Then install:
+
+```sh
+pre-commit install
+```
+
+---
+
+## Allowlist
+
+Create a text file with one entry per line. Any detected value that contains an allowlist entry is suppressed. Lines starting with `#` are comments.
+
+```
+# .zak-guard-allowlist
+AKIAEXAMPLE         # known-fake key in test fixtures
+sk_live_test_       # Stripe test mode prefix used in integration tests
+```
+
+Pass it with `--allowlist <file>` or set the `ZAK_GUARD_ALLOWLIST` environment variable.
+
+---
+
+## How detectors work
+
+Each rule combines a regex pattern with a Shannon entropy minimum. The entropy gate cuts false positives on placeholder values like `YOUR_API_KEY_HERE` or `xxxxxxxxxxxx` that match the pattern shape but are obviously not real credentials.
+
+The staged scanner (`--staged`) parses `git diff --cached` and flags only added lines. It won't block you for secrets that were already in the repo before your change.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Clean, no findings |
+| 1 | One or more secrets detected |
+| 2 | Error (not inside a git repo, git not found, etc.) |
+
+---
+
+## Development
+
+```sh
+git clone https://github.com/molloyzak13/zak-guard
+cd zak-guard
+pip install -e ".[dev]"
+pytest -v
+```
+
+---
+
+## License
+
+MIT

zak_guard-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zak-guard"
+version = "0.1.0"
+description = "Pre-commit secret scanner: catches AWS keys, GitHub PATs, Stripe tokens, private keys, and more before they hit your repo"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Zak Molloy", email = "zakguard@proton.me" }]
+keywords = ["pre-commit", "security", "secrets", "git", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.scripts]
+zak-guard = "zak_guard.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/molloyzak13/zak-guard"
+Repository = "https://github.com/molloyzak13/zak-guard"
+Issues = "https://github.com/molloyzak13/zak-guard/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov>=4", "build>=1.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

zak_guard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zak_guard-0.1.0/src/zak_guard/__init__.py

@@ -0,0 +1,2 @@
+"""zak-guard: pre-commit secret scanner."""
+__version__ = "0.1.0"

zak_guard-0.1.0/src/zak_guard/cli.py

@@ -0,0 +1,157 @@
+"""
+zak-guard CLI entry point.
+
+Usage:
+  zak-guard [--staged] [--allowlist FILE]          # scan staged changes (default)
+  zak-guard --all [--allowlist FILE]               # scan entire repo from cwd
+  zak-guard --all PATH [--allowlist FILE]          # scan a specific path
+  zak-guard install                                # wire the git pre-commit hook
+"""
+
+import argparse
+import os
+import stat
+import sys
+from pathlib import Path
+
+from .scanner import scan_staged, scan_directory, scan_file, Finding
+
+
+EXIT_CLEAN = 0
+EXIT_FINDINGS = 1
+EXIT_ERROR = 2
+
+
+PRE_COMMIT_HOOK = """\
+#!/usr/bin/env sh
+# zak-guard pre-commit hook (installed by: zak-guard install)
+# Scans staged changes for secrets before each commit.
+exec zak-guard --staged
+"""
+
+
+def install_hook() -> int:
+    """Write the pre-commit hook into .git/hooks/pre-commit."""
+    git_dir = _find_git_dir()
+    if git_dir is None:
+        print("error: not inside a git repository", file=sys.stderr)
+        return EXIT_ERROR
+
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(exist_ok=True)
+    hook_path = hooks_dir / "pre-commit"
+
+    if hook_path.exists():
+        existing = hook_path.read_text()
+        if "zak-guard" in existing:
+            print(f"zak-guard hook already installed at {hook_path}")
+            return EXIT_CLEAN
+        # Back up existing hook
+        backup = hook_path.with_suffix(".pre-zak-guard")
+        hook_path.rename(backup)
+        print(f"existing pre-commit hook backed up to {backup}")
+
+    hook_path.write_text(PRE_COMMIT_HOOK)
+    hook_path.chmod(hook_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+    print(f"installed zak-guard pre-commit hook at {hook_path}")
+    return EXIT_CLEAN
+
+
+def _find_git_dir() -> Path | None:
+    """Walk up the directory tree looking for a .git directory."""
+    p = Path.cwd()
+    for candidate in [p, *p.parents]:
+        git = candidate / ".git"
+        if git.is_dir():
+            return git
+    return None
+
+
+def _print_summary(findings: list[Finding], mode: str) -> None:
+    if findings:
+        print(f"\nzak-guard found {len(findings)} potential secret(s) ({mode}):\n")
+        for f in findings:
+            print(f.format())
+        print(
+            "\nIf these are false positives, add the matching string to an allowlist file\n"
+            "and pass --allowlist <file> (or set ZAK_GUARD_ALLOWLIST in your environment).\n"
+            "Never commit real secrets. Redact them from history with git-filter-repo."
+        )
+    else:
+        print(f"zak-guard: no secrets found ({mode})")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="zak-guard",
+        description="Scan staged changes (or a path) for secrets before they hit your repo.",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand")
+
+    # install subcommand
+    subparsers.add_parser("install", help="Install zak-guard as the git pre-commit hook")
+
+    # Main scan flags
+    parser.add_argument(
+        "--staged",
+        action="store_true",
+        default=False,
+        help="Scan staged changes only (default mode for the pre-commit hook)",
+    )
+    parser.add_argument(
+        "--all",
+        dest="scan_all",
+        metavar="PATH",
+        nargs="?",
+        const=".",
+        default=None,
+        help="Scan all files under PATH (default: current directory)",
+    )
+    parser.add_argument(
+        "--allowlist",
+        metavar="FILE",
+        default=os.environ.get("ZAK_GUARD_ALLOWLIST"),
+        help="Path to a file of known-safe strings to ignore (one per line)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="zak-guard 0.1.0",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.subcommand == "install":
+        return install_hook()
+
+    allowlist = args.allowlist
+
+    if args.scan_all is not None:
+        # --all [PATH]
+        target = args.scan_all
+        path = Path(target)
+        if path.is_file():
+            findings = scan_file(target, allowlist)
+            mode = f"file scan: {target}"
+        elif path.is_dir():
+            findings = scan_directory(target, allowlist)
+            mode = f"directory scan: {target}"
+        else:
+            print(f"error: path does not exist: {target}", file=sys.stderr)
+            return EXIT_ERROR
+        _print_summary(findings, mode)
+        return EXIT_FINDINGS if findings else EXIT_CLEAN
+
+    # Default: staged scan (also what --staged explicitly requests)
+    try:
+        findings = scan_staged(allowlist)
+    except RuntimeError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return EXIT_ERROR
+
+    _print_summary(findings, "staged changes")
+    return EXIT_FINDINGS if findings else EXIT_CLEAN
+
+
+if __name__ == "__main__":
+    sys.exit(main())