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

> Explore the CTF-Sandbox-Orchestrator scenario structure. Learn how to build modular CTF routing with its plug-in architecture, YAML metadata, and workflow steps. Get the complete guide.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: tutorial
- Published: 2026-08-18

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CTF-Sandbox-Orchestrator/competition-zip-archive/SKILL.md) reveals this pattern.

### 1. YAML Header

Every SKILL.md begins with frontmatter defining identity:

```yaml
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:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file implements deterministic intent resolution. Keywords map to skill names through a priority-ordered matrix:

```json
{
  "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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/competition-zip-archive/SKILL.md) | Archive forensics and encryption | `bkcrack`, `pkcrack`, `john` |
| [`competition-web-runtime/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/competition-web-runtime/SKILL.md) | JavaScript bundle analysis | Source map recovery, AST parsing |
| [`competition-android-hooking/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/competition-android-hooking/SKILL.md) | Mobile runtime instrumentation | Frida, Objection, JADX |
| [`competition-kernel-container-escape/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.