Multi-Agent System

​

Agent Architecture

​

Agent Definition Format

---
name: crash-analysis-agent
description: Analyze security bugs from C/C++ projects with full root-cause tracing
tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, Git, Task
model: inherit
skills: rr-debugger, function-tracing, gcov-coverage
---

​

The 17 Specialized Agents

​

Crash Analysis Agents

​

crash-analysis-agent

1. Fetch bug report from tracker URL
2. Clone repository to ./repo-<project-name>
3. Create working directory ./crash-analysis-<timestamp>/
4. Understand build system (autotools, CMake, Makefile, meson)
5. Rebuild with instrumentation (AddressSanitizer, debug symbols)
6. Reproduce the crash
7. Generate execution trace (function-level)
8. Generate coverage data (gcov)
9. Create RR recording for deterministic replay
10. Invoke crash-analyzer agent for root-cause analysis
11. Validate analysis with crash-analyzer-checker agent
12. Write confirmed hypothesis

​

crash-analyzer-agent

• Analyze rr deterministic replay traces
• Examine function execution traces
• Review coverage data
• Form hypotheses about root cause
• Write hypothesis to root-cause-hypothesis-YYY.md

​

crash-analyzer-checker-agent

• Review hypothesis against evidence
• Check for logical inconsistencies
• Verify claims against actual code
• Write rebuttal file if hypothesis rejected
• Iterate until validated (max 3 iterations)

​

function-trace-generator-agent

• Instruments code with -finstrument-functions
• Captures function entry/exit events
• Generates trace files in <working-dir>/traces/

​

coverage-analysis-generator-agent

• Compiles with --coverage flags
• Runs program to generate .gcda files
• Produces coverage reports in <working-dir>/gcov/

​

OSS Forensics Agents

​

oss-investigator-gh-archive-agent

• Construct BigQuery queries for GitHub events
• Execute queries for PushEvent, PullRequestEvent, IssuesEvent, etc.
• Create evidence using GHArchiveCollector
• Track which table each event came from
• Store evidence in evidence.json

• Force push recovery (deleted commits)
• Workflow vs Direct API attribution
• Deleted tags/branches

​

oss-investigator-github-agent

• Commits, issues, pull requests
• Files, branches, tags, releases
• Forks and repository metadata

​

oss-investigator-local-git-agent

• Find dangling commits (not reachable from any ref)
• Reveal force-pushed or deleted commits
• Analyze local git history

​

oss-investigator-wayback-agent

• Archived snapshots of GitHub pages
• Historical content with date filtering
• Snapshot content retrieval

​

oss-investigator-ioc-extractor-agent

• COMMIT_SHA, FILE_PATH, FILE_HASH
• CODE_SNIPPET, EMAIL, USERNAME
• REPOSITORY, TAG_NAME, BRANCH_NAME
• WORKFLOW_NAME, IP_ADDRESS, DOMAIN
• URL, API_KEY, SECRET

​

oss-hypothesis-former-agent

• Analyze collected evidence
• Identify patterns and anomalies
• Form testable hypotheses
• Document predictions

​

oss-evidence-verifier-agent

• Run store.verify_all() on evidence
• Check for tampering or inconsistencies
• Validate against GitHub API, GH Archive, Wayback
• Report verification status

​

oss-hypothesis-checker-agent

• Review hypotheses
• Check against verified evidence
• Accept or reject based on evidence
• Document reasoning

​

oss-report-generator-agent

• Executive summary
• Evidence timeline
• Hypothesis validation results
• Forensic conclusions
• IOCs and recommendations

​

Exploitability Validation Agent

​

exploitability-validator-agent

• Enumerate all files in target path
• Exclude test/mock files
• Extract functions per file
• Write checklist.json

• Assess each function for vulnerability type
• Attempt PoC for candidates
• Write findings.json
• Route based on findings

• Build attack trees
• Form and test hypotheses
• Track PROXIMITY
• Attempt multiple attack paths
• Update working documents

• Verify files exist
• Verify code matches verbatim
• Verify flow is real
• Verify code is reachable

• Check for test/mock/example code
• Check for unrealistic preconditions
• Check for hedging language
• Write CONFIRMED findings

• Applies to memory corruption only
• Run analyze_binary() from exploit_feasibility package
• Save context with save_exploit_context()
• Update finding with feasibility verdict

​

Offensive Security Specialist

​

offsec-specialist

• Penetration testing methodology
• Exploit development guidance
• Attack surface analysis
• Security research techniques

​

Skills System

​

Crash Analysis Skills

​

rr-debugger

# Record
rr record <program> [args]

# Replay (enters gdb interface with reverse execution)
rr replay

• reverse-next / rn - Step back over function calls
• reverse-step / rs - Step back into functions
• reverse-continue / rc - Continue backward to previous breakpoint
• reverse-stepi / rsi - Step back one instruction

​

function-tracing

• trace_instrument.c - Instrumentation callbacks
• trace_to_perfetto.cpp - Convert traces to Perfetto format

gcc -finstrument-functions -g program.c trace_instrument.c -o program
./program
# Generates trace.txt with function entry/exit events

