@vtx-labs/recon

v0.2.0

Published

7 days ago

Secret intelligence for authorized engagements — find a key, then prove what it can actually do. Read-only capability ladders, gated by construction, with a redacted evidence bundle.

0High
0Medium
0Low

bankkroll

security secrets secret-scanning bug-bounty capability-ladder trufflehog credential redaction cli vtx-labs

██████╗ ███████╗ ██████╗ ██████╗ ███╗   ██╗
██╔══██╗██╔════╝██╔════╝██╔═══██╗████╗  ██║
██████╔╝█████╗  ██║     ██║   ██║██╔██╗ ██║
██╔══██╗██╔══╝  ██║     ██║   ██║██║╚██╗██║
██║  ██║███████╗╚██████╗╚██████╔╝██║ ╚████║
╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝

@vtx-labs/recon

Secret intelligence for authorized engagements — find a key, then prove what it can actually do. The native TypeScript/Node implementation of vtx-recon.

⚠️ Authorized use only
vtx-recon is for security testing of systems you are explicitly authorized to test — an in-scope bug-bounty program or a signed engagement. Validating a credential beyond authentication may constitute unauthorized access under the US CFAA, the UK Computer Misuse Act, and equivalent laws. On HackerOne and similar programs: report leaked credentials first; do not exercise their functionality beyond what the program permits. Provided "as is", no warranty, no liability. By using it you accept the TERMS.

A found secret that merely exists is not a finding. A found secret you can prove does something the program cares about is. TruffleHog finds secrets and tells you if they're live; vtx-recon picks up from there — it runs ordered, read-only capability ladders to prove depth of access, tiers each key as PROVEN / VALID / DENIED, and emits a redacted, timestamped evidence bundle you can drop into a report.

trufflehog ──▶ findings ──▶ vtx-recon ladder ──▶ PROVEN / VALID / DENIED ──▶ evidence bundle
   (find +        (live/        (safe, ordered        (impact tier)        (JSON,
    verify)        dead)         read-only probes)                          secrets redacted)

This package is a faithful, native port of the Python implementation: the same pipeline, the same safety guarantees, the same providers, the same CLI surface — idiomatic ESM TypeScript with zero runtime dependencies (built-in fetch, node:crypto, node:child_process).

Requirements

vtx-recon orchestrates the TruffleHog binary for the find/verify stage — install it first:

# macOS / Linux
brew install trufflehog
# or: curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

The binary is located on PATH on demand — it is never spawned at import time.

Install

npx @vtx-labs/recon find . --i-am-authorized "bugbounty:acme"
# or install it:
pnpm add -g @vtx-labs/recon
npm  install -g @vtx-labs/recon

Quick start

# Find + verify secrets in a repo, then ladder the live ones (read-only):
vtx-recon find . --i-am-authorized "bugbounty:acme"

# Validate a single key you already have:
echo "AIza..." | vtx-recon ladder --i-am-authorized "bugbounty:acme"

# Machine-readable evidence bundle:
vtx-recon ladder --key ghp_xxx --i-am-authorized "h1:acme" --json

By default only safe, read-only probes run. Probes that cost money, read PII, or change state are gated (see below) and never run unless you explicitly arm them.

Programmatic API

import { Consent, getLadder, Finding } from "@vtx-labs/recon";

const consent = new Consent({ authorizedScope: "bugbounty:acme" });
const finding = new Finding({ detectorName: "GoogleAI", verified: true, raw: "AIza..." });

const ladder = getLadder(finding.detectorName);
if (ladder) {
  const result = await ladder(finding, consent);
  console.log(result.verdict, JSON.stringify(result.toPublic(), null, 2));
}

The safety model — read-only by default, gated by construction

Every probe is one of two tiers:

SAFE — read-only, non-billable, idempotent (list models, GetCallerIdentity, auth.test, read token scopes). Runs by default.
GATED — billable, PII-reading, state-changing, or resource-creating (Gemini generateContent / file upload, a billable Maps call, Firebase anonymous signup, a Stripe account read).

A gated probe is structurally unreachable unless you pass both:

--prove                      # arm gated probes
--i-am-authorized "<scope>"  # name the engagement you're authorized to test

This is enforced in code (src/safety.ts), not just docs:

guard(consent, tier, probeName) is a no-op for SAFE and throws GatedProbeBlocked before any I/O for GATED unless consent.prove and a non-empty authorizedScope are both present.
gated(probeName, fn) wraps a probe so the guard runs before the body, and fails closed: if no Consent is reachable in the arguments it is treated as denied (blocked), never allowed.
Consent is frozen at construction — a probe cannot mutate its own consent to escalate its tier mid-run.
Consent.requireLadderScope() makes the whole ladder refuse to run (throws ScopeRequired) without a named scope, which is recorded verbatim in the evidence bundle so every action is attributable.

There is no flag, env var, or config that runs a gated probe with only one of the two conditions met. Both are required, every time.

Capability ladders

51 providers ship with a dedicated ladder, auto-detected from the key's shape / TruffleHog detector name. Each climbs from cheapest/safest to deepest: identity/whoami first, then reach/scope, then the impactful rung. Gated rungs are marked 🔒. Where a rung needs an out-of-band value the engine cannot derive from the secret alone (a second credential half, an account/host/project id), it never fires a live call — it prints the exact copy-pasteable safe curl with the secret kept as $KEY (marked manual) for an authorized operator to run by hand. getLadder(detectorName) returns the registered ladder so you can introspect or invoke any of them programmatically.

Cloud & infra

Data stores

CI/CD & packages

Comms & email

Support & productivity

Observability & ops

Payments & SaaS

Beyond these 51, the generic declarative layer is a runtime extensibility hook: loadSpecs([...]) (or registerSpec) plugs a new provider in as data — header + read-only endpoint per rung — with no core changes. A billable rung declared SAFE is rejected; when a spec has no automated rung it prints the exact safe curl for the operator. It is no longer a catch-all for the named providers above (every one now has its own ladder); BUILTIN_SPECS ships empty.

Impact tiers

Exit codes

| Code | Meaning | | :--- | :------ | | 0 | Success | | 1 | Runtime error | | 2 | Usage error | | 3 | TruffleHog binary not found | | 4 | Authorized scope required (laddering without --i-am-authorized) | | 5 | A gated probe was blocked (missing --prove / scope) |

Development

pnpm install
pnpm typecheck   # tsc --noEmit (strict)
pnpm test        # vitest run (all HTTP / spawn mocked — never hits real APIs)
pnpm build       # tsup -> dist/ (ESM + .d.ts + sourcemaps)
pnpm dev -- --help

License

Built by VTX Labs · GitHub · @vtxlabs

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@vtx-labs/recon

⚠️ Authorized use only

Requirements

Install

Quick start

Programmatic API

The safety model — read-only by default, gated by construction

Capability ladders

Impact tiers

Exit codes

Development

License