{"id":30961650,"url":"https://github.com/magier/ran","last_synced_at":"2026-04-01T19:51:05.755Z","repository":{"id":276373014,"uuid":"777406366","full_name":"Magier/Ran","owner":"Magier","description":"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.","archived":false,"fork":false,"pushed_at":"2025-09-10T19:49:53.000Z","size":2727,"stargazers_count":13,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-10T23:39:08.396Z","etag":null,"topics":["adversary-emulation","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Magier.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-25T19:45:22.000Z","updated_at":"2025-09-10T19:49:57.000Z","dependencies_parsed_at":"2025-02-07T21:18:56.267Z","dependency_job_id":"e61279a9-4028-4496-bcab-15dc66b57aaf","html_url":"https://github.com/Magier/Ran","commit_stats":null,"previous_names":["magier/ran"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Magier/Ran","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magier%2FRan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magier%2FRan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magier%2FRan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magier%2FRan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Magier","download_url":"https://codeload.github.com/Magier/Ran/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Magier%2FRan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274684299,"owners_count":25330750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adversary-emulation","kubernetes"],"created_at":"2025-09-11T18:30:54.356Z","updated_at":"2026-04-01T19:51:05.750Z","avatar_url":"https://github.com/Magier.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/Ran.svg\" width=\"110\" alt=\"Ran\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eRan\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAdversary emulation tool for Kubernetes clusters\u003c/strong\u003e\u003cbr/\u003e\n  \u003csub\u003eNamed after Rán — Norse goddess of the sea, whose net ensnares the unwary into the depths\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/magier/ran/actions/workflows/build.yaml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/magier/ran/build.yaml?label=build\u0026logo=github\" alt=\"Build Status\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/magier/ran/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/magier/ran?logo=github\" alt=\"Latest Release\"/\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/magier/ran/pkgs/container/ran\"\u003e\u003cimg src=\"https://img.shields.io/badge/container-ghcr.io-blue?logo=github\" alt=\"Container Registry\"/\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/go-1.24-00ADD8?logo=go\" alt=\"Go 1.24\"/\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-green\" alt=\"Apache 2.0 License\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e [!CAUTION]\n\u003e This tool is intended for **educational and authorized demonstration purposes only**. Any other usage is not endorsed by the authors.\n\n\u003e [!WARNING]\n\u003e Ran is early-stage and highly experimental. Use at your own risk. See [Milestones](./Milestones.md) for the planned roadmap.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/ui_example.png\" alt=\"Ran UI\" width=\"800\"/\u003e\n\u003c/p\u003e\n\n---\n\n## What is Ran?\n\nRan is an adversary emulation platform for modern Kubernetes environments with two core objectives:\n\n- **Realistic TTP emulation** — execute predefined adversary techniques mapped to the MITRE ATT\u0026CK framework against your own cluster\n- **Living knowledge base** — a curated armory of known Kubernetes attack vectors, ready to run\n\nRan covers the full MITRE ATT\u0026CK tactic spectrum for Kubernetes: from *Initial Access* and *Discovery* through *Privilege Escalation*, *Lateral Movement*, and *Impact*.\n\n### Why Ran?\n\nA common security cliché:\n\u003e *an attacker only has to be right once, but a defender has to be right every time*\n\nThis 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.\n\nRan encourages **micro-emulation**: multi-step sequences where a simulated adversary discovers and adapts to your environment, surfacing detection gaps that atomic tests miss entirely.\n\n#### For defenders\n\n- View your cluster through an adversary's lens to find gaps in visibility and detection coverage\n- Record and replay attacker step sequences to validate detection logic\n- Export full attack trails as [MITRE Attack Flow](https://ctid.mitre.org/projects/attack-flow) (STIX 2) for documentation and threat-informed defense\n\n---\n\n## Installation\n\n### Download a release binary (recommended)\n\nPre-built binaries for Linux, macOS (Intel \u0026 Apple Silicon), and Windows are available on the [Releases page](https://github.com/magier/ran/releases/latest).\n\n```sh\n# macOS (Apple Silicon)\ncurl -sL https://github.com/magier/ran/releases/latest/download/ran-darwin-arm64.tar.gz | tar xz\nchmod +x ran \u0026\u0026 sudo mv ran /usr/local/bin/\n\n# macOS (Intel)\ncurl -sL https://github.com/magier/ran/releases/latest/download/ran-darwin-amd64.tar.gz | tar xz\nchmod +x ran \u0026\u0026 sudo mv ran /usr/local/bin/\n\n# Linux (amd64)\ncurl -sL https://github.com/magier/ran/releases/latest/download/ran-linux-amd64.tar.gz | tar xz\nchmod +x ran \u0026\u0026 sudo mv ran /usr/local/bin/\n```\n\nVerify:\n```sh\nran --help\n```\n\n### Docker\n\n```sh\ndocker pull ghcr.io/magier/ran:latest\n```\n\nRun against your local kubeconfig:\n```sh\ndocker run --rm -it \\\n  -v ~/.kube:/root/.kube:ro \\\n  -p 8080:8080 \\\n  ghcr.io/magier/ran:latest emulate --port 8080\n```\n\nThen open `http://localhost:8080` in your browser.\n\n### Build from source\n\n**Prerequisites:** Go 1.24+, Node.js 20+, pnpm\n\n```sh\ngit clone https://github.com/magier/ran.git\ncd ran\nmake build\n./dist/ran --help\n```\n\n---\n\n## Quick Start\n\nRan 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.\n\n\u003e [!IMPORTANT]\n\u003e Only run Ran against clusters you own or have explicit written permission to test.\n\n### Interactive emulation mode\n\nStart the Ran server and open the web UI to run TTPs interactively:\n\n```sh\nran emulate\n# 🚀 Server started on :8080\n```\n\nOpen `http://localhost:8080` to explore and execute techniques from the armory.\n\n**Key flags:**\n\n| Flag | Default | Description |\n|---|---|---|\n| `--port, -p` | `8080` | Port to listen on |\n| `--target, -t` | — | Initial target: `\u003cnamespace\u003e/\u003cpod-or-service\u003e` |\n| `--godmode` | `false` | Use local kubeconfig to load all cluster resources |\n| `--armory, -a` | — | Path to a custom armory directory |\n| `--config` | `ran.yaml` | Path to a custom config file |\n\n### Atomic testing (single TTP)\n\nRun a single TTP directly from the command line without the UI:\n\n```sh\n# List all available TTPs in the armory\nran armory\n\n# Execute a specific TTP by ID\nran invoke \u003cttp-id\u003e --target \u003cnamespace\u003e/\u003cpod\u003e\n\n# Example: list pods from within a compromised pod\nran invoke get-pods --target default/my-pod\n```\n\n### Configuration\n\nRan looks for `ran.yaml` in the current working directory. Copy the example to get started:\n\n```sh\ncp ran.yaml.example ran.yaml\n```\n\n```yaml\nnamespaces:\n  # Blacklist mode: hide noisy system namespaces\n  excluded:\n    - kube-system\n    - kube-public\n    - kube-node-lease\n\n  # Whitelist mode: show only specific namespaces (takes precedence over excluded)\n  # included:\n  #   - default\n  #   - production\n```\n\n---\n\n## Architecture\n\nRan is built around two major components:\n\n| Component | Responsibility |\n|---|---|\n| **Actuator** | Executes TTPs against the cluster, tracks results, and builds the audit trail |\n| **Planner / Reasoner** | Decides which actions to run and in what order |\n\n### Armory\n\nThe 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.\n\n```yaml\nid: get-pods\nname: Get Pods via K8s API\ntactic: Discovery\ntechniques: [\"Container and Resource Discovery\", T1613]\npreconditions:\n  rbac:\n    - verb: list\n      resource: pods\nprocedures:\n  - key: kubectl\n    command: kubectl get pods --token=${TOKEN} -n=${NS}\n  - key: curl\n    command: \u003e-\n      curl -H \"Authorization: Bearer ${TOKEN}\"\n      \"${API_SERVER}/api/v1/namespaces/${NS}/pods\"\n```\n\nTTPs are organized by MITRE tactic:\n\n```\narmory/TTPs/\n├── CommandAndControl/\n├── CredentialAccess/\n├── Defense Evasion/\n├── Discovery/\n├── Execution/\n├── Impact/\n├── InitialAccess/\n├── Lateral Movement/\n├── Persistence/\n├── Privilege Escalation/\n└── Resource Development/\n```\n\n### Planner approaches\n\nRan is designed to support progressively more autonomous planning:\n\n| Mode | Status | Description |\n|---|---|---|\n| **Human operator** | ✅ Available | Manually select and invoke individual TTPs |\n| **Imperative plan** | 🔄 In progress | Follow a pre-defined [Attack Flow](https://ctid.mitre.org/projects/attack-flow) runbook |\n| **Classical AI** | 🗺️ Planned | Behavior Trees, HTN, GOAP |\n| **Modern AI** | 🔭 Future | Reinforcement learning, Active Inference |\n\n*Planning approaches are inspired by [📖 Artificial Intelligence: A Modern Approach](https://aima.cs.berkeley.edu/) and motivated by MITRE's [📄 Automated Adversary Emulation: A Case for Planning and Acting with Unknowns](https://www.mitre.org/sites/default/files/2021-11/prs-18-0944-1-automated-adversary-emulation-planning-acting.pdf).*\n\n---\n\n## Roadmap\n\nSee [Milestones.md](./Milestones.md) for the full roadmap. Key upcoming work:\n\n- [ ] Cleanup logic for every TTP\n- [ ] Attack Flow as an executable plan input\n- [ ] Derive STIX Observables from TTP execution\n- [ ] [D3FEND](https://d3fend.mitre.org/) mapping\n- [ ] [MCP](https://modelcontextprotocol.io) server support 🤖\n- [ ] Autonomous emulation via Behavior Trees\n\n---\n\n## Similar Projects\n\n| Tool | Focus |\n|---|---|\n| [Caldera](https://github.com/mitre/caldera) | General adversary emulation platform |\n| [Peirates](https://github.com/inguardians/peirates) | Kubernetes penetration testing |\n| [Kubesploit](https://github.com/cyberark/kubesploit) | Kubernetes post-exploitation |\n| [kube-hunter](https://github.com/aquasecurity/kube-hunter) | Kubernetes weakness discovery |\n| [Leonidas](https://github.com/WithSecureLabs/leonidas) | AWS/K8s attack simulation |\n| [IceKube](https://github.com/WithSecureLabs/IceKube) | Kubernetes attack path analysis |\n| [Stratus Red Team](https://stratus-red-team.cloud) | Cloud-native attack techniques |\n| [CDK](https://github.com/cdk-team/CDK/) | Container/K8s penetration toolkit |\n| [kdigger](https://github.com/quarkslab/kdigger) | In-cluster context discovery |\n| [red-kube](https://github.com/lightspin-tech/red-kube) | Kubernetes red team scripts |\n| [MKAT](https://github.com/DataDog/managed-kubernetes-auditing-toolkit/) | Managed Kubernetes auditing |\n| [clusterfuck](https://bsssq.xyz/posts/kube/) | Kubernetes exploitation |\n\nFor a detailed feature comparison see [docs/tool_comparison.md](docs/tool_comparison.md).\n\n---\n\n## References\n\n- [MITRE ATT\u0026CK for Containers](https://attack.mitre.org/matrices/enterprise/containers/)\n- [MITRE — Automated Adversary Emulation: A Case for Planning and Acting with Unknowns](https://www.mitre.org/sites/default/files/2021-11/prs-18-0944-1-automated-adversary-emulation-planning-acting.pdf)\n- [Raesene's Kubernetes Security Lab](https://github.com/raesene/kube_security_lab)\n- [BishopFox — BadPods: Kubernetes Pod Privilege Escalation](https://bishopfox.com/blog/kubernetes-pod-privilege-escalation)\n- [D3FEND](https://d3fend.mitre.org)\n\n---\n\n## Contributing\n\nContributions are welcome — especially new TTPs in the armory, bug reports, and documentation improvements. Please open an issue or pull request on [GitHub](https://github.com/magier/ran).\n\n## License\n\nRan is released under the [Apache 2.0 License](LICENSE).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagier%2Fran","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagier%2Fran","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagier%2Fran/lists"}