@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shield/discovery/dockerScanner.js

@@ -0,0 +1,543 @@
+"use strict";
+/**
+ * Docker environment scanner — Phase 2, READ-ONLY Docker daemon inspection.
+ *
+ * Maps a local Docker environment into the SAME normalized {@link RawEnvironment}
+ * shape the macOS scanner produces, so {@link topologyNormalizer.buildInfraPlane}
+ * folds it into the frozen topology envelope through the identical code path.
+ * Docker supplies the INFRA plane only; the ZT plane is still built solely from
+ * the Shield Broker.
+ *
+ * SECURITY MODEL (hard requirements — mirrors environmentScanner.ts):
+ *   - Only the `docker` binary is ever executed, and only with READ-ONLY
+ *     subcommands (version/info/ps/inspect/network ls|inspect/volume ls|inspect/
+ *     stats). No run/stop/rm/exec/build — enforced at type + runtime.
+ *   - Every spawn uses execFile with an ARGUMENT ARRAY — never a shell string,
+ *     never string-interpolation. Container/network/volume ids come from CLI
+ *     output; any id beginning with "-" is rejected and option parsing is
+ *     terminated with `--` so an id can never be read as a flag.
+ *   - Every spawn has a timeout + maxBuffer. A missing binary, a failed
+ *     `docker info` (daemon down), malformed output, or a timeout DEGRADES
+ *     GRACEFULLY: we return whatever we have plus a human-readable note. The
+ *     scan must never throw.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanDockerEnvironment = scanDockerEnvironment;
+const node_child_process_1 = require("node:child_process");
+const os = __importStar(require("node:os"));
+const logger_1 = require("../../shared/logger");
+// ── Binary + subcommand allowlist ────────────────────────────────────────────
+// The `docker` CLI only, and only read-only verbs. The first arg of every
+// invocation MUST be one of these; runAllowed asserts it at runtime.
+const DOCKER_BINARY = "docker";
+const ALLOWED_SUBCOMMANDS = new Set([
+    "version",
+    "info",
+    "ps",
+    "inspect",
+    "network",
+    "volume",
+    "stats",
+]);
+// For the two-word subcommands (`network`/`volume`), only these verbs are allowed.
+const ALLOWED_NETWORK_VERBS = new Set(["ls", "inspect"]);
+const ALLOWED_VOLUME_VERBS = new Set(["ls", "inspect"]);
+const EXEC_TIMEOUT_MS = 8_000;
+const STATS_TIMEOUT_MS = 6_000; // `docker stats --no-stream` can be slow; keep it bounded.
+const MAX_BUFFER = 8 * 1024 * 1024; // 8 MB
+/**
+ * Run `docker <args…>` read-only. Enforces the binary + subcommand allowlist at
+ * runtime, uses an argument array (no shell), and never throws.
+ */
+function runAllowed(args, timeoutMs = EXEC_TIMEOUT_MS) {
+    const sub = args[0];
+    if (!sub || !ALLOWED_SUBCOMMANDS.has(sub)) {
+        return Promise.resolve({ ok: false, stdout: "", stderr: "", error: `subcommand not allowlisted: ${sub ?? "<none>"}` });
+    }
+    if (sub === "network" && !ALLOWED_NETWORK_VERBS.has(args[1] ?? "")) {
+        return Promise.resolve({ ok: false, stdout: "", stderr: "", error: `network verb not allowlisted: ${args[1] ?? "<none>"}` });
+    }
+    if (sub === "volume" && !ALLOWED_VOLUME_VERBS.has(args[1] ?? "")) {
+        return Promise.resolve({ ok: false, stdout: "", stderr: "", error: `volume verb not allowlisted: ${args[1] ?? "<none>"}` });
+    }
+    return new Promise((resolve) => {
+        (0, node_child_process_1.execFile)(DOCKER_BINARY, args, { timeout: timeoutMs, maxBuffer: MAX_BUFFER, windowsHide: true }, (err, stdout, stderr) => {
+            if (err) {
+                const isMissing = err.code === "ENOENT";
+                resolve({
+                    ok: false,
+                    stdout: stdout ?? "",
+                    stderr: stderr ?? "",
+                    error: isMissing ? "missing" : err.message,
+                });
+                return;
+            }
+            resolve({ ok: true, stdout: stdout ?? "", stderr: stderr ?? "", error: null });
+        });
+    });
+}
+/** A container/network/volume id is safe to pass after `--` unless it starts with "-". */
+function safeId(id) {
+    return !!id && !/^-/.test(id);
+}
+/** Parse one JSON object (single line). Returns null on failure. */
+function parseJsonObject(text) {
+    const t = text.trim();
+    if (!t)
+        return null;
+    try {
+        const v = JSON.parse(t);
+        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse NDJSON (one JSON object per line, as `--format '{{json .}}'` emits). */
+function parseNdjson(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const v = JSON.parse(t);
+            if (v && typeof v === "object" && !Array.isArray(v))
+                out.push(v);
+        }
+        catch {
+            // skip malformed line; degrade gracefully
+        }
+    }
+    return out;
+}
+function asRecord(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+}
+function str(rec, ...keys) {
+    for (const k of keys) {
+        const v = rec[k];
+        if (typeof v === "string" && v.length)
+            return v;
+        if (typeof v === "number")
+            return String(v);
+    }
+    return null;
+}
+function num(rec, ...keys) {
+    for (const k of keys) {
+        const v = rec[k];
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+        if (typeof v === "string" && v.trim() && Number.isFinite(Number(v)))
+            return Number(v);
+    }
+    return null;
+}
+/** Parse a "12.34%" string from `docker stats` into a number. Returns null on failure. */
+function parsePercent(v) {
+    if (!v)
+        return undefined;
+    const n = Number(v.replace("%", "").trim());
+    return Number.isFinite(n) ? n : undefined;
+}
+// ── Docker status → frozen status mapping ─────────────────────────────────────
+// The viz `dotFor()` set recognizes running/stopped (among others). Docker
+// container State is one of: running, exited, dead, created, paused, restarting,
+// removing. Per the contract: running→running; everything else→stopped.
+function mapDockerState(state) {
+    const s = (state ?? "").toLowerCase();
+    if (s === "running" || s === "restarting")
+        return { status: "running", running: true };
+    // exited | dead | created | paused | removing | unknown → stopped
+    return { status: "stopped", running: false };
+}
+// ── Daemon/host facts ─────────────────────────────────────────────────────────
+async function collectHostFacts(notes) {
+    // Pure-Node host facts (mirrors the Mac scanner's local section).
+    const cpus = os.cpus() ?? [];
+    const totalMemBytes = os.totalmem();
+    const ifaces = os.networkInterfaces();
+    const interfaces = [];
+    for (const [name, addrs] of Object.entries(ifaces)) {
+        for (const a of addrs ?? []) {
+            if (a.internal)
+                continue;
+            const fam = a.family;
+            interfaces.push({
+                name,
+                address: a.address,
+                family: typeof fam === "number" ? `IPv${fam}` : fam,
+                cidr: a.cidr ?? null,
+            });
+        }
+    }
+    // Engine facts via `docker version` + `docker info`. `docker info` failing is
+    // the canonical "daemon not reachable" signal.
+    let engineVersion = null;
+    let engineOs = null;
+    let engineArch = null;
+    let containersRunning = null;
+    let containersStopped = null;
+    let engineMemBytes = null;
+    let operatingSystem = null;
+    const ver = await runAllowed(["version", "--format", "{{json .}}"]);
+    if (ver.ok) {
+        const obj = parseJsonObject(ver.stdout);
+        const server = obj ? asRecord(obj["Server"]) : null;
+        if (server) {
+            engineVersion = str(server, "Version");
+            engineOs = str(server, "Os");
+            engineArch = str(server, "Arch");
+        }
+    }
+    const info = await runAllowed(["info", "--format", "{{json .}}"]);
+    let daemonUp = false;
+    if (info.ok) {
+        daemonUp = true;
+        const obj = parseJsonObject(info.stdout);
+        if (obj) {
+            containersRunning = num(obj, "ContainersRunning");
+            containersStopped = num(obj, "ContainersStopped");
+            engineMemBytes = num(obj, "MemTotal");
+            operatingSystem = str(obj, "OperatingSystem");
+            if (!engineArch)
+                engineArch = str(obj, "Architecture");
+        }
+    }
+    else if (info.error === "missing") {
+        notes.push("`docker` CLI not found — Docker infra discovery skipped");
+    }
+    else {
+        notes.push(`docker info failed (${info.error}) — Docker daemon unreachable; infra plane empty`);
+    }
+    const host = {
+        hostname: os.hostname(),
+        arch: os.arch(),
+        platform: os.platform(),
+        release: os.release(),
+        vcpu: cpus.length,
+        cpuModel: cpus[0]?.model?.trim() ?? "unknown",
+        totalMemBytes,
+        totalMemGB: `${Math.round(totalMemBytes / 1024 ** 3)} GB`,
+        interfaces,
+        containerCliPresent: daemonUp,
+    };
+    // Stash engine facts on the host record via the (open) RawHostFacts? No — keep
+    // RawHostFacts shape stable. The normalizer reads host fields it knows; engine
+    // detail is surfaced through notes instead to avoid contract drift.
+    if (daemonUp) {
+        const parts = [
+            engineVersion ? `engine ${engineVersion}` : null,
+            operatingSystem ?? (engineOs ? `${engineOs}/${engineArch ?? "?"}` : null),
+            containersRunning != null ? `${containersRunning} running` : null,
+            containersStopped != null ? `${containersStopped} stopped` : null,
+            engineMemBytes != null ? `${Math.round(engineMemBytes / 1024 ** 3)} GB engine mem` : null,
+        ].filter(Boolean);
+        if (parts.length)
+            notes.push(`Docker daemon: ${parts.join(", ")}`);
+    }
+    return { host, daemonUp };
+}
+// ── Containers ────────────────────────────────────────────────────────────────
+async function listContainers(notes) {
+    // `-a` so stopped containers appear (the viz shows stopped nodes). NDJSON out.
+    const ps = await runAllowed(["ps", "-a", "--format", "{{json .}}"]);
+    if (!ps.ok) {
+        if (ps.error !== "missing")
+            notes.push(`docker ps -a failed (${ps.error}); no containers discovered`);
+        return [];
+    }
+    const rows = parseNdjson(ps.stdout);
+    const out = [];
+    for (const r of rows) {
+        const id = str(r, "ID", "Id") ?? "";
+        if (!id)
+            continue;
+        // ps `State` is the canonical lifecycle word (running/exited/created/paused…).
+        const { status, running } = mapDockerState(str(r, "State"));
+        // ps `Networks` is a comma-joined string; `Ports` is a comma-joined string.
+        const netStr = str(r, "Networks");
+        const portStr = str(r, "Ports");
+        out.push({
+            id,
+            name: str(r, "Names", "Name") ?? id,
+            image: str(r, "Image"),
+            status,
+            running,
+            ip: null, // ps doesn't carry the IP; inspect fills it.
+            networks: netStr ? netStr.split(",").map((s) => s.trim()).filter(Boolean) : [],
+            volumes: [], // inspect fills named volumes.
+            ports: portStr ? portStr.split(",").map((s) => s.trim()).filter(Boolean) : [],
+            command: str(r, "Command"),
+        });
+    }
+    await enrichContainers(out, notes);
+    return out;
+}
+/**
+ * Per-container enrichment via `docker inspect <id>`. Fills ip, networks (with
+ * subnet-bearing names), named volumes, command, image. Failures are silent
+ * per-container (we already have a node from `ps`).
+ */
+async function enrichContainers(containers, notes) {
+    let failures = 0;
+    for (const c of containers) {
+        if (!safeId(c.id)) {
+            failures++;
+            continue;
+        }
+        const res = await runAllowed(["inspect", "--", c.id]);
+        if (!res.ok) {
+            failures++;
+            continue;
+        }
+        // `docker inspect` returns a JSON ARRAY of one object.
+        let parsed;
+        try {
+            parsed = JSON.parse(res.stdout.trim());
+        }
+        catch {
+            continue;
+        }
+        const rec = Array.isArray(parsed) ? asRecord(parsed[0]) : asRecord(parsed);
+        if (!rec)
+            continue;
+        const config = asRecord(rec["Config"]);
+        const netSettings = asRecord(rec["NetworkSettings"]);
+        const state = asRecord(rec["State"]);
+        if (state) {
+            const mapped = mapDockerState(str(state, "Status"));
+            c.status = mapped.status;
+            c.running = mapped.running;
+        }
+        if (!c.image && config)
+            c.image = str(config, "Image");
+        if (!c.command && config) {
+            const cmd = config["Cmd"];
+            if (Array.isArray(cmd))
+                c.command = cmd.filter((x) => typeof x === "string").join(" ") || c.command;
+            else
+                c.command = str(config, "Cmd") ?? c.command;
+        }
+        // NetworkSettings.Networks: { "<netName>": { IPAddress, NetworkID, … } }
+        const networks = netSettings ? asRecord(netSettings["Networks"]) : null;
+        if (networks) {
+            const names = Object.keys(networks);
+            if (names.length)
+                c.networks = names;
+            for (const n of names) {
+                const ns = asRecord(networks[n]);
+                const ip = ns ? str(ns, "IPAddress") : null;
+                if (ip && !c.ip)
+                    c.ip = ip;
+            }
+        }
+        // Mounts: [{ Type:"volume", Name, Source, Destination }]. Only NAMED volumes
+        // (Type === "volume" with a Name) map to volume nodes; bind mounts are skipped.
+        const mounts = rec["Mounts"];
+        if (Array.isArray(mounts)) {
+            const vols = [];
+            for (const m of mounts) {
+                const mr = asRecord(m);
+                if (!mr)
+                    continue;
+                if (str(mr, "Type") === "volume") {
+                    const name = str(mr, "Name");
+                    if (name)
+                        vols.push(name);
+                }
+            }
+            if (vols.length)
+                c.volumes = vols;
+        }
+    }
+    if (failures && failures === containers.length) {
+        notes.push("docker inspect unavailable for all containers; node detail is partial");
+    }
+}
+// ── Networks ──────────────────────────────────────────────────────────────────
+async function listNetworks(notes) {
+    const ls = await runAllowed(["network", "ls", "--format", "{{json .}}"]);
+    if (!ls.ok) {
+        if (ls.error !== "missing")
+            notes.push(`docker network ls failed (${ls.error})`);
+        return [];
+    }
+    const rows = parseNdjson(ls.stdout);
+    const out = [];
+    for (const r of rows) {
+        const name = str(r, "Name");
+        const id = str(r, "ID", "Id");
+        if (!name && !id)
+            continue;
+        out.push({
+            id: id ?? name,
+            name: name ?? id,
+            subnet: null,
+            gateway: null,
+            driver: str(r, "Driver"),
+        });
+    }
+    // Optional enrichment: subnet/gateway via `docker network inspect`.
+    for (const net of out) {
+        if (!safeId(net.id))
+            continue;
+        const res = await runAllowed(["network", "inspect", "--", net.id]);
+        if (!res.ok)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(res.stdout.trim());
+        }
+        catch {
+            continue;
+        }
+        const rec = Array.isArray(parsed) ? asRecord(parsed[0]) : asRecord(parsed);
+        if (!rec)
+            continue;
+        const ipam = asRecord(rec["IPAM"]);
+        const cfg = ipam ? ipam["Config"] : null;
+        if (Array.isArray(cfg) && cfg.length) {
+            const first = asRecord(cfg[0]);
+            if (first) {
+                net.subnet = str(first, "Subnet");
+                net.gateway = str(first, "Gateway");
+            }
+        }
+    }
+    return out;
+}
+// ── Volumes ───────────────────────────────────────────────────────────────────
+async function listVolumes(notes) {
+    const ls = await runAllowed(["volume", "ls", "--format", "{{json .}}"]);
+    if (!ls.ok) {
+        if (ls.error !== "missing")
+            notes.push(`docker volume ls failed (${ls.error})`);
+        return [];
+    }
+    const rows = parseNdjson(ls.stdout);
+    const out = [];
+    for (const r of rows) {
+        const name = str(r, "Name");
+        if (!name)
+            continue;
+        out.push({
+            id: name,
+            name,
+            driver: str(r, "Driver"),
+            source: str(r, "Mountpoint", "Source"),
+        });
+    }
+    return out;
+}
+// ── Live metrics (best-effort) ────────────────────────────────────────────────
+async function attachStats(containers, notes) {
+    const running = containers.filter((c) => c.running);
+    if (!running.length)
+        return;
+    const res = await runAllowed(["stats", "--no-stream", "--format", "{{json .}}"], STATS_TIMEOUT_MS);
+    if (!res.ok) {
+        notes.push(res.error === "missing"
+            ? "docker stats unavailable — live cpu/mem metrics skipped"
+            : `docker stats failed (${res.error}) — live cpu/mem metrics skipped`);
+        return;
+    }
+    const rows = parseNdjson(res.stdout);
+    // Index stats by both full id and short id (and name) for robust matching.
+    const byKey = new Map();
+    for (const r of rows) {
+        const sid = str(r, "ID", "Container");
+        const name = str(r, "Name");
+        if (sid)
+            byKey.set(sid, r);
+        if (name)
+            byKey.set(name, r);
+    }
+    for (const c of running) {
+        const row = byKey.get(c.id) ??
+            byKey.get(c.id.slice(0, 12)) ??
+            byKey.get(c.name) ??
+            // stats short id vs our (possibly full) id: match by prefix.
+            [...byKey.entries()].find(([k]) => c.id.startsWith(k) || k.startsWith(c.id))?.[1];
+        if (!row)
+            continue;
+        const cpu = parsePercent(str(row, "CPUPerc"));
+        const mem = parsePercent(str(row, "MemPerc"));
+        if (cpu !== undefined)
+            c.cpu = cpu;
+        if (mem !== undefined)
+            c.mem = mem;
+    }
+}
+// ── Public entry point ────────────────────────────────────────────────────────
+/**
+ * Inspect the local Docker environment READ-ONLY and return the raw environment
+ * in the SAME shape as {@link scanMacEnvironment}. Never throws: any failure is
+ * captured in `notes` and the corresponding section is returned empty/partial.
+ *
+ * `listeningPorts` is left empty for the Docker provider — published container
+ * ports are already surfaced per-container; host-level TCP LISTEN inspection is
+ * the macOS scanner's concern.
+ */
+async function scanDockerEnvironment() {
+    const notes = [];
+    const { host, daemonUp } = await collectHostFacts(notes);
+    // If the daemon is unreachable, return an empty-but-valid environment (host
+    // facts only) with a clear note — never throw.
+    if (!daemonUp) {
+        return { host, networks: [], containers: [], volumes: [], listeningPorts: [], notes };
+    }
+    let containers = [];
+    let networks = [];
+    let volumes = [];
+    try {
+        [containers, networks, volumes] = await Promise.all([
+            listContainers(notes),
+            listNetworks(notes),
+            listVolumes(notes),
+        ]);
+        // Stats after we know which containers are running (best-effort, non-blocking
+        // on failure).
+        await attachStats(containers, notes);
+    }
+    catch (err) {
+        logger_1.logger.warn("scanDockerEnvironment: unexpected error during inspection", { err: String(err) });
+        notes.push(`Docker environment scan partially failed: ${String(err)}`);
+    }
+    return { host, networks, containers, volumes, listeningPorts: [], notes };
+}
+//# sourceMappingURL=dockerScanner.js.map

package/build/shield/discovery/endpointScanner.d.ts

@@ -0,0 +1,3 @@
+import type { EndpointInfo, FrameworkInfo } from "../types";
+export declare function scanEndpoints(projectPath: string, frameworkInfo: FrameworkInfo): Promise<EndpointInfo[]>;
+//# sourceMappingURL=endpointScanner.d.ts.map