GitShield

Stop secrets from ever reaching GitHub — before they leave your laptop.

A local, zero account pre-commit secret scanner with a built in dashboard, entropy based detection for unknown secret formats, custom rules, and a CI safety net. No signup. No cloud. No data leaves your machine.

Quick Start • Why GitShield • Features • Comparison • Config • Contributing

---

The problem

Every developer has done this at least once:

git add .
git commit -m "quick fix"
git push

...and thirty seconds later realized .env was in that commit. By then it's in your git history forever, bots are already scraping public repos for exposed keys, and you're rotating credentials at 2 AM.

GitShield stops this before it happens — it scans what you're about to commit, before it's committed, and blocks it if something looks like a secret.

---

⚡ Quick Start

# 1. Install
git clone <your-repo-url> gitshield && cd gitshield && npm install && npm link

# 2. Protect any repo
cd ~/your-project
gitshield init

# That's it. Every commit is now scanned automatically.

---

Features

100% local	No account, no API key, nothing ever leaves your machine
Entropy detection	Catches unknown/custom secret formats, not just known patterns
10+ built-in patterns	AWS, Discord, Slack, Stripe, private keys, DB connection strings, and more
Local dashboard	Visual leak history at localhost:4517 — see trends, not just terminal noise
Fully configurable	Your own regex rules and severity thresholds via .gitshield.yml
One-command setup	gitshield init and you're protected — no manual husky/hook wiring
CI backup	GitHub Action template catches anything bypassed with --no-verify
VS Code extension	Inline warnings as you type (starter included)
Minimal dependencies	3 small, well-known packages,nothing sketchy to audit

---

How it compares :

	GitShield	gitleaks	truffleHog	GitGuardian (ggshield)
Local pre-commit hook	✅	✅ (manual setup)	✅ (manual setup)	✅
Zero account / zero cloud	✅	✅	✅	❌ requires account
Visual local dashboard	✅	❌	❌	❌ (cloud dashboard only)
Entropy-based detection	✅	✅	✅	✅
Custom rules via config file	✅	✅	✅	✅
One-command hook install	✅ gitshield init	❌ manual	❌ manual	✅
CI template included	✅	✅	✅	✅

GitShield's niche: the combination of zero-cloud and a visual dashboard — most tools give you one or the other, not both.

---

What it detects out of the box

• AWS Access Key IDs and secret keys
• Discord bot tokens and webhook URLs
• Slack tokens
• Stripe live secret keys
• Private key blocks (RSA / EC / OpenSSH / DSA)
• Generic API key / secret / password assignments
• Database connection strings with embedded credentials
• Anything else with high enough randomness — via Shannon-entropy analysis

---

CLI Reference

gitshield init                 # install the pre-commit hook in this repo
gitshield scan                 # scan all tracked files
gitshield scan --staged        # scan only staged files (used by the hook)
gitshield dashboard             # open the dashboard at http://localhost:4517
gitshield dashboard -p 8080     # run the dashboard on a custom port
gitshield --help
gitshield --version

Bypass a blocked commit if you're confident it's a false positive:

git commit --no-verify

---

Ignoring files

.gitshieldignore in your repo root, one glob pattern per line:

test/fixtures/*
docs/example.env

Or ignore a single line with a # gitshield-ignore comment on that line.

---

Custom configuration (.gitshield.yml)

Copy .gitshield.yml.example to .gitshield.yml and customize:

entropy:
  enabled: true
  threshold: 4.0
  minLength: 20
  severity: medium

ignore:
  - "test/fixtures/*"

customPatterns:
  - name: "Internal Company Token"
    regex: "INTL_[A-Za-z0-9]{20,}"
    severity: high

severityThreshold: low   # low | medium | high | critical

severityThreshold controls what actually blocks a commit — raise it to high if entropy-based medium findings are too noisy for your project.

---

CI backup: GitHub Action

Local hooks can be bypassed with --no-verify. Copy templates/github-action.yml into .github/workflows/gitshield.yml in the repo you want protected, and every push/PR gets scanned server-side too.

---

VS Code extension (starter)

vscode-extension/ underlines likely secrets inline as you type, using the same pattern list as the CLI. It's a working prototype, not yet marketplace-published — see vscode-extension/README.md for the remaining steps.

---

Roadmap

• Publish to npm (npx gitshield init with no clone needed)
• Publish the VS Code extension to the marketplace
• GitLab CI / Bitbucket Pipelines templates
• gitshield scan --fix to auto-suggest .env + .gitignore fixes

How the demo animation was made / how to regenerate it

assets/gitshield-demo.svg is generated from a real terminal session using asciinema-format recordings and svg-term-cli — no screen recording software needed.

npm install -g svg-term-cli
asciinema rec assets/gitshield-demo.cast
# run: gitshield init, add a fake secret, then git commit -m "oops"
# press Ctrl+D to stop recording
svg-term --in assets/gitshield-demo.cast --out assets/gitshield-demo.svg --window --profile "Dracula"

It plays automatically once pushed to GitHub — no extra setup needed.

---

Contributing

Issues and PRs welcome. Good first contributions:

• New secret patterns in lib/patterns.js
• False positive reports (open an issue with a redacted example)
• Dashboard UI improvements

---

📜 License:

MIT — see LICENSE

Made by DieBack Theatre ~~ Faysal Ahmed