exploit-pipeline/OPERATIONAL-PROCEDURE.md

# GreySec RED — Operational Procedure
**Product:** GreySec Exploit Development Pipeline (Reverse Engineering + Exploit Dev)
**Version:** 1.0
**Updated:** 2026-05-07
**Parent:** `~/greysec/tools/exploit-pipeline/kanban.md`

---

## What This Pipeline Is

GreySec RED is an AI-augmented reverse engineering and exploit development lab. You give it a binary and it gives you a vulnerability brief, a working exploit, and shellcode. No manual RE required.

The pipeline runs in two stages:
1. **RE Agent** — Static and dynamic analysis. Produces `analysis.md` and `struct.json`.
2. **Exploit Writer** — Takes `struct.json`, writes a pwntools exploit, tests it against the real binary.

---

## Prerequisites

Before running the pipeline, verify:

```bash
# 1. Kali container running
docker ps | grep kal

# 2. Protostar binaries present
ls /opt/protostar/bin/

# 3. MacBook Ollama reachable (for abliterator model)
curl -s http://100.127.137.64:11434/api/tags | jq '.models[].name'
# Should show: huihui_ai/qwen2.5-coder-abliterate:latest

# 4. If MacBook unreachable, cloud fallback works:
curl -s http://localhost:11434/api/tags | jq '.models[].name'
# Should show: qwen2.5-coder:14b
```

If MacBook SSH is blocked (password rejected), use cloud fallback — abliterator is better but cloud works.

---

## How to Run the Full Pipeline

### For a single binary:

```bash
cd ~/greysec/engagements/exploit-lab

# Stage 1: RE Agent
./agents/re-agent.sh <binary_name> <binary_path>
# Example: ./agents/re-agent.sh heap0 /opt/protostar/bin/heap0

# Check output
cat reports/heap0/struct.json

# Stage 2: Exploit Writer (only runs if struct.json was produced)
./agents/exploit-writer.sh <binary_name> <path_to_struct.json> <binary_path>
# Example: ./agents/exploit-writer.sh heap0 reports/heap0/struct.json /opt/protostar/bin/heap0

# Check results
cat exploits/heap0/test-results.md
```

### For all Protostar binaries at once:

```bash
cd ~/greysec/engagements/exploit-lab
for binary in stack0 stack1 format0 heap0 heap1 heap2; do
    echo "=== Processing $binary ==="
    ./agents/re-agent.sh $binary /opt/protostar/bin/$binary || continue
    ./agents/exploit-writer.sh $binary reports/$binary/struct.json /opt/protostar/bin/$binary
done
```

---

## Interpreting the Outputs

### struct.json — what each field means

| Field | What it is | Example |
|-------|-----------|---------|
| `vuln_class` | Type of vulnerability | `buffer_overflow`, `format_string`, `use_after_free` |
| `affected_function` | Function containing the bug | `vuln_function at 0x08048484` |
| `primitive` | What you can control | `write-what-where`, `code-exec` |
| `offset` | Bytes to overflow before saved return | `64` |
| `bad_chars` | Bytes that break the exploit | `["0x00", "0x0a"]` |
| `mitigations_bypass` | Which mitigations the exploit defeats | `["DEP", "NX"]` |
| `difficulty` | Complexity of the exploit | `beginner`, `intermediate`, `advanced` |
| `winner_address` | Address of the `winner()` function (Protostar) | `0x08048464` |

### test-results.md — reading the verdict

**PASS:** Exploit ran successfully. Code execution achieved. You're done.

**FAIL (offset):** Exploit crashed. The offset in struct.json might be wrong, or bad chars are breaking the payload. Review the disasm and recalculate.

**FAIL (SIGSEGV):** The exploit wrote to a bad address. ASLR might be active and you need a leak or a ROP chain. Check if the binary has PIE enabled.

**FAIL (timeout):** Exploit hung. It might be waiting for input it won't receive, or the shellcode might be trying to connect back to a non-existent host.

---

## Troubleshooting

### Problem: re-agent.sh exits with code 1

**Symptoms:** Script fails immediately after disassembly step.

**Diagnosis:**
```bash
# Check what was produced
ls -la reports/<binary_name>/

# If struct.json is missing:
cat reports/<binary_name>/struct.json.raw.md | head -100
# This is the raw LLM output — check if struct.json was generated but malformed
```

**Fix:** If the LLM didn't produce valid struct.json, the model may have failed. Check if MacBook Ollama is reachable. If not, the cloud fallback ran — results may be lower quality.

---

### Problem: struct.json has wrong offset

**Symptoms:** Exploit fails with SIGSEGV even though struct.json looks reasonable.

**Diagnosis:**
```bash
# Check the disassembly
cat reports/<binary_name>/disasm.txt | grep -A5 -B5 "vuln"

# For stack buffer overflows: count bytes to saved return address
# For heap: understand chunk size and free() metadata layout
```

