@skaleagents/swarm 0.3.1 → 0.5.0

package/README.md

@@ -1,15 +1,74 @@
 # @skaleagents/swarm
 
-Public stdio MCP server for SkaleAgents Phase 1. Talks to the Laravel **api**
-over JSON and uses browser OAuth for sign-in.
+SkaleAgents MCP server with local stdio and hosted Streamable HTTP transports.
+Uses browser OAuth for sign-in.
 
-Tools: `review_architecture`, `scan_iac_stub`.
+Tools: `review_architecture`, `scan_iac`. The older `scan_iac_stub` name remains
+an alias for the full scanner.
 
 `review_architecture` accepts application source or infrastructure text. Your AI
 client reads the files in its workspace and sends the relevant content through
 the MCP tool for a structured review.
 
-## Prerequisites
+## Infrastructure scanning
+
+`scan_iac` parses Terraform HCL/JSON, CloudFormation YAML/JSON, and Kubernetes
+manifests, including multi-document YAML and Kubernetes Lists. It returns a
+resource inventory and findings with stable rule IDs, severity, property paths,
+line locations, and remediation. Findings never include matched secret values.
+
+Checks cover public ingress, wildcard IAM, public storage, encryption settings,
+bucket versioning, RDS protection, EC2 metadata, Kubernetes privileges, images,
+resource requests, probes, replicas, inline Secrets, and RBAC. Literal credential
+and HTTP URL checks also run against parsed resource properties.
+
+Example tool arguments:
+
+```json
+{
+  "content": "resource \"aws_db_instance\" \"app\" { publicly_accessible = true }",
+  "format": "terraform",
+  "focus": "security",
+  "minSeverity": "medium",
+  "maxFindings": 100
+}
+```
+
+Both tools accept `focus` (`general`, `security`, `reliability`, or `cost`),
+`minSeverity` (`info` through `critical`), and `maxFindings` (1 to 500, default
+100). Content must contain 1 to 500,000 characters and cannot be whitespace.
+`format` defaults to `auto`; only `review_architecture` accepts `application`.
+
+Results are returned as JSON text and MCP `structuredContent`. `totalFindings`
+and `totals` cover all findings matching the filters; `truncated` signals that
+`maxFindings` limited the returned list. `rulesEvaluated` lists the IaC checks
+that ran. Malformed input returns a tool error, not a clean scan.
+
+IaC reviews use the same scanner through either tool. Application reviews use
+text patterns. Neither mode inspects live infrastructure. Terraform expressions,
+CloudFormation intrinsics, and external modules are not evaluated. HCL line
+locations point to resource declarations; property paths identify the setting.
+YAML aliases must be expanded before submission. Coverage limits are included
+in every result. An empty finding list is not proof that a system is secure.
+
+## Hosted connection
+
+Use `https://skaleagents.com/mcp` in Claude Desktop or ChatGPT's custom connector
+settings. Choose OAuth and leave client ID and secret fields blank. The client
+registers itself, opens Google sign-in, and asks you to approve MCP access.
+See [client setup](https://skaleagents.com/settings) for Cursor, Claude Code,
+Claude Desktop, ChatGPT, and Codex instructions.
+
+The web app hosts this endpoint using `handleMcpRequest` from
+`@skaleagents/swarm/http`. It validates each bearer credential with the API's
+`/api/oauth/mcp-token` endpoint before running a tool. Tokens are bound to the
+MCP resource and cannot access unrelated API routes. Credentials are not
+forwarded to the public bot directory.
+
+`protectedResourceMetadata` exports the discovery response for
+`/.well-known/oauth-protected-resource/mcp`.
+
+## Local stdio prerequisites
 
 1. Node.js 20 or newer. The client connects to `https://api.skaleagents.com` by default.
 2. A browser that can open the SkaleAgents sign-in page.
@@ -74,13 +133,13 @@ Dev without build:
   "mcpServers": {
     "skaleagents": {
       "command": "npx",
-      "args": ["-y", "@skaleagents/swarm@0.3.1"]
+       "args": ["-y", "@skaleagents/swarm@0.5.0"]
     }
   }
 }
 ```
 
-Restart Cursor after saving. In Agent/Chat, tools should appear as `review_architecture` and `scan_iac_stub`.
+Restart Cursor after saving. In Agent/Chat, tools should appear as `review_architecture`, `scan_iac`, and the compatibility alias `scan_iac_stub`.
 
 ## Claude Code
 
@@ -94,6 +153,7 @@ Use the published package configuration above in `.mcp.json`. OAuth starts on th
 | `PLATFORM_API_URL` | No | Defaults to `https://api.skaleagents.com`. Override only for local development or another API deployment. Empty values use the default. |
 | `SKALEAGENTS_OAUTH_CACHE` | No | OAuth cache path. Default `~/.config/skaleagents/oauth.json`. |
 | `SKALEAGENTS_OAUTH_ENABLED` | No | Set to `false` only to disable browser OAuth. |
