@thotischner/observability-mcp 1.5.1 → 1.6.0

package/dist/enterprise-gate.test.js

@@ -0,0 +1,178 @@
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defaultContext } from "./context.js";
+import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, validatePolicyShape, validateCatalogShape, authorizeAdmin, _resetEnterpriseGate, } from "./enterprise-gate.js";
+// These tests run in the mcp-server sandbox where enterprise/ is ABSENT
+// (it is excluded from the npm package and the Docker build context) —
+// exactly the published-artifact state. They pin the security contract:
+//
+//   - no opt-in            → OFF, perfect no-op (zero behaviour change)
+//   - control configured   → FAIL-CLOSED when the gate can't activate
+//                            (a broken/absent entitlement must DENY,
+//                             never silently open)
+function clearEnv() {
+    for (const k of [
+        "OMCP_ENTITLEMENT_TOKEN",
+        "OMCP_ENTITLEMENT_PUBKEY",
+        "OMCP_RBAC_POLICY",
+        "OMCP_CATALOG",
+        "OMCP_AUDIT_FILE",
+    ]) {
+        delete process.env[k];
+    }
+    _resetEnterpriseGate();
+}
+describe("enterprise-gate — OFF (no opt-in, published-artifact state)", () => {
+    afterEach(clearEnv);
+    it("no entitlement, no controls → awaited no-op, gate mode 'off'", async () => {
+        clearEnv();
+        await assert.doesNotReject(enforceEntitledAccess(defaultContext(), { tool: "query_metrics", service: "payment" }));
+        const st = await enterpriseGateStatus();
+        assert.equal(st.active, false);
+        assert.equal(st.mode, "off");
+    });
+    it("token set but NO control configured → still OFF (no opt-in), no throw", async () => {
+        clearEnv();
+        process.env.OMCP_ENTITLEMENT_TOKEN = "deadbeef.cafebabe";
+        process.env.OMCP_ENTITLEMENT_PUBKEY = "-----BEGIN PUBLIC KEY-----\\nX\\n-----END PUBLIC KEY-----";
+        _resetEnterpriseGate();
+        await assert.doesNotReject(enforceEntitledAccess(defaultContext(), { tool: "list_sources" }));
+        assert.equal((await enterpriseGateStatus()).mode, "off");
+    });
+    it("every tool name passes through cleanly when OFF", async () => {
+        clearEnv();
+        for (const tool of [
+            "list_sources",
+            "list_services",
+            "query_metrics",
+            "query_logs",
+            "get_service_health",
+            "detect_anomalies",
+        ]) {
+            await assert.doesNotReject(enforceEntitledAccess(defaultContext(), { tool }));
+        }
+    });
+    it("gate state is memoised across calls", async () => {
+        clearEnv();
+        assert.deepEqual(await enterpriseGateStatus(), await enterpriseGateStatus());
+    });
+});
+describe("enterprise-gate — FAIL-CLOSED (opted in, cannot activate)", () => {
+    afterEach(clearEnv);
+    it("RBAC policy configured but enterprise/ absent → DENY every tool call", async () => {
+        clearEnv();
+        const dir = mkdtempSync(join(tmpdir(), "gate-fc-"));
+        const policy = join(dir, "rbac.json");
+        writeFileSync(policy, JSON.stringify({ roles: {}, bindings: {} }));
+        process.env.OMCP_RBAC_POLICY = policy; // operator opted into a control
+        _resetEnterpriseGate();
+        const st = await enterpriseGateStatus();
+        assert.equal(st.active, false);
+        assert.equal(st.mode, "fail-closed");
+        await assert.rejects(() => enforceEntitledAccess(defaultContext(), { tool: "query_metrics" }), /access denied: enterprise control configured but inactive/);
+    });
+    it("control configured + no token → fail-closed (not a silent open)", async () => {
+        clearEnv();
+        process.env.OMCP_CATALOG = "/nonexistent/catalog.json";
+        _resetEnterpriseGate();
+        assert.equal((await enterpriseGateStatus()).mode, "fail-closed");
+        await assert.rejects(() => enforceEntitledAccess(defaultContext(), { tool: "list_services" }), /access denied/);
+    });
+});
+describe("enterprise-gate — read-only console introspection", () => {
+    afterEach(clearEnv);
+    it("gateInfo: off → entitlement null, no token ever exposed", async () => {
+        clearEnv();
+        process.env.OMCP_ENTITLEMENT_TOKEN = "SECRET.SHOULD-NEVER-LEAK";
+        process.env.OMCP_ENTITLEMENT_PUBKEY = "x";
+        _resetEnterpriseGate();
+        const info = await enterpriseGateInfo();
+        assert.equal(info.active, false);
+        assert.equal(info.entitlement, null);
+        assert.equal("rbacConfigured" in info, true);
+        const dump = JSON.stringify(info);
+        assert.equal(dump.includes("SECRET"), false, "token must never appear in gate info");
+    });
+    it("gateInfo: configured-flags reflect env", async () => {
+        clearEnv();
+        process.env.OMCP_RBAC_POLICY = "/tmp/x.json";
+        process.env.OMCP_AUDIT_FILE = "/tmp/a.jsonl";
+        _resetEnterpriseGate();
+        const info = await enterpriseGateInfo();
+        assert.equal(info.rbacConfigured, true);
+        assert.equal(info.catalogConfigured, false);
+        assert.equal(info.auditConfigured, true);
+    });
+    it("policy/catalog view: not configured vs file error", () => {
+        clearEnv();
+        assert.deepEqual(enterprisePolicyView(), { configured: false });
+        assert.deepEqual(enterpriseCatalogView(), { configured: false });
+        const dir = mkdtempSync(join(tmpdir(), "gate-ro-"));
+        const f = join(dir, "p.json");
+        writeFileSync(f, '{"roles":{"a":{"tools":["*"]}},"bindings":{}}');
+        process.env.OMCP_RBAC_POLICY = f;
+        const v = enterprisePolicyView();
+        assert.equal(v.configured, true);
+        assert.deepEqual(Object.keys(v.data.roles), ["a"]);
+        process.env.OMCP_RBAC_POLICY = "/no/such/file.json";
+        const e = enterprisePolicyView();
+        assert.equal(e.configured, true);
+        assert.ok(e.error);
+    });
+    it("audit tail: not configured when no audit file", async () => {
+        clearEnv();
+        assert.deepEqual(await enterpriseAuditTail(10), { configured: false });
+    });
+});
+describe("enterprise-gate — P2 admin RBAC write", () => {
+    afterEach(clearEnv);
+    it("validatePolicyShape accepts a well-formed policy", () => {
+        assert.equal(validatePolicyShape({ roles: { a: { tools: ["*"] } }, bindings: { p: ["a"] }, defaultRoles: [] }), null);
+    });
+    it("validatePolicyShape rejects malformed shapes", () => {
+        assert.match(validatePolicyShape(null) || "", /must be a JSON object/);
+        assert.match(validatePolicyShape([]) || "", /must be a JSON object/);
+        assert.match(validatePolicyShape({ bindings: {} }) || "", /roles must be an object/);
+        assert.match(validatePolicyShape({ roles: {} }) || "", /bindings must be an object/);
+        assert.match(validatePolicyShape({ roles: {}, bindings: {}, defaultRoles: "x" }) || "", /defaultRoles must be an array/);
+        assert.match(validatePolicyShape({ roles: { r: { tools: "x" } }, bindings: {} }) || "", /role 'r.tools' must be an array/);
+        assert.match(validatePolicyShape({ roles: {}, bindings: { p: "x" } }) || "", /binding 'p' must be an array/);
+    });
+    it("authorizeAdmin denies when the gate is not active", async () => {
+        clearEnv(); // no entitlement → mode off
+        const r = await authorizeAdmin("someone");
+        assert.equal(r.ok, false);
+        assert.equal(r.status, 409);
+        assert.match(r.error ?? "", /gate not active/);
+    });
+    it("authorizeAdmin requires a principal once a control is configured", async () => {
+        clearEnv();
+        process.env.OMCP_RBAC_POLICY = "/tmp/none.json"; // fail-closed (no token)
+        _resetEnterpriseGate();
+        const r = await authorizeAdmin(null);
+        assert.equal(r.ok, false);
+        // gate is fail-closed here → still 409 (not active); never silently allows
+        assert.equal(r.ok, false);
+    });
+});
+describe("enterprise-gate — P3 catalog write validation", () => {
+    it("validateCatalogShape accepts a well-formed catalog", () => {
+        assert.equal(validateCatalogShape({
+            products: { p: { sources: ["*"], services: ["a"] } },
+            grants: { who: ["p"] },
+            defaultProducts: [],
+        }), null);
+    });
+    it("validateCatalogShape rejects malformed shapes", () => {
+        assert.match(validateCatalogShape(null) || "", /must be a JSON object/);
+        assert.match(validateCatalogShape({ grants: {} }) || "", /products must be an object/);
+        assert.match(validateCatalogShape({ products: {} }) || "", /grants must be an object/);
+        assert.match(validateCatalogShape({ products: { p: {} }, grants: {} }) || "", /product 'p.sources' must be an array/);
+        assert.match(validateCatalogShape({ products: { p: { sources: [], services: "x" } }, grants: {} }) || "", /product 'p.services' must be an array/);
+        assert.match(validateCatalogShape({ products: {}, grants: { g: "x" } }) || "", /grant 'g' must be an array/);
+        assert.match(validateCatalogShape({ products: {}, grants: {}, defaultProducts: 1 }) || "", /defaultProducts must be an array/);
+    });
+});

