trufflehog-js/README.md

TypeScript wrapper for TruffleHog secret scanner

<!--
Copyright (c) 2025 maloma7. All rights reserved.
SPDX-License-Identifier: MIT
-->

<img src="assets/logo.svg" width="100%" alt="TruffleHog-JS" />

# TruffleHog-JS

A high-performance TypeScript wrapper for TruffleHog secret scanner, designed for modern development workflows and CI/CD pipelines.

[![npm version](https://img.shields.io/npm/v/trufflehog-js?color=efda4f)](https://npmjs.com/package/trufflehog-js)
[![npm downloads](https://img.shields.io/npm/dm/trufflehog-js?color=efda4f)](https://npmjs.com/package/trufflehog-js)
[![License: MIT](https://img.shields.io/badge/License-MIT-efda4f)](LICENSE)
[![Built with Claude](https://img.shields.io/badge/Built_with-Claude-efda4f?style=flat&logo=claude&logoColor=efda4f)](https://anthropic.com/claude-code)
[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-efda4f?style=flat&logo=biome&logoColor=efda4f)](https://biomejs.dev)
[![Secured with Lefthook](https://img.shields.io/badge/Secured_with-Lefthook-efda4f?style=flat&logo=lefthook&logoColor=efda4f)](https://lefthook.dev/)

## What is TruffleHog?

[TruffleHog](https://trufflesecurity.com/trufflehog) is a powerful secrets scanning engine that searches for credentials, API keys, and other sensitive data across your codebase, Git history, and file systems. It uses pattern recognition and entropy analysis to detect secrets that might accidentally be committed to your repository.

## Features

- **Secret Detection** - Comprehensive scanning for 800+ secret types including API keys, passwords, tokens, and certificates
- **High Performance** - Asynchronous scanning with configurable timeouts and caching
- **Git Integration** - Native support for scanning staged files, perfect for pre-commit hooks
- **TypeScript API** - Full TypeScript support with comprehensive type definitions
- **Binary Management** - Automatic TruffleHog binary download, verification, and caching
- **Cross-Platform** - Support for Linux, macOS, and Windows (x64 and ARM64)
- **Security First** - Cryptographic verification of downloaded binaries with checksums and signatures
- **Configurable** - Extensive configuration options for detectors, paths, and verification
- **Rich Logging** - Detailed logging with multiple verbosity levels and colored output
- **CI/CD Ready** - Optimized for continuous integration and pre-commit workflows

## Installation

### Using Bun (Recommended)

```bash
bun add trufflehog-js
```

### Using npm

```bash
npm install trufflehog-js
```

### Using yarn

```bash
yarn add trufflehog-js
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `TRUFFLEHOG_BINARY_PATH` | Custom path to TruffleHog binary | Auto-download |
| `TRUFFLEHOG_LOG_LEVEL` | Logging level (debug, info, warn, error) | `warn` |
| `TRUFFLEHOG_VERBOSE` | Enable verbose output | `false` |
| `TRUFFLEHOG_CONFIG_PATH` | Path to TruffleHog configuration file | - |

### Pre-commit Hook Setup

#### With Lefthook (Recommended)

Add to your `.lefthook.yml`:

```yaml
pre-commit:
  commands:
    secrets:
      run: bunx trufflehog-js --staged --quiet
      fail_text: "Secrets detected! Please remove before committing."
```

#### With Husky

```json
{
  "husky": {
    "hooks": {
      "pre-commit": "bunx trufflehog-js --staged --quiet"
    }
  }
}
```

## How It Works

TruffleHog-JS provides a seamless integration layer between your JavaScript/TypeScript application and the TruffleHog secret scanner:

1. **Binary Management**: Automatically downloads and verifies the appropriate TruffleHog binary for your platform
2. **Git Integration**: Scans staged files in Git repositories, perfect for pre-commit workflows
3. **Result Processing**: Parses TruffleHog's JSON output into structured TypeScript objects
4. **Error Handling**: Provides comprehensive error types with appropriate exit codes for CI/CD
5. **Caching**: Efficiently caches downloaded binaries and scan results for improved performance

### Scanning Process

1. **Repository Check**: Verifies you're in a Git repository with staged files
2. **Binary Verification**: Ensures TruffleHog binary is available and verified
3. **File Analysis**: Scans staged files using TruffleHog's pattern recognition
4. **Result Parsing**: Converts findings into structured data with file paths, secret types, and verification status
5. **Action Decision**: Returns appropriate exit codes based on findings (0 = clean, 1 = secrets found, 2 = error)

## Usage Examples

### CLI Usage

#### Basic Scanning

```bash
# Scan staged files (typical pre-commit usage)
bunx trufflehog-js --staged

# Scan with verbose output for debugging
bunx trufflehog-js --staged --verbose

# Scan with custom timeout and excluded patterns
bunx trufflehog-js --staged --timeout 60000 --exclude "*.test.ts" --exclude "dist/*"
```

#### Advanced Options

```bash
# Scan with specific detectors only
bunx trufflehog-js --staged --include-detectors "aws,github,slack"

# Scan excluding certain detectors
bunx trufflehog-js --staged --exclude-detectors "generic,test"

# Scan with verification enabled
bunx trufflehog-js --staged --verify

# Quiet mode for CI/CD (minimal output)
bunx trufflehog-js --staged --quiet
```

### TypeScript/JavaScript API

#### Basic Usage

```typescript
import { TruffleHogScanner, scanStagedFiles } from 'trufflehog-js';

// Simple staged file scanning
try {
  const results = await scanStagedFiles();
  if (results.length > 0) {
    console.log(`Found ${results.length} secrets!`);
    results.forEach(result => {
      console.log(`${result.detector} in ${result.file}`);
    });
  } else {
    console.log('No secrets detected');
  }
} catch (error) {
  console.error('Scan failed:', error.message);
}
```

#### Advanced Scanner Configuration

```typescript
import { TruffleHogScanner, createLogger } from 'trufflehog-js';

const logger = createLogger({ level: 'debug', timestamp: true });

const scanner = new TruffleHogScanner({
  timeout: 120000,
  logger,
  binaryPath: '/custom/path/to/trufflehog' // Optional: use custom binary
});

// Scan with detailed options
const results = await scanner.scanStagedFiles({
  verify: true,
  includeDetectors: ['aws', 'github', 'slack'],
  excludePaths: ['node_modules/**', '*.test.ts'],
  timeout: 60000
});

// Process results
results.forEach(result => {
  console.log(`Detector: ${result.detector}`);
  console.log(`File: ${result.file}`);
  console.log(`Verified: ${result.verified ? 'Yes' : 'No'}`);
  console.log(`Secret: ${result.secret}`); // Redacted for security
});
```

#### File and Text Scanning

```typescript
import { TruffleHogScanner } from 'trufflehog-js';

const scanner = new TruffleHogScanner();

// Scan specific files
const fileResults = await scanner.scanFiles([
  'src/config.ts',
  'src/database.ts'
], {
  verify: false,
  excludeDetectors: ['test']
});

// Scan text content directly
const textResults = await scanner.scanText(`
  const apiKey = "sk-1234567890abcdef";
  const dbPassword = "super_secret_password";
`, 'config.ts');

console.log(`Found ${textResults.length} secrets in text`);
```

#### Error Handling

```typescript
import {
  TruffleHogScanner,
  SecretsFoundError,
  BinaryNotFoundError,
  throwIfSecretsFound
} from 'trufflehog-js';

try {
  const results = await scanStagedFiles({ verify: true });

  // Throw error if secrets are found (useful for CI/CD)
  throwIfSecretsFound(results);

  console.log('No secrets detected');
} catch (error) {
  if (error instanceof SecretsFoundError) {
    console.error(`Found ${error.secretCount} secrets`);
    process.exit(1);
  } else if (error instanceof BinaryNotFoundError) {
    console.error('TruffleHog binary not found. Run: bun install trufflehog-js');
    process.exit(2);
  } else {
    console.error('Unexpected error:', error.message);
    process.exit(2);
  }
}
```

## Architecture

TruffleHog-JS is built with a modular architecture focused on reliability and performance:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Interface │    │  TypeScript API │    │  Git Integration│
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼───────────┐
                    │    Scanner Engine       │
                    │  ┌─────────────────────┐│
                    │  │   Binary Manager    ││
                    │  │ ┌─────────────────┐ ││
                    │  │ │  Cache System   │ ││
                    │  │ └─────────────────┘ ││
                    │  └─────────────────────┘│
                    └─────────────────────────┘
                                 │
                    ┌─────────────▼───────────┐
                    │     TruffleHog          │
                    │    Native Binary        │
                    └─────────────────────────┘
```

### Core Components

- **Scanner Engine**: Main orchestration layer that coordinates scanning operations
- **Binary Manager**: Handles TruffleHog binary download, verification, and execution
- **Cache System**: Efficient caching of downloaded binaries and metadata
- **Git Integration**: Native Git operations for repository and staged file management
- **Error System**: Comprehensive error handling with typed exceptions
- **Logger System**: Configurable logging with multiple output levels

## Testing

### Running Tests

```bash
# Run all tests
bun test

# Run specific test suites
bun run test:unit
bun run test:integration
bun run test:performance

# Run tests with coverage
bun test --coverage

# Run performance benchmarks
bun run benchmark
```

### Test Structure

- **Unit Tests**: Test individual components in isolation
- **Integration Tests**: Test component interactions and real scanning scenarios
- **Performance Tests**: Benchmark scanning performance and memory usage

## Development

### Prerequisites

- [Bun](https://bun.sh) v1.2.0 or higher
- Git
- Node.js v18+ (for compatibility testing)

### Setup

```bash
# Clone the repository
git clone https://github.com/maloma7/trufflehog-js.git
cd trufflehog-js

# Install dependencies
bun install

# Run type checking
bun run typecheck

# Run linting
bun run lint

# Run all checks
bun run check
```

### Development Workflow

```bash
# Start development mode (watch mode)
bun run dev

# Format code
bun run format

# Fix linting issues
bun run lint:fix

# Clean build artifacts
bun run clean
```

## API Reference

### Core Classes

#### `TruffleHogScanner`

Main scanner class providing comprehensive secret detection functionality.

```typescript
class TruffleHogScanner {
  constructor(options?: {
    binaryPath?: string;
    timeout?: number;
    logger?: Logger;
  });

  scanStagedFiles(options?: ScanOptions): Promise<ScanResult[]>;
  scanFiles(files: string[], options?: ScanOptions): Promise<ScanResult[]>;
  scanText(content: string, filename?: string): Promise<ScanResult[]>;
}
```

#### `ScanResult`

Represents a detected secret with full context.

```typescript
interface ScanResult {
  detector: string;    // Type of secret detected (e.g., 'aws', 'github')
  file: string;        // File path where secret was found
  line: number;        // Line number (when available)
  verified: boolean;   // Whether the secret was verified as active
  secret: string;      // Redacted secret value
  raw: string;         // Full TruffleHog output for debugging
}
```

### Configuration Types

#### `ScanOptions`

Configuration options for scanning operations.

```typescript
interface ScanOptions {
  staged?: boolean;           // Scan staged files only
  quiet?: boolean;            // Minimal output
  verbose?: boolean;          // Detailed output
  config?: string;            // Custom config file path
  timeout?: number;           // Scan timeout in milliseconds
  verify?: boolean;           // Enable secret verification
  includeDetectors?: string[]; // Specific detectors to include
  excludeDetectors?: string[]; // Detectors to exclude
  includePaths?: string[];     // Path patterns to include
  excludePaths?: string[];     // Path patterns to exclude
}
```

### Utility Functions

```typescript
// Convenience functions
function scanStagedFiles(options?: ScanOptions): Promise<ScanResult[]>;
function scanFiles(files: string[], options?: ScanOptions): Promise<ScanResult[]>;
function scanText(content: string, filename?: string): Promise<ScanResult[]>;
function throwIfSecretsFound(results: ScanResult[]): void;

// Platform utilities
function getCurrentPlatform(): Platform;
function getPlatformInfo(): PlatformInfo;
function isSupportedPlatform(platform: string, arch: string): boolean;

// Git utilities
function getStagedFiles(workingDir?: string): Promise<string[]>;
function ensureGitRepository(workingDir?: string): Promise<void>;
function getGitRoot(workingDir?: string): Promise<string>;

// Logger utilities
function createLogger(options?: LoggerOptions): Logger;
```

## Troubleshooting

### Common Issues

#### Binary Download Failures

```bash
# Set custom binary path
export TRUFFLEHOG_BINARY_PATH="/usr/local/bin/trufflehog"

# Or download manually
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin
```

#### Permission Errors

```bash
# Fix binary permissions
chmod +x ~/.cache/trufflehog-js/*/trufflehog

# Clear cache and re-download
rm -rf ~/.cache/trufflehog-js
```

#### Platform Support Issues

```bash
# Check platform support
bunx trufflehog-js --version

# Use custom binary for unsupported platforms
export TRUFFLEHOG_BINARY_PATH="/custom/path/to/trufflehog"
```

### Debug Mode

Enable detailed logging for troubleshooting:

```bash
# Environment variable
export TRUFFLEHOG_LOG_LEVEL=debug

# CLI flag
bunx trufflehog-js --staged --verbose

# Programmatic
const logger = createLogger({ level: 'debug' });
```

### Exit Codes

| Code | Meaning | Action |
|------|---------|--------|
| 0 | No secrets found | Continue (success) |
| 1 | Secrets detected | Block commit/deployment |
| 2 | Tool error | Block commit/deployment |

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [TruffleHog](https://trufflesecurity.com/trufflehog) by Truffle Security for the excellent secret scanning engine

## Related Projects

- [TruffleHog](https://github.com/trufflesecurity/trufflehog) - The original secret scanner

---

**Last Updated**: September 21, 2025  
**Version**: 1.0.1

*This documentation is a living document and will be updated as the project evolves and new features are added.*