CTF-Sandbox-Orchestrator Scenario Structure: A Complete Guide to Modular CTF Routing

The CTF-Sandbox-Orchestrator uses a hierarchical, plug-in architecture with a master orchestrator that routes to competition-specific skills, each defined in a structured SKILL.md file with YAML metadata, workflow steps, and fallback clauses.

The CTF-Sandbox-Orchestrator is the core routing engine in the zhaoxuya520/reverse-skill repository that enables systematic analysis of Capture-the-Flag (CTF) challenges. Understanding the CTF-Sandbox-Orchestrator scenario structure is essential for extending the framework or troubleshooting routing decisions. This guide breaks down the layered architecture, file conventions, and execution flow based on the actual source implementation.

Core Architecture Layers

The CTF-Sandbox-Orchestrator implements four distinct layers that separate concerns between routing logic and challenge-specific workflows.

Layer	Purpose	Primary File Location
Master Orchestrator	Establishes sandbox context, parses user intent, and selects downstream skills	CTF-Sandbox-Orchestrator/ctf-sandbox-orchestrator/SKILL.md
Competition Skills	Concrete implementations for specific challenge types (ZIP, mobile, web, kernel)	CTF-Sandbox-Orchestrator/competition-<type>/SKILL.md
Reference Documents	Decision tables, evidence checklists, and background research	CTF-Sandbox-Orchestrator/*/references/*.md
Routing Configuration	JSON matrix mapping keywords to skill names	skills/config/routing.json

This separation allows analysts to add new challenge types without modifying the master orchestrator logic.

Master Orchestrator: The Entry Point

The ctf-sandbox-orchestrator/SKILL.md file serves as the universal entry point for all CTF sandbox analyses. According to the source code, it performs three critical operations:

• Establishes sandbox context — defines network profile, evidence priorities, and workspace isolation
• Parses user prompts — extracts keywords and tool hints for matching against the routing matrix
• Passes execution context — loads the selected competition skill and provides the current workspace directory

The orchestrator follows a strict initialization requirement. Before any skill executes, the case initialization script must run:

# Required: Initialize case workspace before orchestrator invocation

powershell -File skills/scripts/case-init.ps1 -Hint "zip-archive challenge"

# Execute master orchestrator with routing hint

powershell -NoProfile -ExecutionPolicy Bypass `
    -File skills/scripts/master-route.ps1 -Hint "encrypted zip with known-plaintext"

The master-route.ps1 script internally consults skills/config/routing.json to resolve the hint to a concrete skill path.

Competition Skill Structure

Each CTF-Sandbox-Orchestrator scenario skill follows a standardized template with six mandatory sections. Examining CTF-Sandbox-Orchestrator/competition-zip-archive/SKILL.md reveals this pattern.

1. YAML Header

Every SKILL.md begins with frontmatter defining identity:

name: competition-zip-archive
description: Analyze and exploit ZIP archive challenges including encryption, known-plaintext attacks, and compression artifacts

The master orchestrator reads these fields to display the selected path to the analyst.

2. Invocation Preconditions

A warning paragraph specifies when the skill is appropriate:

"Use only after $ctf-sandbox-orchestrator has established sandbox assumptions. Do not invoke directly without initialized workspace."

3. Workflow Steps

Numbered steps (typically 1-4) guide evidence collection through verification:

1. Collect archive metadata and compression signatures
2. Identify encryption type and key derivation method
3. Execute exploitation with pinned tool versions
4. Verify extracted flags against expected formats

4. Tool-Setup Block

Reproducible environment setup with version-pinned binaries:

# Bootstrap bkcrack for known-plaintext ZIP attacks

winget install bkcrack --version 1.5.0

5. Evidence Preservation Checklist

Bullet list of audit artifacts:

• SHA-256 hashes of original and modified archives
• Full CLI output from extraction tools
• Recovered encryption keys (sanitized)
• Flag submission tokens

6. Re-Routing Fallbacks

Conditional handoffs to alternative skills when preconditions fail:

"If modern AES-256 encryption is detected, hand off to $competition-crypto-mobile"

This clause prevents skill execution in inappropriate contexts.

Routing Configuration Explained

The skills/config/routing.json file implements deterministic intent resolution. Keywords map to skill names through a priority-ordered matrix:

{
  "routing": [
    {
      "patterns": ["zip", "archive", "compression", "pkzip"],
      "skill": "competition-zip-archive",
      "confidence": 0.9
    },
    {
      "patterns": ["apk", "android", "dex", "smali", "frida"],
      "skill": "competition-android-hooking",
      "confidence": 0.85
    },
    {
      "patterns": ["contained", "namespaces", "cgroup", "capability"],
      "skill": "competition-kernel-container-escape",
      "confidence": 0.8
    }
  ]
}

A human-readable mirror exists at CTF-Sandbox-Orchestrator/ctf-sandbox-orchestrator/references/router-matrix.md for quick reference without parsing JSON.

Scenario Examples by Challenge Type

The repository includes four reference implementations demonstrating the CTF-Sandbox-Orchestrator scenario structure across domains:

Skill Path	Challenge Domain	Key Tools
competition-zip-archive/SKILL.md	Archive forensics and encryption	bkcrack, pkcrack, john
competition-web-runtime/SKILL.md	JavaScript bundle analysis	Source map recovery, AST parsing
competition-android-hooking/SKILL.md	Mobile runtime instrumentation	Frida, Objection, JADX
competition-kernel-container-escape/SKILL.md	Privilege escalation	capsh, /proc analysis, LSM bypass

Each implements the same six-section template, enabling predictable navigation regardless of challenge type.

Executing a Complete Workflow

The following PowerShell sequence demonstrates full orchestrator invocation through skill completion:

# Phase 1: Case initialization (creates work/<case>/scope.md)

powershell -File skills/scripts/case-init.ps1 -CaseID "ctf-2024-zip-001" `
    -Hint "encrypted zip with known-plaintext"

# Phase 2: Master orchestrator routes based on hint and routing.json

# Internally resolves to competition-zip-archive skill

# Phase 3: Downstream skill execution (extracted from competition-zip-archive/SKILL.md)

bkcrack -C challenge.zip -c flag.txt -P known.zip -p flag.txt `
    -o recovered-keys.txt

# Phase 4: Evidence preservation (automated by skill compliance checks)

Get-FileHash challenge.zip -Algorithm SHA256 | Out-File evidence/hashes.txt

The orchestrator maintains audit continuity by passing the workspace directory context, ensuring all skills write to the same evidence collection.

Summary

• The CTF-Sandbox-Orchestrator scenario structure comprises a master orchestrator layer plus modular competition skills
• Six mandatory sections define each SKILL.md: YAML header, preconditions, workflow steps, tool setup, evidence checklist, and re-routing clause
• Routing is deterministic via skills/config/routing.json, with patterns matched against user hints
• Evidence-centric design ensures reproducible analysis with complete audit trails
• Adding new scenarios requires only creating a SKILL.md following the established template and updating the routing matrix

Frequently Asked Questions

What triggers the CTF-Sandbox-Orchestrator to select a specific skill?

The orchestrator parses the user-provided hint for keywords that match entries in skills/config/routing.json. When multiple patterns match, it selects the skill with highest confidence score. If no match exceeds the confidence threshold, it falls back to a generic reconnaissance workflow.

Can skills be invoked directly without the master orchestrator?

No. Each SKILL.md contains an explicit precondition warning that it should only run after $ctf-sandbox-orchestrator has established sandbox assumptions. Direct invocation bypasses workspace initialization and evidence collection, breaking audit requirements.

How does the framework handle challenge types not in routing.json?

The master orchestrator includes a default re-routing clause that passes control to a manual analysis skill when no pattern matches. Analysts can then contribute new patterns by creating a SKILL.md following the six-section template and submitting a pull request to update routing.json.

What ensures tool versions remain reproducible across different environments?

Each competition skill's tool-setup block pins specific release versions (e.g., bkcrack --version 1.5.0). The initialization scripts verify these versions before execution, and the evidence checklist captures tool version strings for forensic verification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}