{"id":40447399,"url":"https://github.com/hunt3r157/commit-shield","last_synced_at":"2026-01-20T17:04:26.024Z","repository":{"id":309611758,"uuid":"1036936250","full_name":"hunt3r157/commit-shield","owner":"hunt3r157","description":"A zero‑config, tiny pre-commit \u0026 pre-push guard that blocks accidental commits of secrets, huge files, and junk like node_modules/.","archived":false,"fork":false,"pushed_at":"2025-08-16T13:03:24.000Z","size":52,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-26T13:43:34.014Z","etag":null,"topics":["devsecops","git","git-hooks","github-actions","nodejs","pre-commit","pre-push","secrets","security"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/commit-shield","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hunt3r157.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T20:03:24.000Z","updated_at":"2025-08-16T13:03:27.000Z","dependencies_parsed_at":"2025-08-12T22:07:40.563Z","dependency_job_id":"5cb312cb-5d7f-43d4-8909-fab41173b14f","html_url":"https://github.com/hunt3r157/commit-shield","commit_stats":null,"previous_names":["hunt3r157/commit-shield"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hunt3r157/commit-shield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunt3r157%2Fcommit-shield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunt3r157%2Fcommit-shield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunt3r157%2Fcommit-shield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunt3r157%2Fcommit-shield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hunt3r157","download_url":"https://codeload.github.com/hunt3r157/commit-shield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hunt3r157%2Fcommit-shield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devsecops","git","git-hooks","github-actions","nodejs","pre-commit","pre-push","secrets","security"],"created_at":"2026-01-20T17:04:25.961Z","updated_at":"2026-01-20T17:04:26.016Z","avatar_url":"https://github.com/hunt3r157.png","language":"JavaScript","funding_links":["https://ko-fi.com/hunt3r157"],"categories":[],"sub_categories":[],"readme":"# **Commit-shield**\n\nTiny, zero‑dependency **pre-commit / pre-push guard** for Git that prevents secrets, giant files, and junk from entering your repo. Works with plain Git hooks and Node ≥ 18\\. CI re-check included.\n\n[![CI](https://img.shields.io/github/actions/workflow/status/hunt3r157/commit-shield/ci.yml?branch=main)](https://github.com/hunt3r157/commit-shield/actions)\n[![Release](https://img.shields.io/github/actions/workflow/status/hunt3r157/commit-shield/release.yml?label=release)](https://github.com/hunt3r157/commit-shield/actions)\n[![npm](https://img.shields.io/npm/v/commit-shield.svg)](https://www.npmjs.com/package/commit-shield)\n[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-ff5e5b?logo=kofi\u0026logoColor=white)](https://ko-fi.com/hunt3r157)\n\n\n---\n\n## **Table of contents**\n\n* Overview  \n* Key capabilities  \n* How it works  \n* Install  \n  * Option A — npx (recommended)  \n  * Option B — manual install  \n  * Monorepos  \n* Configuration  \n  * Schema  \n  * Examples  \n* CI integration (GitHub Actions)  \n* Enterprise rollout patterns  \n* Security \u0026 compliance  \n* Troubleshooting  \n* FAQ  \n* Roadmap  \n* Versioning \u0026 release  \n* Contributing  \n* Support  \n* License\n\n---\n\n## **Overview**\n\n`commit-shield` is a lightweight guard rail for teams that want immediate, local protection against accidental leaks and noisy commits. It ships as:\n\n* **Local hooks** (pre-commit \u0026 pre-push) — zero extra tooling like Husky required  \n* **Regex‑based content checks** — catches common secrets (keys/tokens)  \n* **Path/size filters** — blocks `node_modules/`, build artifacts, and files \\\u003e 5 MB by default  \n* **CI re-check** — ensures server‑side enforcement on PRs/pushes  \n* **No telemetry, no network calls** — privacy‑first by design\n\n## **Key capabilities**\n\n* Detects **private keys**, **Google service accounts**, **AWS access keys**, **GitHub PATs**, **Slack tokens**, `.env` files, and more  \n* Blocks **large files** (default \\\u003e 5 MB) and **junk paths** (`node_modules/**`, `dist/**`, `build/**`)  \n* Simple **JSON configuration** per repo  \n* **Fails fast** with actionable output and an intentional `--no-verify` escape hatch (policy‑controlled via CI)\n\n## **How it works**\n\n* The hook inspects **staged files** (`git diff --cached`) for pre-commit. For pre-push, it checks the **last commit range** as a courtesy.  \n* It applies three classes of rules:  \n  1. **Path rules** (globs): block known junk folders and dangerous filenames  \n  2. **Size rule**: block files larger than a configurable threshold  \n  3. **Content rules** (regex): scan text-ish files for common secret patterns  \n* Text detection is a simple heuristic to avoid scanning binaries.\n\n## **Install**\n\nRequires **Node ≥ 18** and **Git**.\n\n### **Option A — npx (recommended)**\n\n```\n# inside your git repo\nnpx commit-shield init\n# re-run safely for teammates at any time\n```\n\nRun a one-off check without installing hooks:\n\n```\nnpx commit-shield check pre-push\n```\n\n### **Option B — manual install**\n\n```\nmkdir -p scripts\n# copy these two files from this repo to your project\ncp scripts/commit-shield.mjs scripts/install.mjs ./scripts/\nnode scripts/install.mjs\n```\n\nAdd a convenience script (optional):\n\n```\n// package.json\n{\n  \"scripts\": { \"commit-shield:init\": \"node scripts/install.mjs\" }\n}\n```\n\n### **Monorepos**\n\n* Install once at the **top-level repo**. Hooks apply across packages.  \n* If you need per‑package policy, commit a `commit-shield.config.json` at the repo root (global rules) and add package‑specific patterns via CI jobs.\n\n## **Configuration**\n\nCreate `commit-shield.config.json` in the repo root. All keys are optional.\n\n### **Schema**\n\n```\n{\n  \"maxFileSizeMB\": 5,\n  \"disallowGlobs\": [\"node_modules/**\", \"dist/**\", \"build/**\"],\n  \"disallowFilenames\": [\".env\", \".env.*\", \"*serviceAccount*.json\", \"*-firebase-adminsdk-*.json\"],\n  \"disallowContentPatterns\": [\n    \"-----BEGIN [A-Z ]*PRIVATE KEY-----\",\n    \"\\\\\"type\\\\\"\\\\s*:\\\\s*\\\\\"service_account\\\\\"\",\n    \"\\\\\"private_key\\\\\"\\\\s*:\\\\s*\\\\\"-----BEGIN\",\n    \"AIza[0-9A-Za-z_\\\\-]{35}\",\n    \"AKIA[0-9A-Z]{16}\",\n    \"ghp_[0-9A-Za-z]{36}\",\n    \"xox[baprs]-[0-9A-Za-z-]+\"\n  ],\n  \"ignoreGlobs\": [\".git/**\"]\n}\n```\n\n**Notes**\n\n* Patterns are treated as **regex** for `disallowContentPatterns` and **globs** for `disallowGlobs`/`disallowFilenames`.  \n* Keep `ignoreGlobs` small — it acts as a hard exclude.\n\n### **Examples**\n\nBlock media and archives, raise file size limit to 10 MB:\n\n```\n{\n  \"maxFileSizeMB\": 10,\n  \"disallowGlobs\": [\n    \"node_modules/**\", \"dist/**\", \"build/**\",\n    \"**/*.zip\", \"**/*.tar\", \"**/*.gz\", \"**/*.7z\",\n    \"**/*.mp4\", \"**/*.mov\", \"**/*.mp3\"\n  ]\n}\n```\n\nAdd Azure \u0026 Stripe patterns:\n\n```\n{\n  \"disallowContentPatterns\": [\n    \"(?:sv|sp|sig|se|sr)=[A-Za-z0-9%]+\u0026sig=[A-Za-z0-9%/+]+\",   \n    \"sk_live_[0-9a-zA-Z]{24}\"                                 \n  ]\n}\n```\n\n## **CI integration (GitHub Actions)**\n\nThis repo includes:\n\n* `.github/workflows/ci.yml` — runs `commit-shield` in a pre‑push style on **pushes/PRs**  \n* `.github/workflows/release.yml` — publishes to **npm** on tags `v*.*.*` when `NPM_TOKEN` is configured\n\nMinimal CI job (inline example):\n\n```\nname: commit-shield CI\non: [push, pull_request]\njobs:\n  check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with: { node-version: 20 }\n      - run: node scripts/commit-shield.mjs pre-push\n```\n\n**Enterprise enforcement**: Protect your main branches to **require the CI check to pass**. This neutralizes local `--no-verify` bypasses.\n\n## **Enterprise rollout patterns**\n\n* **Template repos**: bake `commit-shield` into your org templates.  \n* **Org policy**: branch protection with required status checks.  \n* **Monorepo**: configure at root; optionally run per‑package CI matrix jobs with different patterns.  \n* **Education**: document a standard bypass policy (e.g., generated code) and require a PR approval when bypassing.\n\n## **Security \u0026 compliance**\n\n* **Scope**: best‑effort pattern checks to prevent common mistakes; not a substitute for dedicated secret scanners (e.g., org‑wide providers).  \n* **Privacy**: no telemetry, no network calls, no data leaves the developer machine or CI.  \n* **Performance**: scans staged files only; large binary files are size‑checked without content reads.  \n* **Bypass**: `git commit --no-verify` remains available by Git design. Enforce via CI \\+ branch protection.  \n* **Disclosure**: report vulnerabilities privately via SECURITY.md.\n\n## **Troubleshooting**\n\n**The hook didn’t run**\n\n* Ensure `.git/hooks/pre-commit` and `pre-push` exist and are executable. Re-run `npx commit-shield init`.\n\n**False positives**\n\n* Add narrowly‑scoped patterns to `ignoreGlobs`, or reduce `disallowContentPatterns`.\n\n**Binary files flagged as text**\n\n* Very large files are blocked by size alone. If needed, add explicit globs to `ignoreGlobs`.\n\n**Team member bypasses locally**\n\n* Require the CI job on protected branches. Optionally, codify a PR template checklist.\n\n## **FAQ**\n\n**Why not Husky / pre-commit?**  \nThose are great. `commit-shield` focuses on zero‑dep, native Git hooks and works without extra tooling, while still pairing nicely with CI.\n\n**Does this scan the entire history?**  \nNo. It’s a *preventive* guard on staged changes, plus CI re-checks.\n\n**Can I add custom rules?**  \nYes, via `commit-shield.config.json` (globs \u0026 regexes).\n\n**Windows support?**  \nYes — hooks are POSIX shell scripts invoking Node; Git for Windows provides a compatible shell.\n\n## **Roadmap**\n\n* Git LFS suggestions for large file types  \n* Inline allow‑list pragma (`# commit-shield: allow`)  \n* CI companion with smarter diff range detection  \n* Additional built‑in secret patterns\n\n## **Versioning \u0026 release**\n\n* Semantic Versioning  \n* Tag `vX.Y.Z` to trigger the **Release** workflow, which publishes to npm using `NPM_TOKEN` (see README section on publishing in repo).\n\n## **Contributing**\n\nSee CONTRIBUTING.md. By participating, you agree to the Code of Conduct.\n\n## **Support**\n\n* **Bugs / feature requests**: open an issue  \n* **Security**: follow SECURITY.md\n\n## **License**\n\nMIT © commit-shield contributors\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunt3r157%2Fcommit-shield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhunt3r157%2Fcommit-shield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhunt3r157%2Fcommit-shield/lists"}