+| `MCP_RESOURCE_URL` | No | Hosted transport audience. Defaults to `https://skaleagents.com/mcp`; must match the API OAuth configuration. |
 
 ## Auth behavior
 

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+export declare function protectedResourceMetadata(): Response;
+export declare function handleMcpRequest(request: Request): Promise<Response>;

package/dist/http.js

@@ -0,0 +1,134 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createServer } from "./server.js";
+import { getApiUrl } from "./config.js";
+const resource = process.env.MCP_RESOURCE_URL ?? "https://skaleagents.com/mcp";
+const metadataUrl = `${new URL(resource).origin}/.well-known/oauth-protected-resource/mcp`;
+const allowedOrigins = new Set([
+    "https://claude.ai",
+    "https://chatgpt.com",
+    "https://platform.openai.com",
+    new URL(resource).origin,
+]);
+const headers = {
+    "Cache-Control": "no-store",
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Authorization, Content-Type, Accept, MCP-Protocol-Version, MCP-Session-Id, Last-Event-ID",
+    "Access-Control-Expose-Headers": "WWW-Authenticate, MCP-Session-Id, MCP-Protocol-Version",
+};
+function json(status, body, extraHeaders = {}) {
+    return Response.json(body, {
+        status,
+        headers: { ...headers, ...extraHeaders },
+    });
+}
+function challenge() {
+    return json(401, { error: "unauthorized" }, {
+        "WWW-Authenticate": `Bearer resource_metadata="${metadataUrl}", scope="mcp"`,
+    });
+}
+export function protectedResourceMetadata() {
+    return json(200, {
+        resource,
+        authorization_servers: [getApiUrl()],
+        scopes_supported: ["mcp"],
+        bearer_methods_supported: ["header"],
+        resource_documentation: "https://skaleagents.com/settings",
+    });
+}
+export async function handleMcpRequest(request) {
+    const origin = request.headers.get("origin");
+    if (origin && !allowedOrigins.has(origin))
+        return json(403, { error: "origin_not_allowed" });
+    if (request.method === "OPTIONS")
+        return new Response(null, { status: 204, headers });
+    const authorization = request.headers.get("authorization");
+    if (!authorization || !/^Bearer [^\s]+$/i.test(authorization))
+        return challenge();
+    try {
+        // Validate the opaque token with its issuer, including the MCP audience.
+        const validation = await fetch(`${getApiUrl()}/api/oauth/mcp-token`, {
+            headers: { Authorization: authorization, Accept: "application/json" },
+            signal: AbortSignal.timeout(10_000),
+            redirect: "error",
+            cache: "no-store",
+        });
+        if (validation.status === 401 || validation.status === 403)
+            return challenge();
+        if (!validation.ok)
+            return json(503, { error: "authorization_unavailable" });
+        const token = (await validation.json());
+        if (!token.active ||
+            token.resource !== resource ||
+            token.scope !== "mcp" ||
+            !token.expiresAt ||
+            token.expiresAt * 1000 <= Date.now()) {
+            return challenge();
+        }
+    }
+    catch {
+        return json(503, { error: "authorization_unavailable" });
+    }
+    if (request.method !== "POST")
+        return json(405, { error: "method_not_allowed" }, { Allow: "POST, OPTIONS" });
+    if (!request.headers.get("content-type")?.startsWith("application/json"))
+        return json(415, { error: "expected_json" });
+    let body;
+    try {
+        const reader = request.body?.getReader();
+        if (!reader)
+            return json(400, { error: "missing_body" });
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > 2_100_000) {
+                    await reader.cancel();
+                    return json(413, { error: "request_too_large" });
+                }
+                chunks.push(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return json(400, {
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32700, message: "Invalid JSON" },
+        });
+    }
+    const server = createServer(true);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    try {
+        await server.connect(transport);
+        const response = await transport.handleRequest(request, {
+            parsedBody: body,
+        });
+        // Finish the JSON response before closing this request-scoped transport.
+        const responseBody = await response.arrayBuffer();
+        const responseHeaders = new Headers(response.headers);
+        for (const [key, value] of Object.entries(headers))
+            responseHeaders.set(key, value);
+        return new Response(responseBody.byteLength ? responseBody : null, {
+            status: response.status,
+            headers: responseHeaders,
+        });
+    }
+    catch {
+        return json(500, { error: "mcp_request_failed" });
+    }
+    finally {
+        await server.close();
+    }
+}

