Gitveil

Scan before you push.
Catch what shouldn't leave your machine.

---

What is Gitveil?

Gitveil is a developer security tool designed to prevent secrets, private cryptographic keys, personal data, and risky configuration files from ever leaking to GitHub or remote repositories.

Unlike cloud-based post-push scanners that alert you after credentials are already exposed on public Git logs, Gitveil operates locally in your workflow as a Git pre-commit hook and fast CLI tool.

---

Why Gitveil?

Pushing a secret to a public repository takes one second, but remediating an exfiltrated credential requires immediate key rotation, revoking access tokens, auditing cloud logs for fraudulent usage, and rewriting Git history.

Gitveil is founded on three core architectural principles:

1. Local-First: All code scanning and report generation happen directly on your workstation. No telemetry, no external network requests, and no third-party data transmission.
2. Safe by Design: Gitveil strictly redacts all detected secrets in terminal outputs, JSON reports, and browser viewers. Raw secrets are discarded immediately after cryptographic fingerprinting.
3. Explainable: No alarmist alerts or black-box scores. Every finding clearly explains why it matters and what precise remediation steps are required.

---

Terminal Preview

$ gitveil scan --staged

Gitveil
Scan before you push.

✓ 31 files scanned

Findings

HIGH
  src/config.ts:18:24
  OpenAI API key detected
  value: sk-proj-ab••••••••••••••••••••••••••••••••••••••••91kd

LOW
  scripts/build.ts:7:15
  Local developer workstation directory path detected
  value: C:\Users\••••••\Desktop\project

────────────────────────

2 findings
1 high
1 low

Risk Score: 24 / 100
Status: Low risk
Completed in 18ms

---

Features

• 🔍 Staged Git Scanning (--staged): Directly queries the Git index (git show :path) to ensure you scan the exact payload being committed, not uncommitted edits on disk.
• 🛡️ Non-Destructive Pre-Commit Hook: Easily installs into .git/hooks/pre-commit without clobbering existing pre-commit frameworks like Husky or custom shell scripts.
• ⚡ Lightning Fast: Analyzes hundreds of files in milliseconds with asynchronous traversal, concurrency limits, and automatic binary file detection.
• 🔒 Absolute Redaction: Secrets are always masked (e.g. sk-12••••••••mnop). Raw sensitive values are never logged or stored.
• 📊 Risk Scoring (0–100): Deterministic, heuristic-based risk calculations that factor in finding severity, token count, and commit staging status.
• 📁 Baseline Tracking (.gitveil-baseline.json): Adopt Gitveil on mature, existing repositories without getting blocked by historical findings.
• 🌐 Client-Side Web Report Viewer: Zero-backend interactive visualization viewer (apps/web) with English and Turkish language support.
• 📋 GitHub Code Scanning (SARIF): Native SARIF 2.1.0 output for seamless GitHub Actions security workflows.
• 🛡️ Platform & Symlink Safety: Handles Windows, macOS, and Linux paths consistently and safely rejects symlinks that attempt to escape the repository root.

---

Quick Start

Run instantly with npx:

# Scan current repository
npx gitveil scan

# Scan only staged files before committing
npx gitveil scan --staged

Or install globally:

npm install -g gitveil
gitveil scan

---

CLI Usage

Basic Commands

# Scan current directory
gitveil scan

# Scan a specific directory
gitveil scan ./my-project

# Scan only files staged in the Git index
gitveil scan --staged

# Output machine-readable JSON to stdout
gitveil scan --json

# Save report to a file
gitveil scan --output gitveil-report.json

# Generate SARIF 2.1.0 report for GitHub Security
gitveil scan --format sarif --output gitveil.sarif

# Configure blocking severity threshold (critical, high, medium, low, never)
gitveil scan --fail-on high

# Verbose output with remediation guidance and fingerprints
gitveil scan --verbose

# Quiet mode (summary and exit code only)
gitveil scan --quiet

# List all available detection rules
gitveil rules

# Explain a specific rule and its remediation
gitveil explain private-key

Exit Codes

Exit Code	Meaning
0	Clean — No findings detected, or findings are below the --fail-on threshold.
1	Blocking Findings — Findings detected at or above the --fail-on threshold.
2	Runtime Error — Invalid path, configuration error, or not in a Git repository.

---

Pre-Commit Hook

Protect your repository automatically on every git commit:

# Install Gitveil pre-commit hook
gitveil install

# Specify custom blocking threshold
gitveil install --fail-on critical

When a commit contains high-risk secrets, Gitveil prevents the commit:

Gitveil blocked this commit.
High-risk findings detected in staged files.
Run: gitveil scan --staged

To safely remove the hook:

gitveil uninstall

---

Detection Rules

