@cantinasecurity/apex-cli 0.1.28 → 0.1.33

package/dist/threat-model.js

@@ -0,0 +1,435 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { z } from "zod";
+import { ApiError } from "./api-client.js";
+import { getMe } from "./auth.js";
+import { canPromptInteractively, getFlagList, getFlagString, } from "./args.js";
+import { loadConfig } from "./config.js";
+import { chooseCompany } from "./session.js";
+import { fetchCompanyWorkspaces, findWorkspaceByRef } from "./workspaces.js";
+import { loadWorkspaceBinding } from "./workspace-binding.js";
+import { confirm, promptText } from "./prompt.js";
+const uuid = z.string().uuid();
+export function hasAuditSetupBeta(me, company) {
+    return company
+        ? company.betaFeatures?.auditSetup === true
+        : me?.companies.some((candidate) => candidate.betaFeatures?.auditSetup === true) === true;
+}
+function requireAuditSetupBeta(me, company) {
+    if (!hasAuditSetupBeta(me, company)) {
+        throw new ThreatModelUsageError("Unknown command or option");
+    }
+}
+const field = z.object({
+    id: z.string(),
+    label: z.string(),
+    description: z.string().optional(),
+    kind: z.enum(["single_select", "multi_select", "short_text", "long_text"]),
+    required: z.boolean(),
+    options: z.array(z.object({
+        value: z.string(),
+        label: z.string(),
+        description: z.string().optional(),
+    })),
+    defaultValue: z.union([z.string(), z.array(z.string())]).optional(),
+});
+const stateSchema = z
+    .object({
+    contractVersion: z.literal(1),
+    draftId: uuid,
+    company: z.object({ id: z.string() }).passthrough(),
+    workspace: z
+        .object({ id: z.string(), ref: z.string().nullable(), name: z.string() })
+        .passthrough(),
+    state: z.enum([
+        "preparing",
+        "working",
+        "needs_input",
+        "needs_review",
+        "launch_pending",
+        "launch_retryable",
+        "launched",
+        "failed",
+        "cancelled",
+        "expired",
+    ]),
+    nextAction: z.string(),
+    question: z
+        .object({
+        questionEventId: z.number().int().positive(),
+        title: z.string(),
+        context: z.string().optional(),
+        contextSections: z
+            .array(z.object({
+            title: z.string(),
+            description: z.string().optional(),
+            bullets: z.array(z.string()),
+        }))
+            .optional(),
+        fields: z.array(field),
+        allowAttachments: z.boolean(),
+    })
+        .passthrough()
+        .nullable()
+        .optional(),
+    model: z
+        .object({
+        id: uuid,
+        sha256: z.string().regex(/^[0-9a-f]{64}$/),
+        content: z.string().nullable(),
+    })
+        .passthrough()
+        .nullable()
+        .optional(),
+    pollAfterMs: z.number().nullable().optional(),
+    scanId: uuid.optional(),
+    lastActivityAt: z.string().optional(),
+})
+    .passthrough();
+export class ThreatModelUsageError extends Error {
+}
+export function threatModelExitCode(error) {
+    if (error instanceof ThreatModelUsageError || error instanceof z.ZodError)
+        return 2;
+    if (error instanceof ApiError)
+        return [401, 403].includes(error.status)
+            ? 3
+            : error.status === 409
+                ? 4
+                : error.status === 400 || error.status === 413
+                    ? 2
+                    : 1;
+    return 1;
+}
+export function terminalText(text) {
+    return stripVTControlCharacters(text).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+}
+function required(flags, key) {
+    const value = getFlagString(flags, key);
+    if (!value)
+        throw new ThreatModelUsageError(`--${key} is required`);
+    return value;
+}
+async function requireAccount(client) {
+    const me = await getMe(client);
+    if (!me)
+        throw new ApiError("Sign in with apex login first", 401, {});
+    return me;
+}
+function output(value, flags) {
+    if (flags.json)
+        process.stdout.write(`${JSON.stringify(value)}\n`);
+    else {
+        process.stdout.write(terminalText(`Workspace: ${value.workspace.ref ?? value.workspace.name}\nDraft: ${value.draftId}\nState: ${value.state}\n`));
+        if (value.question)
+            process.stdout.write(terminalText(`${value.question.title}\n${value.question.context ?? ""}\n${JSON.stringify(value.question, null, 2)}\n`));
+        if (value.lastActivityAt)
+            process.stdout.write(`Last activity: ${terminalText(value.lastActivityAt)}\n`);
+        const next = value.state === "launched"
+            ? `apex status --scan ${value.scanId} --json`
+            : value.state === "needs_review"
+                ? `apex threat-model show --draft ${value.draftId}`
+                : value.state === "needs_input"
+                    ? `apex threat-model answer --draft ${value.draftId}`
+                    : value.state === "launch_retryable"
+                        ? `apex threat-model approve --draft ${value.draftId} --sha256 <reviewed-hash> --start-scan`
+                        : `apex threat-model next --draft ${value.draftId} --wait`;
+        process.stdout.write(`Next: ${next}\n`);
+    }
+}
+async function readInput(flags, supplied) {
+    if (supplied !== undefined)
+        return supplied;
+    const file = required(flags, "file");
+    const limit = 600_000;
+    if (file !== "-") {
+        const content = await readFile(file, "utf8");
+        if (Buffer.byteLength(content) > limit)
+            throw new ThreatModelUsageError("Input exceeds 600 KB");
+        return content;
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit)
+            throw new ThreatModelUsageError("Input exceeds 600 KB");
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function mutate(client, flags, endpoint, payload, files = [], idField = "requestId") {
+    const me = await requireAccount(client);
+    const mimeTypes = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".pdf": "application/pdf",
+        ".txt": "text/plain",
+        ".md": "text/markdown",
+        ".json": "application/json",
+    };
+    const uploads = await Promise.all(files.map(async (file) => {
+        const info = await stat(file);
+        if (!info.isFile() || info.size > 10 * 1024 * 1024)
+            throw new ThreatModelUsageError("Attachments must be regular files of at most 10 MB");
+        return {
+            name: path.basename(file),
+            bytes: await readFile(file),
+            type: mimeTypes[path.extname(file).toLowerCase()] ??
+                "application/octet-stream",
+        };
+    }));
+    if (uploads.length > 8 ||
+        uploads.some((f) => f.bytes.length > 10 * 1024 * 1024) ||
+        uploads.reduce((n, f) => n + f.bytes.length, 0) > 25 * 1024 * 1024)
+        throw new ThreatModelUsageError("Audit Setup accepts up to 8 attachments, 10 MB each and 25 MB total");
+    const config = await loadConfig();
+    const identity = createHash("sha256")
+        .update(JSON.stringify({
+        origin: config.baseUrl,
+        user: me.user.id,
+        endpoint,
+        payload,
+        uploads: uploads.map((f) => ({
+            name: f.name,
+            sha256: createHash("sha256").update(f.bytes).digest("hex"),
+        })),
+    }))
+        .digest("hex");
+    const directory = path.join(os.homedir(), ".config", "apex", "pending-threat-model-requests");
+    const receiptFile = path.join(directory, `${identity}.json`);
+    let requestId = getFlagString(flags, "request-id") ??
+        (typeof payload[idField] === "string"
+            ? payload[idField]
+            : null);
+    const persist = !requestId;
+    if (persist) {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        requestId = randomUUID();
+        try {
+            await writeFile(receiptFile, JSON.stringify({ requestId }), {
+                flag: "wx",
+                mode: 0o600,
+            });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            requestId = JSON.parse(await readFile(receiptFile, "utf8")).requestId;
+        }
+    }
+    uuid.parse(requestId);
+    const body = { ...payload, [idField]: requestId };
+    const form = uploads.length ? new FormData() : null;
+    if (form) {
+        form.set("message", JSON.stringify(body));
+        for (const upload of uploads)
+            form.append("files", new Blob([new Uint8Array(upload.bytes)], { type: upload.type }), upload.name);
+    }
+    if (!flags.json)
+        process.stderr.write(`Sending request ${requestId}…\n`);
+    const response = stateSchema.parse(await client.request(endpoint, {
+        method: "POST",
+        ...(form ? { body: form } : { json: body }),
+        signal: AbortSignal.timeout(300_000),
+    }));
+    if (persist &&
+        !["launch_pending", "launch_retryable"].includes(response.state))
+        await rm(receiptFile, { force: true });
+    return response;
+}
+export async function readThreatModel(client, draftId, model = false, timeoutMs = 60_000) {
+    uuid.parse(draftId);
+    return stateSchema.parse(await client.request(`/api/cli/v1/threat-models/${draftId}${model ? "/model" : ""}`, { signal: AbortSignal.timeout(Math.max(1, timeoutMs)) }));
+}
+export async function waitForThreatModel(client, draftId, timeoutSeconds = 60) {
+    if (!Number.isFinite(timeoutSeconds) ||
+        timeoutSeconds < 1 ||
+        timeoutSeconds > 3600)
+        throw new ThreatModelUsageError("--timeout must be between 1 and 3600 seconds");
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let state = await readThreatModel(client, draftId, false, deadline - Date.now());
+    while (["preparing", "working", "launch_pending"].includes(state.state)) {
+        const delay = Math.min(Math.max(state.pollAfterMs ?? 2000, 500), 10_000, Math.max(0, deadline - Date.now()));
+        if (delay <= 0)
+            return { ...state, timedOut: true };
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (Date.now() >= deadline)
+            return { ...state, timedOut: true };
+        try {
+            state = await readThreatModel(client, draftId, false, deadline - Date.now());
+        }
+        catch (error) {
+            if (Date.now() >= deadline &&
+                error instanceof Error &&
+                ["TimeoutError", "AbortError"].includes(error.name))
+                return { ...state, timedOut: true };
+            throw error;
+        }
+    }
+    return state;
+}
+async function interactiveAnswers(state) {
+    if (!state.question)
+        throw new ThreatModelUsageError("There is no pending question. Read the current draft state.");
+    output(state, {});
+    const answers = {};
+    for (const field of state.question.fields) {
+        process.stdout.write(terminalText(`${field.label}\n${field.description ?? ""}\n`));
+        for (const [index, option] of field.options.entries())
+            process.stdout.write(terminalText(`${index + 1}. ${option.label} (${option.value}) ${option.description ?? ""}\n`));
+        if (field.defaultValue !== undefined)
+            process.stdout.write(terminalText(`Suggestion: ${JSON.stringify(field.defaultValue)}. Type = to explicitly use it.\n`));
+        const value = await promptText("Answer (multi-select: comma-separated option numbers or values):");
+        if (value === "=" && field.defaultValue !== undefined) {
+            answers[field.id] = field.defaultValue;
+            continue;
+        }
+        if (!value && !field.required)
+            continue;
+        if (!value)
+            throw new ThreatModelUsageError(`${field.label} requires an answer; nothing was submitted`);
+        const optionValue = (v) => /^\d+$/.test(v) ? (field.options[Number(v) - 1]?.value ?? v) : v;
+        answers[field.id] =
+            field.kind === "multi_select"
+                ? value.split(",").map((v) => optionValue(v.trim()))
+                : field.kind === "single_select"
+                    ? optionValue(value)
+                    : value;
+    }
+    process.stdout.write(terminalText(`${JSON.stringify(answers, null, 2)}\n`));
+    if (!(await confirm("Submit these answers?", false)))
+        throw new ThreatModelUsageError("Answers were not submitted");
+    return {
+        questionEventId: state.question.questionEventId,
+        questionAnswers: answers,
+        text: "",
+    };
+}
+export async function commandThreatModel(client, cwd, flags, action, supplied, emit = true) {
+    const draftId = uuid.parse(required(flags, "draft"));
+    requireAuditSetupBeta(await requireAccount(client));
+    let state;
+    if (action === "status" || action === "next") {
+        state =
+            action === "next" && flags.wait
+                ? await waitForThreatModel(client, draftId, Number(getFlagString(flags, "timeout") ?? 60))
+                : await readThreatModel(client, draftId);
+    }
+    else if (action === "show") {
+        state = await readThreatModel(client, draftId, true);
+        if (!flags.json) {
+            const content = state.model?.content;
+            if (typeof content !== "string")
+                throw new ThreatModelUsageError("The complete model is not ready");
+            process.stderr.write(`SHA-256: ${state.model.sha256}\n`);
+            process.stdout.write(process.stdout.isTTY ? terminalText(content) : content);
+            return state;
+        }
+    }
+    else if (action === "answer" || action === "message") {
+        const payload = action === "answer"
+            ? !getFlagString(flags, "file") &&
+                supplied === undefined &&
+                canPromptInteractively(flags)
+                ? await interactiveAnswers(await readThreatModel(client, draftId))
+                : JSON.parse(await readInput(flags, supplied))
+            : { text: await readInput(flags, supplied) };
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            throw new ThreatModelUsageError("Answer file must contain a JSON object");
+        state = await mutate(client, flags, `/api/cli/v1/threat-models/${draftId}/${action === "answer" ? "answers" : "messages"}`, payload, getFlagList(flags, "attachment"), "clientMessageId");
+    }
+    else if (action === "approve" || action === "request-changes") {
+        const sha256 = z
+            .string()
+            .regex(/^[0-9a-f]{64}$/)
+            .parse(required(flags, "sha256"));
+        if (action === "approve" && flags["start-scan"] !== true)
+            throw new ThreatModelUsageError("Approval requires --start-scan. Read the complete model first.");
+        state = await mutate(client, flags, `/api/cli/v1/threat-models/${draftId}/review`, {
+            decision: action === "approve" ? "approve" : "request_changes",
+            sha256,
+            ...(action === "approve"
+                ? { startScan: true }
+                : { feedback: await readInput(flags, supplied) }),
+        });
+    }
+    else
+        throw new ThreatModelUsageError("Usage: apex threat-model <status|next|answer|message|show|request-changes|approve> --draft <id>");
+    if (emit)
+        output(state, flags);
+    return state;
+}
+export async function commandStartThreatModel(client, cwd, flags, emit = true) {
+    const setup = z.enum(["guided", "auto"]).parse(required(flags, "setup"));
+    const mode = z.enum(["standard", "audit"]).parse(required(flags, "mode"));
+    if (["repo", "pr", "pr-path", "source-mode", "force", "workspace-name"].some((key) => flags[key] !== undefined))
+        throw new ThreatModelUsageError("Audit Setup uses the configured workspace repositories and context; local source and force flags are not supported");
+    const me = await requireAccount(client);
+    const binding = await loadWorkspaceBinding(cwd);
+    const company = await chooseCompany(me, flags, binding);
+    requireAuditSetupBeta(me, company);
+    const ref = getFlagString(flags, "workspace-ref") ??
+        (binding?.companyId === company.id ? binding.workspaceId : null);
+    if (!ref)
+        throw new ThreatModelUsageError("Select --workspace-ref or bind a workspace with apex workspace use");
+    const response = await fetchCompanyWorkspaces(client, company.id);
+    const workspace = findWorkspaceByRef(response.workspaces, ref);
+    if (!workspace)
+        throw new ThreatModelUsageError("Workspace selection is missing or ambiguous. Use an exact workspace reference.");
+    if (canPromptInteractively(flags)) {
+        process.stdout.write(terminalText(`Prepare ${mode} scan in ${company.handle ?? company.id}/${workspace.prefix ?? workspace.name}, ${setup} mode. Feedback context: ${flags["no-feedback-context"] ? "disabled" : "included when available"}.\nUses the workspace's saved repositories, scope, and context. Preparation uses setup compute; the analysis scan starts only after explicit model approval.\n`));
+        if (!(await confirm("Start threat-model preparation?", false)))
+            throw new ThreatModelUsageError("Setup was not started");
+    }
+    let state = await mutate(client, flags, `/api/cli/v1/local-workspaces/${encodeURIComponent(workspace.workspaceId)}/scan-requests`, { mode, setup, includeFeedbackMemory: !flags["no-feedback-context"] });
+    if (emit)
+        output(state, flags);
+    if (!canPromptInteractively(flags))
+        return state;
+    const decisionFlags = { ...flags };
+    delete decisionFlags["request-id"];
+    // Each decision remains explicit. Closing the terminal leaves the server-owned draft intact.
+    while (true) {
+        if (["preparing", "working", "launch_pending"].includes(state.state)) {
+            process.stderr.write("Waiting for Audit Setup. You can exit and resume with the draft ID.\n");
+            state = await waitForThreatModel(client, state.draftId);
+            output(state, flags);
+            if (state.timedOut)
+                return state;
+        }
+        else if (state.state === "needs_input") {
+            state = await commandThreatModel(client, cwd, { ...decisionFlags, draft: state.draftId }, "answer");
+        }
+        else if (state.state === "needs_review") {
+            const review = await commandThreatModel(client, cwd, { ...decisionFlags, draft: state.draftId }, "show");
+            if (await confirm("Approve this exact threat model and start the scan?", false)) {
+                state = await commandThreatModel(client, cwd, {
+                    ...decisionFlags,
+                    draft: state.draftId,
+                    sha256: review.model.sha256,
+                    "start-scan": true,
+                }, "approve");
+            }
+            else {
+                const changes = await promptText("Describe requested changes, or leave blank to stop here:");
+                if (!changes)
+                    return review;
+                state = await commandThreatModel(client, cwd, {
+                    ...decisionFlags,
+                    draft: state.draftId,
+                    sha256: review.model.sha256,
+                }, "request-changes", changes);
+            }
+        }
+        else
+            return state;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.28",
+  "version": "0.1.33",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -9,7 +9,7 @@ This skill is bundled with Apex CLI and can be installed into Codex with `apex s
 
 Prefer the Apex MCP tools over running `apex` in the shell when the server is available. The tools installed by `apex setup` use the local stdio server and device login.
 
-For a production MCP client that does not need local filesystem access, use the hosted Streamable HTTP endpoint at `https://ai.cantina.xyz/mcp`. Read the organization service key from `APEX_SERVICE_KEY` and supply it only as `Authorization: Bearer <TOKEN>`; never put the raw key in a tool argument, result, prompt, source file, or log. The hosted tools are `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-status`, `apex-cancel-scan`, `apex-findings`, and `apex-workspace-findings`.
+For a production MCP client that does not need local filesystem access, use the hosted Streamable HTTP endpoint at `https://ai.cantina.xyz/mcp`. Read the organization service key from `APEX_SERVICE_KEY` and supply it only as `Authorization: Bearer <TOKEN>`; never put the raw key in a tool argument, result, prompt, source file, or log. The hosted tools are `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, and `apex-finding-send`.
 
 For serverless, cron, or other explicit HTTP/JSON integrations, use the hosted Apex REST API instead of CLI or local stdio MCP. The hosted MCP and REST contract is documented at https://ai.cantina.xyz/docs/apex-api.
 
@@ -80,6 +80,7 @@ Guidelines:
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
 - When checking a scan that is not the workspace binding's latest scan, pass `scanId` to `apex-status`; use `apex-scans` first if you need to discover scan IDs.
+- Use only the Bedrock `scanId` returned by Apex. Kernel execution IDs are private and are not returned or accepted as aliases by CLI or MCP tools.
 - Prefer `apex-findings` for quick inspection and `apex-export-findings` when the user needs a file artifact.
 - Use `apex-workspace-findings` when the user asks for findings across a workspace instead of one scan. Set `findingState: "open"` for findings needing review; open excludes fixed, invalid, dismissed, and duplicate findings and is not `status:open`. Pass `company` plus a workspace name, prefix, or ID as `workspaceRef` to avoid relying on or mutating a local binding.
 - Workspace finding responses expose the web UI lifecycle fields `status`, `validity`, `reviewState`, `isDuplicate`, `duplicateOfId`, `repository`, and `sourceFile`. Supported filter facets are `severity`, `scan`, `repo`, `review`, `impact`, `likelihood`, `status`, `validation`, `visibility`, `duplicate`, and `source`; a leading `!` negates a filter.
@@ -99,3 +100,18 @@ redeem response's `claimDeadline` instead.
 Example hosted MCP flow: configure `https://ai.cantina.xyz/mcp` as a
 Streamable HTTP server, source its Bearer token from `APEX_SERVICE_KEY`, and
 verify `apex-credits` without printing the credential.
+
+## Send findings to Linear and Jira
+
+- Use `apex-finding-send` to create a ticket from a finding, using the connected integration and saved frontend routing. Local input: `findingRef`, `provider: "linear" | "jira"`, optional `cwd`/`scanId`. Hosted input: `findingId` (UUID) and `provider`, with explicit `findings:write` scope.
+- CLI fallback: `apex findings send <finding-ref> <linear|jira> --json`. This uses device login and stays non-interactive in automation.
+- Connect the integration and configure its destination in Apex first: Linear workspace project/labels or company default; Jira workspace site/project/issue type. Missing destinations return a typed error; do not guess routing or create a different integration.
+- The result has `created` and `export` with issue key/URL. An existing sent or linked ticket returns `created: false`; an active export is a conflict. After ambiguous transport/provider failure, inspect `apex-finding-tickets` and provider state before retrying. Do not automatically repeat ticket creation.
+- Ticket content uses the same title, severity, finding details, and Apex link as the frontend.
+
+## Existing Linear and Jira tickets
+
+- After the company connects its integration, use `apex-finding-link-ticket` with `findingRef`, `provider: "linear" | "jira"`, and `issueRef` (ticket key or HTTPS issue URL). Local MCP accepts optional `cwd` and `scanId` and uses device login. A finding UUID works without a local binding; an identifier requires the bound workspace.
+- Use `apex-finding-tickets` to read existing links. CLI fallback: `apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url> --json`, then `apex findings tickets <finding-ref> --json`.
+- Hosted MCP uses `findingId` (UUID) instead of `findingRef`, with no `cwd` or `scanId`. Linking requires explicit `findings:write`; listing requires `findings:read`. Default service-key scopes remain scans:create, scans:read, findings:read. Do not infer write permission from read access.
+- Apex verifies the ticket through the connected integration and records the frontend link; it does not create or modify a provider ticket. Repeating the same association is safe. A different existing link or in-progress export is a conflict: do not replace it or create another ticket as a fallback. For ambiguous Jira sites, use the full issue URL.