package/dist/index.js

@@ -9,6 +9,7 @@ import { z } from "zod";
 import { loadConfig, saveConfig, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_SETTINGS } from "./config/loader.js";
 import { ConnectorRegistry, getSupportedTypes } from "./connectors/registry.js";
 import { defaultContext, principalContext } from "./context.js";
+import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, authorizeAdmin, updateRbacPolicy, updateCatalog, } from "./enterprise-gate.js";
 import { loadCredentials, credentialsConfigured, extractToken, resolveToken, } from "./auth/credentials.js";
 import { getPluginLoader } from "./connectors/loader.js";
 import { resolveHubCatalogUrl, describeInstalled, mergeCatalog, fetchHubCatalog, } from "./connectors/hub.js";
@@ -121,7 +122,10 @@ async function main() {
             "When to use: call this first to learn which source names exist and are healthy before passing `source` to other tools, or to debug why a query returns no data.",
             "Behavior: read-only, no side effects. Returns one entry per source with its name, type, configured URL, signal types (metrics/logs), and a live up/down status. Never throws for an unreachable backend — the backend is reported as down instead.",
             "Related: use `list_services` to see what is monitored within these sources.",
-        ].join(" "), {}, async () => withToolMetrics("list_sources", () => listSourcesHandler(registry, ctx)));
+        ].join(" "), {}, async () => {
+            await enforceEntitledAccess(ctx, { tool: "list_sources" });
+            return withToolMetrics("list_sources", () => listSourcesHandler(registry, ctx));
+        });
         mcpServer.tool("list_services", [
             "Discover the service names that can be queried, aggregated across every connected backend.",
             "When to use: call this before `query_metrics`, `query_logs`, or `get_service_health` to obtain the exact, case-sensitive service name those tools require.",
@@ -132,7 +136,10 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional case-insensitive substring to narrow the result to matching service names (e.g. 'payment'). Omit to list every discovered service."),
-        }, async (args) => withToolMetrics("list_services", () => listServicesHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "list_services" });
+            return withToolMetrics("list_services", () => listServicesHandler(registry, args, ctx));
+        });
         const metricsList = getAvailableMetricNames(registry);
         const metricNames = registry.getBySignal("metrics").flatMap(c => c.getMetrics().map(m => m.name));
         const uniqueNames = [...new Set(metricNames)];