Gitveil includes 16 built-in detection rules:

Rule ID	Category	Severity	Description
private-key	private-key	CRITICAL	Unencrypted private cryptographic key blocks (RSA, EC, OpenSSH, DSA, PGP).
github-token	token	CRITICAL	GitHub personal access tokens, OAuth tokens, and fine-grained PATs.
stripe-secret-key	secret	CRITICAL	Stripe live secret (sk_live_) and restricted (rk_live_) API keys.
aws-access-key	credential	HIGH	Amazon Web Services (AWS) Access Key IDs and secret credentials.
openai-api-key	secret	HIGH	OpenAI standard, project, and service account API keys.
anthropic-api-key	secret	HIGH	Anthropic Claude API keys.
slack-token	token	HIGH	Slack bot, app, and user OAuth API tokens.
google-api-key	secret	HIGH	Google Cloud Platform and Firebase API keys.
generic-bearer-token	token	HIGH	Hardcoded HTTP Authorization Bearer tokens.
hardcoded-password	password	HIGH	Password and secret assignments (filters safe references like process.env).
high-entropy-secret	secret	HIGH	Shannon high-entropy random strings assigned to sensitive variables.
credential-file	credential	HIGH / CRITICAL	Sensitive credential files (credentials.json, id_rsa, *.key, *.pem).
env-file	env	MEDIUM	Tracked or staged environment files (.env, .env.production).
jwt-token	token	MEDIUM	Hardcoded JSON Web Tokens containing authorization claims.
personal-email	personal-data	LOW	Personal developer email addresses in source files.
local-path	path	LOW	Local workstation paths exposing developer usernames.

---

Configuration

Create gitveil.config.json in your repository root:

{
  "severityThreshold": "high",
  "maxFileSize": 5242880,
  "ignore": [
    "tests/fixtures/**",
    "docs/snippets/**"
  ],
  "disabledRules": [
    "personal-email"
  ],
  "allowlist": [
    "df1c996b197d23146ef81ec286c4226c"
  ]
}

.gitveilignore

Ignore specific files or mock directories using standard .gitignore syntax:

# Tests and mock credentials
fixtures/**
examples/demo-secret.txt

---

Baseline Management

To introduce Gitveil into a large legacy codebase without blocking existing developers:

gitveil baseline

This creates .gitveil-baseline.json containing the SHA-256 fingerprints of current findings. Subsequent scans will only block on newly introduced secrets.

---

GitHub Actions Integration

Add Gitveil to your CI workflow:

name: Gitveil Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx gitveil scan --fail-on high

For SARIF reporting with GitHub Code Scanning:

name: Gitveil SARIF

on:
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx gitveil scan --format sarif --output gitveil.sarif || true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: gitveil.sarif

---

Web Report Viewer

Gitveil includes a standalone web report viewer in apps/web:

• 100% Client-Side: Processes .json report files locally in the browser via FileReader. No data is uploaded to any server.
• Multilingual: Supports English and Turkish.
• Interactive Filtering: Filter by severity, category, rule, and file path.
• Exporting: Export filtered JSON or Markdown summaries for pull request descriptions.

---

How Detection Works

Gitveil avoids naive, noisy regex patterns like password=.*. Instead, it combines multiple analysis vectors:

1. Known Token Prefixes: High-precision matches for standardized vendor prefixes (sk-proj-, ghp_, AKIA, xoxb-, etc.).
2. Contextual Evaluation: Distinguishes between secret assignments and safe usage patterns (e.g. const password = process.env.PASSWORD is recognized as safe).
3. Shannon Entropy: Evaluates the randomness and character set diversity ($-\sum p(x) \log_2 p(x)$) of candidates to distinguish random keys from repetitive text or English words.
4. File Type & Size Guards: Inspects binary headers for null bytes and respects configurable size limits (maxFileSize, default 5 MB).

---

Important Security Disclaimer

Caution

Gitveil is designed to catch common accidental leaks during local development; it is not a replacement for full security reviews, penetration testing, or defense-in-depth architecture.

No secret scanner can guarantee 100% detection. If a credential has already been pushed to a remote repository, revoke and rotate it immediately. Simply removing the secret in a follow-up commit does not purge it from Git history or attacker caches.

---

Roadmap

• Custom community rule packs
• VS Code Extension with inline privacy squiggles
• Native GitHub App integration
• Standalone Rust CLI binary
• Additional cloud provider rules (Azure, GCP Service Accounts, Supabase, Twilio)
• Enterprise policy enforcement

---

Contributing

We welcome contributions! Please review CONTRIBUTING.md for architecture guidelines, rule development tutorials, and testing workflows.

---

License

Gitveil is open-source software licensed under the MIT License.