@thotischner/observability-mcp 3.7.0 → 3.8.0

package/dist/inspect/index.js

@@ -0,0 +1,13 @@
+// Inspect — observe / learn / enforce for MCP tool calls.
+//
+// Barrel for the inspection subsystem. Phase 1 ships the observe core
+// (recorder + store + signature + mode + flow-graph aggregation); profile
+// derivation and dry-run/enforce decisioning land in later phases.
+export * from "./signature.js";
+export * from "./store.js";
+export * from "./mode.js";
+export * from "./graph.js";
+export * from "./recorder.js";
+export * from "./enforcer.js";
+export * from "./profile.js";
+export * from "./profile-store.js";

package/dist/inspect/mode.d.ts

@@ -0,0 +1,20 @@
+export type InspectMode = "off" | "observe" | "dryrun" | "enforce";
+export declare const INSPECT_MODES: readonly InspectMode[];
+/** Parse a user/env string into a mode, or null when unrecognised. */
+export declare function parseMode(s: unknown): InspectMode | null;
+/** Resolve the boot mode from an env value, defaulting to `observe`. */
+export declare function bootMode(envValue: unknown): InspectMode;
+export declare class ModeController {
+    private mode;
+    private readonly onChange?;
+    constructor(initial?: InspectMode, onChange?: (m: InspectMode) => void);
+    get(): InspectMode;
+    /** Set the mode. Returns the resolved mode; throws on an invalid value. */
+    set(next: unknown): InspectMode;
+    /** True when the recorder should capture observations. */
+    get recording(): boolean;
+    /** True when calls should be evaluated against the profile. */
+    get evaluating(): boolean;
+    /** True when a deviation should actually be blocked. */
+    get blocking(): boolean;
+}

package/dist/inspect/mode.js

@@ -0,0 +1,57 @@
+// Inspect — mode state machine.
+//
+// off → observe → dryrun → enforce. `observe` is the default and is purely a
+// recorder (zero decision on the call path). `dryrun` and `enforce` add a
+// profile evaluation; only `enforce` ever blocks. The boot default comes from
+// OMCP_INSPECT; the mode can be changed at runtime via the API.
+export const INSPECT_MODES = ["off", "observe", "dryrun", "enforce"];
+/** Parse a user/env string into a mode, or null when unrecognised. */
+export function parseMode(s) {
+    if (typeof s !== "string")
+        return null;
+    const v = s.trim().toLowerCase();
+    // Friendly aliases.
+    if (v === "complain")
+        return "dryrun";
+    if (v === "dry-run")
+        return "dryrun";
+    if (v === "on")
+        return "observe";
+    return INSPECT_MODES.includes(v) ? v : null;
+}
+/** Resolve the boot mode from an env value, defaulting to `observe`. */
+export function bootMode(envValue) {
+    return parseMode(envValue) ?? "observe";
+}
+export class ModeController {
+    mode;
+    onChange;
+    constructor(initial = "observe", onChange) {
+        this.mode = initial;
+        this.onChange = onChange;
+    }
+    get() {
+        return this.mode;
+    }
+    /** Set the mode. Returns the resolved mode; throws on an invalid value. */
+    set(next) {
+        const m = parseMode(next);
+        if (!m)
+            throw new Error(`invalid inspect mode '${String(next)}' (allowed: ${INSPECT_MODES.join(", ")})`);
+        this.mode = m;
+        this.onChange?.(m);
+        return m;
+    }
+    /** True when the recorder should capture observations. */
+    get recording() {
+        return this.mode !== "off";
+    }
+    /** True when calls should be evaluated against the profile. */
+    get evaluating() {
+        return this.mode === "dryrun" || this.mode === "enforce";
+    }
+    /** True when a deviation should actually be blocked. */
+    get blocking() {
+        return this.mode === "enforce";
+    }
+}

package/dist/inspect/mode.test.d.ts

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

package/dist/inspect/mode.test.js

