@zivis/mcp 0.1.19 → 0.2.2

package/dist/tools/diagram.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { sanitizeResponse } from "../sanitize.js";
+export const DIAGRAM_NAME = "zivis_diagram";
+const DIAGRAM_TYPE_ENUM = [
+    "architecture",
+    "data_flow",
+    "attack_chain",
+    "sequence",
+    "trust_boundary",
+    "network",
+    "deployment",
+    "custom",
+];
+export const DIAGRAM_DESCRIPTION = `CRUD + link management for Mermaid diagrams (architecture, data flow, attack chain, sequence, trust boundary, network, deployment).
+
+action:
+- create: requires name, diagram_type, content (Mermaid source). Optional description, linked_threat_model_id.
+- get: requires diagram_id. Full Mermaid source + metadata — call before update_source.
+- list: optional diagram_type, search, linked_threat_model_id filters; limit (default 20, max 100).
+- update_metadata: requires diagram_id. Optional name/description/diagram_type.
+- update_source: requires diagram_id, mermaid_source (COMPLETE replacement source — get first, preserve unrelated nodes/edges/styles). Optional description of the change.
+- delete: requires diagram_id.
+- link_threat_model / unlink_threat_model: requires diagram_id, threat_model_id.`;
+export const DIAGRAM_SCHEMA = {
+    action: z
+        .enum([
+        "create",
+        "get",
+        "list",
+        "update_metadata",
+        "update_source",
+        "delete",
+        "link_threat_model",
+        "unlink_threat_model",
+    ])
+        .describe("Which diagram operation to perform"),
+    diagram_id: z.string().optional().describe("Diagram UUID. Required for every action except create/list."),
+    name: z.string().optional().describe("Diagram name. Required for create."),
+    description: z
+        .string()
+        .optional()
+        .describe("Diagram description (create/update_metadata), or a short note of what changed (update_source) — both write the same field."),
+    diagram_type: z.enum(DIAGRAM_TYPE_ENUM).optional().describe("Diagram type. Required for create; optional filter for list; optional for update_metadata."),
+    content: z.string().optional().describe("Mermaid diagram source. Required for create."),
+    linked_threat_model_id: z.string().optional().describe("Threat model UUID to link this diagram to right after creation (create only)."),
+    search: z.string().optional().describe("Search by diagram name or description (list)."),
+    limit: z.number().min(1).max(100).optional().describe("Maximum results, 1-100, default 20 (list)."),
+    mermaid_source: z.string().min(1).optional().describe("Full replacement Mermaid syntax. Required for update_source — replaces the entire content atomically."),
+    threat_model_id: z.string().optional().describe("Threat model UUID. Required for link_threat_model and unlink_threat_model."),
+};
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+function successResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(sanitizeResponse(data), null, 2) }],
+    };
+}
+export function createDiagramHandler(apiClient) {
+    return async (params) => {
+        try {
+            switch (params.action) {
+                case "create": {
+                    if (!params.name)
+                        return errorResult("name is required for create");
+                    if (!params.diagram_type)
+                        return errorResult("diagram_type is required for create");
+                    if (!params.content)
+                        return errorResult("content is required for create");
+                    const data = await apiClient.post("/api/diagrams", {
+                        name: params.name,
+                        description: params.description,
+                        diagramType: params.diagram_type,
+                        contentType: "mermaid",
+                        content: params.content,
+                        sourceType: "manual",
+                    });
+                    const sanitized = sanitizeResponse(data);
+                    const diagramId = sanitized.id;
+                    let linkedThreatModelId = null;
+                    if (params.linked_threat_model_id && diagramId) {
+                        try {
+                            await apiClient.post(`/api/diagrams/${diagramId}/link`, {
+                                threatModelId: params.linked_threat_model_id,
+                            });
+                            linkedThreatModelId = params.linked_threat_model_id;
+                        }
+                        catch {
+                        }
+                    }
+                    return successResult({
+                        diagram_id: diagramId,
+                        name: sanitized.name,
+                        diagram_type: sanitized.diagramType,
+                        linked_threat_model_id: linkedThreatModelId,
+                        _instruction: "Diagram created. Use zivis_diagram(action=get) to see full content, action=update_metadata to change metadata/links, or action=update_source to change the Mermaid source.",
+                    });
+                }
+                case "get": {
+                    if (!params.diagram_id)
+                        return errorResult("diagram_id is required for get");
+                    const data = await apiClient.get(`/api/diagrams/${params.diagram_id}`);
+                    const sanitized = sanitizeResponse(data);
+                    const linkedThreatModelIds = Array.isArray(sanitized.threatModelLinks)
+                        ? sanitized.threatModelLinks.map((l) => l.threatModelId)
+                        : [];
+                    return successResult({
+                        diagram_id: sanitized.id,
+                        name: sanitized.name,
+                        description: sanitized.description || null,
+                        diagram_type: sanitized.diagramType,
+                        content_type: sanitized.contentType,
+                        content: sanitized.content || null,
+                        source_type: sanitized.sourceType,
+                        created_at: sanitized.createdAt,
+                        updated_at: sanitized.updatedAt,
+                        linked_threat_model_ids: linkedThreatModelIds,
+                    });
+                }
+                case "list": {
+                    const query = new URLSearchParams();
+                    if (params.diagram_type)
+                        query.set("diagramType", params.diagram_type);
+                    if (params.search)
+                        query.set("search", params.search);
+                    if (params.linked_threat_model_id)
+                        query.set("linkedThreatModelId", params.linked_threat_model_id);
+                    if (params.limit)
+                        query.set("take", String(params.limit));
+                    const queryStr = query.toString();
+                    const path = `/api/diagrams${queryStr ? `?${queryStr}` : ""}`;
+                    const data = await apiClient.get(path);
+                    const sanitized = sanitizeResponse(data);
+                    const summary = Array.isArray(sanitized.diagrams)
+                        ? sanitized.diagrams.map((d) => ({
+                            diagram_id: d.id,
+                            name: d.name,
+                            diagram_type: d.diagramType,
+                            content_type: d.contentType,
+                            source_type: d.sourceType,
+                            description: d.description || null,
+                            created_at: d.createdAt,
+                            updated_at: d.updatedAt,
+                        }))
+                        : sanitized.diagrams;
+                    return successResult({ total: sanitized.total, diagrams: summary });
+                }
+                case "update_metadata": {
+                    if (!params.diagram_id)
+                        return errorResult("diagram_id is required for update_metadata");
+                    const body = {};
+                    if (params.name)
+                        body.name = params.name;
+                    if (params.description !== undefined)
+                        body.description = params.description;
+                    if (params.diagram_type)
+                        body.diagramType = params.diagram_type;
+                    const data = await apiClient.patch(`/api/diagrams/${params.diagram_id}`, body);
+                    return successResult(data);
+                }
+                case "update_source": {
+                    if (!params.diagram_id)
+                        return errorResult("diagram_id is required for update_source");
+                    if (!params.mermaid_source || params.mermaid_source.trim().length === 0) {
+                        return errorResult("mermaid_source is required and cannot be empty for update_source");
+                    }
+                    const body = { content: params.mermaid_source };
+                    if (params.description)
+                        body.description = params.description;
+                    const updated = await apiClient.patch(`/api/diagrams/${params.diagram_id}`, body);
+                    return successResult({ ok: true, diagram_id: params.diagram_id, updated });
+                }
+                case "delete": {
+                    if (!params.diagram_id)
+                        return errorResult("diagram_id is required for delete");
+                    await apiClient.del(`/api/diagrams/${params.diagram_id}`);
+                    return successResult({ action: "deleted", diagram_id: params.diagram_id });
+                }
+                case "link_threat_model": {
+                    if (!params.diagram_id)
+                        return errorResult("diagram_id is required for link_threat_model");
+                    if (!params.threat_model_id)
+                        return errorResult("threat_model_id is required for link_threat_model");
+                    const data = await apiClient.post(`/api/diagrams/${params.diagram_id}/link`, {
+                        threatModelId: params.threat_model_id,
+                    });
+                    return successResult(data);
+                }
+                case "unlink_threat_model": {
+                    if (!params.diagram_id)
+                        return errorResult("diagram_id is required for unlink_threat_model");
+                    if (!params.threat_model_id)
+                        return errorResult("threat_model_id is required for unlink_threat_model");
+                    await apiClient.del(`/api/diagrams/${params.diagram_id}/link/threat-model/${params.threat_model_id}`);
+                    return successResult({ action: "unlinked", diagram_id: params.diagram_id, threat_model_id: params.threat_model_id });
+                }
+                default:
+                    return errorResult(`Unknown action: ${params.action}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : `Failed to perform diagram action`;
+            return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+        }
+    };
+}

package/dist/tools/document.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+export declare const DOCUMENT_NAME = "zivis_document";
+export declare const DOCUMENT_DESCRIPTION = "CRUD for narrative markdown documents under a ThreatModel (exec summaries, remediation plans, architecture narratives). Can embed Diagrams (see zivis_diagram) via ```mermaid or ```zivis:diagram (UUID) fenced blocks.\n\naction:\n- create: requires title, exactly one of threat_model_id or entity_type+entity_id \u2014 or omit both threat_model_id and entity_type/entity_id entirely to attach to the current workspace's bound Application automatically. entity_type \"application\" with no entity_id also auto-resolves from that binding. Optional content, tags.\n- get: requires document_id. Full markdown + metadata.\n- list: optional threat_model_id or entity_type+entity_id, search filters.\n- update: requires document_id + at least one of title/content/tags. content REPLACES the whole document \u2014 get first, then send the complete edited markdown, preserving unrelated structure.";
+export declare const DOCUMENT_SCHEMA: {
+    action: z.ZodEnum<{
+        list: "list";
+        get: "get";
+        create: "create";
+        update: "update";
+    }>;
+    threat_model_id: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    document_id: z.ZodOptional<z.ZodString>;
+    entity_type: z.ZodOptional<z.ZodEnum<{
+        threat_model: "threat_model";
+        application: "application";
+        agent_instance: "agent_instance";
+        scan: "scan";
+        finding: "finding";
+        attack_scenario: "attack_scenario";
+        component: "component";
+        trust_room: "trust_room";
+        campaign: "campaign";
+    }>>;
+    entity_id: z.ZodOptional<z.ZodString>;
+    search: z.ZodOptional<z.ZodString>;
+};
+type DocumentParams = {
+    action: "create" | "get" | "list" | "update";
+    threat_model_id?: string;
+    title?: string;
+    content?: string;
+    tags?: string[];
+    document_id?: string;
+    entity_type?: string;
+    entity_id?: string;
+    search?: string;
+};
+export declare function createDocumentHandler(apiClient: ApiClient): (params: DocumentParams) => Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export {};

package/dist/tools/document.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { sanitizeResponse, sanitizeInboundText } from "../sanitize.js";
+import { requireApplicationId } from "../resolve-application-id.js";
+export const DOCUMENT_NAME = "zivis_document";
+export const DOCUMENT_DESCRIPTION = `CRUD for narrative markdown documents under a ThreatModel (exec summaries, remediation plans, architecture narratives). Can embed Diagrams (see zivis_diagram) via \`\`\`mermaid or \`\`\`zivis:diagram (UUID) fenced blocks.
+
+action:
+- create: requires title, exactly one of threat_model_id or entity_type+entity_id — or omit both threat_model_id and entity_type/entity_id entirely to attach to the current workspace's bound Application automatically. entity_type "application" with no entity_id also auto-resolves from that binding. Optional content, tags.
+- get: requires document_id. Full markdown + metadata.
+- list: optional threat_model_id or entity_type+entity_id, search filters.
+- update: requires document_id + at least one of title/content/tags. content REPLACES the whole document — get first, then send the complete edited markdown, preserving unrelated structure.`;
+const ENTITY_TYPE_ENUM = [
+    "application",
+    "threat_model",
+    "agent_instance",
+    "scan",
+    "finding",
+    "attack_scenario",
+    "component",
+    "trust_room",
+    "campaign",
+];
+export const DOCUMENT_SCHEMA = {
+    action: z.enum(["create", "get", "list", "update"]).describe("Which document operation to perform"),
+    threat_model_id: z.string().optional().describe("UUID of the parent threat model. For create, alternative to entity_type+entity_id — provide exactly one, not both. Optional filter for list."),
+    title: z.string().optional().describe("Document title. Required for create."),
+    content: z.string().optional().describe("Markdown content. For update, REPLACES the entire document."),
+    tags: z.array(z.string()).optional().describe("Tags. For update, replaces existing tags."),
+    document_id: z.string().optional().describe("UUID of the document. Required for get and update."),
+    entity_type: z.enum(ENTITY_TYPE_ENUM).optional().describe("Polymorphic parent entity type, for attaching a document directly to something other than a ThreatModel (e.g. an Application with no ThreatModel). For create, alternative to threat_model_id — provide exactly one, not both. Must be paired with entity_id. Optional filter for list (also paired with entity_id)."),
+    entity_id: z.string().optional().describe("UUID of the entity_type target. Must be paired with entity_type."),
+    search: z.string().optional().describe("Filter by title (case-insensitive substring) or tag. Used by list."),
+};
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+function successResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(sanitizeResponse(data), null, 2) }],
+    };
+}
+export function createDocumentHandler(apiClient) {
+    return async (params) => {
+        try {
+            switch (params.action) {
+                case "create": {
+                    const { threat_model_id, title, content, tags, entity_type, entity_id } = params;
+                    if (!title || !title.trim())
+                        return errorResult("title is required for create");
+                    const hasTm = !!threat_model_id;
+                    let hasEntityType = !!entity_type;
+                    let hasEntityId = !!entity_id;
+                    let resolvedEntityType = entity_type;
+                    let resolvedEntityId = entity_id;
+                    if (!hasTm && !hasEntityType && !hasEntityId) {
+                        const req = requireApplicationId(undefined);
+                        if (!req.ok)
+                            return errorResult(req.message);
+                        resolvedEntityType = "application";
+                        resolvedEntityId = req.id;
+                        hasEntityType = true;
+                        hasEntityId = true;
+                    }
+                    else if (!hasTm && entity_type === "application" && !hasEntityId) {
+                        const req = requireApplicationId(undefined);
+                        if (!req.ok)
+                            return errorResult(req.message);
+                        resolvedEntityId = req.id;
+                        hasEntityId = true;
+                    }
+                    if (hasEntityType !== hasEntityId) {
+                        return errorResult("entity_type and entity_id must be provided together");
+                    }
+                    const hasEntity = hasEntityType && hasEntityId;
+                    if (hasTm && hasEntity) {
+                        return errorResult("Provide either threat_model_id or entity_type+entity_id, not both");
+                    }
+                    if (!hasTm && !hasEntity) {
+                        return errorResult("Provide either threat_model_id or entity_type+entity_id");
+                    }
+                    const data = await apiClient.post(`/api/documents`, {
+                        ...(hasTm ? { threatModelId: threat_model_id } : { entityType: resolvedEntityType, entityId: resolvedEntityId }),
+                        title: sanitizeInboundText(title, 500),
+                        content: sanitizeInboundText(content ?? "", 200_000),
+                        tags: tags ?? [],
+                    });
+                    return successResult(data);
+                }
+                case "get": {
+                    if (!params.document_id)
+                        return errorResult("document_id is required for get");
+                    const data = await apiClient.get(`/api/documents/${params.document_id}`);
+                    return successResult(data);
+                }
+                case "list": {
+                    const qs = new URLSearchParams();
+                    if (params.threat_model_id)
+                        qs.set("threatModelId", params.threat_model_id);
+                    if (params.entity_type && params.entity_id) {
+                        qs.set("entityType", params.entity_type);
+                        qs.set("entityId", params.entity_id);
+                    }
+                    if (params.search)
+                        qs.set("search", params.search);
+                    const path = `/api/documents${qs.toString() ? `?${qs.toString()}` : ""}`;
+                    const data = await apiClient.get(path);
+                    return successResult(data);
+                }
+                case "update": {
+                    const { document_id, title, content, tags } = params;
+                    if (!document_id)
+                        return errorResult("document_id is required for update");
+                    if (title === undefined && content === undefined && tags === undefined) {
+                        return errorResult("At least one of title, content, or tags must be provided for update");
+                    }
+                    const body = {};
+                    if (title !== undefined)
+                        body.title = sanitizeInboundText(title, 500);
+                    if (content !== undefined)
+                        body.content = sanitizeInboundText(content, 200_000);
+                    if (tags !== undefined)
+                        body.tags = tags;
+                    const data = await apiClient.patch(`/api/documents/${document_id}`, body);
+                    return successResult({ ok: true, document_id, updated: data });
+                }
+                default:
+                    return errorResult(`Unknown action: ${params.action}`);
+            }
+        }
+        catch (err) {
+            return errorResult(err?.message ?? `Failed to ${params.action} document`);
+        }
+    };
+}

package/dist/tools/finding.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+export declare const FINDING_NAME = "zivis_finding";
+export declare const FINDING_DESCRIPTION = "Create, update, or delete a tracked security finding authored by hand (not from a scanner). Every change is audited.\n\naction:\n- create: requires title, severity. For service-delivered results (pen test/red team/ZRT), pass source_type + producer (requires run_agents permission).\n- update: requires finding_id. Two kinds of change, never mixed in one call:\n    1. Direct edit: title/severity/description/category/remediation_steps/cwe_id/owasp_id, and non-closing status (open|triaged|in_progress).\n    2. Disposition (`disposition`: open|fixed|accepted_by_design|accepted_risk_based|planned|not_applicable, + rationale/ref/owner_name/target_date/review_date/compensating_controls/residual_severity/note) \u2014 records the customer's claim/decision. disposition=fixed does NOT close the finding: status is only ever derived from (disposition, independent verification) \u2014 a claim never closes a finding, only an independent ZIVIS verdict does. Closing values (resolved/dismissed/suppressed) are REJECTED on the direct-edit path; use `disposition` instead.\n- delete: requires finding_id. Soft-delete, manual findings only.";
+export declare const FINDING_SCHEMA: {
+    action: z.ZodEnum<{
+        create: "create";
+        delete: "delete";
+        update: "update";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        high: "high";
+        medium: "medium";
+        low: "low";
+        info: "info";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodEnum<{
+        vulnerability: "vulnerability";
+        misconfiguration: "misconfiguration";
+        secret: "secret";
+        anomaly: "anomaly";
+        other: "other";
+    }>>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>>;
+    application_id: z.ZodOptional<z.ZodString>;
+    source_document_id: z.ZodOptional<z.ZodString>;
+    excerpt: z.ZodOptional<z.ZodString>;
+    evidence_location: z.ZodOptional<z.ZodString>;
+    cwe_id: z.ZodOptional<z.ZodString>;
+    owasp_id: z.ZodOptional<z.ZodString>;
+    remediation_steps: z.ZodOptional<z.ZodString>;
+    source_type: z.ZodOptional<z.ZodEnum<{
+        threat_model: "threat_model";
+        manual: "manual";
+        pen_test: "pen_test";
+        red_team: "red_team";
+    }>>;
+    producer: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            zrt: "zrt";
+            frontier_tool: "frontier_tool";
+            third_party: "third_party";
+        }>;
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        toolVersion: z.ZodOptional<z.ZodString>;
+        engagementId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    scenario_id: z.ZodOptional<z.ZodString>;
+    attack_step_id: z.ZodOptional<z.ZodString>;
+    finding_id: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        triaged: "triaged";
+        in_progress: "in_progress";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+    disposition: z.ZodOptional<z.ZodEnum<{
+        fixed: "fixed";
+        open: "open";
+        accepted_by_design: "accepted_by_design";
+        accepted_risk_based: "accepted_risk_based";
+        planned: "planned";
+        not_applicable: "not_applicable";
+    }>>;
+    rationale: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    owner_name: z.ZodOptional<z.ZodString>;
+    target_date: z.ZodOptional<z.ZodString>;
+    review_date: z.ZodOptional<z.ZodString>;
+    compensating_controls: z.ZodOptional<z.ZodString>;
+    residual_severity: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        high: "high";
+        medium: "medium";
+        low: "low";
+        info: "info";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+};
+type Producer = {
+    kind: "human" | "zrt" | "frontier_tool" | "third_party";
+    id?: string;
+    name?: string;
+    toolVersion?: string;
+    engagementId?: string;
+};
+type FindingParams = {
+    action: "create" | "update" | "delete";
+    title?: string;
+    severity?: "critical" | "high" | "medium" | "low" | "info";
+    description?: string;
+    category?: "vulnerability" | "misconfiguration" | "secret" | "anomaly" | "other";
+    confidence?: "high" | "medium" | "low";
+    application_id?: string;
+    source_document_id?: string;
+    excerpt?: string;
+    evidence_location?: string;
+    cwe_id?: string;
+    owasp_id?: string;
+    remediation_steps?: string;
+    source_type?: "manual" | "pen_test" | "red_team" | "threat_model";
+    producer?: Producer;
+    scenario_id?: string;
+    attack_step_id?: string;
+    finding_id?: string;
+    status?: "open" | "triaged" | "in_progress";
+    note?: string;
+    disposition?: "open" | "fixed" | "accepted_by_design" | "accepted_risk_based" | "planned" | "not_applicable";
+    rationale?: string;
+    ref?: string;
+    owner_name?: string;
+    target_date?: string;
+    review_date?: string;
+    compensating_controls?: string;
+    residual_severity?: "critical" | "high" | "medium" | "low" | "info";
+    reason?: string;
+};
+export declare function createFindingHandler(apiClient: ApiClient): (params: FindingParams) => Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export {};