@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

Features
Installation
- Option 1: Install via npm
- Option 2: Clone the Repository
Usage
Integrating with Husky
Configuration
- .gitleaksrc.json
- Default Config
Development
Adding to Another Project
- Install as a Dependency
- Using in Code
Contributing
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:

Stage some changes with sensitive data.
Attempt to commit or push.
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:

Default patterns detection.
Custom patterns detection.
ignoredPatterns functionality.
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:

Fork the repository.
Create a new branch (git checkout -b feature-name).
Implement your feature.
Create tests!
Commit your changes (git commit -m "Add new feature").
Push to your branch (git push origin feature-name).
Create a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Package detail