prehook

prehook

Stop secrets before they ship. prehook is a single-binary CLI that installs local pre-commit and pre-push Git hooks to scan for leaked secrets, vulnerable dependencies, and code quality issues -- before your code ever leaves your machine.

Install

From source (requires Go 1.23+)

go install github.com/arunsanna/prehook@latest

Homebrew (macOS / Linux)

brew tap arunsanna/tap
brew install prehook

Scoop (Windows)

scoop bucket add arunsanna https://github.com/arunsanna/scoop-bucket
scoop install prehook

Binary download

Download the latest release from the Releases page.

Extract and place the binary somewhere on your PATH.

Quickstart

1. Initialize config in your repository root:

prehook init

1. Install managed hooks:

prehook install

1. Check local dependencies:

prehook doctor

1. Enforce pinned scanner versions (optional hard mode):

prehook doctor --require-pins

Commands

• prehook init creates .prehook.yaml with secure defaults.
• prehook install installs managed pre-commit and pre-push hooks.
• prehook doctor validates required scanner binaries and configured version pins.
• prehook run --stage pre-commit|pre-push runs stage gates directly.
• prehook cleanup prints manual secret remediation guidance.
• prehook version prints the CLI version.

Stage Behavior

pre-commit

• Builds a temporary snapshot from the Git index (not the working tree).
• Runs gitleaks and trufflehog against staged content.
• trufflehog policy defaults to block verified secrets and warn on unknown/unverified findings.
• Blocks commit on scanner failures by default.

pre-push

• Computes changed files from pre-push refs; falls back to HEAD~1..HEAD when refs are absent.
• Runs semgrep on changed files.
• Runs osv-scanner when dependency manifest or lock files changed.
• Runs trivy filesystem scan with configured severity.
• Runs quality test command and optional coverage command + threshold gate.
• Blocks push on failures by default.

Tool Dependencies

prehook delegates scanning to external tools. Install the ones you enable in .prehook.yaml:

Run prehook doctor after installing to verify everything is found and version-compatible.

Example Config

version: 1
pre_commit:
  blocking: true
  gitleaks:
    enabled: true
    blocking: true
    timeout: 2m
  trufflehog:
    enabled: true
    blocking: true
    timeout: 2m
    block_verified: true
    block_unknown: false
pre_push:
  blocking: true
  semgrep:
    enabled: true
    blocking: true
    timeout: 5m
  osv:
    enabled: true
    blocking: true
    timeout: 5m
  trivy:
    enabled: true
    blocking: true
    timeout: 8m
    severity: HIGH,CRITICAL
  quality:
    enabled: true # opt-in: set your own test command
    blocking: true
    test_command: go test ./... # replace with your language's test runner
    test_timeout: 10m
    coverage:
      enabled: true
      blocking: true
      command: go test ./... -coverprofile=coverage.out
      timeout: 15m
      threshold: 60
      file: coverage.out
tool_versions:
  gitleaks: ">=8.0.0"
  trufflehog: ">=3.0.0"
  semgrep: ">=1.0.0"
  osv_scanner: ">=1.0.0"
  trivy: ">=0.50.0"
allowlist:
  - pattern: "example-test-secret"
    reason: "fixture data"
    owner: "security@company.com"
    expires_on: "2026-12-31"

Homebrew Tap Packaging

1. Compute source tarball sha256 for vX.Y.Z.
2. Render formula from template:

packaging/scripts/prepare-homebrew-formula.sh \
  --owner <github-owner> \
  --repo <github-repo> \
  --version <x.y.z>

1. Copy packaging/homebrew/prehook.rb into your tap repo under Formula/prehook.rb.
2. Publish release artifacts with goreleaser.

Advanced manual rendering: packaging/scripts/render-homebrew-formula.sh. Template file: packaging/homebrew/prehook.rb.tmpl.

Caveat

Git hooks are local controls and can be bypassed intentionally with --no-verify. Treat prehook as a local guardrail, not a complete enforcement layer.