RefHound

Git repository security and forensic analysis tool.

RefHound is a read-only analysis tool. It inspects the git object database and refs to surface information that is no longer visible in the current working tree:

• deleted branches, lost / unreachable commits, dangling objects

• secrets that were introduced and later removed

• historical versions of credentials, keys and configuration

• suspicious CI/CD, authentication and deployment changes

• timeline, identity and force-push anomalies

It never validates, reuses or brute-forces credentials, and never attempts to bypass an access-control boundary. Use it only on repositories you are authorized to analyse.

Contents

• Installation
  • Requirements
  • Remote repositories
• Core Concepts
  • Reachability
  • Facts and heuristics
  • Secret lifecycle
• Scanning Repositories
  • Local repositories
  • Remote repositories and freshness
  • Shallow, LFS, and submodules
• Command reference
  • Scan result cache
  • Global exit codes
  • scan
  • findings
  • secrets
  • refs
  • commits
  • objects
  • dangling
  • unreachable
  • lost
  • timeline
  • authors
  • stats
  • history
  • interesting
  • explain
  • explain-lost
  • doctor
  • report
  • diff-scan
  • baseline
  • analyze
  • cache
  • Configuration
• Design
  • Layering
  • Git access model
  • Secret pipeline
  • Lost-history reconstruction
  • Fact vs. interpretation
  • Storage
• Detectors
  • Reference
  • Tuning
  • Adding a detector
• Reports and Machine Interfaces
  • SARIF
  • Exit codes
• Configuration
  • Baselines
• Git Forensics Methodology
• Performance
• Limitations
  • Inherent limits
  • Heuristics are labeled
  • False positives
• Security
  • Secret handling
  • Fingerprint privacy tradeoff
  • Remote authentication
  • What RefHound will never do
  • Operating safety
  • Reporting a vulnerability
• Troubleshooting
• Release and Compatibility
• Development
  • Setup
  • Contributing notes

Concepts

• Reachable: objects referenced from any ref (branches, tags, remotes).

• Unreachable: objects still present in the object database but no longer referenced by a ref (deleted branches, force-pushed commits).

• Lost chain: a connected set of unreachable commits that forms a deleted line of history. RefHound can often still recover its contents and estimate the branch it used to belong to.

• Dangling: objects referenced by nothing at all (typically the result of interrupted operations).

• Historical secret: a secret present in a past commit of the reachable history but no longer in the current tree.

• Heuristic: any derived conclusion that could be wrong (branch hints, force-push inference, identity grouping). Always labeled as such and accompanied by a confidence value.

Profiles

Stage	quick	standard	deep	forensic
Refs and reachable history	yes	yes	yes	yes
Pattern secret detectors	yes	yes	yes	yes
Entropy detector	no	yes	yes	yes
Unreachable objects / lost chains	no	no	yes	yes
Reflogs and stash refs	no	no	yes	yes
Binary blob scan	no	no	yes	yes
Git notes	no	no	no	yes

LFS content, submodule traversal and provider APIs are not supported public pipeline stages in v0.1. LFS pointer files and .gitmodules remain visible to ordinary history/file analysis, but RefHound does not fetch or recursively scan their external content.

Quick start

$ refhound scan . --deep
$ refhound scan . --format sarif -o scan.sarif
$ refhound lost .
$ refhound secrets .
$ refhound timeline .
$ refhound interesting .
$ refhound analyze churn .
$ refhound doctor .

Typical workflow

1. refhound doctor . - verify the repository and tool prerequisites.

2. refhound scan . --deep - full scan; findings are redacted by default.

3. refhound findings . --severity high - focus on the serious findings.

4. refhound lost . and refhound explain-lost . CHAIN_ID - inspect deleted lines of history.

5. refhound baseline . -o baseline.json and re-scan with --baseline baseline.json to track new findings only.

6. refhound report . --format markdown -o report.md - shareable report.

See Command reference for the full command reference and Design for the internal architecture.