@zivis/mcp 0.1.0-alpha.21 → 0.1.0-alpha.22

package/dist/pattern-pack/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Local pattern pack reader.
+ *
+ * The pack ships bundled inside the @zivis/mcp npm package at
+ * `dist/pattern-packs/<pack-id>-<version>/`. On first use we copy it to
+ * `~/Library/Caches/zivis/pattern-packs/<pack-id>-<version>/` so future
+ * runs read from the user cache directly.
+ *
+ * Both the CLI's matcher (Phase 3) and the MCP tools that surface
+ * relevant capsules mid-IDE-conversation read through this module.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 2A)
+ * Schemas:
+ *   - schemas/pattern-pack-manifest.schema.json (manifest.json)
+ *   - schemas/pattern-detection-card.schema.json (capsule yaml)
+ */
+export interface PackManifest {
+    schema_version: "1.0.0";
+    pack_id: string;
+    pack_name: string;
+    version: string;
+    built_at: string;
+    tier: "public_teaser" | "public" | "customer_safe";
+    description?: string;
+    capsules: ManifestCapsuleEntry[];
+    prompts: ManifestPromptEntry[];
+}
+export interface ManifestCapsuleEntry {
+    id: string;
+    version: string;
+    path: string;
+    sha256: string;
+    category?: string;
+    lifecycle?: string;
+    applicable_languages?: string[];
+}
+export interface ManifestPromptEntry {
+    path: string;
+    sha256: string;
+    capsule_id?: string;
+}
+export interface RelevanceTerm {
+    dependency?: string;
+    direct_only?: boolean;
+    language?: string;
+    framework?: string;
+    evidence?: string;
+}
+export interface RelevanceFilter {
+    any_of?: RelevanceTerm[];
+    all_of?: RelevanceTerm[];
+    none_of?: RelevanceTerm[];
+}
+export interface Capsule {
+    id: string;
+    slug: string;
+    version: string;
+    category: string;
+    title?: string;
+    headline?: string;
+    description?: string;
+    detection_tier: "public" | "proprietary";
+    scoring_tier: "public" | "proprietary";
+    applicable_languages: string[];
+    relevance_filter?: RelevanceFilter;
+    strategies: unknown[];
+    required_evidence_count: number;
+    threats?: unknown[];
+    lifecycle: "draft" | "active" | "deprecated";
+    sensitivity_level?: "public_teaser" | "customer_safe" | "zivis_confidential";
+    safe_summary?: string;
+    detect_when?: string;
+    risk_hints?: string[];
+    architectural_signals?: string[];
+    model_task_prompt_ref?: string;
+    expected_output_schema?: unknown;
+    minimum_context_required?: {
+        lines?: number;
+        symbols?: string[];
+    };
+    related_patterns?: string[];
+    repair_contract?: {
+        allowed?: string[];
+        forbidden?: string[];
+    };
+    validation_contract?: {
+        requires_tests_pass?: boolean;
+        requires_static_rules?: string[];
+    };
+}
+export interface PackHandle {
+    manifest: PackManifest;
+    rootDir: string;
+}
+/**
+ * Minimal structural interface of a RepoGraphArtifactV1 that the reader
+ * actually needs. Lets this module avoid a hard dep on the full graph-types
+ * package while preserving compatibility with `RepoGraphArtifactV1`.
+ */
+export interface GraphArtifactView {
+    scope: {
+        languages?: string[];
+    };
+    nodes: Array<{
+        type: string;
+        evidence: Array<{
+            kind: string;
+        }>;
+        attributes?: {
+            package?: string;
+        };
+    }>;
+}
+/**
+ * Locate the active pack and ensure it's available in the user cache.
+ *
+ * Resolution order:
+ *  1. ZIVIS_PACK_DIR env var (override for tests / enterprise air-gap imports)
+ *  2. User cache, if present
+ *  3. Bundled pack inside @zivis/mcp (copied to user cache on first use)
+ */
+export declare function loadActivePack(packId?: string): Promise<PackHandle>;
+export declare function getCapsule(handle: PackHandle, capsuleId: string): Promise<Capsule>;
+export declare function getInferencePrompt(handle: PackHandle, ref: string): Promise<string>;
+export declare function listCapsuleIds(handle: PackHandle): Promise<string[]>;
+export declare function findRelevantCapsules(handle: PackHandle, artifact: GraphArtifactView): Promise<Capsule[]>;
+interface EvalContext {
+    packageNames: Set<string>;
+    languages: Set<string>;
+    evidenceKinds: Set<string>;
+}
+export declare function matchesRelevance(cap: Capsule, ctx: EvalContext): boolean;
+export {};

