@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

Option 1: Install via npm

npm install @ziul285/gitleaks

Option 2: Clone the Repository

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:

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:

  gitleaks --staged

• Scan All Files in Quiet Mode:

  gitleaks --all --quiet

• Ignore Additional Paths:

  gitleaks --all --ignore dist build

• Add Custom Patterns:

  gitleaks --all --patterns "CUSTOM_PATTERN_1" "CUSTOM_PATTERN_2"

• Exclude Patterns:

  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:

npm install husky --save-dev

Set up Husky in your project:

npx husky install

Step 2: Create a Pre-Commit Hook

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

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:

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:

  #!/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:

{
  "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):

{
  "customPatterns": [],
  "ignoredPatterns": [],
  "ignorePaths": ["node_modules", ".git", "package.json", "package-lock.json"]
}

Development

Run the Project Locally

node index.js

Run Tests

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

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

npm install gitleaks

Using in Code

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.