@ziul285/gitleaks

@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

• Features
• Installation
  • Option 1: Install via npm
  • Option 2: Clone the Repository
• Usage
  • CLI Command
  • Available Flags
  • Example Commands
• 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
• Configuration
  • .gitleaksrc.json
  • Default Config
• Development
  • Run the Project Locally
  • Run Tests
  • Test Coverage
• 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.