Vsec

A research-grade static analysis tool for detecting hardcoded secrets in Rust codebases with intelligent false-positive filtering.

Features

• Two-Pass Architecture: Indexes constants across files, then analyzes usage patterns
• Four-Layer Filter Pipeline: Dramatically reduces false positives through:
  • Layer 1: Name analysis (benign vs suspicious terms)
  • Layer 2: Scope isolation (test/example/benchmark detection)
  • Layer 3: Consequence analysis (what happens if comparison succeeds)
  • Layer 4: RHS analysis (command routing vs authentication)
• Score-Based Detection: 0-100+ scoring with configurable thresholds
• Multiple Output Formats: Text, JSON, SARIF, Markdown, GitHub Actions
• Parallel Processing: Uses rayon for fast scanning of large codebases
• Configurable Sensitivity: From paranoid (catch everything) to minimal (high confidence only)
• Git History Scanning: Find deleted secrets in commit history with --scan-history

Installation

cargo install --path .

Or build from source:

cargo build --release

Usage

Scan a Directory

# Scan directory
vsec scan --scan-history --config .vsec.toml ../rustfs

# Scan with lower threshold (more findings)
vsec scan --scan-history --config .vsec.toml --threshold 50

# Include test and example files
vsec scan --scan-history --config .vsec.toml --include-tests --include-examples

# Output as JSON
vsec scan --scan-history --config .vsec.toml -f json -o results.json

# Output as SARIF (for CI integration)
vsec scan --scan-history --config .vsec.toml -f sarif -o results.sarif

# Fail CI if findings exist
vsec scan --scan-history --config .vsec.toml --fail-on-findings

Initialize Configuration

# Create default config file
vsec init

# Create minimal config
vsec init --minimal

# Specify output path
vsec init -o my-config.toml

Explain a Finding

# Get details about a specific finding
vsec explain SEC-abc123 --results results.json

Debug Mode

# Show parsing details for a file
vsec debug src/auth.rs

# Include AST dump
vsec debug src/auth.rs --show-ast

Git History Scanning

Scan git history to find secrets that were committed and later deleted:

# Scan git history (requires --scan-history flag)
vsec scan --scan-history

# Limit to last 100 commits
vsec scan --scan-history --max-commits 100

# Only scan commits after a specific date
vsec scan --scan-history --since 2024-01-01

# Combine with other options
vsec scan --scan-history -f sarif -o history-results.sarif

Note: Git history scanning is opt-in because it can be slow on large repositories with many commits. Use it for security audits, not daily CI.

Configuration

Create a .vsec.toml file in your project root:

[general]
# Sensitivity preset: "paranoid", "high", "normal", "low", or a number
sensitivity = "normal"

[scan]
# Patterns to ignore
ignore_paths = ["target", "vendor", ".git"]

# Include test files in scan
include_tests = false

# Include example files in scan
include_examples = false

[output]
# Show score breakdown for each finding
show_scores = false

# Show remediation suggestions
show_remediation = true

Sensitivity Presets

How It Works

Detection Strategy

Secretrace focuses on equality comparisons involving string constants, not just constant definitions. This approach catches actual authentication bypass vulnerabilities:

// This pattern is detected:
const AUTH_TOKEN: &str = "sk_live_12345";

fn authenticate(token: &str) -> bool {
    if token == AUTH_TOKEN {  // <- Comparison triggers detection
        grant_access();
        return true;
    }
    false
}

False Positive Filtering

The four-layer filter pipeline eliminates common false positives:

1. Name Analysis: VERSION, COLOR, HELP_TEXT are benign
2. Scope Isolation: Test files, examples, and benchmarks are filtered
3. Consequence Analysis: Logging-only blocks are deprioritized
4. RHS Analysis: Command routing (if cmd == "help") is filtered

Scoring Factors

Findings are scored based on multiple factors:

Output Formats

Text (default)

Human-readable output with colors and formatting.

JSON

Machine-readable format for tooling integration.

SARIF

Static Analysis Results Interchange Format for CI/CD integration (GitHub, Azure DevOps, etc.)

Markdown

Report format suitable for documentation or PR comments.

GitHub

GitHub Actions annotation format for inline PR comments.

CI Integration

GitHub Actions

- name: Scan for secrets
  run: |
    cargo install vsec
    vsec scan -f sarif -o results.sarif --fail-on-findings

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

Pre-commit Hook

#!/bin/bash
vsec scan --fail-on-findings -t 70

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Scanner                               │
├─────────────────────────────────────────────────────────────┤
│  Phase 1: Indexer                                           │
│  - Parallel file parsing (rayon + syn)                      │
│  - Build SuspectRegistry (DashMap)                          │
│  - Index public constants                                   │
├─────────────────────────────────────────────────────────────┤
│  Phase 2: Analyzer                                          │
│  - Find equality comparisons                                │
│  - Resolve constant references                              │
│  - Run filter pipeline                                      │
│  - Score findings                                           │
├─────────────────────────────────────────────────────────────┤
│  Filter Pipeline                                            │
│  ┌─────────┐ ┌─────────┐ ┌─────────────┐ ┌────────────┐     │
│  │ Layer 1 │→│ Layer 2 │→│   Layer 3   │→│  Layer 4   │     │
│  │  Names  │ │  Scope  │ │ Consequence │ │    RHS     │     │
│  └─────────┘ └─────────┘ └─────────────┘ └────────────┘     │
├─────────────────────────────────────────────────────────────┤
│  Scoring Engine                                             │
│  - Entropy analysis                                         │
│  - Pattern matching                                         │
│  - Factor aggregation                                       │
│  - Threshold application                                    │
└─────────────────────────────────────────────────────────────┘

License

Vsec is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.