# detect-secrets-js

A JavaScript implementation of [Yelp's detect-secrets](https://github.com/Yelp/detect-secrets) with Gitleaks integration for comprehensive secret detection.

## Features

- **Dual Scanner Approach**: Combines Yelp's detect-secrets algorithms and Gitleaks scanning capabilities
- **Git Blame Information**: Associates detected secrets with the authors who added them
- **Remote Repository Scanning**: Scan remote Git repositories without cloning them manually
- **Git History Scanning**: Scan specific commits or commit ranges in your Git history
- **CSV, JSON, and TXT Export**: Flexible output options for integrating with other tools
- **Cross-Platform**: Works on Windows, macOS, and Linux

## Installation

```bash
npm install detect-secrets-js
```

This package will attempt to install Gitleaks automatically using your system's package manager:

- Windows: Using Chocolatey or Scoop
- macOS: Using Homebrew
- Linux: Using apt-get or yum

### Prerequisites

Depending on your system, you might need one of these package managers:

- Windows: [Chocolatey](https://chocolatey.org/install) or [Scoop](https://scoop.sh/)
- macOS: [Homebrew](https://brew.sh/)
- Linux: apt-get or yum (usually pre-installed)

If the automatic installation fails, you can install Gitleaks manually:

1. Visit [Gitleaks Releases](https://github.com/gitleaks/gitleaks/releases)
2. Download the appropriate version for your system
3. Add it to your system PATH

## Background

This project is based on [Yelp's detect-secrets](https://github.com/Yelp/detect-secrets), a tool designed to reliably detect secrets in a codebase. We've enhanced it by integrating with [Gitleaks](https://github.com/zricethezav/gitleaks), providing a more comprehensive scanning solution. While the original Yelp tool focuses on pattern matching, Gitleaks adds capabilities like entropy detection and Git history analysis.

## Usage

### Local Directory Scanning

```bash
# Scan current directory with both scanners
detect-secrets-js scan

# Scan a specific directory
detect-secrets-js scan /path/to/directory

# Use only detect-secrets scanner (Yelp's algorithm)
detect-secrets-js scan --scanner detect-secrets

# Use only Gitleaks scanner
detect-secrets-js scan --scanner gitleaks
```

### Remote Repository Scanning

```bash
# Scan a remote repository
detect-secrets-js scan https://github.com/user/repo --remote

# Scan a specific branch
detect-secrets-js scan https://github.com/user/repo --remote --branch main

# Scan a specific commit
detect-secrets-js scan https://github.com/user/repo --remote --commit a1b2c3d

# Scan a range of commits
detect-secrets-js scan https://github.com/user/repo --remote --from-commit a1b2c3d --to-commit e4f5g6h
```

### Git History Scanning

```bash
# Scan all commits in a local repository
detect-secrets-js scan /path/to/repo --all-commits

# Scan a specific commit
detect-secrets-js scan /path/to/repo --commit a1b2c3d

# Scan a range of commits
detect-secrets-js scan /path/to/repo --from-commit a1b2c3d --to-commit e4f5g6h
```

### Output Options

```bash
# Save results to JSON file (default)
detect-secrets-js scan --output results.json

# Save as CSV for spreadsheet analysis
detect-secrets-js scan --output results.csv

# Save as readable text file
detect-secrets-js scan --output results.txt
```

## Options

| Option                       | Description                                                              |
| ---------------------------- | ------------------------------------------------------------------------ |
| `--scanner <scanner>`        | Scanner to use: `detect-secrets` (Yelp), `gitleaks`, or `both` (default) |
| `--output <path>`            | Output file path (default: ./scan-results.json)                          |
| `--exclude-dirs <dirs...>`   | Directories to exclude                                                   |
| `--exclude-files <files...>` | File patterns to exclude                                                 |
| `--max-file-size <size>`     | Maximum file size in bytes (0 for no limit)                              |
| `--check-missed`             | Check for potentially missed secrets                                     |
| `--verbose`                  | Show additional information                                              |
| `--remote`                   | Scan a remote repository                                                 |
| `--branch <branch>`          | Branch to check out for remote scans                                     |
| `--commit <hash>`            | Scan a specific commit hash                                              |
| `--all-commits`              | Scan all git commit history                                              |
| `--from-commit <hash>`       | Starting commit hash for git history scan                                |
| `--to-commit <hash>`         | Ending commit hash for git history scan                                  |
| `--disable-git-blame`        | Disable git blame information gathering                                  |
| `--git-repo-path <path>`     | Specify git repository path for external scans                           |
| `--include-node-modules`     | Include node_modules in the scan (not recommended)                       |

## API

```javascript
const detectSecrets = require('detect-secrets-js');
const {
  runGitleaksScan,
  scanRemoteRepository,
  scanGitHistory,
} = require('detect-secrets-js/gitleaks');

async function scanMyProject() {
  // Initialize the scanner (required for detect-secrets)
  await detectSecrets.initialize();

  // Scan with both scanners (Yelp's detect-secrets and Gitleaks)
  const results = await detectSecrets.scanWithBothScanners('./src', {
    excludeDirs: ['node_modules', 'dist'],
    checkMissed: true,
    enrichWithGitInfo: true,
  });

  console.log(`Found ${results.secrets.length} secrets`);

  // Scan remote repository
  const remoteResults = await scanRemoteRepository(
    'https://github.com/user/repo',
    'main'
  );

  // Scan git history
  const gitResults = await scanGitHistory('./repo', 'a1b2c3d', 'e4f5g6h');
}
```

## License

MIT