@@ -161,7 +168,10 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional. Metric label to break the result down by, e.g. 'instance', 'pod', 'node'. When set, the response contains one series per distinct label value under `groups`. Default: a single aggregated series."),
-        }, async (args) => withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "query_metrics", source: args?.source, service: args?.service });
+            return withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx));
+        });
         mcpServer.tool("query_logs", [
             "Fetch recent log entries for ONE service over a look-back window, with a pre-computed summary (error/warning counts and the most frequent error patterns).",
             "When to use: to inspect what a service actually logged, or to investigate an error spike surfaced by `detect_anomalies` / `get_service_health`. For numeric metrics use `query_metrics` instead.",
@@ -189,7 +199,10 @@ async function main() {
                 .positive()
                 .optional()
                 .describe("Optional. Maximum number of log entries to return (most recent first). Default: 100."),
-        }, async (args) => withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "query_logs", source: args?.source, service: args?.service });
+            return withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx));
+        });
         mcpServer.tool("get_service_health", [
             "Produce a single aggregated health verdict for ONE service by combining its metrics and logs.",
             "When to use: the fastest way to answer 'is this service healthy right now and why?'. Use `query_metrics`/`query_logs` to drill into the underlying numbers, or `detect_anomalies` to scan many services at once.",
@@ -199,7 +212,10 @@ async function main() {
             service: z
                 .string()
                 .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
-        }, async (args) => withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "get_service_health", service: args?.service });
+            return withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args, ctx));
+        });
         mcpServer.tool("detect_anomalies", [
             "Scan one or all monitored services for abnormal behavior and return the findings ranked by severity.",
             "When to use: the entry point for 'is anything wrong anywhere?' triage. Once a service is flagged, follow up with `get_service_health` for the verdict or `query_metrics`/`query_logs` for the raw evidence.",
@@ -218,7 +234,10 @@ async function main() {
                 .enum(["low", "medium", "high"])
                 .optional()
                 .describe("Optional. Detection threshold: 'low' flags only strong deviations (>3σ), 'medium' is balanced (>2σ), 'high' is most sensitive and noisier (>1.5σ). Default: 'medium'."),
-        }, async (args) => withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args, ctx)));
+        }, async (args) => {
+            await enforceEntitledAccess(ctx, { tool: "detect_anomalies", source: args?.source, service: args?.service });
+            return withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args, ctx));
+        });
         return mcpServer;
     }
     // --- HTTP server ---
