## Contents

- 2. Running a Pentest
- Quick Start
- Configuration (shannon.yaml)
- CLI Commands

## 2. Running a Pentest

### Quick Start

```bash
# Prerequisites: Docker (worker container) + Node.js 18+.

# Configure credentials with the interactive wizard (Anthropic recommended).
# Replaces manually appending ANTHROPIC_API_KEY to .env.
npx @keygraph/shannon setup

# Run against a target (white-box, source-aware, finds more vulns).
# Pass the target repo with -r; it is mounted read-only in an ephemeral Docker worker.
npx @keygraph/shannon start -u https://target-app.example.com -r /path/to/your-repo
```

### Configuration (shannon.yaml)

```yaml
# Authentication config — tell Shannon how to log in
auth:
  login_url: /login
  credentials:
    - username: testuser@example.com
      password: TestPass123!
      role: user
    - username: admin@example.com
      password: AdminPass456!
      role: admin

# Scope rules
rules:
  avoid:
    - /api/admin/delete-all    # Don't hit destructive endpoints
    - /api/billing/*           # Skip billing endpoints
    - /logout                  # Don't log yourself out
  focus:
    - /api/*                   # Prioritize API endpoints
    - /dashboard/*             # Focus on authenticated surfaces

# 2FA support (if app uses TOTP)
totp:
  secret: JBSWY3DPEHPK3PXP   # PLACEHOLDER — replace with your test account's actual TOTP secret
```

### CLI Commands

> Flag names, subcommands, and report file paths change between releases. Verify against the current `KeygraphHQ/shannon` README (`npx @keygraph/shannon --help`) before scripting against them; the names below are the reference set as of Jul 2026. The old `git clone` + `./shannon <cmd> KEY=VALUE` form (`URL=`, `REPO=`, `CONFIG=`, `ID=`, `CLEAN=true`, `WORKSPACE=`) is the pre-2026 invocation; current Shannon uses `npx @keygraph/shannon` with flag args (`-u`, `-r`, `-c`, `-w`). The source-build clone still exists but runs `./shannon` with the same flags.

```bash
npx @keygraph/shannon setup                        # One-time credentials wizard
npx @keygraph/shannon start -u <url> -r <repo>     # Start full pentest (repo mounted read-only)
npx @keygraph/shannon start -u <url> -r <repo> -c shannon.yaml  # With config (always use in CI)
npx @keygraph/shannon start -u <url> -r <repo> -w <name>        # Named workspace (resume with same -w)
npx @keygraph/shannon workspaces                   # List all workspaces
npx @keygraph/shannon logs <workspace>             # Tail live logs
npx @keygraph/shannon status                       # Check progress
npx @keygraph/shannon stop                         # Stop containers (preserves data, safe)
```

**Destructive cleanup, guard it.** `npx @keygraph/shannon stop --clean` deletes ALL workspace data: reports, PoCs, recon output, and logs. There is no undo. Shannon confirms before deleting (skip the prompt with `--yes`/`-y`), but never put the `--yes` form in an unattended script or CI job. Always export first and require an explicit confirmation:

```bash
# 1. Export everything you might need before destroying it.
#    npx mode stores workspaces under ~/.shannon/workspaces/ (source-build: ./workspaces/).
WS="$HOME/.shannon/workspaces/<name>"
mkdir -p "./shannon-archive/<name>-$(date +%Y%m%d)"
cp -r "$WS" "./shannon-archive/<name>-$(date +%Y%m%d)/" 2>/dev/null

# 2. Confirm interactively before the irreversible step
read -r -p "Archived. DELETE all Shannon workspace data now? type 'DELETE': " ok
[ "$ok" = "DELETE" ] && npx @keygraph/shannon stop --clean --yes || echo "Aborted, data preserved."
```

---