Metadata-Version: 2.4
Name: get-report
Version: 0.1.0
Summary: Scan your computer for secrets and generate a report.
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: websocket-client>=1.6.0
Provides-Extra: crypto
Requires-Dist: cryptography>=41.0; extra == "crypto"

# 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

```sh
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](https://github.com/chromedp/chromedp) in Go).
It never makes outbound network connections.

Without `[all]`:

```sh
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

```sh
# 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

| Module | Default | What it does |
|---|---|---|
| `filesystem` | yes | Scans files under `--paths` (default `$HOME`) for secret patterns |
| `shell-history` | yes | Scans `.zsh_history`, `.bash_history`, and other history files |
| `keychain` | yes | Audits macOS Keychain metadata (never decrypts values) |
| `process-env` | yes | Inspects your own running processes' command lines |
| `installed-tools` | yes | Inventories security/dev tools and packages |
| `network` | yes | Lists TCP/UDP ports this machine is listening on |
| `docker` | yes | Lists running containers, checks for exposed Docker API |
| `chrome` | yes | Audits Chrome browser: launches headless, reads cookies via CDP, takes screenshots |
| `lan` | opt-in | Probes other devices on your local network (`--yes-lan`) |
| `internet` | opt-in | Tests outbound connectivity to public endpoints |

## 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
