@zivis/mcp 0.1.8 → 0.1.10

package/dist/index.d.ts

@@ -1,8 +1,2 @@
 #!/usr/bin/env node
-/**
- * ZIVIS MCP Security Server — Entry Point
- *
- * CLI tool and MCP server for AI-assisted security finding remediation.
- * Connects AI coding assistants to the ZIVIS security platform.
- */
 export {};

package/dist/index.js

@@ -1,10 +1,4 @@
 #!/usr/bin/env node
-/**
- * ZIVIS MCP Security Server — Entry Point
- *
- * CLI tool and MCP server for AI-assisted security finding remediation.
- * Connects AI coding assistants to the ZIVIS security platform.
- */
 import { parseArgs, runCli } from "./cli.js";
 import { DEFAULT_CONFIG } from "./types.js";
 const { command, options } = parseArgs(process.argv);
@@ -12,4 +6,3 @@ runCli(command, options, DEFAULT_CONFIG).catch((err) => {
     console.error("Fatal error:", err instanceof Error ? err.message : err);
     process.exit(1);
 });
-//# sourceMappingURL=index.js.map

package/dist/lib/inspect-cache.d.ts

@@ -0,0 +1,10 @@
+export interface LocatedArtifact {
+    path: string;
+    mtimeMs: number;
+}
+export declare function userCacheRoot(): string;
+export declare function deriveRepoId(cwd: string): Promise<string>;
+export declare function locateLatestArtifact(cwd: string): Promise<LocatedArtifact | undefined>;
+export declare const DEFAULT_INSPECT_CACHE_TTL_MS: number;
+export declare function inspectCacheTtlMs(): number;
+export declare function isFresh(mtimeMs: number, now?: number): boolean;

package/dist/lib/inspect-cache.js

