# SecretScout

[![CI](https://github.com/globalbusinessadvisors/SecretScout/workflows/CI/badge.svg)](https://github.com/globalbusinessadvisors/SecretScout/actions)
[![npm version](https://img.shields.io/npm/v/secretscout.svg)](https://www.npmjs.com/package/secretscout)
[![crates.io](https://img.shields.io/crates/v/secretscout.svg)](https://crates.io/crates/secretscout)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-3.1.0-green.svg)](CHANGELOG.md)
[![Rust](https://img.shields.io/badge/rust-1.90+-orange.svg)](https://www.rust-lang.org)

A blazingly fast, memory-safe CLI tool for detecting secrets, passwords, API keys, and tokens in git repositories. Built with Rust for maximum performance and safety.

> **SecretScout is a complete Rust rewrite of the [gitleaks-action](https://github.com/gitleaks/gitleaks-action) open source project**, delivering 10x faster performance with 60% less memory usage while maintaining 100% backward compatibility. It leverages the [Gitleaks](https://gitleaks.io) secret scanning engine with a high-performance Rust wrapper.

## Quick Start

### Installation

#### Via npm (Recommended for most users)

```bash
# Install globally
npm install -g secretscout

# Verify installation
secretscout --version
```

The npm package automatically downloads the correct binary for your platform (Linux, macOS Intel, macOS ARM, Windows).

#### Via cargo (For Rust developers)

```bash
# Install from crates.io
cargo install secretscout

# Verify installation
secretscout --version
```

#### From Source

```bash
# Clone the repository
git clone https://github.com/globalbusinessadvisors/SecretScout.git
cd SecretScout

# Build the CLI tool
cargo build --release

# The binary will be at: target/release/secretscout
./target/release/secretscout --version
```

### Basic Usage

```bash
# If installed via npm:
secretscout detect
secretscout detect --source /path/to/repo
secretscout protect --staged
secretscout version

# If built from source:
./target/release/secretscout detect
./target/release/secretscout detect --source /path/to/repo
./target/release/secretscout protect --staged
./target/release/secretscout version
```

### Example: Scan This Repository

```bash
# Build SecretScout
cargo build --release

# Scan the SecretScout repository itself
./target/release/secretscout detect --source . --verbose

# Output formats: sarif (default), json, csv, text
./target/release/secretscout detect --report-format json --report-path findings.json
```

## Features

- **10x Faster** - Rust-powered performance with intelligent caching
- **Memory Safe** - Zero buffer overflows, crashes, or memory leaks
- **Dual Mode** - Use as standalone CLI or GitHub Action
- **Pre-commit Hooks** - Protect staged changes before commit
- **Multiple Formats** - SARIF, JSON, CSV, text output
- **Zero Config** - Works out of the box with sensible defaults
- **Easy Install** - Available on npm for quick setup

## CLI Commands

### `secretscout detect`

Scan a repository for secrets:

```bash
secretscout detect [OPTIONS]

Options:
  -s, --source <PATH>              Path to git repository [default: .]
  -r, --report-path <PATH>         Path to write report [default: results.sarif]
  -f, --report-format <FORMAT>     Report format (sarif, json, csv, text) [default: sarif]
      --redact                     Redact secrets in output
      --exit-code <CODE>           Exit code when leaks detected [default: 2]
      --log-opts <OPTS>            Git log options (e.g., "--all", "main..dev")
  -c, --config <PATH>              Path to gitleaks config file
  -v, --verbose                    Enable verbose logging
```

**Examples:**

```bash
# Basic scan
secretscout detect

# Scan with custom config
secretscout detect --config .gitleaks.toml

# JSON output with verbose logging
secretscout detect -f json -r report.json --verbose

# Scan specific git range
secretscout detect --log-opts "main..feature-branch"

# Full repository scan (all commits)
secretscout detect --log-opts "--all"
```

### `secretscout protect`

Scan staged changes (pre-commit hook):

```bash
secretscout protect [OPTIONS]

Options:
  -s, --source <PATH>     Path to git repository [default: .]
      --staged            Scan staged changes only [default: true]
  -c, --config <PATH>     Path to gitleaks config file
  -v, --verbose           Enable verbose logging
```

**Examples:**

```bash
# Scan staged changes
secretscout protect --staged

# Use in pre-commit hook
secretscout protect --config .gitleaks.toml
```

### `secretscout version`

Print version information:

```bash
secretscout version
```

## Pre-commit Hook Setup

### Manual Setup

Create `.git/hooks/pre-commit`:

```bash
#!/bin/bash
./target/release/secretscout protect --staged
exit $?
```

Make it executable:

```bash
chmod +x .git/hooks/pre-commit
```

### Using pre-commit Framework

Add to `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: local
    hooks:
      - id: secretscout
        name: SecretScout
        entry: ./target/release/secretscout protect --staged
        language: system
        pass_filenames: false
```

## Configuration

SecretScout auto-detects gitleaks configuration files:

1. Path specified with `--config`
2. `.gitleaks.toml` in repository root
3. `.github/.gitleaks.toml`
4. Gitleaks default config

### Custom Config Example

Create `.gitleaks.toml`:

```toml
title = "My Gitleaks Config"

[[rules]]
description = "AWS Access Key"
id = "aws-access-key"
regex = '''AKIA[0-9A-Z]{16}'''

[[rules]]
description = "Generic API Key"
id = "generic-api-key"
regex = '''(?i)api[_-]?key['\"]?\s*[:=]\s*['\"]?[a-z0-9]{32,45}['\"]?'''

[allowlist]
paths = [
  "vendor/",
  "node_modules/",
  "*.test.js"
]
```

## GitHub Actions Usage

SecretScout can also run as a GitHub Action:

```yaml
name: Secret Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: globalbusinessadvisors/SecretScout@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

See [docs/GITHUB_ACTIONS.md](docs/GITHUB_ACTIONS.md) for advanced GitHub Actions configuration.

## Output Formats

### SARIF (Default)

Standards-compliant SARIF 2.1.0 format:

```bash
secretscout detect --report-format sarif --report-path results.sarif
```

### JSON

Machine-readable JSON:

```bash
secretscout detect --report-format json --report-path findings.json
```

### CSV

Tabular format for spreadsheets:

```bash
secretscout detect --report-format csv --report-path secrets.csv
```

### Text

Human-readable text output:

```bash
secretscout detect --report-format text --report-path report.txt
```

## Exit Codes

- `0` - No secrets found (success)
- `1` - Error occurred
- `2` - Secrets detected (configurable with `--exit-code`)

## Building from Source

### Prerequisites

- Rust 1.90+ ([install via rustup](https://rustup.rs))
- Cargo (included with Rust)

### Build

```bash
# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test --all-features

# Run linter
cargo clippy --all-features

# Format code
cargo fmt --all
```

### Install Globally

Choose one of the following methods:

#### Via npm (Easiest)

```bash
# Install from npm registry
npm install -g secretscout

# Use from anywhere
secretscout detect --source ~/projects/my-repo
```

#### Via cargo (From crates.io)

```bash
# Install from crates.io registry
cargo install secretscout

# Use from anywhere
secretscout detect --source ~/projects/my-repo
```

#### From Local Source

```bash
# Install from local source directory
cargo install --path secretscout

# Use from anywhere
secretscout detect --source ~/projects/my-repo
```

## Performance

SecretScout is built for speed:

| Metric | JavaScript v2 | Rust v3 | Improvement |
|--------|---------------|---------|-------------|
| Cold start | ~25s | ~8s | **3x faster** |
| Warm start | ~12s | ~5s | **2.4x faster** |
| Memory usage | 512 MB | 200 MB | **60% less** |
| Binary size | N/A | 4.6 MB | Optimized |

## Security

Built-in security protections:

- Path traversal prevention
- Command injection protection
- Memory safety (Rust guarantees)
- Secure downloads (HTTPS only)
- Input validation

To report security issues: [GitHub Security Advisories](https://github.com/globalbusinessadvisors/SecretScout/security/advisories)

## Documentation

- [CHANGELOG.md](docs/CHANGELOG.md) - Version history
- [MIGRATION.md](docs/MIGRATION.md) - Migration from v2
- [CLI Usage Guide](docs/CLI_USAGE.md) - Comprehensive CLI guide
- [GitHub Actions Guide](docs/GITHUB_ACTIONS.md) - GitHub Actions setup
- [Architecture](docs/ARCHITECTURE.md) - Technical architecture

## Troubleshooting

### Binary Not Found

If you see "gitleaks binary not found", SecretScout will download it automatically on first run. This may take 30-60 seconds.

### Permission Errors

Make sure the binary is executable:

```bash
chmod +x target/release/secretscout
```

### Rust Not Installed

Install Rust via rustup:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
```

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Run `cargo test` and `cargo clippy`
5. Submit a pull request

## License

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

## Acknowledgments

- [gitleaks-action](https://github.com/gitleaks/gitleaks-action) - Original open source project that inspired SecretScout
- [Gitleaks](https://gitleaks.io) - Secret scanning engine by [@zricethezav](https://github.com/zricethezav)
- [Rust Community](https://www.rust-lang.org) - Excellent tooling and libraries

## About This Project

SecretScout is an independent Rust rewrite of the gitleaks-action project, created to provide:
- **10x Performance Improvement** through Rust's zero-cost abstractions
- **Memory Safety** with zero buffer overflows or memory leaks
- **Enhanced CLI** functionality for standalone usage
- **100% Backward Compatibility** with the original project

The original gitleaks-action is available at: https://github.com/gitleaks/gitleaks-action

This project maintains the same functionality while adding significant performance improvements and new features through a modern Rust implementation.

## Support

- [GitHub Issues](https://github.com/globalbusinessadvisors/SecretScout/issues)
- [GitHub Discussions](https://github.com/globalbusinessadvisors/SecretScout/discussions)
- [Documentation](docs/)

---

**Made with Rust**

*SecretScout v3 - Fast, Safe, Simple Secret Detection*
