Framework Overview
RALPH (Rapid Autonomous Lab Protocol Handler) + GAIT (Git-Aware Iterative Tasking) enables fully autonomous Red and Blue teams competing in chaos engineering exercises with complete audit trails.
System Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β REFEREE (Orchestrator) β
β β
β 1. Restores baseline between rounds 4. Captures evidence at each phase β
β 2. Updates PROMPT.md with specs 5. Scores results β
β 3. Launches RALPH autonomous loops 6. Documents outcomes β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β β
β scripts/run-round.sh β
βΌ βΌ
ββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββ
β ralph-red/ β β ralph-blue/ β
β (Autonomous Attacker) β β (Autonomous Defender) β
β β β β
β βββ PROMPT.md (attack) β β βββ PROMPT.md (NOC ticket) β
β βββ @AGENT.md (identity) β β βββ @AGENT.md (identity) β
β βββ @fix_plan.md (tasks) β βββββββΊ β βββ @fix_plan.md (tasks) β
β βββ expert-catalog.json β creates β βββ diagnostic-playbook.md β
β βββ status.json β ticket β βββ status.json β
ββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββ
β β
β SSH to ContainerLab β SSH to ContainerLab
βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ContainerLab Server () β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β 18 Arista cEOS 4.35.1F Nodes β β
β β RR: RR1, RR2 β Core: P1-P4 β PE: PE1-PE6 β CE: CE1-CE6 β β
β β VRFs: ALPHA (65000:100), BETA (65000:200), GAMMA (65000:300) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Project Structure
projects/ralph-red-vs-blue-v4/
βββ ralph-red/ # Red Team autonomous agent
β βββ PROMPT.md # Per-round attack specification
β βββ @AGENT.md # Agent identity & instructions
β βββ @fix_plan.md # GAIT task tracking
β βββ expert-catalog.json # All 15 expert attacks
β βββ status.json # RALPH loop state
β
βββ ralph-blue/ # Blue Team autonomous agent
β βββ PROMPT.md # Per-round NOC ticket
β βββ @AGENT.md # Agent identity & instructions
β βββ @fix_plan.md # GAIT task tracking
β βββ diagnostic-playbook.md # Troubleshooting procedures
β
βββ rounds/ # Per-round evidence
β βββ round-XX/
β βββ noc-ticket.md # NOC ticket for Blue
β βββ red-attack.log # RALPH-Red execution log
β βββ blue-diagnosis.log # RALPH-Blue execution log
β βββ summary.md # Round results
β βββ evidence/
β βββ baseline-state/
β βββ post-attack-state/
β βββ post-fix-state/
β
βββ scripts/
β βββ run-round.sh # Full round orchestration
β βββ restore-baseline.sh # Reset lab to known-good
β βββ capture-evidence.sh # Snapshot network state
β
βββ topology/ β symlink # Lab definition
GAIT Iron Laws
1
NO NETWORK CHANGES WITHOUT A GIT BRANCH
2
NO ACTIONS WITHOUT COMMITS
3
NO CHANGES WITHOUT VERIFICATION
4
NO COMPLETION WITHOUT SUMMARY
Agent Configuration Files
| File |
Purpose |
PROMPT.md |
Per-round task instructions (attack spec or NOC ticket) |
@AGENT.md |
Agent identity, role, and execution instructions |
@fix_plan.md |
GAIT task tracking with checkboxes |
status.json |
RALPH loop state (calls, status, exit reason) |
progress.json |
Iteration progress for resume capability |
GAIT Commit Types
| Prefix |
Purpose |
gait: |
RALPH loop iteration marker |
baseline: |
State verification before changes |
attack: |
Red team action executed |
fix: |
Blue team correction applied |
complete: |
Round finished successfully |
Per-Round GAIT Workflow
Round N Start
β
βββΊ git checkout -b round-N-<attack-name>
β
βββΊ [RALPH-Red starts]
β βββΊ gait: Loop #1 - starting
β βββΊ attack: <action taken>
β βββΊ gait: Loop #1 - EXIT_SIGNAL
β
βββΊ capture-evidence.sh post-attack
β βββΊ baseline: post-attack state captured
β
βββΊ [RALPH-Blue starts]
β βββΊ gait: Loop #1 - starting
β βββΊ fix: <diagnosis and fix>
β βββΊ gait: Loop #1 - EXIT_SIGNAL
β
βββΊ capture-evidence.sh post-fix
β βββΊ complete: Round N - <WINNER>
β
βββΊ Baseline restored for next round
Evidence Capture System
Three Phases per Round
./scripts/capture-evidence.sh <round> baseline # Before attack
./scripts/capture-evidence.sh <round> post-attack # After Red
./scripts/capture-evidence.sh <round> post-fix # After Blue
Evidence Files Captured
connectivity.txt |
VRF ping tests (CEβCE) |
isis-adjacencies.txt |
ISIS neighbor state |
bgp-summary.txt |
BGP session state |
mpls-lfib.txt |
MPLS label tables |
vrf-routes.txt |
VRF routing tables |
RALPH Loop Execution
Each agent runs in autonomous loop mode: ralph --monitor --timeout 15
Loop Mechanics
1. Read PROMPT.md
2. Execute SSH commands
3. Log to @fix_plan.md
4. GAIT commit
5. Check EXIT_SIGNAL
Exit Conditions
β’ EXIT_SIGNAL: true
β’ 2+ completion indicators
β’ Timeout (10-15 min)
β’ Manual abort (Ctrl+C)
Status Tracking
β’ loop_count: iterations
β’ calls_made_this_hour
β’ last_action: graceful_exit
β’ status: completed
Baseline Restore Process
# Between each round, restore-baseline.sh:
DEVICES=("rr1" "rr2" "p1" "p2" "p3" "p4" "pe1" "pe2" "pe3" "pe4" "pe5" "pe6")
1. Copy golden baseline configs to remote server
2. Apply configs to all 12 cEOS devices via configure replace
3. Wait 15 seconds for protocol convergence
4. Verify all 3 VRFs pass connectivity tests
Expert Attack Catalog (expert-catalog.json)
| Category |
Count |
Attack Types |
| Multi-Layer |
3 |
Triple-Layer, Cross-VRF Route Leak, Policy+Decoy |
| Misdirection |
3 |
One-Way ACL, Metric Maze, Community Strip |
| Policy |
3 |
Route-Map Swap, RCF Inversion, BGP Policy Inversion |
| SR-MPLS |
2 |
SRGB Mismatch, Anycast SID Conflict |
| Intermittent |
2 |
MTU Black Hole, ISIS Metric Oscillation |
| VRF/RT |
1 |
Multi-VRF RT Cascade |
Forbidden Attacks (Too Easy)
interface shutdown on CE-facing interfaces
neighbor X.X.X.X shutdown (BGP session shutdown)
no redistribute connected
no isis enable CORE alone