shannon

Files (5)

• CRAFTBOT.md
• README.md
• SKILL.md
• setup-shannon.sh · scripts/
• sync.sh · scripts/

SKILL.md (first lines)

# Shannon: Autonomous AI Pentester for Web Apps & APIs

> **Permissions overview:** This skill orchestrates Shannon, a Docker-based pentesting tool that actively executes attacks against a target application. It clones/updates the Shannon repo locally, runs Docker containers, and reads pentest reports. **Shannon performs real exploits — only run against apps you own or have explicit written authorization to test.** Never run against production systems.

Shannon analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production. 96.15% exploit success rate on the XBOW security benchmark. Covers OWASP Top 10: Injection, XSS, SSRF, Broken Auth, Broken AuthZ, and more.

---

## CRITICAL: Safety Checks (ALWAYS run first)

Before doing ANYTHING, you MUST confirm:

1. **Authorization**: Ask the user — "Do you have explicit authorization to pentest this target?" If they say no or are unsure, STOP and explain they need written permission from the system owner.
2. **Environment**: Confirm the target is a local, staging, or sandboxed environment — NEVER production.
3. **Scope**: Clarify what they want tested (full pentest vs specific category).

```
⚠️  Shannon executes REAL ATTACKS with mutative effects.
├─ Only run on systems you OWN or have WRITTEN AUTHORIZATION to test
├─ Never target production environments
├─ Results require human review — LLM output may contain hallucinations
└─ You are responsible for complying with all applicable laws
```

Display this warning BEFORE every pentest run. If the user has already confirmed authorization in this session, a brief reminder suffices.

---

## Parse User Intent

Extract from the user's input:

1. **TARGET_URL**: The URL to pentest (e.g., `http://localhost:3000`, `http://staging.example.com`)
2. **REPO_NAME**: The source code folder name (placed in `./repos/` inside Shannon)
3. **SCOPE**: Full pentest (default) or specific categories (injection, xss, ssrf, auth, authz)
4. **WORKSPACE**: Named workspace for resume capability (optional)
5. **CONFIG**: Custom YAML config path (optional, for auth flows, focus/avoid rules)

Common invocation patterns:
- `/shannon http://localhost:3000 myapp` → Full pentest of local app
- `/shannon --workspace=audit1 http://staging.example.com backend-api` → Named workspace for resuming
- `/shannon --scope=xss,injection http://localhost:8080 frontend` → Targeted categories
- `/shannon status` → Check running pentests
- `/shannon results` → Show latest report
- `/shannon stop` → Stop running pentest

Display parsed intent:
```
🔐 Shannon Pentest
├─ Target: {TARGET_URL}
├─ Source: repos/{REPO_NAME}
├─ Scope: {SCOPE or "Full (all 5 OWASP categories)"}
├─ Workspace: {WORKSPACE or "auto-generated"}
└─ Config: {CONFIG or "default"}

Estimated runtime: 1–1.5 hours │ Estimated cost: ~$50 (Claude Sonnet)
```

---

## Step 0: Ensure Shannon is Installed

Check if Shannon is cloned locally:

```bash
SHANNON_HOME="${SHANNON_HOME:-$HOME/shannon}"

if [ -d "$SHANNON_HOME" ] && [ -f "$SHANNON_HOME/shannon" ]; then
  echo "Shannon found at $SHANNON_HOME"
  cd "$SHANNON_HOME" && git pull --ff-only 2>/dev/null || true
else
  echo "Shannon not found. Cloning..."
  git clone https://github.com/KeygraphHQ/shannon.git "$SHANNON_HOME"
fi

# Verify Docker is available
if command -v docker &>/dev/null; then
  echo "Docker: $(docker --version)"
else
  echo "ERROR: Docker is required. Install Docker Desktop: https://docker.com/products/docker-desktop"
  exit 1
fi
```

If Shannon is not installed, clone it and inform the user. If Docker is missing, stop and tell them to install it.

**SHANNON_HOME** defaults to `~/shannon`. Users can override with `SHANNON_HOME` env var.

---

## Step 1: Prepare Source Code

Shannon needs the target's source code in `$SHANNON_HOME/repos/{REPO_NAME}/`.

Ask the user where their source code is:

```bash
# If user provides a local path
REPO_PATH="/path/to/their/source"
REPO_NAME="myapp"

# Create symlink or copy into Shannon's repos directory
mkdir -p "$SHANNON_HOME/repos"
if [ ! -d "$SHANNON_HOME/repos/$REPO_NAME" ]; then
  ln -s "$(realpath "$REPO_PATH")" "$SHANNON_HOME/repos/$REPO_NAME"
  echo "Linked $REPO_PATH → repos/$REPO_NAME"
fi
```

If the user provides a GitHub URL instead:
```bash
cd "$SHANNON_HOME/repos"
git clone "$GITHUB_URL" "$REPO_NAME"
```

---

## Step 2: Configure Authentication (if needed)

From CraftOS-dev/CraftBot, AGPL-3.0.

More from CraftOS-dev/CraftBot