Skip to content

PLAN.md

Latest commit

 

History

History
70 lines (55 loc) · 2.72 KB

PLAN.md

File metadata and controls

70 lines (55 loc) · 2.72 KB
Raw

GForge (Python) Plan

Current goal: a faithful Python port of GForge — a minimal installer for secure global Git hooks, with the same detection engine.

MVP

  1. Command entry point (gforge console script) — Done
  2. Detect Git, platform, shell, and home directory — Done
  3. Create a GForge-owned hooks directory — Done
  4. Install the pre-commit secret firewall — Done
  5. Configure global core.hooksPath — Done
  6. verify, update, and uninstall commands — Done
  7. Tests for repeated runs and safe uninstall — Done

Commands

gforge install
gforge verify
gforge update
gforge uninstall

Safety Requirements

  • Re-running install must be safe.
  • Verify must be read-only.
  • Uninstall must remove only GForge-owned files/config.
  • Git config changes must be backed up or clearly reversible.
  • Hooks must avoid exposing secrets in logs.
  • The scanner must fail closed: if it cannot run, the commit is blocked.

Detection Engine

The pre-commit hook delegates to a self-contained Python scanner (src/gforge/scanner.py, installed as ~/.gforge/hooks/gforge_scan.py):

  • .env cross-reference (values from git-ignored .env files matched verbatim).
  • Provider rules (AWS, GitHub, Google, Slack, Stripe, npm, PyPI, private keys, JWTs, …).
  • Generic credential keyword=value detection (catches DB_PASS=…).
  • Shannon-entropy detection for unnamed secrets (skips SHAs/UUIDs/lockfiles/paths).
  • Secret-file rules (.env, id_rsa, *.p12, keystores, …; templates allowed).
  • Allowlist via .gforgeignore and inline gforge:allow.
  • Optional gitleaks pass merged in when the binary is present.
  • Redacted output (never prints matched values).

Port Status

Upstream module Python module State
src/cli.js src/gforge/cli.py Done
src/environment.js src/gforge/environment.py Done
src/git-config.js src/gforge/git_config.py Done
src/hooks.js src/gforge/hooks.py Done
src/installer.js src/gforge/installer.py Done
src/metadata.js src/gforge/metadata.py Done
src/npm-update.js src/gforge/pypi_update.py Done (pip/PyPI)
src/scanner.js src/gforge/scanner.py Done
src/verify.js src/gforge/verify.py Done
scripts/postinstall.js — Not portable; replaced by explicit gforge install

Next Work

  1. Publish to PyPI and validate pipx install gforge end to end.
  2. Add CI across macOS / Linux / Windows and Python 3.9–3.13. Done (GitHub Actions).
  3. Track upstream releases and carry detection changes across in both directions.
  4. Consider: configurable rule packs, per-org shared allowlists, secret history scan.