@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/middleware/ssrfGuard.d.ts

@@ -0,0 +1,15 @@
+export interface SsrfGuardConfig {
+    allowPrivateBackends: boolean;
+}
+export declare function ssrfGuardFromEnv(env?: NodeJS.ProcessEnv): SsrfGuardConfig;
+export interface SsrfGuardVerdict {
+    allow: boolean;
+    reason?: string;
+}
+/** Inspect a URL and decide whether the connector layer should be
+ *  allowed to dial it. Cheap, synchronous, hostname-only — does not
+ *  resolve DNS. (DNS resolution would still leak the request, so the
+ *  guard would have to additionally pin the resolved IP at connect
+ *  time. That's worth doing in a follow-up; for now we catch the
+ *  most-frequent typed-IP cases and document the resolver limitation.) */
+export declare function checkOutboundUrl(rawUrl: string, cfg: SsrfGuardConfig): SsrfGuardVerdict;

package/dist/middleware/ssrfGuard.js

@@ -0,0 +1,103 @@
+// SSRF strict-mode for operator-supplied URLs.
+//
+// Connectors (Prometheus, Loki, Tempo, Grafana, generic webhook
+// targets) all take a URL the operator types in. Without a guard, an
+// admin who can add a source can also probe cloud-metadata endpoints
+// (169.254.169.254 → IAM creds, GCE service accounts, etc.) or other
+// in-cluster services that should not be reachable from the gateway.
+//
+// This module rejects URLs whose hostname:
+//   - is a private/loopback/link-local IPv4 or IPv6 literal, OR
+//   - is the well-known cloud-metadata IP, OR
+//   - resolves (when an explicit IP is set) to one of the above
+//
+// Operators who legitimately need to reach an in-cluster Prometheus
+// (a frequent case) opt out via OMCP_ALLOW_PRIVATE_BACKENDS=true.
+import { isIP } from "node:net";
+// IPv4 IMDS (AWS / GCE / Azure / Oracle) all share 169.254.169.254.
+// fd00:ec2::254 is the AWS IMDS IPv6 address.
+const METADATA_IPS = new Set(["169.254.169.254", "fd00:ec2::254"]);
+// Private IPv4 ranges per RFC 1918/3927/6890. String-prefix matching
+// is intentionally lo-fi — the guard catches typed-by-hand URLs, not
+// every numerical corner. A DNS-resolved guard is on the F11b list.
+const IPV4_PREFIXES = [
+    "10.", // RFC1918
+    "172.16.", "172.17.", "172.18.", "172.19.",
+    "172.20.", "172.21.", "172.22.", "172.23.",
+    "172.24.", "172.25.", "172.26.", "172.27.",
+    "172.28.", "172.29.", "172.30.", "172.31.",
+    "192.168.", // RFC1918
+    "169.254.", // link-local + cloud metadata
+    "127.", // loopback
+    "0.", // 0.0.0.0/8
+];
+const IPV6_PRIVATE_PREFIXES = [
+    "::1", // loopback
+    "fc", // unique-local (fc00::/7)
+    "fd", // unique-local
+    "fe8", // link-local (fe80::/10)
+    "fe9",
+    "fea",
+    "feb",
+];
+export function ssrfGuardFromEnv(env = process.env) {
+    return {
+        allowPrivateBackends: /^(1|true|yes|on)$/i.test(env.OMCP_ALLOW_PRIVATE_BACKENDS ?? ""),
+    };
+}
+/** Inspect a URL and decide whether the connector layer should be
+ *  allowed to dial it. Cheap, synchronous, hostname-only — does not
+ *  resolve DNS. (DNS resolution would still leak the request, so the
+ *  guard would have to additionally pin the resolved IP at connect
+ *  time. That's worth doing in a follow-up; for now we catch the
+ *  most-frequent typed-IP cases and document the resolver limitation.) */
+export function checkOutboundUrl(rawUrl, cfg) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch (err) {
+        return { allow: false, reason: `invalid URL: ${err.message}` };
+    }
+    if (!/^https?:$/i.test(parsed.protocol)) {
+        return { allow: false, reason: `unsupported protocol: ${parsed.protocol}` };
+    }
+    // URL parser keeps IPv6 brackets on .hostname ("[::1]"); strip
+    // them before isIP / prefix matching so the rest of the guard is
+    // shape-agnostic.
+    let hostname = parsed.hostname.toLowerCase();
+    if (hostname.startsWith("[") && hostname.endsWith("]")) {
+        hostname = hostname.slice(1, -1);
+    }
+    if (METADATA_IPS.has(hostname)) {
+        return {
+            allow: false,
+            reason: `cloud-metadata IP ${hostname} is rejected (set OMCP_ALLOW_PRIVATE_BACKENDS=true to override)`,
+        };
+    }
+    if (cfg.allowPrivateBackends) {
+        return { allow: true };
+    }
+    const v = isIP(hostname);
+    if (v === 4) {
+        for (const p of IPV4_PREFIXES) {
+            if (hostname.startsWith(p)) {
+                return {
+                    allow: false,
+                    reason: `private IPv4 ${hostname} is rejected (set OMCP_ALLOW_PRIVATE_BACKENDS=true to allow in-cluster backends)`,
+                };
+            }
+        }
+    }
+    else if (v === 6) {
+        for (const p of IPV6_PRIVATE_PREFIXES) {
+            if (hostname.startsWith(p)) {
+                return {
+                    allow: false,
+                    reason: `private IPv6 ${hostname} is rejected (set OMCP_ALLOW_PRIVATE_BACKENDS=true to allow in-cluster backends)`,
+                };
+            }
+        }
+    }
+    return { allow: true };
+}

