Metadata-Version: 2.4
Name: secretscan-report
Version: 0.1.0
Summary: Scan your machine for accidentally exposed secrets — API keys, tokens, passwords, private keys — across filesystem, shell history, keychain, processes, and more.
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Provides-Extra: chrome
Requires-Dist: websocket-client>=1.6.0; extra == "chrome"
Requires-Dist: cryptography>=41.0; extra == "chrome"
Provides-Extra: all
Requires-Dist: websocket-client>=1.6.0; extra == "all"
Requires-Dist: cryptography>=41.0; extra == "all"

# secretscan

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), and can
optionally check your local network and internet connectivity.

## Install

```sh
pip install .
```

Or for development:

```sh
pip install -e .
```

## Usage

```sh
# default scan: everything except lan/internet, print a table
secretscan run

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

# full scan including LAN and internet, all formats
secretscan run --modules filesystem,shell-history,keychain,process-env,installed-tools,network,docker,lan,internet \
  --yes-lan --format table,json,html --output-dir ./report

# list all detection rules
secretscan rules list

# use a custom rules file
secretscan run --rules-file my-rules.yaml
```

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

14 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.

## What this tool does NOT do

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