@@ -0,0 +1,53 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ModeController, parseMode, bootMode } from "./mode.js";
+describe("parseMode / bootMode", () => {
+    it("accepts canonical modes + friendly aliases", () => {
+        assert.equal(parseMode("off"), "off");
+        assert.equal(parseMode("observe"), "observe");
+        assert.equal(parseMode("dryrun"), "dryrun");
+        assert.equal(parseMode("enforce"), "enforce");
+        assert.equal(parseMode("DRY-RUN"), "dryrun");
+        assert.equal(parseMode("complain"), "dryrun");
+        assert.equal(parseMode("on"), "observe");
+    });
+    it("rejects junk", () => {
+        assert.equal(parseMode("nope"), null);
+        assert.equal(parseMode(123), null);
+        assert.equal(parseMode(undefined), null);
+    });
+    it("bootMode defaults to observe", () => {
+        assert.equal(bootMode(undefined), "observe");
+        assert.equal(bootMode("enforce"), "enforce");
+        assert.equal(bootMode("garbage"), "observe");
+    });
+});
+describe("ModeController", () => {
+    it("exposes recording/evaluating/blocking per mode", () => {
+        const off = new ModeController("off");
+        assert.equal(off.recording, false);
+        assert.equal(off.evaluating, false);
+        assert.equal(off.blocking, false);
+        const observe = new ModeController("observe");
+        assert.equal(observe.recording, true);
+        assert.equal(observe.evaluating, false);
+        assert.equal(observe.blocking, false);
+        const dry = new ModeController("dryrun");
+        assert.equal(dry.recording, true);
+        assert.equal(dry.evaluating, true);
+        assert.equal(dry.blocking, false);
+        const enf = new ModeController("enforce");
+        assert.equal(enf.recording, true);
+        assert.equal(enf.evaluating, true);
+        assert.equal(enf.blocking, true);
+    });
+    it("set() validates and fires onChange", () => {
+        const seen = [];
+        const m = new ModeController("observe", (x) => seen.push(x));
+        assert.equal(m.set("enforce"), "enforce");
+        assert.equal(m.get(), "enforce");
+        assert.deepEqual(seen, ["enforce"]);
+        assert.throws(() => m.set("bogus"), /invalid inspect mode/);
+        assert.equal(m.get(), "enforce"); // unchanged after a bad set
+    });
+});

package/dist/inspect/profile-store.d.ts

@@ -0,0 +1,42 @@
+import type { Observation } from "./store.js";
+import { type CallSignature, type EvalResult, type ProfileRule, type RuleStatus } from "./profile.js";
+export interface ProfileStoreOptions {
+    file?: string;
+    /** Seam: initial rules (tests). */
+    rules?: ProfileRule[];
+    /** Seams for tests. */
+    reader?: (file: string) => string;
+    writer?: (file: string, data: string) => void;
+    now?: () => number;
+}
+export declare class ProfileStore {
+    private rules;
+    private readonly file?;
+    private readonly reader;
+    private readonly writer;
+    private readonly now;
+    constructor(opts?: ProfileStoreOptions);
+    private load;
+    private persist;
+    list(): ProfileRule[];
+    suggested(): ProfileRule[];
+    accepted(): ProfileRule[];
+    /** Derive suggestions from observations, merge, persist; return all rules. */
+    derive(observations: Observation[]): ProfileRule[];
+    /** Accept/reject/reset a rule by id. Returns the updated rule or null. */
+    setStatus(id: string, status: RuleStatus): ProfileRule | null;
+    /** Replace a rule's constraints (manual edit). Returns updated rule or null. */
+    update(id: string, patch: Partial<Pick<ProfileRule, "constraints" | "subject">>): ProfileRule | null;
+    remove(id: string): boolean;
+    /**
+     * Absorb a single (deviating) call into the profile: widen the accepted rule
+     * for (subject, tool) to include this call's resource values + arg buckets,
+     * creating a tight accepted rule if none exists. Makes exactly that observed
+     * shape allowed — the "add this deviation to the profile" one-click. Returns
+     * the upserted rule.
+     */
+    absorb(call: CallSignature): ProfileRule;
+    evaluate(call: CallSignature): EvalResult;
+    get size(): number;
+    get persisted(): boolean;
+}

