@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shield/discovery/endpointScanner.js

@@ -0,0 +1,306 @@
+"use strict";
+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.scanEndpoints = scanEndpoints;
+/** Extract HTTP endpoints from application source code.
+ *
+ * Workstream-1 credibility upgrade (#13d, #13e):
+ *  - HTTP method is derived from the actual route construct (decorator verb,
+ *    Next.js named export, router call). Routes whose method cannot be
+ *    determined are emitted as "unknown" — never silently defaulted to GET.
+ *  - auth_method is classified per route from inline middleware where possible
+ *    (high confidence) and from file-level signals otherwise (low confidence),
+ *    using a defined enum: public | session | jwt | signature | scheduler |
+ *    token | api_key | oauth | unknown. "unknown" no longer dominates output.
+ *  - Every endpoint carries a line number, detection provenance, and confidence.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const glob_1 = require("glob");
+const HTTP_VERBS = ["get", "post", "put", "delete", "patch", "head", "options", "all"];
+/** Map a character offset to a 1-based line number. */
+function lineOf(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i++)
+        if (content[i] === "\n")
+            line++;
+    return line;
+}
+/** Classify auth signals found in a snippet (a route's middleware args, or a file). */
+function classifyAuthSignal(text) {
+    if (/getServerSession|next-auth|requireSession|express-session|\bsession\b|passport\.authenticate/i.test(text)) {
+        if (/passport/i.test(text))
+            return "oauth";
+        return "session";
+    }
+    if (/getToken|jsonwebtoken|\bjwt\b|verifyJwt|bearer|expressJwt|express-jwt/i.test(text))
+        return "jwt";
+    if (/verifySignature|svix|stripe\.webhooks|x-hub-signature|hmac|webhookSecret/i.test(text))
+        return "signature";
+    if (/x-vercel-cron|CRON_SECRET|isCron|cron/i.test(text))
+        return "scheduler";
+    if (/api[_-]?key|apiKey|x-api-key/i.test(text))
+        return "api_key";
+    if (/requireAuth|isAuthenticated|ensureAuth|authMiddleware|withApiAuth|auth\(\)|authGuard|protect\b/i.test(text))
+        return "token";
+    return null;
+}
+async function scanEndpoints(projectPath, frameworkInfo) {
+    if (frameworkInfo.framework === "next.js")
+        return scanNextJsRoutes(projectPath);
+    const ext = frameworkInfo.runtime === "python" ? "**/*.py" : "**/*.{js,ts,mjs}";
+    const files = await (0, glob_1.glob)(ext, {
+        cwd: projectPath,
+        ignore: ["node_modules/**", "venv/**", ".venv/**", "__pycache__/**", "dist/**", "build/**", "*.test.*", "*.spec.*"],
+        absolute: true,
+    });
+    const endpoints = [];
+    for (const file of files) {
+        const content = fs.readFileSync(file, "utf8");
+        const rel = path.relative(projectPath, file);
+        const fileAuth = classifyAuthSignal(content); // file-level fallback signal
+        if (frameworkInfo.runtime === "python") {
+            extractFlask(content, rel, fileAuth, endpoints);
+            extractFastApi(content, rel, fileAuth, endpoints);
+            extractDjango(content, rel, fileAuth, endpoints);
+        }
+        else {
+            extractExpressLike(content, rel, fileAuth, endpoints);
+        }
+    }
+    return dedup(endpoints);
+}
+/** Express / Fastify / Koa-router: app.get('/x', mwA, mwB, handler) */
+function extractExpressLike(content, file, fileAuth, out) {
+    // Capture verb, path, and the rest of the call arguments (for inline-middleware auth detection).
+    const routeRe = /(?:app|router|fastify)\.(get|post|put|delete|patch|all)\s*\(\s*['"`]([^'"`]+)['"`]([^)]*)/gi;
+    for (const m of content.matchAll(routeRe)) {
+        const method = m[1].toLowerCase();
+        const routePath = m[2];
+        const argsTail = m[3] || "";
+        if (!routePath || routePath.startsWith("__"))
+            continue;
+        const inline = classifyAuthSignal(argsTail);
+        out.push({
+            type: routePath.startsWith("/api") ? "api" : "web",
+            method,
+            path: routePath,
+            protocol: "https",
+            file,
+            auth_method: inline ?? fileAuth ?? "unknown",
+            line: lineOf(content, m.index ?? 0),
+            detected_via: "router-call",
+            confidence: "high",
+            auth_confidence: inline ? "high" : fileAuth ? "low" : "low",
+        });
+    }
+    // Mount points (middleware sub-routers) — informational, method "all".
+    const useRe = /(?:app|router)\.use\s*\(\s*['"`]([^'"`]+)['"`]/gi;
+    for (const m of content.matchAll(useRe)) {
+        const routePath = m[1];
+        if (!routePath || !routePath.startsWith("/"))
+            continue;
+        out.push({
+            type: routePath.startsWith("/api") ? "api" : "web",
+            method: "all",
+            path: routePath,
+            protocol: "https",
+            file,
+            auth_method: fileAuth ?? "unknown",
+            line: lineOf(content, m.index ?? 0),
+            detected_via: "router-call",
+            confidence: "medium",
+            auth_confidence: fileAuth ? "low" : "low",
+        });
+    }
+}
+/** Flask: @app.route('/x', methods=['GET','POST']) — default GET when methods omitted. */
+function extractFlask(content, file, fileAuth, out) {
+    const re = /@(?:app|blueprint|bp)\.route\s*\(\s*['"`]([^'"`]+)['"`](?:[^)]*?methods\s*=\s*\[([^\]]+)\])?/gi;
+    for (const m of content.matchAll(re)) {
+        const routePath = m[1];
+        if (!routePath)
+            continue;
+        const methodsRaw = m[2];
+        const methods = methodsRaw
+            ? methodsRaw.split(",").map(s => s.replace(/['"`\s]/g, "").toLowerCase()).filter(Boolean)
+            : ["get"];
+        for (const method of methods) {
+            out.push({
+                type: routePath.startsWith("/api") ? "api" : "web",
+                method: HTTP_VERBS.includes(method) ? method : "unknown",
+                path: routePath,
+                protocol: "https",
+                file,
+                auth_method: fileAuth ?? "unknown",
+                line: lineOf(content, m.index ?? 0),
+                detected_via: "decorator",
+                confidence: "high",
+                auth_confidence: fileAuth ? "low" : "low",
+            });
+        }
+    }
+}
+/** FastAPI: @app.get('/x') / @router.post('/x') */
+function extractFastApi(content, file, fileAuth, out) {
+    const re = /@(?:app|router)\.(get|post|put|delete|patch|head|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
+    for (const m of content.matchAll(re)) {
+        const method = m[1].toLowerCase();
+        const routePath = m[2];
+        if (!routePath)
+            continue;
+        // FastAPI auth often via Depends(...) on the function signature near the decorator.
+        const depends = /Depends\s*\(/.test(content.slice(m.index ?? 0, (m.index ?? 0) + 400));
+        out.push({
+            type: routePath.startsWith("/api") ? "api" : "web",
+            method,
+            path: routePath,
+            protocol: "https",
+            file,
+            auth_method: depends ? (fileAuth ?? "token") : (fileAuth ?? "unknown"),
+            line: lineOf(content, m.index ?? 0),
+            detected_via: "decorator",
+            confidence: "high",
+            auth_confidence: depends ? "medium" : fileAuth ? "low" : "low",
+        });
+    }
+}
+/** Django URLconf: path('x/', view) — method is not declared at the URL layer. */
+function extractDjango(content, file, fileAuth, out) {
+    const re = /(?:re_)?path\s*\(\s*r?['"`]([^'"`]+)['"`]/gi;
+    for (const m of content.matchAll(re)) {
+        const routePath = m[1];
+        if (!routePath)
+            continue;
+        const norm = routePath.startsWith("/") ? routePath : "/" + routePath;
+        out.push({
+            type: norm.startsWith("/api") ? "api" : "web",
+            method: "unknown", // URLconf does not bind a method; the view decides
+            path: norm,
+            protocol: "https",
+            file,
+            auth_method: fileAuth ?? "unknown",
+            line: lineOf(content, m.index ?? 0),
+            detected_via: "url-conf",
+            confidence: "medium",
+            auth_confidence: fileAuth ? "low" : "low",
+        });
+    }
+}
+function scanNextJsRoutes(projectPath) {
+    const endpoints = [];
+    const dirs = ["app", "pages", "src/app", "src/pages"].map(d => path.join(projectPath, d));
+    const routeDir = dirs.find(d => fs.existsSync(d));
+    if (!routeDir)
+        return endpoints;
+    const apiDir = path.join(routeDir, "api");
+    if (fs.existsSync(apiDir))
+        walkDir(apiDir, routeDir, endpoints, "api", projectPath);
+    walkDir(routeDir, routeDir, endpoints, "web", projectPath);
+    return dedup(endpoints);
+}
+/** Next.js App Router route handlers export named functions per HTTP method. */
+function parseRouteHandlerMethods(content) {
+    const methods = new Set();
+    // export async function GET(...) / export function POST(...)
+    for (const m of content.matchAll(/export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/g)) {
+        methods.add(m[1].toLowerCase());
+    }
+    // export const GET = ... / export { GET, POST }
+    for (const m of content.matchAll(/export\s+const\s+(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/g)) {
+        methods.add(m[1].toLowerCase());
+    }
+    for (const m of content.matchAll(/export\s*\{([^}]*)\}/g)) {
+        for (const tok of m[1].split(",")) {
+            const name = tok.trim().split(/\s+as\s+/i)[0].trim().toUpperCase();
+            if (["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"].includes(name))
+                methods.add(name.toLowerCase());
+        }
+    }
+    return [...methods];
+}
+function walkDir(dir, baseDir, endpoints, type, projectPath) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+            walkDir(path.join(dir, entry.name), baseDir, endpoints, type, projectPath);
+        }
+        else if (entry.isFile() && /^(page|route|index)\.(js|ts|jsx|tsx)$/.test(entry.name)) {
+            const full = path.join(dir, entry.name);
+            const routePath = "/" + path.relative(baseDir, dir).replace(/\\/g, "/");
+            const rel = path.relative(projectPath, full);
+            const isRouteHandler = /^route\./.test(entry.name);
+            const content = fs.readFileSync(full, "utf8");
+            const fileAuth = classifyAuthSignal(content);
+            if (isRouteHandler) {
+                const methods = parseRouteHandlerMethods(content);
+                const list = methods.length > 0 ? methods : ["unknown"];
+                for (const method of list) {
+                    endpoints.push({
+                        type, method, path: routePath, protocol: "https", file: rel,
+                        auth_method: fileAuth ?? "unknown",
+                        line: 1,
+                        detected_via: methods.length > 0 ? "named-export" : "fallback",
+                        confidence: methods.length > 0 ? "high" : "low",
+                        auth_confidence: fileAuth ? "low" : "low",
+                    });
+                }
+            }
+            else {
+                // page/index files render a view → GET-equivalent web route.
+                endpoints.push({
+                    type, method: "get", path: routePath, protocol: "https", file: rel,
+                    auth_method: fileAuth ?? "unknown",
+                    line: 1,
+                    detected_via: "page-file",
+                    confidence: "medium",
+                    auth_confidence: fileAuth ? "low" : "low",
+                });
+            }
+        }
+    }
+}
+function dedup(endpoints) {
+    const seen = new Set();
+    return endpoints.filter(e => {
+        const key = `${e.method}:${e.path}:${e.file}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+//# sourceMappingURL=endpointScanner.js.map

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

@@ -0,0 +1,86 @@
+/**
+ * macOS environment scanner — Phase 1, READ-ONLY host inspection.
+ *
+ * Produces the raw infra-plane material (host + networks + containers + volumes
+ * + candidate service nodes) that {@link topologyNormalizer} folds into the
+ * frozen topology envelope. The vocabulary here is deliberately neutral; the
+ * normalizer is responsible for conforming to the viz contract.
+ *
+ * SECURITY MODEL (hard requirements):
+ *   - Only the three allowlisted binaries below are ever executed.
+ *   - Every spawn uses execFile with an ARGUMENT ARRAY — never a shell string,
+ *     never string-interpolation of any value. There is nothing untrusted to
+ *     interpolate (all args are literals), but we keep the discipline anyway.
+ *   - Every spawn has a timeout. A missing binary, a non-zero exit, malformed
+ *     output, or a timeout DEGRADES GRACEFULLY: we return whatever we have plus
+ *     a human-readable note. The tool must never crash.
+ */
+export interface RawHostFacts {
+    hostname: string;
+    arch: string;
+    platform: string;
+    release: string;
+    vcpu: number;
+    cpuModel: string;
+    totalMemBytes: number;
+    totalMemGB: string;
+    interfaces: Array<{
+        name: string;
+        address: string;
+        family: string;
+        cidr: string | null;
+    }>;
+    containerCliPresent: boolean;
+}
+export interface RawNetwork {
+    id: string;
+    name: string;
+    subnet: string | null;
+    gateway: string | null;
+    driver: string | null;
+}
+export interface RawContainer {
+    id: string;
+    name: string;
+    image: string | null;
+    status: string;
+    running: boolean;
+    ip: string | null;
+    networks: string[];
+    volumes: string[];
+    ports: string[];
+    command: string | null;
+    /** Live CPU % (0–100+) for RUNNING containers when a metrics source provides it; omitted otherwise. */
+    cpu?: number;
+    /** Live memory % (0–100) for RUNNING containers when a metrics source provides it; omitted otherwise. */
+    mem?: number;
+}
+export interface RawVolume {
+    id: string;
+    name: string;
+    driver: string | null;
+    source: string | null;
+}
+export interface RawListeningPort {
+    port: number;
+    proto: string;
+    address: string;
+    process: string | null;
+    pid: number | null;
+}
+export interface RawEnvironment {
+    host: RawHostFacts;
+    networks: RawNetwork[];
+    containers: RawContainer[];
+    volumes: RawVolume[];
+    listeningPorts: RawListeningPort[];
+    /** Human-readable degradation/diagnostic notes (missing binaries, parse fallbacks, …). */
+    notes: string[];
+}
+/**
+ * Inspect the local macOS host READ-ONLY and return the raw environment. Never
+ * throws: any failure is captured in `notes` and the corresponding section is
+ * returned empty/partial.
+ */
+export declare function scanMacEnvironment(): Promise<RawEnvironment>;
+//# sourceMappingURL=environmentScanner.d.ts.map