cloud-pathfinder 🛰️

Attack-path auditor for Infrastructure-as-Code — Terraform, CloudFormation, Kubernetes, CDK, Pulumi, Bicep/ARM. Not a linter. It parses your IaC into a resource graph, resolves cross-resource (and cross-file) relationships, and searches for the multi-hop chains from the public internet to your crown jewels (data stores, secrets, admin). It returns a BREACHABLE / EXPOSED / HARDENED verdict and the concrete route an attacker would walk.

Example chain it finds: open security group (SSH 0.0.0.0/0) → EC2 instance-profile role → iam:PassRole privilege escalation to admin → S3 exfiltration

Available as an MCP server (Claude, Cursor, any MCP agent) and a pay-per-call x402 API (autonomous AI agents with a wallet).

---

🔐 Privacy & data model (read this first)

Sending your IaC to a third party is sensitive — so here is exactly what happens:

• Your IaC is never stored and never logged. Every audit runs in memory on the hosted service and is discarded when the response is sent. No database of your templates, no retention, no analytics on file contents.
• What is sent: only the IaC text you pass (the files map or source blob). Nothing is read from your machine, your cloud account, or your credentials — cloud-pathfinder never touches a live cloud (see "honest limits" below). There are no cloud keys to provide because it analyzes the declared templates only.
• Free tier vs deep tier — both run server-side, here's why and what differs:
  • The thin npm client ships zero analysis logic (no graph engine, no IAM privesc knowledge base). It is a pure HTTP caller. So even the free verdict + counts are computed on the hosted service, then your IaC is dropped. This is the honest tradeoff that keeps the moat off your machine — we say so plainly rather than claim a fake "100% local" mode.
  • Deep analysis is strictly opt-in (deep: true, behind payment). Only then are the full chains, file:line evidence and remediation returned. You send the same IaC either way — nothing extra leaves your machine for the deep tier.

Hosted service: https://cloud-pathfinder.vercel.app — all analysis runs server-side. This npm package is a thin MCP client: it sends the IaC text to the hosted endpoint and renders the verdict. No analysis logic ships to your machine.

---

⚡ How it works (30 seconds)

1. Your MCP agent calls audit_iac_attack_paths { files: { "main.tf": "..." } }.
2. The thin client POSTs the IaC text to https://cloud-pathfinder.vercel.app.
3. The hosted engine builds a typed resource graph, runs a BFS from an INTERNET node to every data store / secret / admin sink, and resolves IAM privilege-escalation reachability along each hop — in memory.
4. The IaC is discarded; nothing is persisted.
5. The deep tier returns every full chain with per-hop file:line evidence; the free tier returns the verdict, score and counts.

The npm tarball contains only the HTTP caller — so nothing, free or deep, runs offline. Without the server it degrades to a clear network error.

---

🆚 Why this isn't a linter (and why a local one can't replace it)

A linter flags resources one at a time: "this SG is open", "this role is broad". cloud-pathfinder reasons about how those facts connect — work a per-file local tool structurally cannot do:

Capability	Local linter	cloud-pathfinder
Flag one open SG / one broad role	✅	✅
Graph — which SG attaches to which instance, which role it assumes, what it reads	❌	✅
Reachability BFS internet → crown jewel, full multi-hop chain + file:line	❌	✅
IAM privilege-escalation KB (20+ primitives: PassRole, CreatePolicyVersion…)	❌	✅
Multi-cloud — AWS / GCP / Azure in one graph	❌	✅
Choke-point analysis (the one hop that, fixed, cuts the most paths)	❌	✅
Diff mode — what a PR INTRODUCES / ELIMINATES / AGGRAVATES	❌	✅
Kubernetes LB/NodePort → privileged pod → cluster-admin SA → Secret	❌	✅
SARIF 2.1.0 for GitHub code scanning (inline chains on the Security tab)	❌	✅

• 🔗 Graph, not lint. Builds a typed resource graph and resolves the real relationships across files and clouds.
• 🧭 Reachability search. BFS from INTERNET to every data store / secret / admin sink, returning the full multi-hop chain with per-hop file:line evidence.
• 👑 IAM privilege-escalation knowledge base. Knows AWS managed-policy permissions and 20+ privilege-escalation primitives (PassRole+RunInstances, CreatePolicyVersion, AttachRolePolicy, SSM SendCommand, UpdateFunctionCode, UpdateAssumeRolePolicy…).
• ☸️ Kubernetes attack surface. LoadBalancer/NodePort exposure → privileged / hostPath / hostNetwork pods, cluster-admin ServiceAccounts, and mounted Secrets.

Formats are auto-detected per file and analyzed together — mix .tf, CloudFormation .yaml/.json and Kubernetes manifests in one call.

---

🚀 Quickstart — add it to your MCP client

{
  "mcpServers": {
    "cloud-pathfinder": { "command": "npx", "args": ["-y", "cloud-pathfinder-mcp"] }
  }
}