​

gcov-coverage

gcc --coverage -g program.c -o program
./program
gcov program.c
# Generates program.c.gcov with line execution counts

​

line-execution-checker

​

OSS Forensics Skills

​

github-evidence-kit

from src.collectors import GitHubAPICollector, LocalGitCollector, GHArchiveCollector

# GitHub API
github = GitHubAPICollector()
commit = github.collect_commit("owner", "repo", "sha")
pr = github.collect_pull_request("owner", "repo", 123)

# Local git (forensic gold!)
local = LocalGitCollector("/path/to/repo")
dangling = local.collect_dangling_commits()  # Force-pushed commits

# GH Archive
archive = GHArchiveCollector()
events = archive.collect_events(timestamp="202507132037", repo="owner/repo")

• Events: PushEvent, PullRequestEvent, IssueEvent, etc.
• Observations: CommitObservation, IssueObservation, FileObservation, etc.
• IOCs: Indicators of Compromise with source verification

from src import EvidenceStore

store = EvidenceStore.load("evidence.json")
is_valid, errors = store.verify_all()

​

github-archive

​

github-commit-recovery

• Query GH Archive for force push events
• Extract deleted commit SHAs from payload.before
• Reconstruct commit metadata

​

github-wayback-recovery

• Query Wayback CDX API for snapshots
• Retrieve archived content
• Extract historical state

​

Exploitability Validation Skill

​

exploitability-validation

models:
  native: true
  additional: false  # Set true to also run GPT, Gemini

output_when_additional:
  display: "agreement: 2/3"
  threshold: "1/3 is enough to proceed"

1. GATE-1 [ASSUME-EXPLOIT]: Assume exploitable until proven otherwise
2. GATE-2 [STRICT-SEQUENCE]: Strictly follow instructions
3. GATE-3 [CHECKLIST]: Check pipeline, update checklist, collect evidence
4. GATE-4 [NO-HEDGING]: Verify all uncertain claims immediately
5. GATE-5 [FULL-COVERAGE]: Test entire codebase against checklist.json
6. GATE-6 [PROOF]: Always provide proof and show vulnerable code

• attack-tree.json - Knowledge graph, source of truth
• hypotheses.json - Active hypotheses with status
• disproven.json - Failed hypotheses and why
• attack-paths.json - Paths attempted, PoC results, PROXIMITY, blockers
• attack-surface.json - Sources, sinks, trust boundaries

from packages.exploit_feasibility import analyze_binary, save_exploit_context

result = analyze_binary(binary_path, vuln_type='format_string')
context_file = save_exploit_context(binary_path)

# Verdict: Likely, Difficult, Unlikely
# chain_breaks: What won't work
# what_would_help: What might work

​

Exploit Development Skill

​

exploit-dev

• Exploit code templates by vulnerability type
• Constraint checking (ASLR, DEP, stack canaries, etc.)
• Technique alternatives when standard approaches blocked
• Environment recommendations (Docker, older glibc)

​

Agent Orchestration Patterns

​

Sequential Orchestration

# Phase 1: Scan
scanner.run(repo_path)

# Phase 2: Analyze
analysis = llm_analyzer.analyze(findings)

# Phase 3: Generate exploits
for finding in analysis:
    exploit = exploit_generator.generate(finding)

​

Parallel Agent Invocation

# Launch multiple investigators in parallel
agents = [
    Task("oss-investigator-gh-archive-agent", query),
    Task("oss-investigator-github-agent", query),
    Task("oss-investigator-local-git-agent", query)
]

# Collect results
for agent in agents:
    evidence.extend(agent.results)

​

Iterative Refinement

max_iterations = 3
for i in range(max_iterations):
    hypothesis = crash_analyzer.analyze(crash_data)
    validation = checker.validate(hypothesis)

    if validation.accepted:
        break

    # Refine based on rebuttal
    crash_data.add_feedback(validation.rebuttal)

​

Agent Usage Examples

​

Crash Analysis

# Via raptor.py
/crash-analysis https://bugs.project.org/1234 https://github.com/project/repo

# Direct agent invocation
claude-code .claude/agents/crash-analysis-agent.md \
  --bug-url https://bugs.project.org/1234 \
  --repo-url https://github.com/project/repo

​

OSS Forensics

# Via raptor.py
/oss-forensics "Investigate Amazon Q PR #7710" --max-followups 3

# Output: .out/oss-forensics-<timestamp>/forensic-report.md

​

Exploitability Validation

# Via raptor.py
/validate /path/to/webapp --vuln-type command_injection

# Direct agent invocation
claude-code .claude/agents/exploitability-validator-agent.md \
  /path/to/binary --vuln-type format_string

# Output: .out/exploitability-validation-<timestamp>/validation-report.md

​

Benefits of Multi-Agent Architecture

1. Specialization: Each agent focuses on one specific task
2. Reusability: Skills can be shared across multiple agents
3. Parallelization: Independent agents can run in parallel
4. Testability: Each agent can be tested in isolation
5. Extensibility: New agents can be added without modifying existing ones
6. Clarity: Clear separation of concerns and responsibilities