package/dist/iac/parse.d.ts

@@ -0,0 +1,25 @@
+export type IacFormat = "terraform" | "cloudformation" | "kubernetes";
+export type Path = (string | number)[];
+export type Location = {
+    line: number;
+    column: number;
+    path: string;
+};
+export type Resource = {
+    id: string;
+    type: string;
+    value: Record<string, unknown>;
+    locate: (path?: Path) => Location;
+};
+export type ParsedIac = {
+    format: IacFormat;
+    resources: Resource[];
+    warnings: string[];
+};
+export declare class ScanInputError extends Error {
+    constructor(message: string);
+}
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function array(value: unknown): unknown[];
+export declare function looksLikeIac(content: string): boolean;
+export declare function parseIac(content: string, requested?: IacFormat | "auto"): ParsedIac;

package/dist/iac/parse.js

@@ -0,0 +1,239 @@
+import hcl from "hcl2-parser";
+import { LineCounter, parseAllDocuments } from "yaml";
+export class ScanInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScanInputError";
+    }
+}
+export function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function array(value) {
+    return Array.isArray(value) ? value : value == null ? [] : [value];
+}
+// Reject deeply nested documents before rule traversal. Never return source text in errors.
+function checkShape(value, depth = 0, budget = { remaining: 50_000 }) {
+    if (depth > 80 || --budget.remaining < 0) {
+        throw new ScanInputError("Document exceeds the nesting or node limit. Split it into smaller inputs.");
+    }
+    if (value && typeof value === "object") {
+        for (const child of Object.values(value))
+            checkShape(child, depth + 1, budget);
+    }
+}
+export function looksLikeIac(content) {
+    if (content.trimStart().startsWith("{")) {
+        try {
+            const value = object(JSON.parse(content));
+            if (value.resource || value.Resources || (value.apiVersion && value.kind))
+                return true;
+        }
+        catch {
+            /* Other format detection still applies to incomplete input. */
+        }
+    }
+    return (/^\s*(?:resource|module|terraform|variable|provider)\s+["{]/m.test(content) ||
+        /^\s*(?:["']?Resources["']?\s*:|apiVersion\s*:)/m.test(content) ||
+        /^\s*\{\s*"(?:resource|Resources|apiVersion|AWSTemplateFormatVersion)"\s*:/.test(content));
+}
+export function parseIac(content, requested = "auto") {
+    if (!content.trim())
+        throw new ScanInputError("Content must not be empty or whitespace.");
+    const warnings = [];
+    const resources = [];
+    const isHcl = (requested === "terraform" && !content.trimStart().startsWith("{")) ||
+        (requested === "auto" &&
+            /^\s*(?:(?:resource|module|variable|provider|data|output)\s+"|(?:terraform|locals)\s*\{)/m.test(content));
+    if (isHcl) {
+        let data;
+        try {
+            const [parsed, error] = hcl.parseToObject(content);
+            if (error || !parsed)
+                throw new Error("parse");
+            data = parsed;
+        }
+        catch {
+            throw new ScanInputError("Invalid Terraform HCL. Check block syntax and attribute separators.");
+        }
+        checkShape(data);
+        // The HCL parser preserves expressions but does not expose source ranges.
+        // Report the resource declaration line and the exact parsed property path.
+        const searchable = content.replace(/\/\*[\s\S]*?\*\/|(?:#|\/\/)[^\n]*/g, (match) => match.replace(/[^\n]/g, " "));
+        for (const [type, instances] of Object.entries(object(object(data).resource))) {
+            for (const [name, blocks] of Object.entries(object(instances))) {
+                const declaration = new RegExp(`\\bresource\\s+"${escapeRegex(type)}"\\s+"${escapeRegex(name)}"`).exec(searchable);
+                const offset = declaration?.index ?? 0;
+                const before = content.slice(0, offset);
+                resources.push({
+                    id: `${type}.${name}`,
+                    type,
+                    value: object(array(blocks)[0]),
+                    locate: (path = []) => ({
+                        line: before.split("\n").length,
+                        column: offset - before.lastIndexOf("\n"),
+                        path: ["resource", type, name, ...path].join("."),
+                    }),
+                });
+            }
+        }
+        if (object(data).module)
+            warnings.push("External Terraform modules are not expanded. Scan their source separately.");
+        if (JSON.stringify(data).includes("${"))
+            warnings.push("Terraform expressions are not evaluated. Findings use literal values and declared settings.");
+        if (!resources.length)
+            warnings.push("No resource declarations found. Variables, data sources, and outputs are not scanned as resources.");
+        return { format: "terraform", resources, warnings };
+    }
+    const lines = new LineCounter();
+    const tags = [
+        "Ref",
+        "Sub",
+        "GetAtt",
+        "Join",
+        "Select",
+        "Split",
+        "If",
+        "Equals",
+        "Not",
+        "And",
+        "Or",
+        "FindInMap",
+        "ImportValue",
+        "GetAZs",
+        "Base64",
+        "Cidr",
+        "Transform",
+        "Length",
+        "ToJsonString",
+    ];
+    let documents;
+    try {
+        documents = parseAllDocuments(content, {
+            lineCounter: lines,
+            prettyErrors: false,
+            customTags: tags.flatMap((name) => ["scalar", "seq", "map"].map((kind) => ({
+                tag: `!${name}`,
+                ...(kind === "scalar" ? {} : { collection: kind }),
+                resolve: () => ({ __intrinsic: name }),
+            }))),
+        });
+    }
+    catch {
+        throw new ScanInputError("Invalid YAML or JSON document.");
+    }
+    let format = requested === "auto" ? undefined : requested;
+    for (const [documentIndex, doc] of documents.entries()) {
+        if (doc.errors.length || doc.warnings.length) {
+            const issue = doc.errors[0] ?? doc.warnings[0];
+            const line = lines.linePos(issue.pos[0]).line;
+            throw new ScanInputError(`Invalid or unsupported YAML/JSON syntax at line ${line}.`);
+        }
+        let data;
+        try {
+            data = doc.toJS({ maxAliasCount: 0 });
+        }
+        catch {
+            throw new ScanInputError("YAML aliases are not supported. Expand anchors before scanning.");
+        }
+        if (data == null)
+            continue;
+        checkShape(data);
+        const root = object(data);
+        const detected = root.Resources
+            ? "cloudformation"
+            : root.apiVersion && root.kind
+                ? "kubernetes"
+                : root.resource
+                    ? "terraform"
+                    : undefined;
+        format ??= detected;
+        if (!format || (detected && detected !== format))
+            throw new ScanInputError("Input format is unsupported or mixed. Submit one IaC format per scan.");
+        const add = (id, type, value, prefix) => {
+            resources.push({
+                id,
+                type,
+                value: object(value),
+                locate: (path = []) => {
+                    let node = doc.getIn([...prefix, ...path], true);
+                    if (!node?.range)
+                        node = doc.getIn(prefix, true);
+                    const position = lines.linePos(node?.range?.[0] ?? doc.range?.[0] ?? 0);
+                    return {
+                        line: position.line,
+                        column: position.col,
+                        path: [documentIndex, ...prefix, ...path].join("."),
+                    };
+                },
+            });
+        };
+        if (format === "cloudformation") {
+            if (!root.Resources ||
+                Array.isArray(root.Resources) ||
+                typeof root.Resources !== "object")
+                throw new ScanInputError("CloudFormation requires a Resources mapping.");
+            for (const [name, raw] of Object.entries(object(root.Resources))) {
+                const value = object(raw);
+                if (typeof value.Type !== "string")
+                    throw new ScanInputError("Each CloudFormation resource requires a Type.");
+                add(name, value.Type, value, ["Resources", name]);
+            }
+        }
+        else if (format === "terraform") {
+            if (!root.resource ||
+                Array.isArray(root.resource) ||
+                typeof root.resource !== "object")
+                throw new ScanInputError("Terraform JSON requires a resource mapping.");
+            for (const [type, instances] of Object.entries(object(root.resource))) {
+                for (const [name, value] of Object.entries(object(instances)))
+                    add(`${type}.${name}`, type, value, ["resource", type, name]);
+            }
+        }
+        else {
+            const manifests = root.kind === "List" ? array(root.items) : [root];
+            for (const [index, raw] of manifests.entries()) {
+                const value = object(raw);
+                if (typeof value.apiVersion !== "string" ||
+                    typeof value.kind !== "string")
+                    throw new ScanInputError("Each Kubernetes manifest requires apiVersion and kind.");
+                if ([
+                    "Pod",
+                    "Deployment",
+                    "StatefulSet",
+                    "DaemonSet",
+                    "ReplicaSet",
+                    "ReplicationController",
+                    "Job",
+                    "CronJob",
+                ].includes(value.kind)) {
+                    let spec = object(value.spec);
+                    if (value.kind === "CronJob")
+                        spec = object(object(spec.jobTemplate).spec);
+                    if (value.kind !== "Pod")
+                        spec = object(object(spec.template).spec);
+                    if (!Array.isArray(spec.containers) ||
+                        !spec.containers.length ||
+                        spec.containers.some((c) => typeof object(c).name !== "string" ||
+                            typeof object(c).image !== "string")) {
+                        throw new ScanInputError("Kubernetes workloads require a containers list with a name and image for each container.");
+                    }
+                }
+                const metadata = object(value.metadata);
+                add(`${value.kind}/${metadata.namespace ?? "default"}/${metadata.name ?? metadata.generateName ?? "unnamed"}`, value.kind, value, root.kind === "List" ? ["items", index] : []);
+            }
+        }
+    }
+    if (!format)
+        throw new ScanInputError("No IaC document found. Choose Terraform, CloudFormation, or Kubernetes.");
+    if (!resources.length)
+        warnings.push("No resources found in the submitted document.");
+    if (/(?:!(?:Ref|Sub|GetAtt|If)\b|"(?:Ref|Fn::\w+)"\s*:|\$\{)/.test(content))
+        warnings.push("Intrinsic functions and expressions are not evaluated. Only literal configuration is checked.");
+    return { format, resources, warnings };
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/iac/rules.d.ts

@@ -0,0 +1,16 @@
+import { type Resource } from "./parse.js";
+import type { Finding, FindingSeverity } from "../review.js";
+type Category = "security" | "reliability" | "cost";
+type Rule = {
+    category: Category;
+    severity: FindingSeverity;
+    title: string;
+    detail: string;
+    remediation: string;
+};
+export declare const rules: Record<string, Rule>;
+export declare function resourceFindings(resources: Resource[], format: string): {
+    findings: Finding[];
+    checked: Set<string>;
+};
+export {};