@ziul285/gitleaks
Version:
A custom Gitleaks-like scanner for detecting sensitive data.
278 lines (202 loc) • 8.13 kB
Markdown
# @ziul285/gitleaks
[](https://www.npmjs.com/package/@ziul285/gitleaks)
[](LICENSE)
[](#run-tests)
[](#test-coverage)
[](https://nodejs.org/)
## By: Luiz Carlos Aguiar Carrion
A lightweight and customizable tool for detecting sensitive data in your repositories. Git Leaks scans files for patterns like API keys, tokens, and other sensitive information based on default or user-defined configurations.
⚙️ Easily configurable via .gitleaksrc.json, with support for:
🔍 Default and custom regex-based patterns
📂 Ignored paths and excluded patterns
🧪 CLI + Husky integration for pre-commit/pre-push scans
🧵 Inline ignore support — skip specific lines with @gitleaks ignore
🔄 Reusable API for embedding into Node.js projects
## Table of Contents
1. [Features](#features)
2. [Installation](#installation)
- [Option 1: Install via npm](#option-1-install-via-npm)
- [Option 2: Clone the Repository](#option-2-clone-the-repository)
3. [Usage](#usage)
- [CLI Command](#cli-command)
- [Available Flags](#available-flags)
- [Example Commands](#example-commands)
4. [Integrating with Husky](#integrating-with-husky)
- [Step 1: Install Husky](#step-1-install-husky)
- [Step 2: Create a Pre-Commit Hook](#step-2-create-a-pre-commit-hook)
- [Step 3: Create a Pre-Push Hook](#step-3-create-a-pre-push-hook)
- [Step 4: Test the Setup](#step-4-test-the-setup)
- [Advanced Husky Integration](#advanced-husky-integration)
5. [Configuration](#configuration)
- [.gitleaksrc.json](#.gitleaksrcjson)
- [Default Config](#default-config-if-gitleaksrcjson-is-not-present)
6. [Development](#development)
- [Run the Project Locally](#run-the-project-locally)
- [Run Tests](#run-tests)
- [Test Coverage](#test-coverage)
7. [Adding to Another Project](#adding-to-another-project)
- [Install as a Dependency](#install-as-a-dependency)
- [Using in Code](#using-in-code)
8. [Contributing](#contributing)
9. [License](#license)
## Features
- Detect sensitive data such as API keys, AWS secrets, GitHub tokens, etc.
- Customizable patterns and ignore paths via `.gitleaksrc.json`.
- CLI support for easy integration into CI/CD pipelines.
- Modular and extensible codebase.
## Installation
### **Option 1: Install via npm**
```bash
npm install @ziul285/gitleaks
```
### **Option 2: Clone the Repository**
```bash
git clone https://github.com/IKuuhakuI/gitleaks.git
cd gitleaks-scanner
npm install
```
## Usage
### **CLI Command**
Run Git Leaks in the root directory of your repository:
```bash
gitleaks [options]
```
### **Available Flags**
| Flag | Alias | Type | Description |
| ------------ | ----- | --------- | ------------------------------------------ |
| `--staged` | `-s` | `boolean` | Scan only files in the staging area |
| `--all` | `-a` | `boolean` | Scan all files in the repository (default) |
| `--quiet` | `-q` | `boolean` | Suppress all output except errors |
| `--ignore` | | `array` | Additional paths to ignore during the scan |
| `--patterns` | `-p` | `array` | Specify additional patterns to scan for |
| `--exclude` | `-e` | `array` | Exclude specific patterns from the scan |
| `--version` | `-v` | `boolean` | Display the current version of the tool |
| `--help` | `-h` | `boolean` | Show help message with usage details |
#### Example Commands
- **Scan Staged Files Only:**
```bash
gitleaks --staged
```
- **Scan All Files in Quiet Mode:**
```bash
gitleaks --all --quiet
```
- **Ignore Additional Paths:**
```bash
gitleaks --all --ignore dist build
```
- **Add Custom Patterns:**
```bash
gitleaks --all --patterns "CUSTOM_PATTERN_1" "CUSTOM_PATTERN_2"
```
- **Exclude Patterns:**
```bash
gitleaks --all --exclude githubToken
```
## Integrating with Husky
You can integrate Git Leaks with Husky to automatically scan files during Git operations like `commit` or `push`.
### **Step 1: Install Husky**
If Husky is not already installed in your project, run:
```bash
npm install husky --save-dev
```
Set up Husky in your project:
```bash
npx husky install
```
### **Step 2: Create a Pre-Commit Hook**
Add a Husky pre-commit hook to scan staged files for sensitive data:
```bash
npx husky add .husky/pre-commit "npx gitleaks --staged"
```
### **Step 3: Create a Pre-Push Hook**
Optionally, add a pre-push hook to scan the entire repository before pushing:
```bash
npx husky add .husky/pre-push "npx gitleaks --all"
```
### **Step 4: Test the Setup**
To verify the integration:
1. Stage some changes with sensitive data.
2. Attempt to commit or push.
3. Git Leaks will run, and the commit/push will be blocked if sensitive data is detected.
### **Advanced Husky Integration**
- If you want to customize the hooks further, you can modify the commands in the `.husky/pre-commit` or `.husky/pre-push` files.
- Example `pre-commit` file:
```bash
#!/bin/sh
npx gitleaks --staged --quiet
```
## Configuration
### **.gitleaksrc.json**
The project uses a `.gitleaksrc.json` file for custom configurations. This file should be located in the root directory of the repository you want to scan.
#### Example `.gitleaksrc.json`:
```json
{
"maxFileSizeKb": 500,
"ignoreExtensions": [".jpg", ".zip", ".log"],
"includePatterns": ["**/*.js", "src/**/*.ts"],
"customPatterns": ["TEST_KEY_[A-Za-z0-9]{10}"],
"ignorePaths": ["node_modules", ".git", "dist"],
"ignoredPatterns": ["awsAccessKey", "openAiSecretKey"]
}
```
### 📘 Available Configuration Fields
| Field | Type | Description |
| ------------------ | ---------- | ------------------------------------------------------- |
| `ignorePaths` | `string[]` | Folders or files to skip entirely. |
| `ignoreExtensions` | `string[]` | File extensions to skip (e.g., `[".zip", ".log"]`). |
| `maxFileSizeKb` | `number` | Skip files larger than this (in kilobytes). |
| `includePatterns` | `string[]` | Glob patterns for files to include (e.g., `"**/*.js"`). |
| `ignoredPatterns` | `string[]` | Keys of default patterns to disable. |
| `customPatterns` | `string[]` | User-defined regex patterns to scan for. |
#### Default Config (if `.gitleaksrc.json` is not present):
```json
{
"customPatterns": [],
"ignoredPatterns": [],
"ignorePaths": ["node_modules", ".git", "package.json", "package-lock.json"]
}
```
## Development
### **Run the Project Locally**
```bash
node index.js
```
### **Run Tests**
The project uses **Mocha** and **Chai** for testing. Run the test suite with:
```bash
npm test
```
### **Test Coverage**
Ensure all major features are tested:
1. Default patterns detection.
2. Custom patterns detection.
3. `ignoredPatterns` functionality.
4. File and path exclusions.
## Adding to Another Project
### **Install as a Dependency**
```bash
npm install gitleaks
```
### **Using in Code**
```javascript
const { scanRepository } = require("gitleaks/core/scanner");
(async () => {
const results = await scanRepository("/path/to/repo", {
ignorePaths: ["node_modules"],
customPatterns: ["MY_SECRET_[A-Za-z0-9]{20}"],
});
console.log(results);
})();
```
## Contributing
Contributions are welcome! Follow these steps to contribute:
1. Fork the repository.
2. Create a new branch (`git checkout -b feature-name`).
3. Implement your feature.
4. Create tests!
5. Commit your changes (`git commit -m "Add new feature"`).
6. Push to your branch (`git push origin feature-name`).
7. Create a pull request.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.