GitHub - Magier/Ran: Ran is an experimental offensive tool for Kubernetes clusters with the goal to enable quick emulation of adversary techniques and a collection for known attack vectors.

Adversary emulation tool for Kubernetes clusters
_{Named after Rán - Norse goddess of the sea, whose net ensnares the unwary into the depths}

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 campaign trails as Ran JSON for reporting, analysis, and replay

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:

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 --host 0.0.0.0 --port 8080

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

Build from source

Prerequisites: Rust 1.93+, Node.js 24+, pnpm

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

Developers building the target-side Ranplant binary can follow the local Ranplant build instructions, including static Linux cross-compilation from macOS.

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.

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 trigger <ttp-id> --target ns/<namespace>/pod/<name>

# Example: list pods from within a compromised pod
ran trigger get-pods --target ns/default/pod/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 from the Pod picker and graph
  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.

KubeTier RBAC assessments

Ran uses an offline metadata snapshot of KubeTier to classify discovered Kubernetes permissions from T0 to T3. The UI links every assessment back to KubeTier and to the relevant Kubernetes documentation. Ran does not contact KubeTier at runtime.

To show descriptions and escalation paths inline without redistributing that content, generate a private full catalog and reference it from ran.yaml:

cargo run -p kubetier --bin update_catalog -- --full --output kubetier.full.json

kubetier:
  catalog: ./kubetier.full.json

Ran also maintains a small reviewed registry for product-specific permission assessments, including custom resources. These local assessments take precedence over KubeTier and are labelled as a Ran assessment in the UI.

The public snapshot can be refreshed without --full using crates/kubetier/data/catalog.json as the output. See THIRD_PARTY_NOTICES.md for attribution and content boundaries, and docs/kubetier_ref.md for the KubeTier escalation paths already implemented by Ran.

id: get-pods
name: Get Pods
tactic: Discovery
techniques: ["Container and Resource Discovery", T1613]
preconditions:
  rbac:
    - verb: list
      resource: pods
parameters:
  K8S_AUTH:
    type: K8sAuth
    description: the Kubernetes identity selected by Authenticate As
procedures:
  - key: kubectl
    command: kubectl ${K8S_AUTH} get pods -n=${NS}
  - key: k8s-request
    k8s_request:
      authentication: ${K8S_AUTH}
      api_server: ${API_SERVER}
      api: /api/v1
      resource: pods
      namespace: ${NS}

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
• MITRE Attack Flow/STIX import and export
• Sliver RPC integration
• WebSocket RPC with a purpose-built protocol
• Derive observables from TTP execution
• D3FEND mapping
• 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.