{"_id":"gitleaks-secret-scanner","_rev":"17-13309542c346bd3d73a73a008c889f17","name":"gitleaks-secret-scanner","dist-tags":{"latest":"2.1.1","beta":"2.0.0-beta.1"},"versions":{"1.1.1":{"name":"gitleaks-secret-scanner","version":"1.1.1","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"author":{"name":"Vijay Kumar"},"license":"MIT","_id":"gitleaks-secret-scanner@1.1.1","maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"bin":{"gitleaks-secret-scanner":"bin/cli.js"},"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues","dist":{"shasum":"99c669ceb0b6e442da4c59a7b7d436773f6de6ac","tarball":"https://registry.npmjs.org/gitleaks-secret-scanner/-/gitleaks-secret-scanner-1.1.1.tgz","fileCount":11,"integrity":"sha512-ndU27QKo79930vSeoIUB9CDvcepZfM2Y2124BPbse0F7oikd2Ari8G2P1yYj0X65qP4tmxkoNPr089jTvNNJiA==","signatures":[{"sig":"MEUCIQCjfpLjZkW1HxEH+ZoPkZ4znwuKJjztKUHM0TeXVdDgCwIgNVqT/0JiNhRrHJ340+B1HTD0ndzONSZc0+UwYNzllcc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":134801},"main":"bin/cli.js","engines":{"node":">=18"},"gitHead":"9a5f7ad371eafe49cae0f56059236c915102da8e","scripts":{"postinstall":"node bin/set-permissions.js && node bin/cli.js --install-only"},"_npmUser":{"name":"the-codepocalypse","actor":{"name":"the-codepocalypse","type":"user","email":"sirigirivijay123@gmail.com"},"email":"sirigirivijay123@gmail.com"},"repository":{"url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git","type":"git"},"_npmVersion":"10.9.2","description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"tar":"^6.2.1","toml":"^3.0.0","axios":"^1.7.2","fs-extra":"^11.2.0","unzipper":"^0.12.3"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gitleaks-secret-scanner_1.1.1_1750833187238_0.601719131195412","host":"s3://npm-registry-packages-npm-production"}},"1.1.2":{"name":"gitleaks-secret-scanner","version":"1.1.2","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"author":{"name":"Vijay Kumar"},"license":"MIT","_id":"gitleaks-secret-scanner@1.1.2","maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"bin":{"gitleaks-secret-scanner":"bin/cli.js"},"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues","dist":{"shasum":"5e8de20e89ec32c1eaf2204e41c54ebf6310172d","tarball":"https://registry.npmjs.org/gitleaks-secret-scanner/-/gitleaks-secret-scanner-1.1.2.tgz","fileCount":11,"integrity":"sha512-9N5kyjH1zkZMsOUpSUFEj1iogfQSXLhDGf1Mk4JW9KQXubnssdjnEQMijyFAXyWBngOqxV2gefbN0jgeLN4zLA==","signatures":[{"sig":"MEQCIARSupIH9ubCSM867zV1jojO+pb0cmKDL4Cx/LJkFdlXAiBD4NxLxSBnOuhvJmqYsHxOFTS9DcOyzANvoB+0B39rVQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":136477},"main":"bin/cli.js","engines":{"node":">=18"},"gitHead":"6c09ecbce9d78a8ebdb6fe3ee03f93c49f601278","scripts":{"postinstall":"node bin/set-permissions.js && node bin/cli.js --install-only"},"_npmUser":{"name":"the-codepocalypse","actor":{"name":"the-codepocalypse","type":"user","email":"sirigirivijay123@gmail.com"},"email":"sirigirivijay123@gmail.com"},"repository":{"url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git","type":"git"},"_npmVersion":"10.9.2","description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"tar":"^6.2.1","toml":"^3.0.0","axios":"^1.7.2","fs-extra":"^11.2.0","unzipper":"^0.12.3"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gitleaks-secret-scanner_1.1.2_1750868643792_0.5493982368543233","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"gitleaks-secret-scanner","version":"1.2.0","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"author":{"name":"Vijay Kumar"},"license":"MIT","_id":"gitleaks-secret-scanner@1.2.0","maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"bin":{"gitleaks-secret-scanner":"bin/cli.js"},"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues","dist":{"shasum":"f75d8d8a718acb98b1dcea5bc1b35cb0f045274d","tarball":"https://registry.npmjs.org/gitleaks-secret-scanner/-/gitleaks-secret-scanner-1.2.0.tgz","fileCount":11,"integrity":"sha512-spK5X29rBuuVEOdgS5UFr5VkoOxgP7cSbp7l5yKzICqxsORZ5eBUf9YE6dyWDaguH2m5cZO9D9DOCNFnfMq6rQ==","signatures":[{"sig":"MEYCIQDK8Dk6HcI/EHHdjbMl7RghDn66eLYhVRl0QaMReX7DiAIhAJoxNU3Z3BIuSIGHv10eN2KSgR0HdxKxKCIxaRMpUST0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":135237},"main":"bin/cli.js","engines":{"node":">=18"},"gitHead":"2d12466f5fc28bae936edd809e4183db6748d807","scripts":{"postinstall":"node bin/set-permissions.js && node bin/cli.js --install-only"},"_npmUser":{"name":"the-codepocalypse","actor":{"name":"the-codepocalypse","type":"user","email":"sirigirivijay123@gmail.com"},"email":"sirigirivijay123@gmail.com"},"repository":{"url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git","type":"git"},"_npmVersion":"10.9.2","description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"tar":"^6.2.1","toml":"^3.0.0","axios":"^1.7.2","fs-extra":"^11.2.0","unzipper":"^0.12.3"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gitleaks-secret-scanner_1.2.0_1751205928726_0.634360715173167","host":"s3://npm-registry-packages-npm-production"}},"1.2.1":{"name":"gitleaks-secret-scanner","version":"1.2.1","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"author":{"name":"Vijay Kumar"},"license":"MIT","_id":"gitleaks-secret-scanner@1.2.1","maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"bin":{"gitleaks-secret-scanner":"bin/cli.js"},"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues","dist":{"shasum":"e919a29e6680b4adb193657faebb85a145bee649","tarball":"https://registry.npmjs.org/gitleaks-secret-scanner/-/gitleaks-secret-scanner-1.2.1.tgz","fileCount":11,"integrity":"sha512-OMDISryNKHd24fJywe9q7QOQUJgK995puof+XuLAnAFiCP3zq4L6Bg9zT/Jx/LVWgYJYT40ZDzDVa/Npig/vQw==","signatures":[{"sig":"MEQCIHa+uhgN0mqq9Ti97+g+bDeP3reaWFFvw2hlesGWnhGSAiBudtEewM8luy4I0Uy1fmFgTFmKf0tC2ts6I8JSN0ywbA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":135074},"main":"bin/cli.js","engines":{"node":">=18"},"gitHead":"d0b8a1a9f8a799670971176003ab513728de1328","scripts":{"postinstall":"node bin/set-permissions.js && node bin/cli.js --install-only"},"_npmUser":{"name":"the-codepocalypse","actor":{"name":"the-codepocalypse","type":"user","email":"sirigirivijay123@gmail.com"},"email":"sirigirivijay123@gmail.com"},"repository":{"url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git","type":"git"},"_npmVersion":"10.9.2","description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"tar":"^6.2.1","toml":"^3.0.0","axios":"^1.7.2","fs-extra":"^11.2.0","unzipper":"^0.12.3"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gitleaks-secret-scanner_1.2.1_1751212034311_0.7770560079447049","host":"s3://npm-registry-packages-npm-production"}},"1.2.2":{"name":"gitleaks-secret-scanner","version":"1.2.2","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"author":{"name":"Vijay Kumar"},"license":"MIT","_id":"gitleaks-secret-scanner@1.2.2","maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"bin":{"gitleaks-secret-scanner":"bin/cli.js"},"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues","dist":{"shasum":"6d9025a64985bf8551d8ae14e8f594bfc5a87721","tarball":"https://registry.npmjs.org/gitleaks-secret-scanner/-/gitleaks-secret-scanner-1.2.2.tgz","fileCount":11,"integrity":"sha512-yGscs91JUSuxPYGa399kgciNLKGB41IwD6tD8GyAnxpBtrYTl7sFAvKQlOz6dI75BpwkDN5vgf3KU1wpCGa84Q==","signatures":[{"sig":"MEUCIBTjI7GJsfi8SiXuiC5qHDyG4ygm6dzPL4pXKR+xl0FUAiEAlFn+VfQsqHRo2go97YXLoi+d3oAxN16/uoCTedB92Fg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":136872},"main":"bin/cli.js","engines":{"node":">=18"},"gitHead":"54dd9929d0cb0df3b9de2ce3cdb02cbcdd61e03f","scripts":{"postinstall":"node bin/set-permissions.js && node bin/cli.js --install-only"},"_npmUser":{"name":"the-codepocalypse","actor":{"name":"the-codepocalypse","type":"user","email":"sirigirivijay123@gmail.com"},"email":"sirigirivijay123@gmail.com"},"repository":{"url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git","type":"git"},"_npmVersion":"10.9.2","description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"tar":"^6.2.1","toml":"^3.0.0","axios":"^1.7.2","fs-extra":"^11.2.0","unzipper":"^0.12.3"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gitleaks-secret-scanner_1.2.2_1751306940187_0.5759728178682415","host":"s3://npm-registry-packages-npm-production"}},"2.0.0-beta.1":{"name":"gitleaks-secret-scanner","version":"2.0.0-beta.1","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"author":{"name":"Vijay Kumar"},"license":"MIT","_id":"gitleaks-secret-scanner@2.0.0-beta.1","maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"bin":{"gitleaks-secret-scanner":"bin/cli.js"},"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues","dist":{"shasum":"6bfcd0d7b4c3ffa23ce02820cdca1d1f499725f1","tarball":"https://registry.npmjs.org/gitleaks-secret-scanner/-/gitleaks-secret-scanner-2.0.0-beta.1.tgz","fileCount":15,"integrity":"sha512-wue4vkyC2naLVTs+V5H76ptBSyLyO30Ip4oDSh/JK9xPT6ljnTcCzYyOz0su3Okj6UVpzmAFdfhnOqfxyeRn5w==","signatures":[{"sig":"MEUCIAuebLD2/TL/HPWU+U5LczjRBovZcbLGAQnQuNHzBC4cAiEA4VOz2PzngJjfAokpXN+oHF8L4bcMdEz4yp5wH15kdj0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":176571},"main":"bin/cli.js","engines":{"node":">=18"},"gitHead":"5a12d26b49a6b8cd4a3a9a295c295464b47e1d8e","scripts":{"postinstall":"node bin/set-permissions.js && node bin/postinstall.js","preuninstall":"node bin/preuninstall.js"},"_npmUser":{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"},"repository":{"url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git","type":"git"},"_npmVersion":"11.6.0","description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","directories":{},"_nodeVersion":"24.7.0","dependencies":{"tar":"^6.2.1","toml":"^3.0.0","axios":"^1.11.0","fs-extra":"^11.2.0","unzipper":"^0.12.3"},"_hasShrinkwrap":false,"readmeFilename":"README.md","peerDependencies":{"husky":">=9.0.0"},"peerDependenciesMeta":{"husky":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/gitleaks-secret-scanner_2.0.0-beta.1_1767343383386_0.4373327767217581","host":"s3://npm-registry-packages-npm-production"}},"2.1.1":{"name":"gitleaks-secret-scanner","version":"2.1.1","description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","author":{"name":"Vijay Kumar"},"main":"bin/cli.js","bin":{"gitleaks-secret-scanner":"bin/cli.js"},"scripts":{"postinstall":"node bin/set-permissions.js && node bin/postinstall.js","preuninstall":"node bin/preuninstall.js"},"dependencies":{"axios":"^1.11.0","fs-extra":"^11.2.0","tar":"^6.2.1","toml":"^3.0.0","unzipper":"^0.12.3"},"peerDependencies":{"husky":">=9.0.0"},"peerDependenciesMeta":{"husky":{"optional":true}},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git"},"homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","url":"https://github.com/criisv7/gitleaks-secret-scanner/issues","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"engines":{"node":">=18"},"bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"_id":"gitleaks-secret-scanner@2.1.1","gitHead":"83978ee126b8bd6f190a8dee8c4be29b569f09f3","_nodeVersion":"24.7.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-Hk0hQHqgcOG+6hy4W8cMIuIVRQgA2PPjqOo2ryrlmsu0rOVM2wXAIpDTtsz82Ngx95UZnQMZTTsHUt5jfo0Fnw==","shasum":"104561c262fb9c9a125551f9fa0b2cc98ee079e5","tarball":"https://registry.npmjs.org/gitleaks-secret-scanner/-/gitleaks-secret-scanner-2.1.1.tgz","fileCount":15,"unpackedSize":176956,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHTN0Upj1699benIXLmDX2HzFlWokNK245CK8r1BsWQvAiEAiSxS+s75/6BZLZiQlPi0vCTlekbw0RHaVl5Xvx0h5ZM="}]},"_npmUser":{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"},"directories":{},"maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gitleaks-secret-scanner_2.1.1_1768470867552_0.5021851071461021"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-25T06:33:07.136Z","modified":"2026-01-15T09:54:27.866Z","1.1.0":"2025-06-21T17:34:23.534Z","1.0.1":"2025-06-21T18:03:10.451Z","1.0.2":"2025-06-21T18:28:36.752Z","1.0.0":"2025-06-23T10:43:33.554Z","2.0.0":"2025-06-23T10:54:31.710Z","2.0.1":"2025-06-23T17:38:35.342Z","1.1.1":"2025-06-25T06:33:07.412Z","1.1.2":"2025-06-25T16:24:03.967Z","1.2.0":"2025-06-29T14:05:28.923Z","1.2.1":"2025-06-29T15:47:14.505Z","1.2.2":"2025-06-30T18:09:00.381Z","2.0.0-beta.1":"2026-01-02T08:43:03.529Z","2.1.1":"2026-01-15T09:54:27.699Z"},"bugs":{"url":"https://github.com/criisv7/gitleaks-secret-scanner/issues"},"author":{"name":"Vijay Kumar"},"license":"MIT","homepage":"https://github.com/criisv7/gitleaks-secret-scanner#readme","keywords":["security","gitleaks","pre-commit","secrets-scanning","git-hooks","toml"],"repository":{"type":"git","url":"git+https://github.com/criisv7/gitleaks-secret-scanner.git"},"description":"A powerful, intelligent wrapper for the Gitleaks engine that provides accurate and safe secret scanning for local pre-commit hooks and CI/CD pipelines.","maintainers":[{"name":"the-codepocalypse","email":"sirigirivijay123@gmail.com"}],"readme":"# Gitleaks Secret Scanner\n\n[![NPM Version](https://img.shields.io/npm/v/gitleaks-secret-scanner.svg)](https://www.npmjs.com/package/gitleaks-secret-scanner)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![NPM Downloads](https://img.shields.io/npm/dm/gitleaks-secret-scanner.svg)](https://www.npmjs.com/package/gitleaks-secret-scanner)\n\nA powerful, intelligent, and safe wrapper for the [Gitleaks](https://github.com/gitleaks/gitleaks) engine.\n\nThis tool solves the main challenge of using Gitleaks in a team environment: the setup. It automatically downloads the correct Gitleaks binary for any operating system and architecture, making it incredibly easy to scan for secrets in local pre-commit hooks and CI/CD pipelines without manual intervention.\n\n## Why Use This Package?\n\nWhile Gitleaks is a phenomenal tool, this package provides a seamless bridge to the Node.js ecosystem, offering several key advantages that go beyond a simple wrapper.\n\n### 🚀 1. Effortless, Zero-Configuration Setup\nThe biggest advantage. You no longer need to manually download Gitleaks binaries or write complex scripts to manage different versions for macOS, Windows, and Linux developers on your team. This package handles everything automatically.\n\n🧠 **2. Truly Accurate & Performant CI/CD Scanning**\n\nThis is not a simple `git diff | gitleaks` pipe. The `--diff-mode ci` is far more intelligent, providing a fast and robust way to secure your merge/pull requests. It's built on a \"scan final state\" philosophy that delivers accuracy and confidence.\n\nHere’s how it works and why it’s better:\n\n*   **Focuses on the Merge Outcome**\n    Instead of analyzing every intermediate commit, `ci` mode identifies all files changed in the pull request and scans their **final content**. This answers the most important question: **\"Will this merge introduce a secret into the target branch?\"** This approach correctly passes the build if a secret is added and then removed within the same PR.\n\n*   **Comprehensive File Analysis**\n    If you modify a file that *already contains a secret*, `ci` mode will find it. By scanning the *entire content* of any changed file (not just the changed lines), it helps you clean up existing security debt and prevents you from unknowingly propagating old vulnerabilities.\n\n*   **High Performance**\n    The scan is surgical and fast. It gets a simple list of changed files from `git` and runs a targeted Gitleaks scan only on them. This is highly efficient, even for large pull requests with extensive commit histories.\n\n*   **Rich, Actionable Context**\n    Findings are automatically enriched with author, email, and commit data using `git blame`. This makes it trivial to identify the source of a leak and take immediate action, directly from the console output or the HTML report.\n\n### 🔒 3. Safe and Powerful Local Scanning\nThis tool uses advanced, non-invasive strategies to scan your uncommitted work safely and effectively.\n-   **For staged changes (`staged` mode):** It uses a safe **\"Virtual Commit\"** strategy with low-level Git commands to create a temporary, in-memory commit. This provides a **full, rich report with commit data** without ever changing your branch history or staging area.\n-   **For all changes (`all` mode):** It performs a comprehensive three-part scan that covers **staged, unstaged, and new untracked files**, ensuring no secret can be missed.\n\n### 📄 4. Rich, User-Friendly Reports\nThe console output and generated HTML reports are populated with the rich contextual data captured by the advanced scanning methods, making it easy to find and fix issues quickly.\n\n## Key Features\n\n-   **Auto-Installation:** Automatically downloads and caches the appropriate Gitleaks binary for your OS and architecture.\n-   **Version Management:** Interactive version selection and support for multiple Gitleaks versions.\n-   **Husky Integration:** Automatic setup of git hooks for pre-commit secret scanning.\n-   **Full History Auditing:** A dedicated `--diff-mode history` for performing a complete scan of your entire repository.\n-   **Accurate CI/CD Mode:** Intelligently scans pull requests, reporting only on newly introduced secrets.\n-   **Advanced Local Scans:** Uses safe, non-invasive methods to provide rich reports for staged and uncommitted work.\n-   **Rich HTML Reports:** Generates a clean, comprehensive HTML report from scan results with full commit context.\n-   **Professional CLI:** Correctly handles pass-through flags like `--no-banner` and `--help`.\n\n## Quick Start & Usage\n\n### One-Off Scan with NPX\nThe easiest way to try it out without installation:\n```bash\n# Scan all of your uncommitted changes (staged, unstaged, and new untracked files)\nnpx gitleaks-secret-scanner --diff-mode all --html-report\n```\n\n### Project Installation (Recommended)\nFor use in `npm scripts` or with tools like Husky, install it as a development dependency.\n```bash\nnpm install gitleaks-secret-scanner --save-dev\n```\nThen, add scripts to your `package.json`:\n```json\n\"scripts\": {\n  \"scan:staged\": \"gitleaks-secret-scanner\",\n  \"scan:all\": \"gitleaks-secret-scanner --diff-mode all\",\n  \"scan:history\": \"gitleaks-secret-scanner --diff-mode history\"\n}\n```\n\n## Command-Line Options\n\nFor a comprehensive menu showing both wrapper commands and the most common Gitleaks flags, run:\n`gitleaks-secret-scanner --options`\n\nFor the complete, native help menu from the Gitleaks binary itself, run:\n`gitleaks-secret-scanner --help`\n\n---\n*Wrapper-Specific Options:*\n| Flag | Description |\n| :--- | :--- |\n| `--diff-mode <mode>` | Sets the scan scope. Modes: `staged` (default), `all`, `ci`, `history`. |\n| `--html-report [path]` | Generates a user-friendly HTML report. Defaults to `gitleaks-report.html`. |\n| `--depth <number>` | Used with `--diff-mode history` to limit the scan to the last `<number>` of commits. |\n| `--gitleaks-version <version>` | Specify a specific Gitleaks version to use (e.g., `8.27.2`). |\n| `--select-version` | Interactive version selector to choose and install a specific Gitleaks version. |\n| `--engine-version` | Display detailed information about the Gitleaks engine and installed versions. |\n| `--setup-husky` | Automatically setup Husky git hooks with Gitleaks pre-commit scanning. |\n---\n\n## Version Management\n\nThe package automatically uses the **latest stable version** of Gitleaks by default. You can control which version to use in several ways:\n\n### Default Behavior (Recommended)\nBy default, the latest stable Gitleaks version is automatically downloaded and used:\n```bash\nnpx gitleaks-secret-scanner\n```\n\n### Interactive Version Selection\nSelect from available Gitleaks versions interactively:\n```bash\nnpx gitleaks-secret-scanner --select-version\n```\n\nThis will fetch the latest 20 versions from GitHub and let you choose which one to install.\n\n### Specify Version Directly\nUse a specific version for a scan:\n```bash\nnpx gitleaks-secret-scanner --gitleaks-version 8.27.2\n```\n\n### Check Current Engine Version\nVerify which Gitleaks engine version you're using:\n```bash\nnpx gitleaks-secret-scanner --engine-version\n```\n\nThis shows:\n- Current engine version\n- Binary location\n- Cache directory\n- All installed versions\n\n### Manage Cached Versions\nMultiple Gitleaks versions are cached for fast switching between projects. To view and clean up old versions:\n```bash\nnpx gitleaks-secret-scanner --manage-versions\n```\n\nThis allows you to:\n- View all cached versions and their sizes\n- Clean up old versions (keeps latest 3 by default)\n- Free up disk space\n\n**Delete all cached versions:**\n```bash\nnpx gitleaks-secret-scanner --clean-all\n```\n\nOr manually:\n```bash\nrm -rf ~/.gitleaks-cache\n```\n\n**Why multiple versions?**\n- Different projects may require different Gitleaks versions\n- Faster to switch between versions (no re-download)\n- Versions are stored in `~/.gitleaks-cache/`\n\n### Uninstalling\n\n**Local installation (project):**\n```bash\nnpm uninstall gitleaks-secret-scanner\n```\n\n**Global installation:**\n```bash\nnpm uninstall -g gitleaks-secret-scanner\n```\n\n⚠️ **Note:** Due to npm lifecycle hook limitations, you need to manually delete cached binaries:\n```bash\n# Remove all cached versions\nrm -rf ~/.gitleaks-cache\n\n# Or selectively manage versions (requires package to be installed)\nnpx gitleaks-secret-scanner --manage-versions\n```\n\n## Husky Integration\n\nAutomatically setup git hooks to run Gitleaks on every commit.\n\n### Automatic Setup During Installation\nWhen you install the package in a git repository, you'll be prompted:\n```bash\nnpm install gitleaks-secret-scanner --save-dev\n```\n\nThe installer will ask if you want to setup git hooks automatically. If you choose \"Yes\", it will:\n1. Install Husky (if not already installed)\n2. Initialize Husky in your repository\n3. Create or update the `.husky/pre-commit` hook\n4. Configure it to run Gitleaks secret scanning before each commit\n\n### Manual Setup\nYou can also setup Husky manually at any time:\n```bash\nnpx gitleaks-secret-scanner --setup-husky\n```\n\n**Note:** If a pre-commit hook already exists, the Gitleaks command will be **appended** to it, preserving your existing hooks\n\n### Custom Command\nYou can specify a custom command for the pre-commit hook:\n```bash\nnpx gitleaks-secret-scanner --setup-husky --command \"npx gitleaks-secret-scanner --diff-mode all --html-report\"\n```\n\n### Manual Husky Setup\nIf you prefer to setup Husky manually, add this to your `.husky/pre-commit` file:\n```bash\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\n# Gitleaks secret scanning\nnpx gitleaks-secret-scanner\n```\n\n---\n\n## CI/CD Integration Guide\n\nThe following examples show how to configure your CI pipeline for different use cases.\n\n### GitHub Actions Example\n\nThis workflow runs a fast, targeted scan on every pull request.\n\n```yaml\n# .github/workflows/secret-detection.yml\nname: 'Secret Detection Scan'\non:\n  pull_request:\n    branches: [ main ]\n\njobs:\n  gitleaks-scan:\n    runs-on: ubuntu-latest\n    steps:\n      - name: 'Check out repository'\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - name: 'Run Gitleaks Secret Scanner for Pull Request'\n        run: npx gitleaks-secret-scanner@latest --diff-mode ci --html-report scan-report-mr.html\n        env:\n          BASE_SHA: ${{ github.event.pull_request.base.sha }}\n          HEAD_SHA: ${{ github.event.pull_request.head.sha }}\n      \n      - name: 'Upload HTML Report Artifact'\n        if: always()\n        uses: actions/upload-artifact@v4\n        with:\n          name: gitleaks-scan-report\n          path: scan-report-mr.html\n```\n\n### GitLab CI Example\n\nThis example demonstrates how to set up two separate jobs: one for merge requests and one for a scheduled weekly audit of recent history.\n\n```yaml\n# .gitlab-ci.yml\nstages:\n  - security\n\nsecret-scan-mr:\n  stage: security\n  image: node:lts-bullseye\n  variables:\n      BASE_SHA: ${CI_MERGE_REQUEST_DIFF_BASE_SHA}\n      HEAD_SHA: ${CI_COMMIT_SHA}\n      \n  script:\n    - npm install -g gitleaks-secret-scanner\n    - gitleaks-secret-scanner --diff-mode ci --html-report scan-report-mr.html\n  artifacts:\n    when: always\n    paths: [scan-report-mr.html]\n    expire_in: 1 week\n  rules:\n    - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n\nsecret-scan-weekly:\n  stage: security\n  image: node:lts-bullseye\n  script:\n    - npm install -g gitleaks-secret-scanner\n    - gitleaks-secret-scanner --diff-mode history --html-report scan-report-weekly.html\n  artifacts:\n    when: always\n    paths: [scan-report-weekly.html]\n    expire_in: 1 week\n  rules:\n    - if: '$CI_PIPELINE_SOURCE == \"schedule\"'\n```\n\n## Troubleshooting\n\nThe package includes comprehensive error handling with helpful guidance when things go wrong. Here are common scenarios:\n\n### Network Issues\nIf you encounter network errors when fetching versions or downloading binaries:\n```bash\n# The package will automatically provide fallback instructions\n# You can specify a version directly instead:\nnpx gitleaks-secret-scanner --gitleaks-version 8.30.0\n```\n\n### Husky Setup Failures\nIf automatic Husky setup fails, manual instructions will be provided. You can also set up manually:\n```bash\nnpm install husky --save-dev\nnpx husky init\n```\n\nThen create `.husky/pre-commit`:\n```bash\n#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\n# Gitleaks secret scanning\nnpx gitleaks-secret-scanner\n```\n\n## Known Issues\n\n*   **CLI Argument Parsing:** The current argument parser is intentionally permissive to allow all native Gitleaks flags to be passed through. As a result, it does not throw an error for unknown or misspelled flags (e.g., `gitleaks-secret-scanner --verrbose`). This behavior is scheduled to be improved in a future release with a more intelligent \"typo-check\" mechanism.\n\n## License and Attribution\n\nThis package is licensed under the MIT License. It is a wrapper around the **Gitleaks** engine, which is developed by Zachary Rice and is also licensed under the MIT License.","readmeFilename":"README.md"}