CloudFall

A research scaffold for demonstrating cloud resource-placement reach and co-residency across every region / availability zone / location, using OpenTofu.

⚠️ Authorized, own-account use only. CloudFall places real resources and runs adjacency/side-channel probes. Run it only between resources you own and control. Never target third-party tenants or networks. See ETHICS.md.

CloudFall is a foundation to build on, not a finished weapon. It exists to make one thing concrete and reproducible: that with infrastructure-as-code and a modest amount of cloud-API spelunking, a tenant can systematically place resources across an entire provider footprint — and that this placement reach is the precondition for the whole co-residency / side-channel / one-hop attack literature, from Ristenpart et al. (CCS 2009) through Zhao et al. (ASPLOS 2024, ~100% co-location on Google Cloud Run).

Threat model in one paragraph

Placement is not random from an adversary's point of view: which physical host, socket, core, and network segment your resource lands on is a controllable, partially-observable function of region, physical AZ-ID, instance type, placement hints, and launch timing. Achieve co-residency and the payoff scales with how tightly you co-locate — same host (memory-bus/DRAM channels), same socket (LLC Prime+Probe, key extraction), same core (L1/Foreshadow), same SMT sibling (MDS). And short of host co-residency, mere one-hop network adjacency (same subnet/AZ) exposes link-scoped IPv6/ND and on-link host/embedded/network-gear TCP/IP-stack bugs an Internet-distant attacker can't reach (e.g. the OpenBSD ICMPv6 mbuf RCE CVE-2007-1365 and Windows IPv6 DoS CVE-2021-24086 in host stacks; Ripple20 and AMNESIA:33 in embedded/gear stacks). The full, citation-verified grounding is in docs/literature-review.md.

Architecture: three decoupled layers, one contract

  enumerate/  ──►  PlacementMatrix (JSON)  ──►  place/  ──►  OpenTofu  ──►  cloud
                          ▲                                                   │
                          │                                                   ▼
                    schemas/*.json                                        verify/
                   (the contract)                              CoResidencyResult (JSON)

• enumerate/ — turns a cloud account into a PlacementMatrix: every region × AZ-ID × resource-type × placement-option you could deploy into. Keys on the physical AZ-ID (use1-az1), never the per-account AZ name (us-east-1a) — they're shuffled per account, and getting this wrong silently breaks multi-account placement. AWS is implemented; Azure/GCP are stubs.
• place/ — turns a matrix into OpenTofu. Two modes: OpenTofu ≥1.9 provider for_each (data-driven multi-region fan-out, no codegen) and a stock-Terraform-compatible codegen fallback. Places by az_id via subnet binding, so configs are account-portable.
• verify/ — measures which granularity of co-residency a deployed pair achieved and emits a vector {same_az, same_host, same_socket_llc, same_core, same_smt_sibling}, because each tier unlocks a different attack class. Ships the network-RTT (same_az) and memory-bus (same_host) tiers; tighter tiers are documented extension points.

See docs/architecture.md for the design rationale.

Quickstart (fully offline — no cloud account, no credentials)

pip install -e ".[dev]"

# 1. build a placement matrix from the bundled sample (no API calls)
cloudfall enumerate --fixtures --out matrix.json

# 2. generate OpenTofu (touches nothing in the cloud)
cloudfall plan --matrix matrix.json --mode provider_foreach --out out/tofu
cloudfall plan --matrix matrix.json --mode codegen          --out out/tofu-static

# 3. validate the memory-bus (same_host) verifier pipeline locally
make -C native/membus
cloudfall verify selftest

# tier -> attack-class reference
cloudfall info

Against a real account (requires explicit authorization)

export CLOUDFALL_AUTHORIZED=1          # asserts own-account-only use (see ETHICS.md)
pip install -e ".[aws]"

cloudfall enumerate --cloud aws --types t3.micro,m5.large,c5.large --spot-scores --out matrix.json
cloudfall plan --matrix matrix.json --out out/tofu
cd out/tofu && tofu init && tofu apply        # creates real, billable resources

Status

Alpha / scaffold. AWS enumerator + placer + two verification tiers are working and tested; Azure/GCP enumerators and the LLC/core/SMT verification tiers are stubbed extension points. Contributions welcome — see CONTRIBUTING.md and ROADMAP.md.

License

Apache-2.0. If you use CloudFall in research, please cite it and the underlying literature (see CITATION.cff).