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:

# 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:

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:

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:

# 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:

# 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:

# 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:

   ./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