No key needed for the free tier. Restart your client and the audit_iac_attack_paths + diff_attack_paths tools appear. (Remote server: https://cloud-pathfinder.vercel.app/mcp.)

Tool: audit_iac_attack_paths

{
  "files": {
    "main.tf": "resource \"aws_security_group\" \"web\" { ingress { ... cidr_blocks = [\"0.0.0.0/0\"] } } ...",
    "k8s.yaml": "apiVersion: v1\nkind: Service\n..."
  }
  // or: "source": "<a single IaC blob>", "filename": "main.tf"
}

Example — input → output

audit_iac_attack_paths { "files": { "main.tf": "<SG open to 0.0.0.0/0 on 22 +
                          EC2 with instance-profile role that can s3:* + iam:PassRole>" } }

→ FREE:  verdict: BREACHABLE · risk 86/100 · 1 attack path · 1 crown jewel · 3 misconfigs

→ DEEP (deep:true):  verdict: BREACHABLE
   PATH #1 (internet → admin):
     [1] INTERNET → aws_security_group.web   (main.tf:4  — ingress 22 from 0.0.0.0/0)
     [2] → aws_instance.app                  (main.tf:19 — attaches sg web)
     [3] → aws_iam_role.app_role             (main.tf:31 — instance profile)
     [4] → iam:PassRole + ec2:RunInstances   (privesc → launch instance as admin role)
     [5] → s3:* on aws_s3_bucket.data        (main.tf:52 — exfiltration sink)
   CHOKE POINT: tighten main.tf:4 ingress → cuts this entire path.
   FIX: restrict ingress CIDR; split the role; add a permissions boundary.

The free tier returns the verdict, risk score, and the counts (how many attack paths, crown jewels and misconfigurations). The deep tier returns every full chain with hops, file:line evidence, privilege-escalation reachability and remediation.

Tool: diff_attack_paths — the CI/CD gate

Give it the IaC before and after a change (a PR's base and head trees) and it reports exactly what the change did to your attack surface: which internet→crown-jewel chains it INTRODUCES, which it ELIMINATES, and which it AGGRAVATES — with an INTRODUCES_BREACH / REDUCES_RISK / NEUTRAL / MIXED verdict.

{
  "before": { "files": { "main.tf": "...security group admits 10.0.0.0/16..." } },
  "after":  { "files": { "main.tf": "...security group admits 0.0.0.0/0..." } }
  // deep: true → full introduced/eliminated chains + before→after exploitability + which choke points now matter
}

A per-file linter or a single-state scan cannot answer this: it needs the full graph

• privesc reachability on both states and a semantic cross-state path match. HTTP: POST /diff (free, counts only) / POST /pro/diff (deep).

Free HTTP API

POST /audit
Content-Type: application/json

{ "files": { "main.tf": "resource \"aws_security_group\" ..." } }

Rate-limited to 30 requests/hour/IP. For unlimited/commercial/deep use, call /pro/audit.

Input formats: Terraform / OpenTofu, CloudFormation, Kubernetes, Helm, Kustomize, Pulumi (TS/JS/Python), Bicep/ARM, and AWS CDK — both the synthesized cdk.out/*.template.json and the un-synthed CDK program (TypeScript + Python), so a CI gate runs on the PR diff before cdk synth.

---

SARIF 2.1.0 → GitHub code scanning

Add ?format=sarif (or { "format": "sarif" }) to /audit, /pro/audit, /diff or /pro/diff to get SARIF 2.1.0 you can upload to GitHub code scanning — every attack chain shows up inline on the PR's Security tab.

• Each chain is one SARIF result with a codeFlow (a step-through walk: internet → SG → instance role → privesc → S3), anchored to the IaC file:line, plus security-severity/CVSS so the badge colors correctly.
• The diff SARIF only fails the check on introduced/aggravated routes (error-level); eliminated/eased land as note.
• The free tier returns a redacted-but-schema-valid SARIF (counts only — no chains, no code-flows, no route file:line); the full code-flows are premium.

# .github/workflows/cloud-pathfinder.yml (sketch)
- run: curl -s -X POST "$CPF/pro/diff?format=sarif" -H "Authorization: Bearer $KEY" \
       --data @payload.json -o cloud-pathfinder.sarif
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: cloud-pathfinder.sarif }

---

💳 Unlock /pro — two ways to pay (dual-pay)

The deep /pro/audit returns the full attack chains, per-hop evidence, privilege-escalation analysis and remediation. Two payment lanes coexist:

Lane	For	How
💳 Card (Stripe)	Humans / teams	Buy a prepaid key at /pro/checkout, then send Authorization: Bearer <key> (or set CLOUD_PATHFINDER_KEY).
🪙 x402 (USDC)	AI agents with a wallet	Pay $0.30 per call automatically. Settles on Base. No signup, no key.

POST /pro/audit          # 402 (shows BOTH lanes) → pay → result

---

What it catches (selected)

Class	Detail
Public → role → data	Open SG on a sensitive port (SSH/RDP/DB) → instance role that can read S3/Dynamo/RDS/Secrets → exfiltration
IAM privilege escalation	iam:PassRole+ec2:RunInstances, iam:CreatePolicyVersion, iam:AttachRolePolicy, ssm:SendCommand, wildcard * on *, and ~15 more
Public data stores	publicly_accessible = true RDS, world-open buckets
Kubernetes	LoadBalancer/NodePort → privileged pod → cluster-admin ServiceAccount → Secret
CloudFormation	!Ref/!GetAtt intrinsics resolved; ManagedPolicyArns/inline policies analyzed

---

How it stays honest

The premium engine and knowledge base never ship in the npm package — the published client is a thin renderer that calls the hosted analysis service. The free tier is genuinely useful (verdict + counts); the deep chains, evidence and privesc analysis are server-side behind payment.

Heuristic static analysis of declared IaC, not a live cloud assessment. It reasons over what the templates declare (no runtime SCP/permissions-boundary/condition evaluation). Treat findings as prioritized leads, not a guarantee.

MIT · github.com/Baneado98/cloud-pathfinder