secure-scan-js/wasm-version/README.md

A JavaScript implementation of Yelp's detect-secrets tool - no Python required

# secure-scan-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 secure-scan-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
secure-scan-js scan

# Scan a specific directory
secure-scan-js scan /path/to/directory

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

# Use only Gitleaks scanner
secure-scan-js scan --scanner gitleaks
```

### Remote Repository Scanning

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

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

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

# Scan a range of commits
secure-scan-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
secure-scan-js scan /path/to/repo --all-commits

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

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

### Output Options

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

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

# Save as readable text file
secure-scan-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("secure-scan-js");
const {
	runGitleaksScan,
	scanRemoteRepository,
	scanGitHistory,
} = require("secure-scan-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