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:

Flag	Default	Description
--port, -p	8080	Port to listen on
--target, -t	—	Initial target: <namespace>/<pod-or-service>
--godmode	false	Use local kubeconfig to load all cluster resources
--armory, -a	—	Path to a custom armory directory
--config	ran.yaml	Path to a custom config file

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:

Component	Responsibility
Actuator	Executes TTPs against the cluster, tracks results, and builds the audit trail
Planner / Reasoner	Decides which actions to run and in what order

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:

Mode	Status	Description
Human operator	✅ Available	Manually select and invoke individual TTPs
Imperative plan	🔄 In progress	Follow a pre-defined Attack Flow runbook
Classical AI	🗺️ Planned	Behavior Trees, HTN, GOAP
Modern AI	🔭 Future	Reinforcement learning, Active Inference

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
• D3FEND mapping
• MCP server support 🤖
• Autonomous emulation via Behavior Trees

---

Similar Projects

Tool	Focus
Caldera	General adversary emulation platform
Peirates	Kubernetes penetration testing
Kubesploit	Kubernetes post-exploitation
kube-hunter	Kubernetes weakness discovery
Leonidas	AWS/K8s attack simulation
IceKube	Kubernetes attack path analysis
Stratus Red Team	Cloud-native attack techniques
CDK	Container/K8s penetration toolkit
kdigger	In-cluster context discovery
red-kube	Kubernetes red team scripts
MKAT	Managed Kubernetes auditing
clusterfuck	Kubernetes exploitation

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.