# Novelty

**Burp inside your AI harness.** An MCP security toolkit that plugs into your
coding agent — Claude Code, Codex, OpenCode — and hunts real vulnerabilities in
**web apps and source code**.

Add it once and your agent gains a Burp-style HTTP proxy (Repeater + Logger),
an AI-driven vulnerability hunt, a whole-file source auditor, and a
disposable-inbox helper for testing authenticated flows. Every finding is
**reasoned on Claude**, not matched by a regex.

Novelty weights the classes that actually pay out:
**BOLA/IDOR · BFLA · XSS · SQLi · business logic · RCE · broken auth.**

## The brain

The reasoning layer runs on the official **Anthropic SDK** with **intelligent
routing** — default **`claude-opus-4-6`**, and for a 5-family model an automatic
server-side fallback to **`claude-opus-4-8`** so a cyber-safeguard refusal on an
authorized assessment still completes. Swap the model with one env var
(`ANTHROPIC_MODEL`).

## Install (works in any MCP harness)

Novelty ships as a package — no clone, no venv. `uvx` downloads and runs it. You
only need [`uv`](https://docs.astral.sh/uv/) installed and your `ANTHROPIC_API_KEY`.

The one command every harness runs under the hood:

```bash
uvx --from git+https://github.com/GOJO-SENPA1/novelty.git novelty-mcp
```

**Claude Code** (one-liner):

```bash
claude mcp add novelty --env ANTHROPIC_API_KEY=sk-ant-YOUR_KEY_HERE \
  -- uvx --from git+https://github.com/GOJO-SENPA1/novelty.git novelty-mcp
```

**Codex** — add to `~/.codex/config.toml`:

```toml
[mcp_servers.novelty]
command = "uvx"
args = ["--from", "git+https://github.com/GOJO-SENPA1/novelty.git", "novelty-mcp"]
env = { ANTHROPIC_API_KEY = "sk-ant-YOUR_KEY_HERE" }
```

**OpenCode** — add to `opencode.json`:

```json
{
  "mcp": {
    "novelty": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/GOJO-SENPA1/novelty.git", "novelty-mcp"],
      "environment": { "ANTHROPIC_API_KEY": "sk-ant-YOUR_KEY_HERE" },
      "enabled": true
    }
  }
}
```

**Cursor / Claude Desktop / Windsurf / Cline** — add to the harness's `mcp.json`:

```json
{
  "mcpServers": {
    "novelty": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/GOJO-SENPA1/novelty.git", "novelty-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-YOUR_KEY_HERE" }
    }
  }
}
```

Then just ask your agent: *"use novelty to hunt example.com and write a report"*, or
*"review this file with novelty"*.

> No `uv`? Install with `curl -LsSf https://astral.sh/uv/install.sh | sh`, or
> swap `uvx` for `pipx run --spec git+https://github.com/GOJO-SENPA1/novelty.git novelty-mcp`.

### Tools (31)

| Group | Tools |
|-------|-------|
| **Plan** | `plan` (tailored phased hunt plan, memory-aware), `methodology` (load a playbook) |
| **Scope** | `scope_set`, `scope_show` — authorization allowlist, enforced across traffic tools |
| **Recon** | `recon`, `param_discover`, `secrets_hunt` |
| **Hunt** | `hunt`, `http_send`, `http_replay`, `http_history`, `http_get`, `intruder`, `bypass_hunter` |
| **Source** | `review_code`, `review_file` |
| **Analyst** | `arsenal` (bypass helper), `chain`, `triage` |
| **Report** | `report_web`, `report_source`, `report` |
| **Memory** | `recall`, `pickup`, `remember`, `memory_index`, `memory_sources`, `hunt_log` |
| **Auth** | `mail_new`, `mail_inbox` |
| **Meta** | `health` |

### Memory

Novelty remembers across sessions. It keeps its **own** writable store at
`~/.novelty/memory/` (target dossiers + wins, plus the append-only `hunt-log.jsonl`,
secrets redacted), and **connects your existing memory read-only** — auto-discovered
Claude project-memory dirs and a `~/tools/bugbounty` workspace (curate the exact list
in `~/.novelty/sources.json`).

- **`recall`** searches everything (own + connected), deduped.
- **`pickup(target)`** merges every layer about a target — prior dossiers, hunt-log,
  audit entries — so you resume a hunt cold; `plan` auto-loads it.
- **`remember`** writes a new dossier note / win to Novelty's own store (never your
  connected files); **`memory_sources`** connects/disconnects sources.

Point Novelty at a target and it already knows what you found last time.

## Autopilot harness — `novelty hunt`

