Ran

Adversary emulation tool for Kubernetes clusters

_{Named after Rán — Norse goddess of the sea, whose net ensnares the unwary into the depths}

[!CAUTION] This tool is intended for educational and authorized demonstration purposes only. Any other usage is not endorsed by the authors.

[!WARNING] Ran is early-stage and highly experimental. Use at your own risk. See Milestones for the planned roadmap.

What is Ran?

Ran is an adversary emulation platform for modern Kubernetes environments with two core objectives:

• Realistic TTP emulation — execute predefined adversary techniques mapped to the MITRE ATT&CK framework against your own cluster
• Living knowledge base — a curated armory of known Kubernetes attack vectors, ready to run

Ran covers the full MITRE ATT&CK tactic spectrum for Kubernetes: from Initial Access and Discovery through Privilege Escalation, Lateral Movement, and Impact.

Why Ran?

A common security cliché:

an attacker only has to be right once, but a defender has to be right every time

This holds for Initial Access — but the dynamic flips afterwards. Post-IA, defenders have full environmental visibility while the attacker must explore. This is a major defensive advantage that purely atomic, single-event detections fail to leverage.

Ran encourages micro-emulation: multi-step sequences where a simulated adversary discovers and adapts to your environment, surfacing detection gaps that atomic tests miss entirely.

For defenders

• View your cluster through an adversary's lens to find gaps in visibility and detection coverage
• Record and replay attacker step sequences to validate detection logic
• Export full attack trails as MITRE Attack Flow (STIX 2) for documentation and threat-informed defense

Installation

Download a release binary (recommended)

Pre-built binaries for Linux, macOS (Intel & Apple Silicon), and Windows are available on the Releases page.

# macOS (Apple Silicon)
curl -sL https://github.com/magier/ran/releases/latest/download/ran-darwin-arm64.tar.gz | tar xz
chmod +x ran && sudo mv ran /usr/local/bin/

# macOS (Intel)
curl -sL https://github.com/magier/ran/releases/latest/download/ran-darwin-amd64.tar.gz | tar xz
chmod +x ran && sudo mv ran /usr/local/bin/

# Linux (amd64)
curl -sL https://github.com/magier/ran/releases/latest/download/ran-linux-amd64.tar.gz | tar xz
chmod +x ran && sudo mv ran /usr/local/bin/

Verify:

ran --help

Docker

docker pull ghcr.io/magier/ran:latest

Run against your local kubeconfig:

docker run --rm -it \
  -v ~/.kube:/root/.kube:ro \
  -p 8080:8080 \
  ghcr.io/magier/ran:latest emulate --port 8080

Then open http://localhost:8080 in your browser.

Build from source

Prerequisites: Go 1.24+, Node.js 20+, pnpm

git clone https://github.com/magier/ran.git
cd ran
make build
./dist/ran --help

Quick Start

Ran reads your local ~/.kube/config to discover and target cluster resources. Ensure your kubeconfig is configured and points at the cluster you want to emulate against.

[!IMPORTANT] Only run Ran against clusters you own or have explicit written permission to test.

Interactive emulation mode

Start the Ran server and open the web UI to run TTPs interactively:

ran emulate
# 🚀 Server started on :8080

Open http://localhost:8080 to explore and execute techniques from the armory.

Key flags:

Atomic testing (single TTP)

Run a single TTP directly from the command line without the UI:

# List all available TTPs in the armory
ran armory

# Execute a specific TTP by ID
ran invoke <ttp-id> --target <namespace>/<pod>

# Example: list pods from within a compromised pod
ran invoke get-pods --target default/my-pod

Configuration

Ran looks for ran.yaml in the current working directory. Copy the example to get started:

cp ran.yaml.example ran.yaml

namespaces:
  # Blacklist mode: hide noisy system namespaces
  excluded:
    - kube-system
    - kube-public
    - kube-node-lease

  # Whitelist mode: show only specific namespaces (takes precedence over excluded)
  # included:
  #   - default
  #   - production

Architecture

Ran is built around two major components:

Armory

The armory is Ran's library of executable TTPs. Each TTP is a YAML file describing the technique, its MITRE mapping, required preconditions (RBAC, access level), and one or more execution procedures.

id: get-pods
name: Get Pods via K8s API
tactic: Discovery
techniques: ["Container and Resource Discovery", T1613]
preconditions:
  rbac:
    - verb: list
      resource: pods
procedures:
  - key: kubectl
    command: kubectl get pods --token=${TOKEN} -n=${NS}
  - key: curl
    command: >-
      curl -H "Authorization: Bearer ${TOKEN}"
      "${API_SERVER}/api/v1/namespaces/${NS}/pods"

TTPs are organized by MITRE tactic:

armory/TTPs/
├── CommandAndControl/
├── CredentialAccess/
├── Defense Evasion/
├── Discovery/
├── Execution/
├── Impact/
├── InitialAccess/
├── Lateral Movement/
├── Persistence/
├── Privilege Escalation/
└── Resource Development/

Planner approaches

Ran is designed to support progressively more autonomous planning:

Planning approaches are inspired by 📖 Artificial Intelligence: A Modern Approach and motivated by MITRE's 📄 Automated Adversary Emulation: A Case for Planning and Acting with Unknowns.

Roadmap

See Milestones.md for the full roadmap. Key upcoming work:

• [ ] Cleanup logic for every TTP
• [ ] Attack Flow as an executable plan input
• [ ] Derive STIX Observables from TTP execution
• [ ] HTTP API for programmatic interaction
• [ ] D3FEND mapping
• [ ] MCP server support 🤖
• [ ] Autonomous emulation via Behavior Trees

Similar Projects

For a detailed feature comparison see docs/tool_comparison.md.

References

• MITRE ATT&CK for Containers
• MITRE — Automated Adversary Emulation: A Case for Planning and Acting with Unknowns
• Raesene's Kubernetes Security Lab
• BishopFox — BadPods: Kubernetes Pod Privilege Escalation
• D3FEND

Contributing

Contributions are welcome — especially new TTPs in the armory, bug reports, and documentation improvements. Please open an issue or pull request on GitHub.

License

Ran is released under the Apache 2.0 License.