package/dist/middleware/ssrfGuard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/middleware/ssrfGuard.test.js

@@ -0,0 +1,81 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { checkOutboundUrl, ssrfGuardFromEnv } from "./ssrfGuard.js";
+const STRICT = { allowPrivateBackends: false };
+const LAX = { allowPrivateBackends: true };
+test("ssrfGuardFromEnv: defaults strict, opts in on truthy", () => {
+    assert.equal(ssrfGuardFromEnv({}).allowPrivateBackends, false);
+    for (const v of ["1", "true", "yes", "on", "TRUE"]) {
+        assert.equal(ssrfGuardFromEnv({ OMCP_ALLOW_PRIVATE_BACKENDS: v }).allowPrivateBackends, true, v);
+    }
+    for (const v of ["", "0", "false", "no", "off"]) {
+        assert.equal(ssrfGuardFromEnv({ OMCP_ALLOW_PRIVATE_BACKENDS: v }).allowPrivateBackends, false, v);
+    }
+});
+test("rejects malformed URLs", () => {
+    const r = checkOutboundUrl("not-a-url", STRICT);
+    assert.equal(r.allow, false);
+});
+test("rejects non-http(s) schemes", () => {
+    assert.equal(checkOutboundUrl("ftp://example.com", STRICT).allow, false);
+    assert.equal(checkOutboundUrl("file:///etc/passwd", STRICT).allow, false);
+});
+test("rejects AWS cloud-metadata IP regardless of allowPrivateBackends", () => {
+    for (const cfg of [STRICT, LAX]) {
+        const r = checkOutboundUrl("http://169.254.169.254/latest/meta-data/", cfg);
+        assert.equal(r.allow, false, JSON.stringify(cfg));
+        assert.match(r.reason ?? "", /cloud-metadata/);
+    }
+});
+test("rejects private IPv4 ranges in strict mode", () => {
+    for (const url of [
+        "http://10.0.0.1/",
+        "http://172.16.0.5/",
+        "http://172.31.255.1/",
+        "http://192.168.1.1/",
+        "http://127.0.0.1:9090/",
+        "http://169.254.10.1/",
+    ]) {
+        const r = checkOutboundUrl(url, STRICT);
+        assert.equal(r.allow, false, url);
+    }
+});
+test("ACCEPTS private IPs when allowPrivateBackends=true (in-cluster opt-out)", () => {
+    for (const url of [
+        "http://prometheus.monitoring.svc.cluster.local:9090/",
+        "http://10.0.0.1:9090/",
+        "http://172.20.0.1:9090/",
+    ]) {
+        assert.equal(checkOutboundUrl(url, LAX).allow, true, url);
+    }
+});
+test("accepts public IPv4 / hostnames in strict mode", () => {
+    for (const url of [
+        "https://prometheus.example.com/api/v1/query",
+        "https://8.8.8.8/x",
+        "https://1.1.1.1/x",
+    ]) {
+        assert.equal(checkOutboundUrl(url, STRICT).allow, true, url);
+    }
+});
+test("rejects IPv6 loopback + link-local + unique-local in strict mode", () => {
+    for (const url of [
+        "http://[::1]/",
+        "http://[fc00::1]/",
+        "http://[fd00::1]/",
+        "http://[fe80::1]/",
+    ]) {
+        assert.equal(checkOutboundUrl(url, STRICT).allow, false, url);
+    }
+});
+test("172.{16-31} private range edge cases", () => {
+    // 172.15 is public; 172.16-172.31 is private; 172.32 is public.
+    assert.equal(checkOutboundUrl("http://172.15.0.1/", STRICT).allow, true);
+    assert.equal(checkOutboundUrl("http://172.16.0.1/", STRICT).allow, false);
+    assert.equal(checkOutboundUrl("http://172.31.0.1/", STRICT).allow, false);
+    assert.equal(checkOutboundUrl("http://172.32.0.1/", STRICT).allow, true);
+});
+test("uppercase IPv6 hostnames are still caught", () => {
+    // URL parser lowercases hostnames, but we still test for safety.
+    assert.equal(checkOutboundUrl("http://[FE80::1]/", STRICT).allow, false);
+});

