secretscan-report

A personal security-hygiene tool: scans your own machine for accidentally exposed secrets (API keys, tokens, passwords, private keys), audits what's installed and what's exposed (Docker containers, listening ports, Chrome browser cookies), and can optionally check your local network and internet connectivity.

Everything runs locally. No secrets ever leave your machine.

Install

pip install secretscan-report[all]

The [all] extra installs websocket-client, which is used only to talk to Chrome's DevTools Protocol on localhost:9222 for headless browser auditing (the same mechanism as chromedp in Go). It never makes outbound network connections.

Without [all]:

pip install secretscan-report

This installs the core scanner (filesystem, shell history, keychain, processes, network, Docker). Chrome headless auditing is skipped if websocket-client is not installed.

Usage

# Full scan — all modules including Chrome, LAN, Internet
# Generates HTML + JSON reports with a progress bar
secretscan fullscan

# Default scan (home dir, default modules)
secretscan run

# Scan a specific directory, filesystem module only
secretscan run --paths ~/Projects --modules filesystem

# Full scan with custom output directory
secretscan fullscan --output-dir ./report

# List all detection rules
secretscan rules list

Modules

Output formats

• table — colored terminal output (default)
• json — machine-readable {meta, findings} document
• html — self-contained HTML report with dark/light theme
• csv — flat CSV of findings

Detection

15 built-in rules covering AWS, GitHub, GitLab, Slack, Stripe, Google, npm, PEM private keys, and generic password/secret/token assignments. Each rule uses regex matching with optional Shannon entropy scoring and keyword pre-filtering for performance.

Values that look like placeholders ({{password}}, changeme, your_api_key_here) are detected and downgraded rather than competing with real findings.

Security & privacy

• No outbound network calls from secret-detection modules — ever.
• The chrome module connects to localhost:9222 (Chrome DevTools Protocol) to audit your own browser. This is the same protocol used by Selenium, Playwright, Puppeteer, and chromedp. It copies essential Chrome profile files to a temp directory, launches headless Chrome against the copy, reads cookies and takes a screenshot, then deletes the copy.
• The optional lan module sends pings to your local subnet (requires --yes-lan).
• The optional internet module makes TCP connections to well-known public endpoints (e.g. google.com:443) to test connectivity.
• All scan results stay on disk in the output directory you choose.

Cross-platform

Works on macOS, Linux, and Windows. Platform-specific features:

• macOS: Keychain audit, Chrome cookie decryption via Keychain
• Linux: /proc-based process inspection
• Windows: netstat/wmic/ipconfig fallbacks

What this tool does NOT do

• No git-history scanning (use Gitleaks/TruffleHog for that)
• No live credential verification
• No bypassing macOS security prompts
• No outbound transmission of findings
• Secret detection modules never make outbound network calls

Dependencies

• pyyaml — for loading rules YAML files
• websocket-client (optional, via [all]) — localhost-only CDP communication for Chrome auditing
• cryptography (optional, via [crypto]) — macOS Chrome cookie decryption from SQLite fallback