Novelty is an MCP, so it runs inside any harness. It also ships its **own** — a
Claude-Code-class hunting cockpit built on the **Claude Agent SDK** (Claude Code's
engine as a library, so we don't rebuild the loop/context/subagents):

```bash
# install globally (needs uv + Node.js + the `claude` CLI):
uv tool install "novelty-mcp[harness] @ git+https://github.com/GOJO-SENPA1/novelty.git"
export ANTHROPIC_API_KEY=sk-ant-YOUR_KEY    # the MCP brain's key (the harness itself uses your `claude` login)
novelty-hunt http://target --budget 100     # one governed, autonomous hunt
```

(`pipx install "novelty-mcp[harness] @ git+…"` works too. Plain `pip install` fails on
externally-managed systems like Arch, and the package isn't on PyPI — install from git.)

It runs the whole hunt end to end and **owns the impact + severity call**, calibrated
by memory of what your past reports landed at — you're the reviewer who counters:

- **Doctrine as system prompt** → hunts like a senior operator, not a scanner.
- **Scope-gated & non-destructive** — `scope_set` first, and the autopilot toolset omits
  Bash/Write/exec entirely; it runs on Novelty's own scope-guarded tools.
- **Hard `$` budget cap** (`--budget`, default $100) — the SDK's native `max_budget_usd`
  stops the loop at the cap; live cost is printed.
- **Memory-driven** — `pickup` at start, findings auto-save, your severity counters feed
  back into memory so its judgement sharpens over time.

The MCP stays usable in Claude Code / Codex / Cursor too — the harness is just a dedicated cockpit.

### The mind — methodology + arsenal

Novelty carries a senior operator's playbooks, shipped in the package and consulted
by the brain. `plan` fingerprints a target and lays out a phased hunt — naming the
exact tool to drive at each step: Novelty's own tools, **Claude-in-Chrome** for
browser-only work (SPA/JS mining, DOM-XSS proof, network-waterfall capture,
authenticated surface mapping, console-secrets), and CLI recon
(`subfinder`/`httpx`/`katana`/`jsluice`/`nuclei`) where the harness has it. `methodology`
loads any playbook:

| Page | What it is |
|------|------------|
| `doctrine` | the hunting law — scope, impact bar, negative controls, honest severity |
| `recon-methodology` | nothing → mapped attack surface (JS-mining first) |
| `pentest-catalogue` | systematic sweep of every web vuln category, with FP-killers |
| `vuln-classes` | per-class encyclopedia: root cause → test → confirm → report |
| `hackerone-patterns` | what actually lands per bug type (from disclosed reports) |
| `reporting-and-triage` | the 7-question gate + impact-first report craft |
| `chaining` | combine findings into higher-impact chains |
| `bypass-hunter` | exhaust every control bypass before walking |

Plus the **arsenal** — a HackTricks-style bypass library across 9 vuln classes,
auto-primed into every hunt and pulled by `arsenal` / `bypass_hunter` when a control blocks you.

### Memory & arsenal

Novelty ships a persistent brain modelled on a real bug-bounty workspace:

- **`arsenal/`** — a HackTricks-style bypass/technique reference per class (SQLi,
  XSS, IDOR/BOLA/BFLA, auth/JWT, RCE/SSTI, SSRF, traversal/LFI/upload, business
  logic/race, WAF bypass). The `arsenal` tool pulls a page when a hunt is blocked
  by a control, and its cues auto-prime the hunt brain.
- **hunt log** — `recon`/`hunt`/`report` append milestones (`~/.novelty/hunt-log.jsonl`,
  secrets scrubbed); `hunt_log`/`remember` read and add to it so a later session picks up.
- **doctrine** — an impact-first, non-destructive, chain-relentlessly creed baked into every AI prompt.

### Reports

`report_web`, `report_source`, and `report` turn findings into a polished
security-assessment report — an AI-written executive summary, an overall risk
rating, a severity tally, and per-finding detail (exploitation, impact, evidence,
a non-destructive confirm step, and remediation). You get clean **Markdown** back,
and passing `save_html` writes a self-contained, print-ready **HTML** report in the
Novelty aesthetic. `report` builds a report from findings you already collected
(e.g. `hunt` output plus your own `http_send`/`intruder` evidence).

## Run the site / API locally

The product is the MCP server. The Flask app just serves the product page and a
health check the page reads for the live brain badge.

```bash
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env        # paste your key into ANTHROPIC_API_KEY
python app.py               # serves the showcase page on http://127.0.0.1:5000
```

## Deploy

The static product page (`frontend/`) deploys to **Netlify** — see
**[DEPLOY.md](DEPLOY.md)**. The MCP server and its brain run locally beside your
agent; nothing about your traffic or code leaves the machine except the model calls.

## ⚠ Authorized use only

Point these tools at targets you **own** or have **explicit, written permission**
to test. They are non-destructive and do **not** defeat CAPTCHAs or bot-detection.
Secrets are never stored or logged.