@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shield/discovery/frameworkDetector.js

@@ -0,0 +1,114 @@
+"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.detectFramework = detectFramework;
+/** Detect application framework and runtime from project files. */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const FRAMEWORK_MAP = {
+    express: { framework: "express", runtime: "node" },
+    next: { framework: "next.js", runtime: "node" },
+    koa: { framework: "koa", runtime: "node" },
+    fastify: { framework: "fastify", runtime: "node" },
+    "@nestjs/core": { framework: "nestjs", runtime: "node" },
+    hapi: { framework: "hapi", runtime: "node" },
+    flask: { framework: "flask", runtime: "python" },
+    django: { framework: "django", runtime: "python" },
+    fastapi: { framework: "fastapi", runtime: "python" },
+    uvicorn: { framework: "fastapi", runtime: "python" },
+};
+async function detectFramework(projectPath) {
+    const result = { framework: "unknown", runtime: "unknown", version: null, packageManager: null };
+    // Node.js
+    const pkgPath = path.join(projectPath, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            result.packageManager = fs.existsSync(path.join(projectPath, "yarn.lock")) ? "yarn"
+                : fs.existsSync(path.join(projectPath, "pnpm-lock.yaml")) ? "pnpm" : "npm";
+            for (const [dep, meta] of Object.entries(FRAMEWORK_MAP)) {
+                if (allDeps[dep]) {
+                    result.framework = meta.framework;
+                    result.runtime = meta.runtime;
+                    result.version = String(allDeps[dep]).replace(/[\^~>=<]/g, "");
+                    break;
+                }
+            }
+            if (pkg.engines?.node)
+                result.runtimeVersion = pkg.engines.node;
+        }
+        catch { /* ignore parse errors */ }
+    }
+    // Python requirements.txt
+    const reqPath = path.join(projectPath, "requirements.txt");
+    if (fs.existsSync(reqPath) && result.framework === "unknown") {
+        const content = fs.readFileSync(reqPath, "utf8").toLowerCase();
+        for (const [dep, meta] of Object.entries(FRAMEWORK_MAP)) {
+            if (content.includes(dep)) {
+                result.framework = meta.framework;
+                result.runtime = meta.runtime;
+                const match = content.match(new RegExp(`${dep}[=~><]*([\\d.]+)`));
+                if (match)
+                    result.version = match[1];
+                break;
+            }
+        }
+        result.packageManager = "pip";
+    }
+    // pyproject.toml
+    const pyprojectPath = path.join(projectPath, "pyproject.toml");
+    if (fs.existsSync(pyprojectPath) && result.framework === "unknown") {
+        const content = fs.readFileSync(pyprojectPath, "utf8").toLowerCase();
+        for (const [dep, meta] of Object.entries(FRAMEWORK_MAP)) {
+            if (content.includes(dep)) {
+                result.framework = meta.framework;
+                result.runtime = meta.runtime;
+                break;
+            }
+        }
+        result.packageManager = "poetry";
+    }
+    // Docker
+    const dockerfilePath = path.join(projectPath, "Dockerfile");
+    if (fs.existsSync(dockerfilePath)) {
+        const dockerfile = fs.readFileSync(dockerfilePath, "utf8");
+        const fromMatch = dockerfile.match(/FROM\s+(\S+)/i);
+        if (fromMatch)
+            result.dockerImage = fromMatch[1];
+    }
+    return result;
+}
+//# sourceMappingURL=frameworkDetector.js.map

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

@@ -0,0 +1,12 @@
+import type { FrameworkInfo, EndpointInfo, ExternalService, DataStore, PiiField, SecurityManifest } from "../types";
+interface GenerateInput {
+    framework: FrameworkInfo;
+    endpoints: EndpointInfo[];
+    externalServices: ExternalService[];
+    dataStores: DataStore[];
+    piiFields: PiiField[];
+    projectPath: string;
+}
+export declare function generateManifest(input: GenerateInput): SecurityManifest;
+export {};
+//# sourceMappingURL=manifestGenerator.d.ts.map

package/build/shield/discovery/manifestGenerator.js