package/dist/net/egress-policy.js

@@ -25,6 +25,8 @@ export const EGRESS_ALLOWLIST = [
     { prefix: "connectors/", reason: "connectors query operator-configured source backends" },
     { prefix: "cli/index.ts", reason: "CLI fetches a source location the operator passed explicitly" },
     { prefix: "index.ts", reason: "connector-hub plugin install of an operator/registry-requested tarball URL" },
+    { prefix: "auth/oidc/", reason: "OIDC client calls the operator-configured OMCP_OIDC_ISSUER for discovery, JWKS, and code-exchange" },
+    { prefix: "auth/policy/", reason: "OpaPolicyEngine queries the operator-configured OMCP_OPA_URL on every RBAC decision" },
 ];
 /**
  * Hard-blocked analytics/telemetry SDKs — matches an *import/require of the

package/dist/observability/otel.d.ts

@@ -0,0 +1,20 @@
+export interface OtelInitResult {
+    enabled: boolean;
+    endpoint?: string;
+    serviceName?: string;
+    reason?: string;
+}
+export declare function isOtelEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function otelStatus(): OtelInitResult;
+/**
+ * Idempotent init. Returns synchronously; the SDK starts in the
+ * background. Safe to call multiple times — the second call is a
+ * no-op.
+ */
+export declare function initOtel(opts?: {
+    serviceVersion?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<OtelInitResult>;
+export declare function parseOtelHeaders(raw: string | undefined): Record<string, string> | undefined;
+/** Test-only — resets internal state so re-init can be exercised. */
+export declare function _resetOtelForTests(): void;

package/dist/observability/otel.js

@@ -0,0 +1,118 @@
+// OpenTelemetry self-instrumentation of the gateway.
+//
+// Opt-in via OMCP_OTEL_ENABLED=true; default off so the OSS demo and
+// any deployment that does not run a collector stays silent. When on,
+// the Node SDK auto-instruments HTTP (covers /api/* and /mcp routes
+// out of the box) and exports to an OTLP/HTTP endpoint.
+//
+// Env:
+//   OMCP_OTEL_ENABLED   true|1|yes to enable (default off)
+//   OMCP_OTEL_ENDPOINT  OTLP/HTTP traces URL (default http://localhost:4318/v1/traces)
+//   OMCP_OTEL_HEADERS   "key1=val1,key2=val2" for collector auth
+//   OMCP_OTEL_SERVICE_NAME    override resource service.name (default observability-mcp)
+//   OMCP_OTEL_SERVICE_VERSION override resource service.version (default from package.json at runtime)
+//
+// Imports are dynamic so the @opentelemetry/* packages stay outside the
+// startup hot path when otel is disabled.
+import { hostname } from "node:os";
+let initialized = false;
+let result = { enabled: false, reason: "init not called" };
+export function isOtelEnabled(env = process.env) {
+    return /^(1|true|yes|on)$/i.test(env.OMCP_OTEL_ENABLED ?? "");
+}
+export function otelStatus() {
+    return result;
+}
+/**
+ * Idempotent init. Returns synchronously; the SDK starts in the
+ * background. Safe to call multiple times — the second call is a
+ * no-op.
+ */
+export async function initOtel(opts = {}) {
+    if (initialized)
+        return result;
+    initialized = true;
+    const env = opts.env ?? process.env;
+    if (!isOtelEnabled(env)) {
+        result = { enabled: false, reason: "OMCP_OTEL_ENABLED is off" };
+        return result;
+    }
+    const endpoint = env.OMCP_OTEL_ENDPOINT ?? "http://localhost:4318/v1/traces";
+    const serviceName = env.OMCP_OTEL_SERVICE_NAME ?? "observability-mcp";
+    const serviceVersion = env.OMCP_OTEL_SERVICE_VERSION ?? opts.serviceVersion ?? "unknown";
+    const headers = parseOtelHeaders(env.OMCP_OTEL_HEADERS);
+    try {
+        // Dynamic imports keep the cold-start overhead off the
+        // OTEL-disabled path. Failures here log + degrade gracefully —
+        // the gateway must never refuse to boot because tracing is
+        // misconfigured.
+        const { NodeSDK } = await import("@opentelemetry/sdk-node");
+        const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+        const { resourceFromAttributes } = await import("@opentelemetry/resources");
+        const { getNodeAutoInstrumentations } = await import("@opentelemetry/auto-instrumentations-node");
+        const semconv = await import("@opentelemetry/semantic-conventions");
+        const ATTR_SERVICE_NAME = semconv.ATTR_SERVICE_NAME ??
+            semconv.SEMRESATTRS_SERVICE_NAME ??
+            "service.name";
+        const ATTR_SERVICE_VERSION = semconv.ATTR_SERVICE_VERSION ??
+            semconv.SEMRESATTRS_SERVICE_VERSION ??
+            "service.version";
+        const ATTR_SERVICE_INSTANCE_ID = semconv.ATTR_SERVICE_INSTANCE_ID ??
+            semconv.SEMRESATTRS_SERVICE_INSTANCE_ID ??
+            "service.instance.id";
+        const sdk = new NodeSDK({
+            resource: resourceFromAttributes({
+                [ATTR_SERVICE_NAME]: serviceName,
+                [ATTR_SERVICE_VERSION]: serviceVersion,
+                [ATTR_SERVICE_INSTANCE_ID]: hostname(),
+            }),
+            traceExporter: new OTLPTraceExporter({ url: endpoint, headers }),
+            instrumentations: [
+                getNodeAutoInstrumentations({
+                    // Filesystem instrumentation generates a span per fs call —
+                    // it explodes the trace volume for negligible value at the
+                    // gateway level. Off by default; operators can re-enable
+                    // via direct SDK config if they need it.
+                    "@opentelemetry/instrumentation-fs": { enabled: false },
+                }),
+            ],
+        });
+        sdk.start();
+        // Best-effort flush on shutdown so in-flight spans reach the
+        // collector during a rolling restart.
+        process.on("SIGTERM", () => {
+            sdk
+                .shutdown()
+                .catch((err) => console.warn("OTel SDK shutdown failed:", err));
+        });
+        result = { enabled: true, endpoint, serviceName };
+        console.log("OTel self-tracing enabled: exporting to %s as service.name=%s", endpoint, serviceName);
+        return result;
+    }
+    catch (err) {
+        result = {
+            enabled: false,
+            reason: `OTel init failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+        console.warn("OTel self-tracing requested but init failed; gateway continues without tracing. %s", result.reason);
+        return result;
+    }
+}
+export function parseOtelHeaders(raw) {
+    if (!raw)
+        return undefined;
+    const out = {};
+    for (const pair of raw.split(",")) {
+        const [k, ...rest] = pair.split("=");
+        const key = k?.trim();
+        const value = rest.join("=").trim();
+        if (key && value)
+            out[key] = value;
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/** Test-only — resets internal state so re-init can be exercised. */
+export function _resetOtelForTests() {
+    initialized = false;
+    result = { enabled: false, reason: "init not called" };
+}

package/dist/observability/otel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/observability/otel.test.js

@@ -0,0 +1,56 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { initOtel, isOtelEnabled, parseOtelHeaders, otelStatus, _resetOtelForTests, } from "./otel.js";
+test("isOtelEnabled — accepts true/1/yes/on (any case), rejects others", () => {
+    for (const v of ["true", "1", "yes", "on", "TRUE", "Yes", "ON"]) {
+        assert.equal(isOtelEnabled({ OMCP_OTEL_ENABLED: v }), true, v);
+    }
+    for (const v of ["", "false", "0", "no", "off", "anything-else"]) {
+        assert.equal(isOtelEnabled({ OMCP_OTEL_ENABLED: v }), false, v);
+    }
+    assert.equal(isOtelEnabled({}), false, "unset env");
+});
+test("parseOtelHeaders — splits comma-separated key=value pairs", () => {
+    assert.deepEqual(parseOtelHeaders("a=1,b=2"), { a: "1", b: "2" });
+    assert.deepEqual(parseOtelHeaders(" a = 1 , b = 2 "), { a: "1", b: "2" });
+    // Value containing `=` is preserved
+    assert.deepEqual(parseOtelHeaders("Authorization=Bearer abc=def"), {
+        Authorization: "Bearer abc=def",
+    });
+    assert.equal(parseOtelHeaders(""), undefined);
+    assert.equal(parseOtelHeaders(undefined), undefined);
+    // Drops malformed entries silently rather than throwing
+    assert.deepEqual(parseOtelHeaders("nokey,b=2"), { b: "2" });
+});
+test("initOtel — no-op when OMCP_OTEL_ENABLED is off", async () => {
+    _resetOtelForTests();
+    const r = await initOtel({ env: { OMCP_OTEL_ENABLED: undefined } });
+    assert.equal(r.enabled, false);
+    assert.match(r.reason ?? "", /OMCP_OTEL_ENABLED is off/);
+});
+test("initOtel — second call is idempotent (returns cached result)", async () => {
+    _resetOtelForTests();
+    const r1 = await initOtel({ env: { OMCP_OTEL_ENABLED: "false" } });
+    const r2 = await initOtel({ env: { OMCP_OTEL_ENABLED: "true" } });
+    // Second call MUST return the cached result, not re-init
+    assert.equal(r1.enabled, false);
+    assert.equal(r2.enabled, false, "second init returned cached disabled state");
+    assert.deepEqual(otelStatus(), r1);
+});
+test("initOtel — failure to import OTel packages degrades to disabled, not throw", async () => {
+    // We cannot easily simulate a missing dep in this sandbox, but we
+    // confirm the contract: on init failure, the result has enabled=false
+    // and a reason; nothing is thrown. With the actual deps installed the
+    // happy path is exercised in integration tests.
+    _resetOtelForTests();
+    const r = await initOtel({ env: { OMCP_OTEL_ENABLED: "true" } });
+    // Either it succeeded (deps present, enabled=true) or it failed
+    // gracefully (enabled=false + reason). Both are acceptable.
+    if (r.enabled) {
+        assert.ok(r.endpoint, "endpoint must be set when enabled");
+        assert.equal(r.serviceName, "observability-mcp");
+    }
+    else {
+        assert.ok(r.reason, "must include a reason on failure");
+    }
+});