**Fix:** Manually verify the offset against the disasm. Edit struct.json with the correct value, then re-run exploit-writer.sh.

---

### Problem: MacBook Ollama unreachable

**Symptoms:** `curl http://100.127.137.64:11434/api/tags` times out.

**Fix:** Use cloud fallback — the script automatically falls back to `qwen2.5-coder:14b` via localhost:11434 when MacBook is unreachable. Results are slightly lower quality but functional.

**Long-term fix (Adam's decision):**
- Option A: Fix SSH password on MacBook
- Option B: Use Tailscale SSH (passwordless)
- Option C: Copy abliterator model to Linux Ollama

---

### Problem: heap0 RE Agent still failing

**Symptoms:** re-agent.sh produces analysis.md but no struct.json.

**Diagnosis:** heap0 requires understanding heap chunk metadata. The model may not have produced valid struct.json on the first pass.

**Fix:**
```bash
# Manually provide the known-correct struct.json for heap0:
cat > reports/heap0/struct.json << 'EOF'
{
  "binary": "heap0",
  "arch": "x86",
  "vuln_class": "heap_corruption",
  "affected_function": "get_permission (0x08048484)",
  "primitive": "write-what-where",
  "offset": 80,
  "bad_chars": ["0x00"],
  "mitigations_bypass": ["DEP", "NX"],
  "difficulty": "beginner",
  "winner_address": "0x08048464",
  "next_steps": [
    "Overflow the 64-byte heap buffer",
    "Overwrite chunk->next pointer",
    "Trigger free() to write to arbitrary location",
    "Overwrite winner GOT entry with winner() address"
  ]
}
EOF

# Now run exploit-writer.sh directly
./agents/exploit-writer.sh heap0 reports/heap0/struct.json /opt/protostar/bin/heap0
```

---

### Problem: exploit.py runs but doesn't get shell

**Symptoms:** Exploit exits 0 but no shell. Partial success.

**Diagnosis:** The exploit may be hitting the right function but not getting code execution. Check:
- Is ASLR enabled on the host? (`cat /proc/sys/kernel/randomize_va_space`)
- Does the exploit need a ROP chain instead of direct return address overwrite?
- Are bad chars correctly excluded from the payload?

**Fix:** Review the test-output.txt and adjust struct.json fields. Re-run exploit-writer.sh.

---

## Escalation Path

**Ping @Adam if:**
1. MacBook Ollama has been unreachable for more than 24 hours
2. All three Protostar beginner binaries fail (stack0, stack1, format0) — this means the pipeline itself is broken
3. You have spent more than 2 hours on a single binary without progress
4. The abliterator model quality is consistently worse than expected

**Before escalating:**
- Document what was tried
- Note which step failed (RE Agent / Exploit Writer / test loop)
- Note the model used (abliterator or cloud fallback)

---

## How to Add New Binary Targets

1. **Copy the binary** to `/tmp/lab_binaries/<target_name>` inside the Kali container, or mount it from the host.

2. **Run the pipeline:**
   ```bash
   ./agents/re-agent.sh <target_name> /path/to/target
   ./agents/exploit-writer.sh <target_name> reports/<target_name>/struct.json /path/to/target
   ```

3. **If the target is Windows:**
   - Set up a Windows VM analysis path (V2 roadmap)
   - Change architecture detection from `file` output to PE header parsing
   - Use Windows-specific shellcode (msfvenom: `windows/meterpreter/reverse_tcp`)

4. **If the target is ARM:**
   - Use ARM-specific pwntools (`context.arch = 'arm'`)
   - Use ARM shellcode (`msfvenom -p linux/arm/shell_reverse_tcp -f raw -a arm`)
   - Note in struct.json that ARM analysis takes longer

---

## Agent Scripts Reference

### re-agent.sh

**Input:** Binary name + path
**Output:**
- `reports/<binary>/analysis.md` — full RE brief
- `reports/<binary>/struct.json` — structured vulnerability data
- `reports/<binary>/disasm.txt` — rizin disassembly
- `reports/<binary>/functions.txt` — function list
- `reports/<binary>/checksec.txt` — mitigation status
- `reports/<binary>/strings.txt` — interesting strings

**Exit codes:**
- `0` — success, struct.json produced
- `1` — failure (model error, missing output, validation failed)

**Hooks:**
- On success: logs to gbrain + TIME-LOG
- On failure: writes raw LLM output to `struct.json.raw.md` for manual review

### exploit-writer.sh

**Input:** Binary name + struct.json path + binary path
**Output:**
- `exploits/<binary>/exploit.py` — working pwntools exploit
- `exploits/<binary>/shellcode.bin` — raw shellcode
- `exploits/<binary>/test-results.md` — test verdict with output

**Exit codes:**
- `0` — success, exploit PASSED
- `1` — failure (struct.json missing, exploit FAILED)

**Hooks:**
- On success: logs to gbrain + TIME-LOG
- On failure: writes `test-output.txt` with raw output for debugging