@@ -0,0 +1,124 @@
+"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.generateManifest = generateManifest;
+/** Generate security manifest from discovery results. */
+const path = __importStar(require("path"));
+const piiDetector_1 = require("./piiDetector");
+function generateManifest(input) {
+    const { framework, endpoints, externalServices, dataStores, piiFields, projectPath } = input;
+    const complianceHints = (0, piiDetector_1.getComplianceHints)(piiFields);
+    const sensitivityLevel = (0, piiDetector_1.getSensitivityLevel)(piiFields);
+    const defaultPort = inferPort(framework);
+    const dataFlows = inferDataFlows(endpoints, externalServices, dataStores, piiFields);
+    return {
+        application: {
+            name: path.basename(projectPath),
+            version: "1.0",
+            framework: framework.framework,
+            runtime: framework.runtime,
+            ...(framework.runtimeVersion && { runtimeVersion: framework.runtimeVersion }),
+        },
+        endpoints: endpoints.map(ep => ({
+            type: ep.type, protocol: ep.protocol || "https", port: defaultPort,
+            path: ep.path, auth_method: ep.auth_method || "unknown",
+        })),
+        external_services: externalServices.map(svc => ({
+            name: svc.name, domain: svc.domain, port: svc.port, protocol: svc.protocol || "https", purpose: svc.purpose,
+        })),
+        data_stores: dataStores.map(ds => ({
+            type: ds.type, host: ds.host, port: ds.port, encrypted: ds.encrypted, contains_pii: piiFields.length > 0,
+        })),
+        data_flows: dataFlows,
+        compliance: {
+            frameworks: complianceHints.length > 0 ? complianceHints : ["SOC2"],
+            data_residency: "US",
+            audit_required: sensitivityLevel !== "low",
+        },
+        security_preferences: {
+            session_ttl: sensitivityLevel === "critical" ? 15 : sensitivityLevel === "high" ? 30 : 60,
+            mfa_required: sensitivityLevel === "critical" || sensitivityLevel === "high",
+            ip_binding: true,
+            auto_rotate_certs: true,
+        },
+        _metadata: {
+            generated_by: "@blacksandscyber/mcp-server-bursar",
+            generated_at: new Date().toISOString(),
+            confidence: calculateConfidence(framework, endpoints, externalServices, dataStores),
+            pii_summary: {
+                total_fields: piiFields.length,
+                sensitivity_level: sensitivityLevel,
+                types: [...new Set(piiFields.map(f => f.type))],
+            },
+        },
+    };
+}
+function inferPort(framework) {
+    const portMap = {
+        "next.js": 3000, express: 3000, fastify: 3000, koa: 3000, nestjs: 3000, hapi: 3000,
+        flask: 5000, django: 8000, fastapi: 8000,
+    };
+    return portMap[framework.framework] || 3000;
+}
+function inferDataFlows(endpoints, services, stores, pii) {
+    const flows = [];
+    const piiTypes = [...new Set(pii.map(f => f.type))];
+    const web = endpoints.filter(e => e.type === "web");
+    const api = endpoints.filter(e => e.type === "api");
+    if (web.length > 0 && api.length > 0) {
+        flows.push({ source: "web", destination: "api", data_types: piiTypes.length > 0 ? piiTypes.slice(0, 3) : ["user_input"], sensitivity: piiTypes.length > 0 ? "high" : "medium" });
+    }
+    for (const svc of services) {
+        const dt = svc.purpose === "payments" ? ["payment_info"] : svc.purpose === "email" ? ["email"] : ["api_data"];
+        flows.push({ source: "api", destination: svc.name.toLowerCase(), data_types: dt, sensitivity: svc.purpose === "payments" ? "critical" : "medium" });
+    }
+    for (const ds of stores) {
+        flows.push({ source: "api", destination: ds.type, data_types: piiTypes.length > 0 ? piiTypes : ["application_data"], sensitivity: piiTypes.length > 0 ? "high" : "medium" });
+    }
+    return flows;
+}
+function calculateConfidence(fw, ep, svc, ds) {
+    let score = 10;
+    if (fw.framework !== "unknown")
+        score += 30;
+    if (ep.length > 0)
+        score += 25;
+    if (svc.length > 0)
+        score += 20;
+    if (ds.length > 0)
+        score += 15;
+    return Math.min(score, 100);
+}
+//# sourceMappingURL=manifestGenerator.js.map

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

@@ -0,0 +1,5 @@
+import type { PiiField } from "../types";
+export declare function detectPii(projectPath: string): Promise<PiiField[]>;
+export declare function getSensitivityLevel(findings: PiiField[]): string;
+export declare function getComplianceHints(findings: PiiField[]): string[];
+//# sourceMappingURL=piiDetector.d.ts.map