@@ -313,6 +332,7 @@ async function main() {
         res.json({
             name: "observability-mcp",
             version: SERVER_VERSION,
+            enterpriseGate: await enterpriseGateStatus(),
             mcpProtocolVersion: "2025-03-26",
             build: {
                 commit: process.env.GIT_COMMIT || null,
@@ -336,6 +356,58 @@ async function main() {
     app.get("/api/connectors", (_req, res) => {
         res.json({ connectors: describeInstalled(getPluginLoader().list()) });
     });
+    // --- Enterprise console (read-only introspection) -------------------
+    // Drives the management UI's Enterprise page. Read-only in this phase;
+    // never exposes the entitlement token or any key. Same trusted-local
+    // management plane as the other /api/* endpoints (see auth-and-tls).
+    app.get("/api/enterprise/status", async (_req, res) => {
+        try {
+            res.json(await enterpriseGateInfo());
+        }
+        catch (e) {
+            res.status(500).json({ error: String(e) });
+        }
+    });
+    app.get("/api/enterprise/policy", (_req, res) => {
+        res.json(enterprisePolicyView());
+    });
+    app.get("/api/enterprise/catalog", (_req, res) => {
+        res.json(enterpriseCatalogView());
+    });
+    app.get("/api/enterprise/audit", async (req, res) => {
+        const limit = Math.min(Number(req.query.limit) || 50, 500);
+        try {
+            res.json(await enterpriseAuditTail(limit));
+        }
+        catch (e) {
+            res.status(500).json({ error: String(e) });
+        }
+    });
+    // Phase 2: edit the RBAC policy. NOT on the open local plane — requires
+    // an API-key principal the CURRENT policy grants `enterprise:admin`.
+    app.put("/api/enterprise/policy", async (req, res) => {
+        const cred = resolveToken(extractToken(req.headers), loadCredentials());
+        const principal = cred ? cred.name : null;
+        const authz = await authorizeAdmin(principal);
+        if (!authz.ok)
+            return res.status(authz.status).json({ error: authz.error });
+        const result = await updateRbacPolicy(principal, req.body);
+        if (!result.ok)
+            return res.status(result.status).json({ error: result.error });
+        res.json({ ok: true });
+    });
+    // Phase 3: edit the product catalog. Same admin model as the RBAC write.
+    app.put("/api/enterprise/catalog", async (req, res) => {
+        const cred = resolveToken(extractToken(req.headers), loadCredentials());
+        const principal = cred ? cred.name : null;
+        const authz = await authorizeAdmin(principal);
+        if (!authz.ok)
+            return res.status(authz.status).json({ error: authz.error });
+        const result = await updateCatalog(principal, req.body);
+        if (!result.ok)
+            return res.status(result.status).json({ error: result.error });
+        res.json({ ok: true });
+    });
     // Server-side proxy of the connector hub catalog (so the browser
     // needn't reach the hub directly — works behind a proxy / against a
     // mirror via HUB_CATALOG_URL). Installed status merged in.

package/dist/tools/get-service-health.js

@@ -1,6 +1,6 @@
 import { defaultContext } from "../context.js";
 import { calculateHealthScore } from "../analysis/health.js";
-import { detectRecentAnomaly } from "../analysis/anomaly.js";
+import { detectRobustAnomaly, classifyMetric } from "../analysis/anomaly.js";
 import { sanitizeForLog } from "../util/sanitize.js";
 let _thresholds = null;
 export function setHealthThresholds(t) {
@@ -94,17 +94,20 @@ export async function getServiceHealthHandler(registry, args, _ctx = defaultCont
     };
 }
 function checkAnomaly(values, metric, service, source, anomalies) {
-    const result = detectRecentAnomaly(values);
+    // Robust, metric-type-aware detector (same path as detect_anomalies):
+    // latency/error_rate/saturation are one-sided, so a *decrease* (e.g.
+    // latency dropping) is correctly NOT flagged as an anomaly.
+    const result = detectRobustAnomaly(values, { metricKind: classifyMetric(metric) });
     if (result.isAnomaly) {
-        const deviationPercent = result.baselineAvg === 0
+        const deviationPercent = result.baselineValue === 0
             ? 100
-            : Math.round(((result.recentAvg - result.baselineAvg) / result.baselineAvg) * 100);
+            : Math.round(((result.recentValue - result.baselineValue) / result.baselineValue) * 100);
         anomalies.push({
             metric,
-            severity: Math.abs(result.zScore) >= 3 ? "high" : Math.abs(result.zScore) >= 2 ? "medium" : "low",
-            description: `${metric} is ${result.zScore.toFixed(1)}σ ${result.zScore > 0 ? "above" : "below"} baseline (${result.baselineAvg.toFixed(2)} → ${result.recentAvg.toFixed(2)})`,
-            currentValue: result.recentAvg,
-            baselineValue: result.baselineAvg,
+            severity: Math.abs(result.score) >= 6 ? "high" : Math.abs(result.score) >= 4 ? "medium" : "low",
+            description: `${metric}: ${result.reason}`,
+            currentValue: result.recentValue,
+            baselineValue: result.baselineValue,
             deviationPercent,
             source,
             service,

package/dist/tools/handlers.test.js

@@ -4,6 +4,7 @@ import { ConnectorRegistry } from "../connectors/registry.js";
 import { listSourcesHandler } from "./list-sources.js";
 import { listServicesHandler } from "./list-services.js";
 import { detectAnomaliesHandler } from "./detect-anomalies.js";
+import { getServiceHealthHandler } from "./get-service-health.js";
 // --- Mock Connector ---
 function createMockConnector(overrides) {
     return {
@@ -209,3 +210,33 @@ describe("detectAnomaliesHandler — A5 memory/OOM coverage", () => {
         assert.equal(data.anomalies.length, 0);
     });
 });
+describe("getServiceHealthHandler — one-sided latency (regression)", () => {
+    const series = (vals) => ({
+        source: "prom1", service: "payment-service", metric: "x", unit: "",
+        values: vals.map((v, i) => ({ timestamp: new Date(Date.now() - (vals.length - i) * 9000).toISOString(), value: v })),
+        summary: { current: vals[vals.length - 1], average: vals[0], min: Math.min(...vals), max: Math.max(...vals), trend: "falling" },
+    });
+    it("a DECREASING latency_p99 is NOT flagged as an anomaly", async () => {
+        const reg = new ConnectorRegistry();
+        const mock = {
+            connect: async () => { }, disconnect: async () => { },
+            healthCheck: async () => ({ status: "up", latencyMs: 1 }),
+            getDefaultMetrics: () => [], getMetrics: () => [],
+            listServices: async () => [{ name: "payment-service", source: "prom1", signalType: "metrics" }],
+            name: "prom1", type: "prometheus", signalType: "metrics",
+            queryMetrics: async ({ metric }) => {
+                if (metric === "latency_p99")
+                    return series(Array.from({ length: 30 }, (_, i) => 1.0 - i * 0.025)); // 1.0 → 0.275, strictly down
+                if (metric === "cpu")
+                    return series(Array.from({ length: 30 }, () => 20 + (Math.random() < 0 ? 1 : 0)));
+                return series(Array.from({ length: 30 }, () => 0.01)); // error_rate flat
+            },
+        };
+        reg.connectors.set("prom1", mock);
+        reg.sourceConfigs.set("prom1", { name: "prom1", type: "prometheus", url: "http://m", enabled: true });
+        const result = await getServiceHealthHandler(reg, { service: "payment-service" });
+        const data = JSON.parse(result.content[0].text);
+        const latAnom = (data.anomalies || []).find((a) => a.metric === "latency_p99");
+        assert.equal(latAnom, undefined, `latency dropping must not be an anomaly, got: ${JSON.stringify(latAnom)}`);
+    });
+});