# ZeroForge

**An adaptive binary-0day research brain that sits on top of [HexStrike AI](https://github.com/0x4m4/hexstrike-ai).**

HexStrike is an excellent *executor*: 150+ security tools wrapped behind an HTTP
API and MCP. But it is **stateless** — every tool returns raw text to the LLM
and the target model is forgotten the moment the call returns, and its "decision
engine" is a hard-coded effectiveness table that never adapts.

ZeroForge adds the part that was missing: **memory and reasoning.**

```
   ┌── LLM (Claude via MCP) ──┐
   │   reasons & decides       │
   └────────────┬──────────────┘
                │  small stateful verbs (zf_ingest / zf_plan / zf_assess …)
        ┌───────▼─────────┐
        │   ZeroForge     │   persistent knowledge graph  (SQLite)
        │   • model       │   adaptive planner (state → ranked actions)
        │   • planner     │   action log (never repeat work)
        └───────┬─────────┘
                │  executes via …
     ┌──────────▼───────────┐        ┌───────────────┐
     │  HexStrike /api/tools │  or →  │ local tools   │  (fallback if HS down)
     └──────────────────────┘        └───────────────┘
```

## Why it's more powerful than raw HexStrike

| | HexStrike | ZeroForge |
|---|---|---|
| Target model | none — raw tool text per call | **persistent knowledge graph** that accumulates across runs |
| Tool selection | static effectiveness table | **adaptive planner** reacting to discovered facts |
| Repeated work | re-runs freely | **action log dedup** — never repeats a completed step |
| Reasoning | in the LLM only, each turn cold | LLM + a growing state it can query |
| Backend | its own wrappers | **reuses HexStrike**, with local fallback |

## Install

```bash
python3 -m pip install requests            # only hard dep for the core
# MCP mode additionally needs fastmcp (already in the HexStrike venv)
```

## Use — CLI

```bash
python3 -m zeroforge.cli ingest ./target      # characterize + enumerate + gadgets
python3 -m zeroforge.cli assess               # narrative state
python3 -m zeroforge.cli plan                 # ranked next actions + rationale
python3 -m zeroforge.cli exploit ./target     # autonomous ret2win -> real shell
python3 -m zeroforge.cli show sink            # dump graph nodes
python3 -m zeroforge.cli log                  # what has already run
```

### Autonomous exploitation (proven end-to-end)

Against a no-canary stack overflow with a `win()`/`system("/bin/sh")` function,
`zeroforge exploit` runs the whole chain by itself — no offsets hard-coded:

```
[*] Attempting autonomous ret2win on ./vuln_test
    detail: ret2win -> win@0x401166 offset=72 align_ret=0x401016
[+] EXPLOIT SUCCESSFUL — code execution proven:
      | ZEROFORGE_PWNED_1000
      | uid=1000(benny) gid=1000(benny) groups=1000(benny),...
[+] Reproducible exploit written to: ./vuln_test.zeroforge_exploit.py
```

It (1) detects the input vector from the discovered sinks, (2) computes the
saved-RIP offset by crashing the target under GDB with a cyclic pattern,
(3) locates a win/`system` function, (4) builds a stack-aligned payload and
(5) runs the binary to obtain a shell — then records `GOAL ACHIEVED: shell`
into the knowledge graph and emits a standalone pwntools script.
`tests/test_exploit.py` compiles a fresh target and asserts the shell.

Example against a `scanf`/`strcpy`/`system("/bin/sh")` binary with no canary:

```
[ 98] Trace reachability to system()/popen() (exploit)
       ↳ system()/popen() present and a /bin/sh string exists — likely a one-shot command-injection path.
[ 93] Dynamically confirm stack overflow (offset) (exploit)
       ↳ Unbounded copy sink present. No stack canary → saved-return overwrite is viable.
[ 82] Probe format-string primitive (exploit)
       ↳ Non-constant format sink present → test for arbitrary read/write & leaks.
```

## Use — MCP (drive it from Claude)

Point your MCP client at `zeroforge.mcp_server`. Verbs: `zf_ingest`,
`zf_plan`, `zf_assess`, `zf_show`, `zf_note`, `zf_run_hexstrike`.

```jsonc
{
  "mcpServers": {
    "zeroforge": {
      "command": "/home/you/hexstrike-ai/hexstrike-env/bin/python",
      "args": ["-m", "zeroforge.mcp_server"],
      "env": { "ZEROFORGE_DB": "engagement.db", "HEXSTRIKE_URL": "http://localhost:8888" }
    }
  }
}
```

## Status

v0.2 — working core: knowledge graph, triage capabilities (file/checksec/sinks/
strings/ROP gadgets), adaptive planner, CLI, MCP server (7 verbs incl.
`zf_exploit`), and **autonomous ret2win exploitation proven end-to-end**.
Roadmap: ret2libc / full ROP chaining, format-string primitive, taint-based
reachability (angr), fuzzing orchestration + crash triage, agentic run-loop.

## Legal

For authorized security research, CTFs and pentesting engagements only. You are
responsible for having permission to test any target.