leakwatch

Leakwatch

Next-generation secret scanning platform — fast, accurate, open source.

Leakwatch is a high-performance security tool that detects, verifies, and reports leaked secrets (API keys, passwords, certificates) in codebases, Git histories, and container images.

Why Leakwatch?

[^gl-action]: The Gitleaks CLI is MIT-licensed. The official gitleaks-action GitHub Action, however, runs under a commercial EULA and requires a (free) license key for organization accounts (personal accounts are exempt). [^th-sarif]: TruffleHog emits JSON / plain / GitHub-Actions output; it has no native SARIF formatter (SARIF requires an external converter). All three tools use Aho-Corasick keyword pre-filtering and Shannon-entropy filtering, and all three support custom rules (Leakwatch: YAML, TruffleHog: config.yaml detectors: block, Gitleaks: TOML).

What makes Leakwatch different:

• MIT license with verification — Among these tools, Leakwatch is the only one that is both permissively licensed (MIT, unlike TruffleHog's AGPL-3.0) and performs live secret verification (unlike Gitleaks, which is detection-only)
• 85.7% verification coverage — 54 of 63 detectors have live API or format validation verification
• Verification + container + SARIF in one MIT binary — TruffleHog lacks SARIF; Gitleaks lacks verification and container scanning
• Easy extensibility — YAML for simple rules, Go plugin for advanced ones
• Single binary, zero dependencies — Runs on every platform
• Scan summary — Every scan prints a summary to stderr (date, source, target, files scanned, duration, findings)
• Colored terminal output — Severity-colored table output (red=critical/high, yellow=medium, blue=low), auto-disabled for file output

Quick Start

Installation

# Homebrew (macOS/Linux)
brew install HodeTech/tap/leakwatch

# Go install
go install github.com/HodeTech/leakwatch@latest

# Docker
docker run --rm -v $(pwd):/scan ghcr.io/hodetech/leakwatch:latest scan fs /scan

# Binary download — pick the archive for your OS/arch from the releases page:
#   https://github.com/HodeTech/Leakwatch/releases  (e.g. leakwatch_1.5.0_linux_amd64.tar.gz)

Quick Setup

# Generate a recommended .leakwatch.yaml in the current directory
leakwatch init

Usage

# Scan current directory (default when no path given)
leakwatch scan fs

# Scan a specific directory
leakwatch scan fs /path/to/project

# Scan Git repository (full history)
leakwatch scan git /path/to/repo
leakwatch scan git https://github.com/org/repo.git

# Scan container image
leakwatch scan image nginx:latest

# Show only verified secrets
leakwatch scan git . --only-verified

# Output in SARIF format
leakwatch scan fs . --format sarif --output results.sarif

# Scan since last commit (for CI/CD)
leakwatch scan git . --since-commit HEAD~1

# Scan AWS S3 bucket
leakwatch scan s3 my-bucket --prefix config/

# Scan Google Cloud Storage bucket
leakwatch scan gcs my-bucket --prefix secrets/

# Scan Slack workspace
leakwatch scan slack --token xoxb-... --channels general,engineering

# Scan multiple repos in parallel
leakwatch scan repos https://github.com/org/repo1.git https://github.com/org/repo2.git --parallel 5

# Include remediation guidance (rotation steps, doc links)
leakwatch scan fs . --remediation

Supported Secret Types

63 built-in secret detectors across 60 packages.

Verification Coverage (54/63 — 85.7%)

Can't find your secret type? Leakwatch supports YAML custom rules — define your own detector in 5 lines of YAML without writing Go code.

CI/CD Integration

GitHub Actions

- uses: HodeTech/Leakwatch@v1
  with:
    scan-type: git
    no-verify: false      # turn verification ON (required for only-verified)
    only-verified: true   # report only secrets confirmed live
    sarif-upload: true

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/HodeTech/Leakwatch
    rev: v1.5.0
    hooks:
      - id: leakwatch

Configuration

Create a configuration file with recommended defaults using leakwatch init, or write one manually:

# .leakwatch.yaml
scan:
  concurrency: 8
  max-file-size: 10485760  # 10MB

detection:
  entropy:
    enabled: true
    threshold: 4.0

verification:
  enabled: true
  timeout: 10s

filter:
  exclude-paths:
    - "vendor/**"
    - "node_modules/**"
    - "**/*.lock"

output:
  format: json
  show-raw: false

Architecture

flowchart LR
    subgraph Sources["Sources (6)"]
        S1["Git (go-git)"]
        S2["Filesystem (io/fs)"]
        S3["Container (crane)"]
        S4["AWS S3"]
        S5["GCS"]
        S6["Slack"]
    end

    subgraph Engine["Detection Engine"]
        E1[Aho-Corasick]
        E2[Regex]
        E3[Entropy]
    end

    subgraph Verify["Verification (54 verifiers, 51 packages)"]
        V1[Live API Verification]
        V2[Format Validation]
    end

    Sources -->|Chunks| Engine
    Engine -->|Findings| Verify
    Verify --> Output["JSON / SARIF / CSV"]

Detailed architecture: docs/architecture/03-ARCHITECTURE.md

Documentation

Architecture & Design

Standards

Decisions (ADR)

Guides

Planning

Contributing

We welcome your contributions! Please see the CONTRIBUTING.md file.

# Set up the development environment
git clone https://github.com/HodeTech/Leakwatch.git
cd Leakwatch
go mod download
go test ./...

License

MIT License — see the LICENSE file for details.

Status

Phases 1–8 are complete. Leakwatch supports filesystem, Git, container, S3, GCS, and Slack scanning (6 sources) with 63 detectors across 60 packages, 54 verifiers (85.7% coverage), multiple output formats, and CI/CD integration.

To track the project's progress, see the Roadmap document.