package/dist/inspect/profile-store.js

@@ -0,0 +1,139 @@
+// Inspect — profile persistence + CRUD.
+//
+// Holds the rule set, derives suggestions from observations, lets a reviewer
+// accept/reject, and evaluates calls against the accepted rules. Persists to
+// OMCP_INSPECT_PROFILE_FILE (JSON) when configured; in-memory otherwise.
+// Reads/writes are best-effort and never throw into the call path.
+import { readFileSync, writeFileSync } from "node:fs";
+import { deriveProfile, evaluateCall, ruleId, } from "./profile.js";
+export class ProfileStore {
+    rules = [];
+    file;
+    reader;
+    writer;
+    now;
+    constructor(opts = {}) {
+        this.file = opts.file;
+        this.reader = opts.reader ?? ((f) => readFileSync(f, "utf8"));
+        this.writer = opts.writer ?? ((f, d) => writeFileSync(f, d));
+        this.now = opts.now ?? (() => Date.now());
+        if (opts.rules)
+            this.rules = opts.rules;
+        else if (this.file)
+            this.load();
+    }
+    load() {
+        if (!this.file)
+            return;
+        try {
+            const parsed = JSON.parse(this.reader(this.file));
+            if (parsed && Array.isArray(parsed.rules))
+                this.rules = parsed.rules;
+        }
+        catch {
+            // Missing/invalid file → start empty; never fatal.
+        }
+    }
+    persist() {
+        if (!this.file)
+            return;
+        try {
+            this.writer(this.file, JSON.stringify({ rules: this.rules }, null, 2));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    list() {
+        return [...this.rules];
+    }
+    suggested() {
+        return this.rules.filter((r) => r.status === "suggested");
+    }
+    accepted() {
+        return this.rules.filter((r) => r.status === "accepted");
+    }
+    /** Derive suggestions from observations, merge, persist; return all rules. */
+    derive(observations) {
+        this.rules = deriveProfile(observations, this.rules);
+        this.persist();
+        return this.list();
+    }
+    /** Accept/reject/reset a rule by id. Returns the updated rule or null. */
+    setStatus(id, status) {
+        const r = this.rules.find((x) => x.id === id);
+        if (!r)
+            return null;
+        r.status = status;
+        this.persist();
+        return r;
+    }
+    /** Replace a rule's constraints (manual edit). Returns updated rule or null. */
+    update(id, patch) {
+        const r = this.rules.find((x) => x.id === id);
+        if (!r)
+            return null;
+        if (patch.constraints)
+            r.constraints = patch.constraints;
+        if (patch.subject)
+            r.subject = patch.subject;
+        this.persist();
+        return r;
+    }
+    remove(id) {
+        const before = this.rules.length;
+        this.rules = this.rules.filter((x) => x.id !== id);
+        if (this.rules.length !== before) {
+            this.persist();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Absorb a single (deviating) call into the profile: widen the accepted rule
+     * for (subject, tool) to include this call's resource values + arg buckets,
+     * creating a tight accepted rule if none exists. Makes exactly that observed
+     * shape allowed — the "add this deviation to the profile" one-click. Returns
+     * the upserted rule.
+     */
+    absorb(call) {
+        const id = ruleId(call.principal, call.tool);
+        const ts = new Date(this.now()).toISOString();
+        let r = this.rules.find((x) => x.id === id);
+        if (!r) {
+            r = { id, subject: call.principal, tool: call.tool, constraints: {}, status: "accepted", provenance: { learnedFrom: 1, firstSeen: ts, lastSeen: ts } };
+            this.rules.push(r);
+        }
+        else {
+            r.status = "accepted";
+            r.provenance.lastSeen = ts;
+        }
+        const add = (arr, v) => {
+            const a = arr ?? [];
+            if (!a.includes(v))
+                a.push(v);
+            a.sort();
+            return a;
+        };
+        for (const dim of ["source", "service", "namespace"]) {
+            const v = call[dim];
+            if (v != null)
+                r.constraints[dim] = add(r.constraints[dim], v);
+        }
+        for (const [k, b] of Object.entries(call.argShape || {})) {
+            r.constraints.argShape = r.constraints.argShape ?? {};
+            r.constraints.argShape[k] = add(r.constraints.argShape[k], b);
+        }
+        this.persist();
+        return r;
+    }
+    evaluate(call) {
+        return evaluateCall(call, this.rules);
+    }
+    get size() {
+        return this.rules.length;
+    }
+    get persisted() {
+        return !!this.file;
+    }
+}

package/dist/inspect/profile-store.test.d.ts

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

package/dist/inspect/profile-store.test.js

@@ -0,0 +1,82 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ProfileStore } from "./profile-store.js";
+import { ruleId } from "./profile.js";
+let seq = 0;
+function obs(over = {}) {
+    return {
+        ts: new Date(1_700_000_000_000 + seq * 1000).toISOString(),
+        seq: ++seq,
+        principal: "key:bot", auth: "apikey", tenant: "default", tool: "query_logs",
+        argShape: {}, outcome: "ok", decision: "allow", redactions: 0, ...over,
+    };
+}
+describe("ProfileStore", () => {
+    it("derive → setStatus(accept) → evaluate allows learned, flags novel", () => {
+        const s = new ProfileStore();
+        s.derive([obs({ principal: "a", tool: "query_logs", service: "pay", argShape: { window: "<=1h" } })]);
+        assert.equal(s.suggested().length, 1);
+        assert.equal(s.accepted().length, 0);
+        const id = ruleId("a", "query_logs");
+        s.setStatus(id, "accepted");
+        assert.equal(s.accepted().length, 1);
+        assert.equal(s.evaluate({ principal: "a", tool: "query_logs", service: "pay", argShape: { window: "<=1h" } }).verdict, "allow");
+        assert.equal(s.evaluate({ principal: "a", tool: "query_logs", service: "x", argShape: {} }).kind, "new-resource");
+    });
+    it("setStatus/remove return null/false for unknown ids", () => {
+        const s = new ProfileStore();
+        assert.equal(s.setStatus("nope", "accepted"), null);
+        assert.equal(s.remove("nope"), false);
+    });
+    it("update replaces constraints", () => {
+        const s = new ProfileStore();
+        s.derive([obs({ principal: "a", tool: "t", service: "s1" })]);
+        const id = ruleId("a", "t");
+        s.update(id, { constraints: { service: ["s1", "s2"] } });
+        assert.deepEqual(s.list().find((r) => r.id === id).constraints.service, ["s1", "s2"]);
+    });
+    it("persists via the writer seam and reloads via the reader seam", () => {
+        let blob = "";
+        const a = new ProfileStore({ file: "profile-store-test.json", reader: () => { throw new Error("absent"); }, writer: (_f, d) => { blob = d; } });
+        a.derive([obs({ principal: "a", tool: "t", service: "s" })]);
+        a.setStatus(ruleId("a", "t"), "accepted");
+        assert.ok(blob.includes('"accepted"'));
+        // a fresh store reads it back
+        const b = new ProfileStore({ file: "profile-store-test.json", reader: () => blob, writer: () => { } });
+        assert.equal(b.accepted().length, 1);
+        assert.equal(b.persisted, true);
+    });
+    it("absorb: creates a tight accepted rule for a brand-new deviation", () => {
+        const s = new ProfileStore();
+        const r = s.absorb({ principal: "mallory", tool: "query_logs", service: "pay", argShape: { window: "<=1h" } });
+        assert.equal(r.status, "accepted");
+        assert.deepEqual(r.constraints.service, ["pay"]);
+        assert.deepEqual(r.constraints.argShape.window, ["<=1h"]);
+        // that exact call is now allowed
+        assert.equal(s.evaluate({ principal: "mallory", tool: "query_logs", service: "pay", argShape: { window: "<=1h" } }).verdict, "allow");
+    });
+    it("absorb: widens an existing accepted rule (sorted union, no dupes)", () => {
+        const s = new ProfileStore();
+        s.absorb({ principal: "a", tool: "t", service: "s1", argShape: {} });
+        const r = s.absorb({ principal: "a", tool: "t", service: "s2", argShape: {} });
+        assert.deepEqual(r.constraints.service, ["s1", "s2"]);
+        // idempotent
+        const r2 = s.absorb({ principal: "a", tool: "t", service: "s2", argShape: {} });
+        assert.deepEqual(r2.constraints.service, ["s1", "s2"]);
+        assert.equal(s.list().filter((x) => x.id === ruleId("a", "t")).length, 1);
+    });
+    it("absorb: flips a previously-rejected/suggested rule to accepted", () => {
+        const s = new ProfileStore();
+        s.derive([obs({ principal: "a", tool: "t", service: "s1" })]); // suggested
+        s.setStatus(ruleId("a", "t"), "rejected");
+        const r = s.absorb({ principal: "a", tool: "t", service: "s9", argShape: {} });
+        assert.equal(r.status, "accepted");
+        assert.deepEqual(r.constraints.service, ["s1", "s9"]);
+    });
+    it("a missing/invalid file starts empty, never throws", () => {
+        assert.doesNotThrow(() => {
+            const s = new ProfileStore({ file: "profile-store-missing.json", reader: () => "not json{", writer: () => { } });
+            assert.equal(s.size, 0);
+        });
+    });
+});

package/dist/inspect/profile.d.ts

@@ -0,0 +1,51 @@
+import type { Observation } from "./store.js";
+export type RuleStatus = "suggested" | "accepted" | "rejected";
+export type DeviationKind = "new-principal" | "new-tool" | "new-resource" | "arg-out-of-range";
+export interface RuleConstraints {
+    source?: string[];
+    service?: string[];
+    namespace?: string[];
+    /** Per arg key → the set of buckets seen during learning. */
+    argShape?: Record<string, string[]>;
+}
+export interface ProfileRule {
+    id: string;
+    subject: string;
+    tool: string;
+    constraints: RuleConstraints;
+    status: RuleStatus;
+    provenance: {
+        learnedFrom: number;
+        firstSeen: string;
+        lastSeen: string;
+    };
+}
+export interface EvalResult {
+    verdict: "allow" | "deviation";
+    kind?: DeviationKind;
+    ruleId?: string;
+    detail?: string;
+}
+/** Stable per (subject, tool) id so derive() is idempotent. */
+export declare function ruleId(subject: string, tool: string): string;
+/**
+ * Derive suggested rules from observations, merged onto an existing rule set.
+ * Returns the FULL updated rule list. Accepted/rejected rules are preserved;
+ * suggested rules are refreshed from the latest traffic.
+ */
+export declare function deriveProfile(observations: Observation[], existing?: ProfileRule[]): ProfileRule[];
+/** A minimal call shape evaluate() needs (a subset of an Observation). */
+export interface CallSignature {
+    principal: string;
+    tool: string;
+    source?: string;
+    service?: string;
+    namespace?: string;
+    argShape: Record<string, string>;
+}
+/**
+ * Evaluate a call against the ACCEPTED rules of a profile. Returns allow when
+ * an accepted rule covers it, else a deviation classified by kind. Suggested /
+ * rejected rules are ignored.
+ */
+export declare function evaluateCall(call: CallSignature, rules: ProfileRule[]): EvalResult;

package/dist/inspect/profile.js

@@ -0,0 +1,111 @@
+// Inspect — behavior profile (the AppArmor-style learned ruleset).
+//
+// A profile is a set of rules, one per (subject, tool). Each rule is *derived*
+// from observed traffic (the union of resource dimensions + argument-shape
+// buckets seen for that subject+tool), lands as `suggested`, and a human
+// accepts / rejects it. Only `accepted` rules are consulted by evaluate() in
+// dry-run / enforce — `suggested` rules never block anything.
+//
+// derive() is idempotent: re-running refreshes `suggested` rules from fresh
+// traffic but never mutates a human's accepted/rejected decision, and never
+// resurrects a rejected rule.
+/** Stable per (subject, tool) id so derive() is idempotent. */
+export function ruleId(subject, tool) {
+    return subject + "::" + tool;
+}
+const RES_DIMS = ["source", "service", "namespace"];
+function uniqSorted(xs) {
+    return [...new Set(xs)].sort();
+}
+/** Build a constraint set from a group of observations. */
+function constraintsFrom(group) {
+    const c = {};
+    for (const dim of RES_DIMS) {
+        const vals = group.map((o) => o[dim]).filter((v) => typeof v === "string" && v.length > 0);
+        if (vals.length)
+            c[dim] = uniqSorted(vals);
+    }
+    const argKeys = new Set();
+    group.forEach((o) => Object.keys(o.argShape || {}).forEach((k) => argKeys.add(k)));
+    if (argKeys.size) {
+        c.argShape = {};
+        for (const k of argKeys) {
+            const buckets = group.map((o) => o.argShape?.[k]).filter((v) => typeof v === "string");
+            c.argShape[k] = uniqSorted(buckets);
+        }
+    }
+    return c;
+}
+/**
+ * Derive suggested rules from observations, merged onto an existing rule set.
+ * Returns the FULL updated rule list. Accepted/rejected rules are preserved;
+ * suggested rules are refreshed from the latest traffic.
+ */
+export function deriveProfile(observations, existing = []) {
+    const byId = new Map();
+    for (const r of existing)
+        byId.set(r.id, r);
+    // Group observations by (subject, tool).
+    const groups = new Map();
+    for (const o of observations) {
+        const id = ruleId(o.principal, o.tool);
+        const g = groups.get(id);
+        if (g)
+            g.push(o);
+        else
+            groups.set(id, [o]);
+    }
+    for (const [id, group] of groups) {
+        const existingRule = byId.get(id);
+        if (existingRule && existingRule.status !== "suggested")
+            continue; // never touch a human decision
+        const sorted = [...group].sort((a, b) => a.ts.localeCompare(b.ts));
+        byId.set(id, {
+            id,
+            subject: group[0].principal,
+            tool: group[0].tool,
+            constraints: constraintsFrom(group),
+            status: "suggested",
+            provenance: {
+                learnedFrom: group.length,
+                firstSeen: sorted[0].ts,
+                lastSeen: sorted[sorted.length - 1].ts,
+            },
+        });
+    }
+    return [...byId.values()];
+}
+/**
+ * Evaluate a call against the ACCEPTED rules of a profile. Returns allow when
+ * an accepted rule covers it, else a deviation classified by kind. Suggested /
+ * rejected rules are ignored.
+ */
+export function evaluateCall(call, rules) {
+    const accepted = rules.filter((r) => r.status === "accepted");
+    const subjectRules = accepted.filter((r) => r.subject === call.principal || r.subject === "*");
+    if (subjectRules.length === 0) {
+        // Has the subject any accepted rule at all? (Distinguishes a wholly-new
+        // principal from a known principal reaching for a new tool.)
+        const known = accepted.some((r) => r.subject === call.principal);
+        return { verdict: "deviation", kind: known ? "new-tool" : "new-principal" };
+    }
+    const rule = subjectRules.find((r) => r.tool === call.tool);
+    if (!rule)
+        return { verdict: "deviation", kind: "new-tool" };
+    for (const dim of RES_DIMS) {
+        const v = call[dim];
+        if (v == null)
+            continue;
+        const allowed = rule.constraints[dim];
+        if (!allowed || !allowed.includes(v)) {
+            return { verdict: "deviation", kind: "new-resource", ruleId: rule.id, detail: `${dim}=${v}` };
+        }
+    }
+    for (const [k, bucket] of Object.entries(call.argShape || {})) {
+        const allowed = rule.constraints.argShape?.[k];
+        if (!allowed || !allowed.includes(bucket)) {
+            return { verdict: "deviation", kind: "arg-out-of-range", ruleId: rule.id, detail: `${k}=${bucket}` };
+        }
+    }
+    return { verdict: "allow", ruleId: rule.id };
+}

package/dist/inspect/profile.test.d.ts

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