Metadata-Version: 2.4
Name: redrun
Version: 0.1.0
Summary: RedRun — continuous, proof-backed security testing you run yourself.
Author: RedRun
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.10.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: dnspython>=2.7.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: lxml>=5.3.0
Requires-Dist: cryptography>=42.0.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40.0; extra == "ai"

# RedRun CLI

**Proof-backed security testing you run yourself.** A standalone command-line tool
that runs RedRun's scanning engine **locally on your machine** — passive recon and
real, evidence-verified exploitation (SQLi, XSS, SSRF, IDOR, broken auth) — with
no cloud dependency.

This is the licensed-software M1 (see `../LICENSED-SOFTWARE-PLAN.md`): the engine
runs inside your own environment, so authorization is implicit (you point it at
your own assets) and deeper/internal testing is possible.

## Install (customers)
```bash
# Recommended: isolated install on PATH
pipx install ./dist/redrun-0.1.0-py3-none-any.whl
# or
pip install ./dist/redrun-0.1.0-py3-none-any.whl
```
For AI executive summaries: `pipx install "redrun[ai]"` and set `ANTHROPIC_API_KEY`.

## Licensing
Passive scans are **free**. Active exploitation requires a license.
```bash
redrun license status                 # show current license
redrun license activate your.lic      # install a license file (offline-verified)
```
Licenses are Ed25519-signed and verified **offline** with an embedded public key —
no server call, air-gap friendly. Tampering invalidates the signature.

## Usage
```bash
# Passive scan — recon, headers, TLS, DNS, exposed paths, nuclei CVE templates
redrun scan example.com

# Active exploitation — requires explicit authorization
redrun scan staging.myapp.com --active --authorized

# Production-looking host needs an extra confirmation
redrun scan myapp.com --active --authorized --confirm-production

# Extra in-scope hosts, JSON export, kernel sandbox
redrun scan myapp.com --active --authorized --scope api.myapp.com --json out.json
redrun scan myapp.com --active --authorized --sandbox docker
```

### Options
| Flag | Meaning |
|---|---|
| `--active` | run real exploitation (not just passive observation) |
| `--authorized` | confirm you own / may test the target (**required for `--active`**) |
| `--confirm-production` | authorize an active scan against a production-looking host |
| `--scope a,b` | additional in-scope hosts |
| `--sandbox local\|docker\|auto` | containment for active scans (default `local` egress guard; `docker` = kernel iptables allowlist, needs a Docker host) |
| `--json FILE` | write full results to JSON |
| `--no-ai` | skip the AI executive summary |

## Safety
- **Passive** scans are read-only and legal on any domain.
- **Active** scans send real attack payloads — only run them against systems you
  own or are authorized to test. The `--authorized` flag is your rules-of-engagement.
- Active scanning is **detection-only**: it proves a vulnerability exists with
  request/response evidence, then stops — it never exfiltrates data or causes damage.
- Outbound traffic is scope-enforced (egress guard by default; optional Docker
  kernel sandbox).

## Optional
- **AI summaries:** set `ANTHROPIC_API_KEY` and install the `[ai]` extra for an
  executive summary. Without it, the CLI runs fully offline.
- **Nuclei:** if the `nuclei` binary is on PATH, CVE templates run automatically;
  otherwise that step is skipped.

## Build & release (maintainers)
```bash
python -m build --wheel          # → dist/redrun-<v>-py3-none-any.whl
```
Issue a license (internal — needs the private signing key in `scripts/.keys/`,
which is gitignored and must never ship):
```bash
python scripts/issue_license.py --email user@co.com --tier pro --days 365
```

## Architecture
`redrun/engine/` is a vendored copy of the scanning engine (recon, scope, egress
guard, exploit tools, reporter). The CLI orchestrates it locally. Vendored for
M1 to keep the tool standalone and zero-risk to the live web backend; a shared
`redrun_core` package can de-duplicate later. `redrun/licensing.py` holds the
embedded license-verification public key.