package/build/shield/discovery/piiDetector.js

@@ -0,0 +1,203 @@
+"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.detectPii = detectPii;
+exports.getSensitivityLevel = getSensitivityLevel;
+exports.getComplianceHints = getComplianceHints;
+/** Detect PII fields in source code and infer compliance requirements.
+ *
+ * Workstream-1 credibility upgrade: every finding now carries file:line, the
+ * source snippet, a confidence level, and remediation guidance. Matches that
+ * occur only in comments or prose (no structural evidence) are classified
+ * "low" confidence and filtered out by default, sharply cutting the
+ * word-match false-positive rate that eroded trust on earlier scans.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const glob_1 = require("glob");
+const PII_PATTERNS = [
+    { pattern: /\b(email|e_mail|email_address|emailAddress)\b/gi, type: "email", sensitivity: "medium" },
+    { pattern: /\b(password|passwd|pass_word|passwordHash)\b/gi, type: "password", sensitivity: "high" },
+    { pattern: /\b(ssn|social_security|socialSecurity|social_security_number)\b/gi, type: "ssn", sensitivity: "critical" },
+    { pattern: /\b(phone|phone_number|phoneNumber|mobile|cell)\b/gi, type: "phone", sensitivity: "medium" },
+    { pattern: /\b(address|street_address|streetAddress|mailing_address)\b/gi, type: "address", sensitivity: "medium" },
+    { pattern: /\b(credit_card|creditCard|card_number|cardNumber|ccNumber)\b/gi, type: "credit_card", sensitivity: "critical" },
+    { pattern: /\b(date_of_birth|dateOfBirth|dob|birthdate|birthday)\b/gi, type: "date_of_birth", sensitivity: "high" },
+    { pattern: /\b(first_name|firstName|last_name|lastName|full_name|fullName)\b/gi, type: "name", sensitivity: "low" },
+    { pattern: /\b(passport|passport_number|passportNumber)\b/gi, type: "passport", sensitivity: "critical" },
+    { pattern: /\b(driver_license|driversLicense|driverLicense)\b/gi, type: "driver_license", sensitivity: "critical" },
+    { pattern: /\b(bank_account|bankAccount|routing_number|routingNumber)\b/gi, type: "bank_account", sensitivity: "critical" },
+    { pattern: /\b(medical|diagnosis|health_record|healthRecord|patient)\b/gi, type: "health_data", sensitivity: "critical" },
+    { pattern: /\b(ip_address|ipAddress|user_agent|userAgent)\b/gi, type: "tracking", sensitivity: "low" },
+];
+const REMEDIATION = {
+    email: "Treat as GDPR personal data: encrypt at rest, scope access by role, and avoid logging in plaintext.",
+    password: "Never store plaintext; hash with bcrypt/argon2 and exclude from logs, responses, and audit trails.",
+    ssn: "Highest-sensitivity PII: encrypt at rest + in transit, mask in UI/logs, restrict to least-privilege access.",
+    phone: "Encrypt at rest and mask in logs; subject to GDPR/CCPA personal-data handling.",
+    address: "Encrypt at rest; subject to GDPR/CCPA personal-data handling.",
+    credit_card: "PCI-DSS scope: do not store PAN unless tokenized; if stored, encrypt and isolate the cardholder data environment.",
+    date_of_birth: "Encrypt at rest and minimize retention; with name/address it becomes high-risk identity data.",
+    name: "Low individually but combines with other fields into identifiable PII; apply GDPR/CCPA handling in aggregate.",
+    passport: "Government identifier: encrypt at rest + in transit, mask in UI, restrict to least-privilege access.",
+    driver_license: "Government identifier: encrypt at rest, mask in UI/logs, restrict access.",
+    bank_account: "Financial PII: encrypt at rest, mask in UI/logs, restrict to least-privilege access.",
+    health_data: "PHI under HIPAA: encrypt at rest + in transit, enforce access logging, apply minimum-necessary access.",
+    tracking: "Tracking identifier: subject to GDPR/CCPA consent; minimize retention and avoid joining to identity data.",
+};
+/** Paths whose matches are almost always documentation/fixtures/prose, not live data handling. */
+const SKIP_PATH_RE = /(^|\/)(docs?|test|tests|__tests__|__mocks__|mocks|spec|specs|fixtures?|examples?|stories|\.storybook|sample|samples)(\/|$)|\.(md|mdx|stories\.[jt]sx?)$/i;
+const MAX_PER_TYPE_PER_FILE = 5;
+/** Build a per-line "is this line a comment" mask for a file. */
+function buildCommentMask(lines) {
+    const mask = new Array(lines.length).fill(false);
+    let inBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (inBlock) {
+            mask[i] = true;
+            if (trimmed.includes("*/"))
+                inBlock = false;
+            continue;
+        }
+        if (/^\/\*/.test(trimmed)) {
+            mask[i] = true;
+            if (!trimmed.includes("*/"))
+                inBlock = true;
+            continue;
+        }
+        // Whole-line single-line comment (JS/TS //, Python/YAML #, JSDoc-continuation *)
+        if (/^(\/\/|#|\*)/.test(trimmed))
+            mask[i] = true;
+    }
+    return mask;
+}
+/** Classify the structural evidence for a keyword match on a given line. */
+function classifyConfidence(keyword, line, isCommentLine) {
+    if (isCommentLine)
+        return "low";
+    const kw = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Strong structural evidence: object/schema key, quoted field, form input name,
+    // SQL column declaration, or typed/ORM-column declaration.
+    const structural = [
+        new RegExp(`\\b${kw}\\b\\s*:`, "i"), // object/type key:  email:
+        new RegExp(`["'\`]${kw}["'\`]`, "i"), // quoted field:     "email"
+        new RegExp(`name\\s*=\\s*["'\`]${kw}["'\`]`, "i"), // form input:       name="email"
+        new RegExp(`\\b${kw}\\b\\s+(varchar|text|char|int|bigint|numeric|date|timestamp|boolean|serial|uuid)`, "i"), // SQL column
+        new RegExp(`(const|let|var|field|column|@column)\\b[^=]*\\b${kw}\\b`, "i"), // declaration / ORM column
+    ];
+    if (structural.some(re => re.test(line)))
+        return "high";
+    // Bare identifier in real code (destructuring, params, property access).
+    return "medium";
+}
+async function detectPii(projectPath) {
+    const findings = [];
+    const seen = new Set();
+    const perTypePerFile = new Map();
+    const files = await (0, glob_1.glob)("**/*.{js,ts,py,jsx,tsx,json,yaml,yml}", {
+        cwd: projectPath,
+        ignore: ["node_modules/**", "venv/**", ".venv/**", "dist/**", "build/**", "package-lock.json", "yarn.lock", "*.test.*", "*.spec.*"],
+        absolute: true,
+    });
+    for (const file of files.slice(0, 200)) {
+        const rel = path.relative(projectPath, file);
+        if (SKIP_PATH_RE.test(rel))
+            continue;
+        const content = fs.readFileSync(file, "utf8");
+        const lines = content.split("\n");
+        const commentMask = buildCommentMask(lines);
+        for (const { pattern, type, sensitivity } of PII_PATTERNS) {
+            const regex = new RegExp(pattern.source, pattern.flags);
+            for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+                const lineText = lines[lineIdx];
+                if (!regex.test(lineText))
+                    continue; // fast reject; resets lastIndex below
+                regex.lastIndex = 0;
+                const matches = [...lineText.matchAll(regex)];
+                if (matches.length === 0)
+                    continue;
+                const isComment = commentMask[lineIdx] === true;
+                const confidence = classifyConfidence(matches[0][0], lineText, isComment);
+                // Filter low-confidence (comment/prose) matches — the false-positive reducer.
+                if (confidence === "low")
+                    continue;
+                const key = `${type}:${rel}:${lineIdx + 1}`;
+                if (seen.has(key))
+                    continue;
+                const ptfKey = `${type}:${rel}`;
+                const count = perTypePerFile.get(ptfKey) ?? 0;
+                if (count >= MAX_PER_TYPE_PER_FILE)
+                    continue;
+                perTypePerFile.set(ptfKey, count + 1);
+                seen.add(key);
+                findings.push({
+                    type,
+                    sensitivity,
+                    field: matches[0][0],
+                    file: rel,
+                    line: lineIdx + 1,
+                    snippet: lineText.trim().slice(0, 160),
+                    confidence,
+                    remediation: REMEDIATION[type],
+                });
+            }
+        }
+    }
+    return findings;
+}
+function getSensitivityLevel(findings) {
+    if (findings.some(f => f.sensitivity === "critical"))
+        return "critical";
+    if (findings.some(f => f.sensitivity === "high"))
+        return "high";
+    if (findings.some(f => f.sensitivity === "medium"))
+        return "medium";
+    return "low";
+}
+function getComplianceHints(findings) {
+    const hints = [];
+    const types = new Set(findings.map(f => f.type));
+    if (types.has("credit_card") || types.has("bank_account"))
+        hints.push("PCI-DSS");
+    if (types.has("health_data"))
+        hints.push("HIPAA");
+    if (types.has("email") || types.has("name") || types.has("address") || types.has("phone"))
+        hints.push("GDPR");
+    if (types.has("ssn") || types.has("passport") || types.has("driver_license"))
+        hints.push("SOC2");
+    return hints;
+}
+//# sourceMappingURL=piiDetector.js.map

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

