# SecretScout
[](https://github.com/globalbusinessadvisors/SecretScout/actions)
[](https://www.npmjs.com/package/secretscout)
[](https://crates.io/crates/secretscout)
[](LICENSE)
[](CHANGELOG.md)
[](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:
| 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
```
## 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*