@@ -0,0 +1,75 @@
+import * as fs from "node:fs/promises";
+import * as fssync from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+export function userCacheRoot() {
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Caches", "zivis");
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        return path.join(localAppData, "zivis", "Cache");
+    }
+    const xdg = process.env.XDG_CACHE_HOME;
+    return path.join(xdg ?? path.join(home, ".cache"), "zivis");
+}
+export async function deriveRepoId(cwd) {
+    const remote = await tryGit(cwd, "remote get-url origin");
+    if (remote) {
+        return "remote-" + sha256Short(remote);
+    }
+    return "path-" + sha256Short(cwd);
+}
+async function tryGit(cwd, args) {
+    try {
+        const { stdout } = await execAsync(`git ${args}`, { cwd });
+        const value = stdout.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sha256Short(value) {
+    return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+export async function locateLatestArtifact(cwd) {
+    const repoId = await deriveRepoId(cwd);
+    const runsDir = path.join(userCacheRoot(), "repos", repoId, "inspect", "runs");
+    if (!fssync.existsSync(runsDir))
+        return undefined;
+    const candidates = [];
+    for (const entry of await fs.readdir(runsDir)) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const full = path.join(runsDir, entry);
+        try {
+            const stat = await fs.stat(full);
+            candidates.push({ path: full, mtimeMs: stat.mtimeMs });
+        }
+        catch {
+        }
+    }
+    if (candidates.length === 0)
+        return undefined;
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return candidates[0];
+}
+export const DEFAULT_INSPECT_CACHE_TTL_MS = 15 * 60 * 1000;
+export function inspectCacheTtlMs() {
+    const raw = process.env.ZIVIS_INSPECT_CACHE_TTL_MS;
+    if (!raw)
+        return DEFAULT_INSPECT_CACHE_TTL_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_INSPECT_CACHE_TTL_MS;
+    return parsed;
+}
+export function isFresh(mtimeMs, now = Date.now()) {
+    return now - mtimeMs <= inspectCacheTtlMs();
+}

package/dist/lib/next-steps.d.ts

@@ -0,0 +1,27 @@
+export interface NextStep {
+    id: string;
+    label: string;
+    tool: string;
+    args_hint?: Record<string, unknown>;
+    why: string;
+    requires_tier?: "free" | "pro" | "enterprise";
+}
+export interface ZivisToolPayload<T> {
+    result: T;
+    next_steps?: NextStep[];
+    summary?: string;
+}
+export declare function withNextSteps<T>(result: T, nextSteps: NextStep[], summary?: string): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export declare function withNextStepsError(message: string, nextSteps: NextStep[], summary?: string): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};

package/dist/lib/next-steps.js

@@ -0,0 +1,21 @@
+export function withNextSteps(result, nextSteps, summary) {
+    const payload = {
+        result,
+        next_steps: nextSteps,
+        ...(summary ? { summary } : {}),
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+export function withNextStepsError(message, nextSteps, summary) {
+    const payload = {
+        result: { error: message },
+        next_steps: nextSteps,
+        ...(summary ? { summary } : {}),
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        isError: true,
+    };
+}

package/dist/matcher/ast-eval.d.ts

@@ -0,0 +1,8 @@
+export type AstLanguage = "typescript" | "javascript" | "python" | "go";
+export interface AstMatch {
+    file: string;
+    start_line: number;
+    end_line: number;
+    matched_text: string;
+}
+export declare function evaluateAstStrategy(expression: unknown, language: AstLanguage, files: string[], rootDir: string): Promise<AstMatch[]>;

package/dist/matcher/ast-eval.js

@@ -0,0 +1,95 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import * as napi from "@ast-grep/napi";
+let registered = false;
+async function ensureLanguagesRegistered() {
+    if (registered)
+        return;
+    const py = (await import("@ast-grep/lang-python")).default;
+    const go = (await import("@ast-grep/lang-go")).default;
+    napi.registerDynamicLanguage({ python: py, go: go });
+    registered = true;
+}
+export async function evaluateAstStrategy(expression, language, files, rootDir) {
+    await ensureLanguagesRegistered();
+    const rule = normalizeExpressionToRule(expression);
+    if (!rule)
+        return [];
+    const matches = [];
+    const langKey = languageKey(language);
+    for (const file of files) {
+        let raw;
+        try {
+            raw = await fs.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!raw)
+            continue;
+        let root;
+        try {
+            root = napi.parse(langKey, raw);
+        }
+        catch {
+            continue;
+        }
+        let foundNodes;
+        try {
+            foundNodes = root.root().findAll(rule);
+        }
+        catch {
+            continue;
+        }
+        for (const node of foundNodes) {
+            const range = node.range();
+            matches.push({
+                file: relPosix(rootDir, file),
+                start_line: (range.start.line ?? 0) + 1,
+                end_line: (range.end.line ?? 0) + 1,
+                matched_text: truncate(node.text(), 240),
+            });
+        }
+    }
+    return matches;
+}
+function normalizeExpressionToRule(expression) {
+    if (typeof expression === "string") {
+        try {
+            return ensureRuleWrapper(yaml.load(expression));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (expression && typeof expression === "object") {
+        return ensureRuleWrapper(expression);
+    }
+    return undefined;
+}
+function ensureRuleWrapper(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return parsed;
+    const obj = parsed;
+    if ("rule" in obj)
+        return obj;
+    return { rule: obj };
+}
+function languageKey(lang) {
+    switch (lang) {
+        case "typescript": return "ts";
+        case "javascript": return "js";
+        case "python": return "python";
+        case "go": return "go";
+    }
+}
+function relPosix(rootDir, abs) {
+    const rel = path.relative(rootDir, abs);
+    return rel.split(path.sep).join("/");
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + "…";
+}

package/dist/matcher/finding.d.ts

@@ -0,0 +1,55 @@
+export type Lane = "trusted" | "inferred";
+export interface MatchedEvidence {
+    file: string;
+    start_line: number;
+    end_line?: number;
+    matched_text?: string;
+    strategy_code: string;
+}
+export interface FiredStrategy {
+    code: string;
+    language?: string;
+    trusted: boolean;
+    confidence_weight: number;
+    match_count: number;
+}
+export interface InferenceCandidate {
+    prompt_ref: string;
+    expected_output_schema?: unknown;
+    minimum_context_required?: {
+        lines?: number;
+        symbols?: string[];
+    };
+    reason: string;
+}
+export interface Finding {
+    pattern_id: string;
+    pattern_version: string;
+    lane: Lane;
+    confidence: number;
+    fired_strategies: FiredStrategy[];
+    evidence: MatchedEvidence[];
+    inference_candidate?: InferenceCandidate;
+    safe_summary?: string;
+    threats?: unknown[];
+    repair_contract?: unknown;
+}
+export interface MatcherSummary {
+    trusted_count: number;
+    inferred_count: number;
+    total: number;
+}
+export interface MatcherResult {
+    pack: {
+        id: string;
+        version: string;
+    };
+    artifact_path: string;
+    cwd: string;
+    capsules_relevant: number;
+    capsules_evaluated: number;
+    ast_files_scanned: number;
+    duration_ms: number;
+    summary: MatcherSummary;
+    findings: Finding[];
+}

package/dist/matcher/finding.js

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

package/dist/matcher/index.d.ts

@@ -0,0 +1,8 @@
+import type { MatcherResult } from "./finding.js";
+export type { Finding, FiredStrategy, MatchedEvidence, MatcherResult, Lane } from "./finding.js";
+export interface RunMatcherOpts {
+    artifactPath: string;
+    cwd: string;
+    packId?: string;
+}
+export declare function runMatcher(opts: RunMatcherOpts): Promise<MatcherResult>;

package/dist/matcher/index.js

@@ -0,0 +1,202 @@
+import * as fs from "node:fs/promises";
+import * as fssync from "node:fs";
+import { loadActivePack, findRelevantCapsules, getControl, } from "../pattern-pack/index.js";
+import { walkLanguageFiles } from "./walker.js";
+import { evaluateAstStrategy } from "./ast-eval.js";
+const SUPPORTED_AST_LANGS = new Set([
+    "typescript",
+    "javascript",
+    "python",
+    "go",
+]);
+export async function runMatcher(opts) {
+    const startedAt = Date.now();
+    const handle = await loadActivePack(opts.packId);
+    const artifact = await readArtifact(opts.artifactPath);
+    const relevant = await findRelevantCapsules(handle, artifact);
+    const langsNeeded = collectAstLanguagesNeeded(relevant);
+    const walked = langsNeeded.length > 0
+        ? await walkLanguageFiles(opts.cwd, langsNeeded)
+        : { filesByLanguage: new Map(), filesScanned: 0, filesSkipped: 0 };
+    const controlPresence = await evaluateAllControls(handle, opts.cwd, walked.filesByLanguage);
+    const findings = [];
+    for (const cap of relevant) {
+        const finding = await evaluateCapsule(cap, opts.cwd, walked.filesByLanguage, controlPresence);
+        if (finding)
+            findings.push(finding);
+    }
+    const summary = {
+        trusted_count: findings.filter((f) => f.lane === "trusted").length,
+        inferred_count: findings.filter((f) => f.lane === "inferred").length,
+        total: findings.length,
+    };
+    return {
+        pack: { id: handle.manifest.pack_id, version: handle.manifest.version },
+        artifact_path: opts.artifactPath,
+        cwd: opts.cwd,
+        capsules_relevant: relevant.length,
+        capsules_evaluated: relevant.length,
+        ast_files_scanned: walked.filesScanned,
+        duration_ms: Date.now() - startedAt,
+        summary,
+        findings,
+    };
+}
+async function evaluateCapsule(cap, cwd, filesByLanguage, controlPresence) {
+    const strategies = (cap.strategies ?? []);
+    const fired = [];
+    const evidence = [];
+    let inferenceCandidate;
+    for (const strategy of strategies) {
+        const code = strategy.code;
+        const trusted = strategy.trusted !== false && code !== "INFER" && code !== "SEM" && code !== "REGEX";
+        if (code === "AST") {
+            const lang = (strategy.language ?? "").toLowerCase();
+            if (!SUPPORTED_AST_LANGS.has(lang)) {
+                fired.push({ code, language: lang, trusted, confidence_weight: strategy.confidence_weight, match_count: 0 });
+                continue;
+            }
+            const files = filesByLanguage.get(lang) ?? [];
+            if (files.length === 0) {
+                fired.push({ code, language: lang, trusted, confidence_weight: strategy.confidence_weight, match_count: 0 });
+                continue;
+            }
+            const matches = await evaluateAstStrategy(strategy.expression, lang, files, cwd);
+            fired.push({
+                code,
+                language: lang,
+                trusted,
+                confidence_weight: strategy.confidence_weight,
+                match_count: matches.length,
+            });
+            for (const m of matches) {
+                evidence.push({
+                    file: m.file,
+                    start_line: m.start_line,
+                    end_line: m.end_line,
+                    matched_text: m.matched_text,
+                    strategy_code: code,
+                });
+            }
+        }
+        else if (code === "META") {
+            const result = evaluateMetaStrategy(strategy.expression, controlPresence);
+            fired.push({
+                code,
+                trusted,
+                confidence_weight: strategy.confidence_weight,
+                match_count: result.fired ? 1 : 0,
+            });
+            if (result.fired) {
+                evidence.push({
+                    file: "(synthetic)",
+                    start_line: 0,
+                    matched_text: `META: none_of_controls satisfied; absent: [${result.absent.join(", ")}]`,
+                    strategy_code: code,
+                });
+            }
+        }
+        else if (code === "INFER") {
+            if (cap.model_task_prompt_ref) {
+                inferenceCandidate = {
+                    prompt_ref: cap.model_task_prompt_ref,
+                    expected_output_schema: cap.expected_output_schema,
+                    minimum_context_required: cap.minimum_context_required,
+                    reason: "Capsule has an INFER strategy. Use zivis_threat_get_inference_prompt to retrieve the prompt bundle, gather the indicated code spans, and run the inference in your model.",
+                };
+            }
+            fired.push({ code, trusted: false, confidence_weight: strategy.confidence_weight, match_count: 1 });
+        }
+        else {
+            fired.push({ code, trusted, confidence_weight: strategy.confidence_weight, match_count: 0 });
+        }
+    }
+    const anyFired = fired.some((f) => f.match_count > 0);
+    if (!anyFired)
+        return undefined;
+    const trustedFired = fired.filter((f) => f.trusted && f.match_count > 0).length;
+    const requiredCount = cap.required_evidence_count ?? 1;
+    const lane = trustedFired >= requiredCount ? "trusted" : "inferred";
+    const confidence = Math.min(1, fired.reduce((acc, f) => (f.match_count > 0 ? acc + f.confidence_weight : acc), 0));
+    return {
+        pattern_id: cap.id,
+        pattern_version: cap.version,
+        lane,
+        confidence,
+        fired_strategies: fired,
+        evidence,
+        inference_candidate: inferenceCandidate,
+        safe_summary: cap.safe_summary,
+        threats: cap.threats,
+        repair_contract: cap.repair_contract,
+    };
+}
+async function readArtifact(p) {
+    if (!fssync.existsSync(p)) {
+        throw new Error(`Artifact not found: ${p}`);
+    }
+    const raw = await fs.readFile(p, "utf8");
+    return JSON.parse(raw);
+}
+function collectAstLanguagesNeeded(capsules) {
+    const set = new Set();
+    for (const cap of capsules) {
+        for (const strategy of cap.strategies) {
+            if (strategy.code !== "AST")
+                continue;
+            const lang = (strategy.language ?? "").toLowerCase();
+            if (SUPPORTED_AST_LANGS.has(lang))
+                set.add(lang);
+        }
+    }
+    set.add("typescript");
+    set.add("python");
+    return [...set];
+}
+function evaluateMetaStrategy(expression, presence) {
+    const expr = expression;
+    if (!expr || typeof expr !== "object")
+        return { fired: false, absent: [] };
+    if (expr.none_of_controls && expr.none_of_controls.length > 0) {
+        const checkable = expr.none_of_controls.filter((id) => presence.get(id)?.checkable);
+        if (checkable.length === 0)
+            return { fired: false, absent: [] };
+        const absent = checkable.filter((id) => !presence.get(id).present);
+        if (absent.length === checkable.length) {
+            return { fired: true, absent };
+        }
+        return { fired: false, absent };
+    }
+    return { fired: false, absent: [] };
+}
+async function evaluateAllControls(handle, cwd, filesByLanguage) {
+    const out = new Map();
+    const controlEntries = handle.manifest.controls ?? [];
+    for (const entry of controlEntries) {
+        let control;
+        try {
+            control = await getControl(handle, entry.id);
+        }
+        catch {
+            continue;
+        }
+        let present = false;
+        let checkable = false;
+        for (const det of control.detection ?? []) {
+            const lang = det.language;
+            if (!SUPPORTED_AST_LANGS.has(lang))
+                continue;
+            const files = filesByLanguage.get(lang) ?? [];
+            if (files.length === 0)
+                continue;
+            checkable = true;
+            const matches = await evaluateAstStrategy(det.rule, lang, files, cwd);
+            if (matches.length > 0) {
+                present = true;
+                break;
+            }
+        }
+        out.set(control.id, { present, checkable });
+    }
+    return out;
+}

package/dist/matcher/inference-candidates.d.ts

@@ -0,0 +1,26 @@
+import { type Capsule } from "../pattern-pack/index.js";
+import type { Finding } from "./finding.js";
+export interface BundledInferenceCandidate {
+    candidate_id: string;
+    capsule_id: string;
+    capsule_version: string;
+    pattern_title?: string;
+    prompt: string;
+    expected_output_schema: unknown;
+    evidence_focus: Array<{
+        file: string;
+        start_line: number;
+        end_line?: number;
+        note?: string;
+    }>;
+    minimum_context_required?: {
+        lines?: number;
+        symbols?: string[];
+    };
+    instructions_for_host: string;
+}
+export interface InferenceBundle {
+    inference_candidates: BundledInferenceCandidate[];
+    host_required_action: string;
+}
+export declare function buildInferenceBundle(findings: Finding[], capsuleByPatternId?: Map<string, Capsule>): Promise<InferenceBundle>;

package/dist/matcher/inference-candidates.js

@@ -0,0 +1,81 @@
+import { loadActivePack, getInferencePrompt, } from "../pattern-pack/index.js";
+export async function buildInferenceBundle(findings, capsuleByPatternId) {
+    const candidates = [];
+    let handle;
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        if (!f.inference_candidate)
+            continue;
+        if (!handle) {
+            try {
+                handle = await loadActivePack();
+            }
+            catch {
+                candidates.push(toFallbackCandidate(f, i));
+                continue;
+            }
+        }
+        let promptText;
+        try {
+            promptText = await getInferencePrompt(handle, f.inference_candidate.prompt_ref);
+        }
+        catch {
+            candidates.push(toFallbackCandidate(f, i));
+            continue;
+        }
+        const cap = capsuleByPatternId?.get(f.pattern_id);
+        candidates.push({
+            candidate_id: `ic-${i + 1}`,
+            capsule_id: f.pattern_id,
+            capsule_version: f.pattern_version,
+            pattern_title: cap?.title,
+            prompt: promptText,
+            expected_output_schema: f.inference_candidate.expected_output_schema ?? null,
+            evidence_focus: f.evidence
+                .filter((e) => e.file !== "(synthetic)")
+                .map((e) => ({
+                file: e.file,
+                start_line: e.start_line,
+                end_line: e.end_line,
+                note: e.matched_text ? e.matched_text.slice(0, 200) : undefined,
+            })),
+            minimum_context_required: f.inference_candidate.minimum_context_required,
+            instructions_for_host: "Read the source code at each evidence_focus[*].file:start_line — pull at least minimum_context_required.lines around each span. " +
+                "Attach those snippets to the prompt above. Run the prompt against your model. " +
+                "Return JSON matching expected_output_schema. The output enters the inferred lane.",
+        });
+    }
+    const action = buildHostRequiredAction(candidates);
+    return { inference_candidates: candidates, host_required_action: action };
+}
+function toFallbackCandidate(f, i) {
+    return {
+        candidate_id: `ic-${i + 1}`,
+        capsule_id: f.pattern_id,
+        capsule_version: f.pattern_version,
+        prompt: "",
+        expected_output_schema: f.inference_candidate?.expected_output_schema ?? null,
+        evidence_focus: f.evidence
+            .filter((e) => e.file !== "(synthetic)")
+            .map((e) => ({
+            file: e.file,
+            start_line: e.start_line,
+            end_line: e.end_line,
+        })),
+        minimum_context_required: f.inference_candidate?.minimum_context_required,
+        instructions_for_host: "Inline prompt unavailable. Call zivis_threat_get_inference_prompt with capsule_id=" +
+            f.pattern_id +
+            " to retrieve it.",
+    };
+}
+function buildHostRequiredAction(candidates) {
+    if (candidates.length === 0) {
+        return "No inference candidates emitted by this run. Findings are deterministic-only.";
+    }
+    return (`MANDATORY HOST ACTION: For each of the ${candidates.length} inference_candidate${candidates.length === 1 ? "" : "s"} below, ` +
+        `you MUST: (1) read the source code at evidence_focus[*].file:start_line (open each file, grab at least minimum_context_required.lines of surrounding context), ` +
+        `(2) run the candidate's prompt against your model with that source attached, ` +
+        `(3) produce JSON output matching expected_output_schema. ` +
+        `Do this BEFORE summarizing findings to the user — the inferred-lane verdict from your inference is what the user actually wants. ` +
+        `Each candidate is a self-contained inference task; you do not need to call any other ZIVIS tool to execute it.`);
+}

package/dist/matcher/walker.d.ts

@@ -0,0 +1,7 @@
+export type WalkLanguage = "typescript" | "javascript" | "python" | "go";
+export interface WalkResult {
+    filesByLanguage: Map<WalkLanguage, string[]>;
+    filesScanned: number;
+    filesSkipped: number;
+}
+export declare function walkLanguageFiles(rootDir: string, languages: WalkLanguage[]): Promise<WalkResult>;