From 6244aa860fc08d45cb620b428185fab7e57fdc5c Mon Sep 17 00:00:00 2001 From: smakarim Date: Sat, 6 Jun 2026 20:25:10 +0500 Subject: [PATCH] docs: expand why-Revenant-exists and what-it-can-do sections --- README.md | 60 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 40 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index be7d0fd..ca4a2d1 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,23 @@ objects, so the secret stays reachable by its SHA. Revenant is built to find tho Built and maintained by [smakarim](https://github.com/smakarim). -## Why +## Why Revenant exists -TruffleHog, Gitleaks, and GitHound scan the current state of repositories you already know -about. The deleted and force-pushed surface, where credentials get "removed" and forgotten, -is not covered by those tools. Revenant targets that surface and folds the ordinary history -scan into the same run, so you do not have to stitch several tools together. +Secrets get committed by accident constantly. The usual reaction is to delete the offending +commit, or force-push over it, and rotate the key "later." That is not enough. GitHub keeps the +underlying commit objects, so a deleted or rewritten commit stays reachable by its SHA, and the +secret stays valid until the credential is actually rotated. Deleting is not remediation. + +Standard secret scanners (TruffleHog, Gitleaks, GitHound) look at the current state of the +repositories you already point them at. The higher-value surface goes unscanned: secrets in +deleted and force-pushed commits, in gists, and in unrelated repositories scattered across all +of GitHub. Covering that surface today means stitching several narrow tools together by hand. + +Revenant exists to cover it in one place. It recovers commits that are no longer reachable from +any branch, scans current history and gists, searches all of GitHub for a target's leaks, +confirms which secrets are still live, attributes each to the developer who committed it, and +ranks findings by blast radius. In testing against public GitHub it surfaced live database +credentials in unrelated repositories within seconds. ## How Revenant compares @@ -49,21 +60,30 @@ on their own. The table reflects each tool's documented, out-of-the-box behavior deleted commits, gists, and code-search dorking in one pass, deduplicated, attributed to the author, and ranked. -## Features - -- Scans reachable history, deleted and force-pushed commits, and gists in one run. Every - finding carries a SOURCE tag (history, deleted, gist, or dork). -- Discovers a wider footprint: a user's gists by default, and with `--members` an org's - members along with their personal repos and gists. -- GitHub-wide dorking (`--dork`) searches all of GitHub with a code-search dork corpus and - scans each matching file. A custom dork file and a domain term are supported. -- Live-key intelligence (`--analyze`) reports a verified GitHub token's identity and scopes, - so you know what the key can actually do. -- Verifies each secret with TruffleHog and caches the result, so a repeated secret is checked - once. -- Attributes every finding to org, repo, commit, and author, with first and last seen. -- Ranks findings by a transparent score based on verified status, secret type, and spread. -- Handles GitHub rate limits with adaptive backoff and rotation across multiple tokens. +## What it can do + +Point Revenant at an organization, a user, or a list of repositories, and in a single run it +will: + +- **Recover deleted work.** Find commits force-pushed or deleted out of history and scan them + for secrets, using the repository activity log so it is immediate and does not brute-force + commit hashes. +- **Scan the whole footprint.** Cover each repository's current history and public gists, and + with `--members` enumerate an organization's members and fold in their personal repos and + gists. +- **Search all of GitHub.** With `--dork`, run a code-search dork corpus across GitHub for the + target's leaks and scan every matching file (`--domain`, `--dork-file`, and `--dork-max` + refine it). +- **Confirm what is live.** Verify each finding with TruffleHog so you see which secrets are + actually active, not just present; `--verified-only` shows only the live ones. +- **Measure the blast radius.** With `--analyze`, report what a verified GitHub token can do + (its identity and scopes), and rank every finding by a transparent score. +- **Attribute and deduplicate.** Tie each finding to org, repo, commit, and author with + first/last seen, collapse duplicates, and tag each result by `SOURCE` (history, deleted, + gist, or dork). Output is a ranked table or JSON. + +It is built for real targets: scanning runs concurrently (`--concurrency`), rotates across +multiple tokens, and backs off on GitHub rate limits. ## Install