@ziul285/gitleaks


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
2. Installation
- Option 1: Install via npm
- Option 2: Clone the Repository
3. Usage
- CLI Command
- Available Flags
- Example Commands
4. Integrating with Husky
- Step 1: Install Husky
- Step 2: Create a Pre-Commit Hook
- Step 3: Create a Pre-Push Hook
- Step 4: Test the Setup
- Advanced Husky Integration
5. Configuration
- .gitleaksrc.json
- Default Config
6. Development
- Run the Project Locally
- Run Tests
- Test Coverage
7. Adding to Another Project
- Install as a Dependency
- Using in Code
8. Contributing
9. 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

$3

``bash
npm install @ziul285/gitleaks
`

$3

`bash
git clone https://github.com/IKuuhakuI/gitleaks.git
cd gitleaks-scanner
npm install
`

Usage

$3

Run Git Leaks in the root directory of your repository:

`bash
gitleaks [options]
`

$3

| 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.

$3

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
`

$3

Add a Husky pre-commit hook to scan staged files for sensitive data:

`bash
npx husky add .husky/pre-commit "npx gitleaks --staged"
`

$3

Optionally, add a pre-push hook to scan the entire repository before pushing:

`bash
npx husky add .husky/pre-push "npx gitleaks --all"
`

$3

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.

$3

- 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

$3

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"]
}
`

$3

| 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

$3

`bash
node index.js
`

$3

The project uses Mocha and Chai for testing. Run the test suite with:

`bash
npm test
`

$3

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

$3

`bash
npm install gitleaks
`

$3

`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.