{
  "markdown": "# cloud-pathfinder 🛰️\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP-registry%20listed-blue)](https://github.com/Baneado98/cloud-pathfinder)\n[![npm](https://img.shields.io/badge/npm-cloud--pathfinder--mcp-red)](https://www.npmjs.com/package/cloud-pathfinder-mcp)\n[![Pay](https://img.shields.io/badge/pay-x402%20USDC%20%7C%20Stripe-orange)](https://cloud-pathfinder.vercel.app)\n[![SARIF](https://img.shields.io/badge/output-SARIF%202.1.0-purple)](#sarif-210--github-code-scanning)\n\n**Attack-path auditor for Infrastructure-as-Code — Terraform, CloudFormation, Kubernetes, CDK, Pulumi, Bicep/ARM.**\nNot 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.\n\n> Example chain it finds:\n> `open security group (SSH 0.0.0.0/0) → EC2 instance-profile role → iam:PassRole privilege escalation to admin → S3 exfiltration`\n\nAvailable as an **MCP server** (Claude, Cursor, any MCP agent) and a **pay-per-call x402 API** (autonomous AI agents with a wallet).\n\n---\n\n## 🔐 Privacy & data model (read this first)\n\nSending your IaC to a third party is sensitive — so here is **exactly** what happens:\n\n- **Your IaC is never stored and never logged.** Every audit runs **in memory** on\n  the hosted service and is **discarded** when the response is sent. No database of\n  your templates, no retention, no analytics on file contents.\n- **What is sent:** only the IaC text you pass (the `files` map or `source` blob).\n  Nothing is read from your machine, your cloud account, or your credentials —\n  **cloud-pathfinder never touches a live cloud** (see \"honest limits\" below). There\n  are **no cloud keys to provide** because it analyzes the *declared* templates only.\n- **Free tier vs deep tier — both run server-side, here's why and what differs:**\n  - The thin npm client ships **zero analysis logic** (no graph engine, no IAM\n    privesc knowledge base). It is a pure HTTP caller. So even the **free verdict +\n    counts** are computed on the hosted service, then your IaC is dropped. This is\n    the honest tradeoff that keeps the moat off your machine — we say so plainly\n    rather than claim a fake \"100% local\" mode.\n  - **Deep analysis is strictly opt-in** (`deep: true`, behind payment). Only then\n    are the full chains, file:line evidence and remediation returned. You send the\n    same IaC either way — nothing *extra* leaves your machine for the deep tier.\n\n> **Hosted service:** https://cloud-pathfinder.vercel.app — all analysis runs\n> server-side. This npm package is a **thin MCP client**: it sends the IaC text to\n> the hosted endpoint and renders the verdict. No analysis logic ships to your machine.\n\n---\n\n## ⚡ How it works (30 seconds)\n\n1. Your MCP agent calls `audit_iac_attack_paths { files: { \"main.tf\": \"...\" } }`.\n2. The thin client POSTs the IaC text to `https://cloud-pathfinder.vercel.app`.\n3. The hosted engine builds a typed **resource graph**, runs a BFS from an\n   `INTERNET` node to every data store / secret / admin sink, and resolves IAM\n   privilege-escalation reachability along each hop — **in memory**.\n4. The IaC is **discarded**; nothing is persisted.\n5. The deep tier returns every full chain with per-hop `file:line` evidence; the\n   free tier returns the verdict, score and counts.\n\nThe npm tarball contains only the HTTP caller — so **nothing, free or deep, runs\noffline**. Without the server it degrades to a clear network error.\n\n---\n\n## 🆚 Why this isn't a linter (and why a local one can't replace it)\n\nA linter flags resources one at a time: \"this SG is open\", \"this role is broad\".\ncloud-pathfinder reasons about how those facts **connect** — work a per-file local\ntool structurally cannot do:\n\n| Capability | Local linter | **cloud-pathfinder** |\n|---|:---:|:---:|\n| Flag one open SG / one broad role | ✅ | ✅ |\n| **Graph** — which SG attaches to which instance, which role it assumes, what it reads | ❌ | ✅ |\n| **Reachability BFS** internet → crown jewel, full multi-hop chain + file:line | ❌ | ✅ |\n| **IAM privilege-escalation KB** (20+ primitives: PassRole, CreatePolicyVersion…) | ❌ | ✅ |\n| **Multi-cloud** — AWS / GCP / Azure in one graph | ❌ | ✅ |\n| **Choke-point** analysis (the one hop that, fixed, cuts the most paths) | ❌ | ✅ |\n| **Diff mode** — what a PR INTRODUCES / ELIMINATES / AGGRAVATES | ❌ | ✅ |\n| **Kubernetes** LB/NodePort → privileged pod → cluster-admin SA → Secret | ❌ | ✅ |\n| **SARIF 2.1.0** for GitHub code scanning (inline chains on the Security tab) | ❌ | ✅ |\n\n- **🔗 Graph, not lint.** Builds a typed resource graph and resolves the real\n  relationships across files and clouds.\n- **🧭 Reachability search.** BFS from `INTERNET` to every data store / secret /\n  admin sink, returning the full multi-hop chain with **per-hop file:line evidence**.\n- **👑 IAM privilege-escalation knowledge base.** Knows AWS managed-policy\n  permissions and **20+ privilege-escalation primitives** (PassRole+RunInstances,\n  CreatePolicyVersion, AttachRolePolicy, SSM SendCommand, UpdateFunctionCode,\n  UpdateAssumeRolePolicy…).\n- **☸️ Kubernetes attack surface.** LoadBalancer/NodePort exposure → privileged /\n  hostPath / hostNetwork pods, **cluster-admin ServiceAccounts**, and mounted Secrets.\n\nFormats are **auto-detected per file** and analyzed **together** — mix `.tf`,\nCloudFormation `.yaml/.json` and Kubernetes manifests in one call.\n\n---\n\n## 🚀 Quickstart — add it to your MCP client\n\n```json\n{\n  \"mcpServers\": {\n    \"cloud-pathfinder\": { \"command\": \"npx\", \"args\": [\"-y\", \"cloud-pathfinder-mcp\"] }\n  }\n}\n```\nNo key needed for the free tier. Restart your client and the\n**`audit_iac_attack_paths`** + **`diff_attack_paths`** tools appear. (Remote server:\n`https://cloud-pathfinder.vercel.app/mcp`.)\n\n### Tool: `audit_iac_attack_paths`\n\n```jsonc\n{\n  \"files\": {\n    \"main.tf\": \"resource \\\"aws_security_group\\\" \\\"web\\\" { ingress { ... cidr_blocks = [\\\"0.0.0.0/0\\\"] } } ...\",\n    \"k8s.yaml\": \"apiVersion: v1\\nkind: Service\\n...\"\n  }\n  // or: \"source\": \"<a single IaC blob>\", \"filename\": \"main.tf\"\n}\n```\n\n### Example — input → output\n```\naudit_iac_attack_paths { \"files\": { \"main.tf\": \"<SG open to 0.0.0.0/0 on 22 +\n                          EC2 with instance-profile role that can s3:* + iam:PassRole>\" } }\n\n→ FREE:  verdict: BREACHABLE · risk 86/100 · 1 attack path · 1 crown jewel · 3 misconfigs\n\n→ DEEP (deep:true):  verdict: BREACHABLE\n   PATH #1 (internet → admin):\n     [1] INTERNET → aws_security_group.web   (main.tf:4  — ingress 22 from 0.0.0.0/0)\n     [2] → aws_instance.app                  (main.tf:19 — attaches sg web)\n     [3] → aws_iam_role.app_role             (main.tf:31 — instance profile)\n     [4] → iam:PassRole + ec2:RunInstances   (privesc → launch instance as admin role)\n     [5] → s3:* on aws_s3_bucket.data        (main.tf:52 — exfiltration sink)\n   CHOKE POINT: tighten main.tf:4 ingress → cuts this entire path.\n   FIX: restrict ingress CIDR; split the role; add a permissions boundary.\n```\n\nThe **free** tier returns the verdict, risk score, and the **counts** (how many\nattack paths, crown jewels and misconfigurations). The **deep** tier returns every\nfull chain with hops, file:line evidence, privilege-escalation reachability and\nremediation.\n\n### Tool: `diff_attack_paths` — the CI/CD gate\n\nGive it the IaC **before** and **after** a change (a PR's base and head trees) and it\nreports exactly what the change did to your attack surface: which internet→crown-jewel\nchains it **INTRODUCES**, which it **ELIMINATES**, and which it **AGGRAVATES** — with\nan `INTRODUCES_BREACH` / `REDUCES_RISK` / `NEUTRAL` / `MIXED` verdict.\n\n```jsonc\n{\n  \"before\": { \"files\": { \"main.tf\": \"...security group admits 10.0.0.0/16...\" } },\n  \"after\":  { \"files\": { \"main.tf\": \"...security group admits 0.0.0.0/0...\" } }\n  // deep: true → full introduced/eliminated chains + before→after exploitability + which choke points now matter\n}\n```\n\nA per-file linter or a single-state scan cannot answer this: it needs the full graph\n+ privesc reachability on **both** states and a semantic cross-state path match.\nHTTP: `POST /diff` (free, counts only) / `POST /pro/diff` (deep).\n\n## Free HTTP API\n\n```http\nPOST /audit\nContent-Type: application/json\n\n{ \"files\": { \"main.tf\": \"resource \\\"aws_security_group\\\" ...\" } }\n```\n\nRate-limited to 30 requests/hour/IP. For unlimited/commercial/deep use, call `/pro/audit`.\n\n**Input formats:** Terraform / OpenTofu, CloudFormation, Kubernetes, Helm, Kustomize,\nPulumi (TS/JS/Python), Bicep/ARM, and **AWS CDK** — both the synthesized\n`cdk.out/*.template.json` and the **un-synthed CDK program** (TypeScript + Python),\nso a CI gate runs on the PR diff before `cdk synth`.\n\n---\n\n## SARIF 2.1.0 → GitHub code scanning\n\nAdd `?format=sarif` (or `{ \"format\": \"sarif\" }`) to `/audit`, `/pro/audit`, `/diff`\nor `/pro/diff` to get **SARIF 2.1.0** you can upload to **GitHub code scanning** —\nevery attack chain shows up inline on the PR's Security tab.\n\n- Each chain is one SARIF `result` with a **`codeFlow`** (a step-through walk:\n  internet → SG → instance role → privesc → S3), anchored to the IaC `file:line`,\n  plus `security-severity`/CVSS so the badge colors correctly.\n- The **diff** SARIF only fails the check on **introduced/aggravated** routes\n  (error-level); eliminated/eased land as `note`.\n- The **free** tier returns a redacted-but-schema-valid SARIF (counts only — no\n  chains, no code-flows, no route file:line); the full code-flows are premium.\n\n```yaml\n# .github/workflows/cloud-pathfinder.yml (sketch)\n- run: curl -s -X POST \"$CPF/pro/diff?format=sarif\" -H \"Authorization: Bearer $KEY\" \\\n       --data @payload.json -o cloud-pathfinder.sarif\n- uses: github/codeql-action/upload-sarif@v3\n  with: { sarif_file: cloud-pathfinder.sarif }\n```\n\n---\n\n## 💳 Unlock `/pro` — two ways to pay (dual-pay)\n\nThe deep `/pro/audit` returns the **full attack chains**, **per-hop evidence**,\n**privilege-escalation analysis** and **remediation**. Two payment lanes coexist:\n\n| Lane | For | How |\n|---|---|---|\n| 💳 **Card (Stripe)** | Humans / teams | Buy a prepaid key at `/pro/checkout`, then send `Authorization: Bearer <key>` (or set `CLOUD_PATHFINDER_KEY`). |\n| 🪙 **x402 (USDC)** | AI agents with a wallet | Pay **$0.30** per call automatically. Settles on Base. No signup, no key. |\n\n```http\nPOST /pro/audit          # 402 (shows BOTH lanes) → pay → result\n```\n\n---\n\n## What it catches (selected)\n\n| Class | Detail |\n|---|---|\n| Public → role → data | Open SG on a sensitive port (SSH/RDP/DB) → instance role that can read S3/Dynamo/RDS/Secrets → exfiltration |\n| IAM privilege escalation | `iam:PassRole`+`ec2:RunInstances`, `iam:CreatePolicyVersion`, `iam:AttachRolePolicy`, `ssm:SendCommand`, wildcard `*` on `*`, and ~15 more |\n| Public data stores | `publicly_accessible = true` RDS, world-open buckets |\n| Kubernetes | LoadBalancer/NodePort → privileged pod → cluster-admin ServiceAccount → Secret |\n| CloudFormation | `!Ref`/`!GetAtt` intrinsics resolved; `ManagedPolicyArns`/inline policies analyzed |\n\n---\n\n## How it stays honest\n\nThe premium **engine and knowledge base never ship in the npm package** — the\npublished client is a thin renderer that calls the hosted analysis service. The free\ntier is genuinely useful (verdict + counts); the deep chains, evidence and privesc\nanalysis are server-side behind payment.\n\n**Heuristic static analysis of declared IaC**, not a live cloud assessment. It\nreasons over what the templates declare (no runtime SCP/permissions-boundary/condition\nevaluation). Treat findings as prioritized leads, not a guarantee.\n\nMIT · [github.com/Baneado98/cloud-pathfinder](https://github.com/Baneado98/cloud-pathfinder)\n",
  "bytes": 11914,
  "sha": "6b82d8e5b5ab146648fe17a05a9795be29df38059dd0e5156d2906e185aed62b",
  "repo_slug": "baneado98/cloud-pathfinder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_baneado98_cloud_pathfinder_6d4555cd/readme"
}