@@ -0,0 +1,47 @@
+/** Severity tagging for scan findings (Workstream-1 #13g, SHIELD_UPGRADES §2.4).
+ *
+ * Every finding the free-tier scanners emit gets a CRITICAL/HIGH/MEDIUM/LOW/INFO
+ * tag from a small set of explicit, defensible rules — so a report leads with a
+ * risk-ordered summary instead of an undifferentiated wall of matches. The rules
+ * are intentionally conservative: we only escalate to CRITICAL/HIGH when the
+ * evidence is strong (e.g. an unauthenticated mutating admin route), and we tag
+ * authenticated routes INFO rather than pretending they are problems.
+ */
+import type { EndpointInfo, PiiField, Severity } from "../types";
+export declare const SEVERITY_ORDER: Severity[];
+/**
+ * Severity for an HTTP endpoint finding.
+ *
+ * Rule order (first match wins):
+ *  - Authenticated route                              → INFO  (documented, not a finding)
+ *  - No detectable auth + admin namespace + mutating  → CRITICAL
+ *  - No detectable auth + (admin OR mutating)          → HIGH
+ *  - No detectable auth + sensitive path               → MEDIUM
+ *  - No detectable auth + unknown classification       → MEDIUM (couldn't tell — flag it)
+ *  - Explicitly public + read-only + non-sensitive     → LOW
+ */
+export declare function endpointSeverity(e: EndpointInfo): {
+    severity: Severity;
+    rationale: string;
+};
+/**
+ * Severity for a PII finding, from declared data sensitivity × detection confidence.
+ * (Confidence "low" is already filtered upstream, so only high/medium reach here.)
+ */
+export declare function piiSeverity(f: PiiField): {
+    severity: Severity;
+    rationale: string;
+};
+/** Attach severity + rationale to each endpoint (returns new objects, does not mutate). */
+export declare function tagEndpoints(endpoints: EndpointInfo[]): EndpointInfo[];
+/** Attach severity + rationale to each PII finding (returns new objects, does not mutate). */
+export declare function tagPiiFields(fields: PiiField[]): PiiField[];
+/** Build an ordered CRITICAL→INFO count map from a set of tagged findings. */
+export declare function summarizeBySeverity(items: Array<{
+    severity?: Severity;
+}>): Record<Severity, number>;
+/** Highest severity present in a set of findings (defaults to INFO when empty). */
+export declare function topSeverity(items: Array<{
+    severity?: Severity;
+}>): Severity;
+//# sourceMappingURL=severity.d.ts.map

