truffles

Find GitHub repos at scale. Scan every commit. Catch leaked secrets.

Website: truffles.devrecated.com · Org: openhat-security

Enumerate owners or search globally (with a proxy pool for rate limits), filter by glob or regex, then scan full git history with trufflehog. Or write a YAML playbook and run both steps in one shot.

Install

# macOS / Linux — Homebrew
brew install --cask openhat-security/tap/truffles

# Debian / Ubuntu — apt (shared OpenHat pool)
curl -fsSL https://openhat-security.github.io/packages/install-apt-truffles.sh | sudo bash

# Fedora / RHEL — dnf
curl -fsSL https://openhat-security.github.io/packages/install-dnf-truffles.sh | sudo bash

# Windows — Scoop
scoop bucket add openhat https://github.com/openhat-security/scoop-bucket
scoop install truffles

# Windows — winget
winget install OpenHatSecurity.Truffles

# any OS — npm (Node ≥ 18)
npm install -g truffles

# macOS / Linux — direct binary
curl -fsSL https://raw.githubusercontent.com/openhat-security/truffles/main/scripts/install.sh | bash

# from source
git clone https://github.com/openhat-security/truffles
cd truffles
make build          # → ./truffles
make install        # or: go install ./cmd/truffles

# Go (module path is still github.com/adamsiwiec/truffles)
go install github.com/adamsiwiec/truffles/cmd/truffles@latest

Packaging details: packaging/README.md · Releases: github.com/openhat-security/truffles/releases

Requires trufflehog on PATH for scan (override with -bin). A GitHub token is optional for public search and required for private repos. Scan defaults to -since 2y (full clone; only commits in the window are scanned — use -since all for entire history).

Quick start

# guided walkthrough (search + scan)
./truffles wizard

# every public repo under an org
./truffles search -owner openhat-security -out repos.txt

# AI / LLM key pattern search (shuffled; skips scanned+clean)
./examples/search-ai-keys.sh

# scan history (default report format: csv; also writes .txt)
./truffles scan -f repos.txt

# 24/7 remote loop (search → cluster scan)
./truffles job start -c remote-playbook.yaml --prefix-file examples/prefixes-openai.txt

# live-verify CSV secrets; roll up results
./truffles verify -f data/remote-results/results.csv
./truffles consolidate --update-master --update-clean

# coordinated disclosure from a results CSV (dry-run; add -submit to POST)
./truffles disclose -f data/remote-results/results.csv
./truffles disclose -f data/remote-results -submit   # prompts for token once, then reuses it

# or: author a playbook and run both steps
vim playbook.yaml
./truffles playbook -f playbook.yaml

# GCE scan workers (size suggestions, create/list/resize):
./scripts/manage-gce-workers.sh YOUR_PROJECT suggest
./scripts/manage-gce-workers.sh YOUR_PROJECT create --count 2 --machine e2-standard-2

./truffles                # banner + short help
./truffles -help          # same short help
./truffles help full      # full flag reference
./truffles examples
./truffles wizard         # interactive setup

wizard

New here? Run truffles wizard. It walks you through owner vs global search, optional filters, writing a repo list, and kicking off a scan — same pipeline as the commands above, without memorizing flags.

Tips

• Status lines: [ok] clean · [++] findings · [!!] not scanned (never counted as clean).
• Reports default to a timestamped file and are fsynced after every repo — Ctrl-C keeps what finished.
• -format pretty|csv|jsonl. Colour respects NO_COLOR and -color always|never.
• -max-depth N and default -since 2y are lossy (miss older commits). Use -since all when full history matters.
• Record demo GIFs: brew install vhs && make demo-vhs TAPE=quickstart → assets/screenshots/quickstart.{gif,mp4}. Full gallery (search/scan/playbook/remote/job/…): docs/demos.md · make demo-vhs-all.

search / scan

Enumeration (-owner) lists every public repo, then filters locally with globs or -regex.

Global search (no -owner) hits GitHub's search API; -q is repeatable and -filter narrows locally.

scan reads a URL list and runs trufflehog. Progress stays on stderr; the report goes to -out.

Deep notes (proxy pool, durability, measured performance): docs/architecture.md.

Operations wiki (jobs, remote cluster, kill/restart, troubleshooting): GitHub Wiki — source in docs/wiki/; publish with ./scripts/sync-wiki.sh.

Security

Reports contain secrets in plaintext. They are gitignored by default — keep them out of version control. Use -results verified when you want only confirmed-live credentials. Rotation, not deletion, removes a leaked secret from GitHub history.

License & contributing

LICENSE · CONTRIBUTING.md · CHANGELOG.md

make check is what CI runs.