package/dist/pattern-pack/index.js

@@ -0,0 +1,212 @@
+/**
+ * Local pattern pack reader.
+ *
+ * The pack ships bundled inside the @zivis/mcp npm package at
+ * `dist/pattern-packs/<pack-id>-<version>/`. On first use we copy it to
+ * `~/Library/Caches/zivis/pattern-packs/<pack-id>-<version>/` so future
+ * runs read from the user cache directly.
+ *
+ * Both the CLI's matcher (Phase 3) and the MCP tools that surface
+ * relevant capsules mid-IDE-conversation read through this module.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 2A)
+ * Schemas:
+ *   - schemas/pattern-pack-manifest.schema.json (manifest.json)
+ *   - schemas/pattern-detection-card.schema.json (capsule yaml)
+ */
+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 { fileURLToPath } from "node:url";
+import * as crypto from "node:crypto";
+import * as yaml from "js-yaml";
+// ── Cache layout ──
+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");
+}
+function userPackRoot() {
+    return path.join(userCacheRoot(), "pattern-packs");
+}
+/**
+ * Locate the pack bundled inside the @zivis/mcp npm install. We resolve
+ * from this module's own URL so it works whether the MCP is installed
+ * globally, locally, or run via pnpm workspace symlink.
+ */
+function bundledPackRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // dist layout: dist/pattern-pack/index.js → dist/pattern-packs
+    return path.resolve(here, "../pattern-packs");
+}
+const DEFAULT_PACK_ID = "zivis-public";
+// ── Loader ──
+/**
+ * Locate the active pack and ensure it's available in the user cache.
+ *
+ * Resolution order:
+ *  1. ZIVIS_PACK_DIR env var (override for tests / enterprise air-gap imports)
+ *  2. User cache, if present
+ *  3. Bundled pack inside @zivis/mcp (copied to user cache on first use)
+ */
+export async function loadActivePack(packId = DEFAULT_PACK_ID) {
+    if (process.env.ZIVIS_PACK_DIR) {
+        return readManifest(process.env.ZIVIS_PACK_DIR);
+    }
+    const cached = await findCachedPack(packId);
+    if (cached) {
+        return readManifest(cached);
+    }
+    const bundledDir = await findBundledPack(packId);
+    if (!bundledDir) {
+        throw new Error(`No pattern pack found. Looked in user cache (${userPackRoot()}) and bundled location (${bundledPackRoot()}). ` +
+            `Set ZIVIS_PACK_DIR to override.`);
+    }
+    const handle = await readManifest(bundledDir);
+    const cacheDir = path.join(userPackRoot(), `${handle.manifest.pack_id}-${handle.manifest.version}`);
+    await copyDir(bundledDir, cacheDir);
+    return { manifest: handle.manifest, rootDir: cacheDir };
+}
+async function findCachedPack(packId) {
+    const root = userPackRoot();
+    if (!fssync.existsSync(root))
+        return undefined;
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const candidates = entries
+        .filter((e) => e.isDirectory() && e.name.startsWith(`${packId}-`))
+        .map((e) => e.name)
+        .sort()
+        .reverse();
+    for (const name of candidates) {
+        const dir = path.join(root, name);
+        if (fssync.existsSync(path.join(dir, "manifest.json"))) {
+            return dir;
+        }
+    }
+    return undefined;
+}
+async function findBundledPack(packId) {
+    const root = bundledPackRoot();
+    if (!fssync.existsSync(root))
+        return undefined;
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const matches = entries
+        .filter((e) => e.isDirectory() && e.name.startsWith(`${packId}-`))
+        .map((e) => path.join(root, e.name))
+        .sort()
+        .reverse();
+    return matches[0];
+}
+async function readManifest(rootDir) {
+    const manifestPath = path.join(rootDir, "manifest.json");
+    const raw = await fs.readFile(manifestPath, "utf8");
+    const manifest = JSON.parse(raw);
+    return { manifest, rootDir };
+}
+async function copyDir(src, dst) {
+    await fs.mkdir(dst, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    await Promise.all(entries.map(async (entry) => {
+        const s = path.join(src, entry.name);
+        const d = path.join(dst, entry.name);
+        if (entry.isDirectory())
+            await copyDir(s, d);
+        else if (entry.isFile())
+            await fs.copyFile(s, d);
+    }));
+}
+// ── Reader API ──
+export async function getCapsule(handle, capsuleId) {
+    const entry = handle.manifest.capsules.find((c) => c.id === capsuleId);
+    if (!entry)
+        throw new Error(`Capsule not found in pack: ${capsuleId}`);
+    const fullPath = path.join(handle.rootDir, entry.path);
+    const raw = await fs.readFile(fullPath, "utf8");
+    await verifySha256(raw, entry.sha256, entry.path);
+    return yaml.load(raw);
+}
+export async function getInferencePrompt(handle, ref) {
+    const entry = handle.manifest.prompts.find((p) => p.path === ref);
+    if (!entry)
+        throw new Error(`Prompt not found in pack: ${ref}`);
+    const fullPath = path.join(handle.rootDir, ref);
+    const raw = await fs.readFile(fullPath, "utf8");
+    await verifySha256(raw, entry.sha256, ref);
+    return raw;
+}
+async function verifySha256(content, expected, label) {
+    const actual = crypto.createHash("sha256").update(content).digest("hex");
+    if (actual !== expected) {
+        throw new Error(`Pack integrity check failed for ${label}: expected ${expected.slice(0, 12)}…, got ${actual.slice(0, 12)}…`);
+    }
+}
+export async function listCapsuleIds(handle) {
+    return handle.manifest.capsules.map((c) => c.id);
+}
+// ── Relevance evaluation ──
+export async function findRelevantCapsules(handle, artifact) {
+    const out = [];
+    const ctx = buildEvalContext(artifact);
+    for (const entry of handle.manifest.capsules) {
+        const cap = await getCapsule(handle, entry.id);
+        if (matchesRelevance(cap, ctx))
+            out.push(cap);
+    }
+    return out;
+}
+function buildEvalContext(artifact) {
+    const packageNames = new Set();
+    for (const node of artifact.nodes) {
+        if (node.type === "external_dependency" && node.attributes?.package) {
+            packageNames.add(node.attributes.package);
+        }
+    }
+    const languages = new Set(artifact.scope.languages ?? []);
+    const evidenceKinds = new Set();
+    for (const node of artifact.nodes) {
+        for (const ev of node.evidence)
+            evidenceKinds.add(ev.kind);
+    }
+    return { packageNames, languages, evidenceKinds };
+}
+export function matchesRelevance(cap, ctx) {
+    if (cap.applicable_languages.length > 0) {
+        const hit = cap.applicable_languages.some((l) => l === "cross" || ctx.languages.has(l));
+        if (!hit)
+            return false;
+    }
+    const f = cap.relevance_filter;
+    if (!f)
+        return true;
+    if (f.any_of && f.any_of.length > 0) {
+        if (!f.any_of.some((t) => evalTerm(t, ctx)))
+            return false;
+    }
+    if (f.all_of && f.all_of.length > 0) {
+        if (!f.all_of.every((t) => evalTerm(t, ctx)))
+            return false;
+    }
+    if (f.none_of && f.none_of.length > 0) {
+        if (f.none_of.some((t) => evalTerm(t, ctx)))
+            return false;
+    }
+    return true;
+}
+function evalTerm(term, ctx) {
+    if (term.dependency !== undefined)
+        return ctx.packageNames.has(term.dependency);
+    if (term.language !== undefined)
+        return ctx.languages.has(term.language);
+    if (term.evidence !== undefined)
+        return ctx.evidenceKinds.has(term.evidence);
+    return false;
+}
+//# sourceMappingURL=index.js.map

package/dist/pattern-pack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pattern-pack/index.ts"],"names":[],"mappings":"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"}

package/dist/pattern-packs/zivis-public-0.1.0/capsules/agents/privilege-separation.yaml

@@ -0,0 +1,228 @@
+# Detection Card: Privilege Separation (absent)
+# Spec: docs/specs/PATTERN-MATCHING-LIBRARY-V1.md
+# Schema: schemas/pattern-detection-card.schema.json
+
+id: agents.privilege-separation
+slug: privilege-separation
+version: 0.1.0
+category: agents
+title: Privilege Separation
+headline: Per-Subtask Capability Scoping
+description: >
+  Detects agentic codebases where multiple agents share a single tool/capability
+  set without per-agent scoping. Absence of privilege separation means one
+  compromised agent inherits the full capability surface of the system.
+detection_tier: public
+scoring_tier: proprietary
+
+applicable_languages:
+  - typescript
+  - javascript
+  - python
+
+# Don't run this pattern unless an agent framework is actually present.
+# Mirrors nuclei-style relevance gating to keep the noise floor low.
+relevance_filter:
+  any_of:
+    - dependency: "langgraph"
+      direct_only: true
+    - dependency: "langchain"
+      direct_only: true
+    - dependency: "@langchain/langgraph"
+      direct_only: true
+    - dependency: "crewai"
+      direct_only: true
+    - dependency: "llama-index"
+      direct_only: true
+    - dependency: "openai-agents"
+      direct_only: true
+    - dependency: "autogen-agentchat"
+      direct_only: true
+
+strategies:
+  # 1. AST: Find tool list assignments (Python — LangChain/LangGraph idiom).
+  - code: AST
+    language: python
+    expression: |
+      rule:
+        kind: assignment
+        pattern: $TOOLS = [$$$]
+        has:
+          stopBy: end
+          any:
+            - pattern: create_react_agent
+            - pattern: bind_tools
+            - pattern: AgentExecutor
+    evidence_fields: [file_path, line_span, symbol]
+    confidence_weight: 0.25
+
+  # 2. AST: TypeScript/JavaScript equivalent.
+  - code: AST
+    language: typescript
+    expression: |
+      rule:
+        any:
+          - pattern: const $TOOLS = [$$$]
+          - pattern: bindTools($$$)
+          - pattern: createReactAgent($$$)
+    evidence_fields: [file_path, line_span, symbol]
+    confidence_weight: 0.25
+
+  # 3. GRAPH: Two or more agent declarations share the same tool set.
+  # Predicate evaluated against extractor output (components/edges).
+  - code: GRAPH
+    expression: |
+      count(distinct agent_declaration) >= 2
+      AND any_pair(agents, lambda a, b: a.tool_set == b.tool_set)
+    evidence_fields: [graph_path, file_spans, node_ids]
+    confidence_weight: 0.35
+
+  # 4. META: Absence of per-agent capability scope OR explicit authz layer.
+  - code: META
+    expression: |
+      NOT exists_any_of(
+        per_agent_tool_filter,
+        capability_token_check,
+        authorization_layer_around_tool_dispatch,
+        langgraph_state_machine_with_per_node_tools
+      )
+    evidence_fields: [missing_controls]
+    confidence_weight: 0.30
+
+  # 5. INFER: Last-resort semantic check; never alone proves a finding.
+  - code: INFER
+    expression: "prompt_id:agents.privilege-separation.identify"
+    evidence_fields: [llm_rationale]
+    confidence_weight: 0.15
+    trusted: false
+
+required_evidence_count: 3
+
+# Presence of any of these controls downgrades or eliminates the finding.
+control_negations:
+  - "presence_of(per_agent_tool_filter)"
+  - "presence_of(capability_token_check)"
+  - "presence_of(langgraph_state_machine_with_per_node_tools)"
+
+threats:
+  - title: Compromised planner inherits executor capabilities
+    stride: [tampering, elevation_of_privilege]
+    description: >
+      A prompt-injection compromise of any agent escalates to the full set of
+      tools available to all agents in the system, including high-impact tools
+      like code execution, email, or file write.
+    remediation: >
+      Bind only the minimum tools required to each agent. In LangGraph, define
+      tools per node rather than globally. Add a capability token or
+      authorization layer that validates tool dispatch against agent identity.
+  - title: Lateral compromise via shared tool registry
+    stride: [elevation_of_privilege, information_disclosure]
+    description: >
+      Any tool callable from one agent is callable from every agent. There is
+      no blast-radius reduction even if one agent is otherwise constrained.
+
+fixtures:
+  positive:
+    - "fixtures/positive/privilege-separation/langgraph_shared_tools_python"
+    - "fixtures/positive/privilege-separation/langchain_shared_tools_typescript"
+  negative:
+    - "fixtures/negative/privilege-separation/langgraph_per_node_tools"
+    - "fixtures/negative/privilege-separation/non_agentic_repo"
+
+lifecycle: draft
+owner: platform-threat-modeling
+tags:
+  - agentic-ai
+  - least-privilege
+  - blast-radius
+
+# Capsule fields — added in Phase 2A so the pack builder can ship this card
+# as a runnable customer-safe capsule (deterministic strategies + inference prompt).
+sensitivity_level: customer_safe
+allowed_execution_modes:
+  - local_only
+  - local_model
+  - hybrid_cloud_eval
+
+safe_summary: >
+  Multi-agent systems often share a single tool registry across agents. When that
+  happens, a prompt-injection compromise of any one agent inherits the full
+  capability surface of the system — including high-impact tools like code
+  execution, email, or filesystem write. Privilege separation means each agent
+  is bound only to the minimum tools required for its role.
+
+detect_when: >
+  Two or more agent declarations are wired to the same tool list, or a single
+  shared tool array is referenced by every agent factory call, with no per-agent
+  capability scoping or authorization layer between agent and tool dispatch.
+
+risk_hints:
+  - Any tool callable from one agent becomes callable from every agent
+  - Compromise of the weakest-prompted agent escalates to the most-privileged tool
+  - LangGraph's per-node tool binding is the idiomatic fix; AgentExecutor with a flat tool list is the anti-pattern
+
+architectural_signals:
+  - Shared TOOLS array reused across multiple agent constructors
+  - No capability_token / authorization_layer between planner and tool dispatch
+  - LangGraph used without per-node tool binding
+
+model_task_prompt_ref: prompts/agents/privilege-separation/identify.md
+
+expected_output_schema:
+  type: object
+  required: [verdict, rationale, evidence_spans]
+  properties:
+    verdict:
+      type: string
+      enum: [present, absent, unclear]
+      description: present = privilege separation IS implemented; absent = the anti-pattern fires; unclear = needs human review
+    confidence:
+      type: number
+      minimum: 0
+      maximum: 1
+    rationale:
+      type: string
+      description: One paragraph, cites specific code constructs.
+    evidence_spans:
+      type: array
+      items:
+        type: object
+        required: [file]
+        properties:
+          file: { type: string }
+          start_line: { type: integer }
+          end_line: { type: integer }
+          note: { type: string }
+
+minimum_context_required:
+  lines: 120
+  symbols:
+    - bind_tools
+    - bindTools
+    - create_react_agent
+    - createReactAgent
+    - AgentExecutor
+
+related_patterns:
+  - agents.goal-decomposition-attack-surface
+  - agents.tool-call-without-authorization
+
+repair_contract:
+  allowed:
+    - Bind a per-agent tool subset at construction time
+    - Introduce a capability-token or authorization layer between agent and tool dispatch
+    - Migrate to LangGraph state machines with per-node tools
+  forbidden:
+    - Removing tools entirely without functional replacement
+    - Centralizing tools further (the opposite direction)
+    - Disabling agent execution to "fix" the finding
+
+validation_contract:
+  requires_tests_pass: false
+  requires_static_rules:
+    - no_shared_tool_registry_after_patch
+
+unsafe_to_expose_fields:
+  - internal_rubric
+  - golden_transcripts
+  - exploit_templates