package/build/shield/discovery/severity.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEVERITY_ORDER = void 0;
+exports.endpointSeverity = endpointSeverity;
+exports.piiSeverity = piiSeverity;
+exports.tagEndpoints = tagEndpoints;
+exports.tagPiiFields = tagPiiFields;
+exports.summarizeBySeverity = summarizeBySeverity;
+exports.topSeverity = topSeverity;
+exports.SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"];
+/** Routes under an administrative / privileged namespace. */
+const ADMIN_RE = /(^|\/)(admin|administrator|internal|debug|management|mgmt|root|superuser|sudo|console)(\/|$|-)/i;
+/** Paths that touch sensitive resources even outside an explicit admin namespace. */
+const SENSITIVE_RE = /(payment|billing|invoice|charge|payout|refund|secret|credential|password|token|apikey|api[-_]?key|\buser\b|\busers\b|account|tenant|\borg\b|\brole\b|permission|delete|destroy|drop|wipe|purge|export|download|upload)/i;
+/** Methods that change state. */
+const MUTATING = new Set(["post", "put", "delete", "patch"]);
+function isMutating(method) {
+    const m = method.toLowerCase();
+    // "all" mounts every verb; "unknown" can't be ruled out as a mutation.
+    return MUTATING.has(m) || m === "all" || m === "unknown";
+}
+function hasNoDetectableAuth(authMethod) {
+    return authMethod === "unknown" || authMethod === "public";
+}
+/**
+ * Severity for an HTTP endpoint finding.
+ *
+ * Rule order (first match wins):
+ *  - Authenticated route                              → INFO  (documented, not a finding)
+ *  - No detectable auth + admin namespace + mutating  → CRITICAL
+ *  - No detectable auth + (admin OR mutating)          → HIGH
+ *  - No detectable auth + sensitive path               → MEDIUM
+ *  - No detectable auth + unknown classification       → MEDIUM (couldn't tell — flag it)
+ *  - Explicitly public + read-only + non-sensitive     → LOW
+ */
+function endpointSeverity(e) {
+    const method = (e.method || "unknown").toLowerCase();
+    const path = e.path || "";
+    const admin = ADMIN_RE.test(path);
+    const sensitive = SENSITIVE_RE.test(path);
+    const mutating = isMutating(method);
+    if (!hasNoDetectableAuth(e.auth_method)) {
+        return { severity: "INFO", rationale: `Authenticated route (auth_method=${e.auth_method}).` };
+    }
+    // From here down: no detectable authentication on the route.
+    if (admin && mutating) {
+        return {
+            severity: "CRITICAL",
+            rationale: `Unauthenticated, state-changing route (${method.toUpperCase()}) under an admin namespace — anyone can mutate privileged state.`,
+        };
+    }
+    if (admin) {
+        return {
+            severity: "HIGH",
+            rationale: `Unauthenticated route under an admin namespace — privileged surface exposed without auth.`,
+        };
+    }
+    if (mutating) {
+        return {
+            severity: "HIGH",
+            rationale: `Unauthenticated, state-changing route (${method.toUpperCase()}) — unprotected write surface.`,
+        };
+    }
+    if (sensitive) {
+        return {
+            severity: "MEDIUM",
+            rationale: `Unauthenticated route touching a sensitive resource — possible information disclosure.`,
+        };
+    }
+    if (e.auth_method === "unknown") {
+        return {
+            severity: "MEDIUM",
+            rationale: `Authentication could not be determined for this route — verify it is intentionally open.`,
+        };
+    }
+    return {
+        severity: "LOW",
+        rationale: `Read-only route marked public — confirm no sensitive data is returned.`,
+    };
+}
+/**
+ * Severity for a PII finding, from declared data sensitivity × detection confidence.
+ * (Confidence "low" is already filtered upstream, so only high/medium reach here.)
+ */
+function piiSeverity(f) {
+    const conf = f.confidence ?? "medium";
+    const high = conf === "high";
+    let severity;
+    switch (f.sensitivity) {
+        case "critical":
+            severity = high ? "CRITICAL" : "HIGH";
+            break;
+        case "high":
+            severity = high ? "HIGH" : "MEDIUM";
+            break;
+        case "medium":
+            severity = high ? "MEDIUM" : "LOW";
+            break;
+        default: // "low"
+            severity = "LOW";
+    }
+    return {
+        severity,
+        rationale: `${f.sensitivity}-sensitivity ${f.type} detected with ${conf} confidence.`,
+    };
+}
+/** Attach severity + rationale to each endpoint (returns new objects, does not mutate). */
+function tagEndpoints(endpoints) {
+    return endpoints.map(e => {
+        const { severity, rationale } = endpointSeverity(e);
+        return { ...e, severity, severity_rationale: rationale };
+    });
+}
+/** Attach severity + rationale to each PII finding (returns new objects, does not mutate). */
+function tagPiiFields(fields) {
+    return fields.map(f => {
+        const { severity, rationale } = piiSeverity(f);
+        return { ...f, severity, severity_rationale: rationale };
+    });
+}
+/** Build an ordered CRITICAL→INFO count map from a set of tagged findings. */
+function summarizeBySeverity(items) {
+    const counts = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0, INFO: 0 };
+    for (const it of items) {
+        if (it.severity)
+            counts[it.severity]++;
+    }
+    return counts;
+}
+/** Highest severity present in a set of findings (defaults to INFO when empty). */
+function topSeverity(items) {
+    for (const s of exports.SEVERITY_ORDER) {
+        if (items.some(it => it.severity === s))
+            return s;
+    }
+    return "INFO";
+}
+//# sourceMappingURL=severity.js.map