secure-scan-js/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) tool, with **no Python dependency required**.

This package provides the same functionality as Yelp's detect-secrets but implemented in JavaScript using WebAssembly technology, eliminating the need for Python installation.

## Features

- **No Python Required**: Uses WebAssembly to run the scanning code directly in Node.js
- **Easy Installation**: Simple npm installation with no external dependencies
- **Fast Scanning**: Efficiently scans files and directories for secrets
- **Customizable**: Configure exclusions, scan specific directories, and more
- **False Positive Detection**: Identifies likely false positives to reduce noise
- **Missed Secret Detection**: Optional detection of patterns that might be missed by the main scanner
- **Compatible API**: Similar interface to Yelp's detect-secrets for easy migration
- **Memory Efficient**: Automatically skips binary files and handles large codebases

## Installation

```bash
npm install -g secure-scan-js
```

## Usage

### Command Line

```bash
# Scan the current directory
secure-scan-js

# Scan a specific directory
secure-scan-js --directory ./src

# Exclude specific files or directories
secure-scan-js --exclude-files "*.test.js,*.spec.js" --exclude-dirs "node_modules,dist"

# Check for potentially missed secrets
secure-scan-js --check-missed

# Save results to a file
secure-scan-js --output results.json

# Enable file size limits to prevent memory issues with very large files
secure-scan-js --limit-file-size

# Set a custom maximum file size (in KB) when limits are enabled
secure-scan-js --limit-file-size --max-file-size 2048
```

### API

```javascript
const detectSecrets = require("secure-scan-js");

async function scanMyProject() {
	// Initialize the WebAssembly module (required before scanning)
	await detectSecrets.initialize();

	// Scan a directory
	const results = await detectSecrets.scanDirectory("./src", {
		excludeFiles: ["*.test.js", "*.spec.js"],
		excludeDirs: ["node_modules", "dist"],
		checkMissed: true,
		limitFileSize: false, // Set to true to enable file size limits
		maxFileSize: 2 * 1024 * 1024, // Custom max file size in bytes (2MB) when limits are enabled
	});

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

	// Scan a specific file
	const fileResults = await detectSecrets.scanFile("./config.js");

	// Scan a string
	const contentResults = await detectSecrets.scanContent(
		'const apiKey = "1234567890abcdef";',
		"example.js"
	);
}

scanMyProject().catch(console.error);
```

## Options

| Option          | CLI Flag                         | Description                                         |
| --------------- | -------------------------------- | --------------------------------------------------- |
| `directory`     | `-d, --directory <path>`         | Directory to scan (default: current directory)      |
| `root`          | `-r, --root`                     | Scan from project root                              |
| `excludeFiles`  | `-e, --exclude-files <patterns>` | File patterns to exclude (comma-separated)          |
| `excludeDirs`   | `-x, --exclude-dirs <patterns>`  | Directory patterns to exclude (comma-separated)     |
| `checkMissed`   | `-m, --check-missed`             | Check for potentially missed secrets                |
| `verbose`       | `-v, --verbose`                  | Include additional information                      |
| `output`        | `-o, --output <file>`            | Output file path                                    |
| `limitFileSize` | `-l, --limit-file-size`          | Enable file size limits to prevent memory issues    |
| `maxFileSize`   | `--max-file-size <size>`         | Maximum file size to scan in KB (default: no limit) |

## How It Works

This package implements the same secret detection patterns as Yelp's detect-secrets but uses WebAssembly technology to eliminate the Python dependency. The scanning is performed using a combination of regex patterns to detect common secret formats.

The first time you run the tool, it will download and initialize the WebAssembly environment. This may take a few seconds, but subsequent runs will be faster.

### Memory Management

By default, the tool will scan all files regardless of size, but you can enable memory protection features:

1. **Binary File Detection**: Automatically skips binary files like images, executables, and compressed files
2. **Optional Size Limits**: Use `--limit-file-size` to enable file size limits
3. **Custom Size Limits**: Set your own maximum file size with `--max-file-size`
4. **Automatic Truncation**: Very large text files can be truncated to prevent memory issues

## Types of Secrets Detected

The tool can detect a wide range of secrets, including:

- API Keys (Google, Stripe, etc.)
- AWS Access Keys and Secret Keys
- Private Keys (RSA, DSA, etc.)
- Database Connection Strings
- JWT Tokens
- GitHub Tokens
- OAuth Tokens
- Generic Passwords and Secrets

## Testing

You can run basic tests with:

```bash
cd wasm-version
npm run build
node test/test.js
```

## Comparison with Yelp's detect-secrets

This package is inspired by and compatible with [Yelp's detect-secrets](https://github.com/Yelp/detect-secrets) but offers several advantages:

1. **No Python Dependency**: Works without requiring Python installation
2. **Easier Installation**: Simple npm installation process
3. **JavaScript Native**: Fully integrated with Node.js ecosystem
4. **Similar Detection Patterns**: Implements the same secret detection patterns
5. **Memory Efficient**: Better handling of large repositories and binary files

## Version History

### v2.1.1

- Removed example files containing secrets to avoid GitHub secret scanning
- Updated test files to use safe example values
- Fixed repository URLs

### v2.1.0

- Removed default file size limits to scan all files by default
- Added comprehensive secret type documentation
- Fixed minor bugs and improved error handling

### v2.0.0

- Complete rewrite using WebAssembly technology
- Removed Python dependency requirement
- Enhanced pattern matching for better secret detection
- Improved performance and cross-platform compatibility
- Added memory-efficient handling of large repositories

## License

MIT