@cantinasecurity/apex-cli 0.1.27 → 0.1.33

package/dist/service-keys.js

@@ -2,6 +2,7 @@ export const SERVICE_API_SCOPES = [
     "scans:create",
     "scans:read",
     "findings:read",
+    "findings:write",
 ];
 export function isServiceApiScope(value) {
     return (typeof value === "string" &&
@@ -13,7 +14,7 @@ function serviceApiKeysPath(companyId) {
 function serviceApiKeyMetadata(key) {
     const scopes = Array.isArray(key.scopes)
         ? [...new Set(key.scopes.filter(isServiceApiScope))]
-        : [...SERVICE_API_SCOPES];
+        : ["scans:create", "scans:read", "findings:read"];
     return {
         id: key.id,
         name: key.name,

package/dist/shell.js

@@ -1,5 +1,6 @@
-import { SHELL_HELP_TEXT } from "./help.js";
-import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandLogout, commandScan, commandScans, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
+import { commandStartThreatModel, hasAuditSetupBeta } from "./threat-model.js";
+import { shellHelpText } from "./help.js";
+import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingTickets, commandFindingLinkTicket, commandFindingSend, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandLogout, commandScan, commandScans, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
 import { withFlag } from "./args.js";
 import { printCompanyDetails, printInteractiveSessionSummary, printSourceList, printWorkspaceDetails, } from "./output.js";
 import { readLine } from "./prompt.js";
@@ -12,7 +13,7 @@ const SHELL_COMPLETIONS = [
     { command: "scans" },
     {
         command: "findings",
-        args: ["workspace", "comment", "feedback", "fix-review"],
+        args: ["workspace", "comment", "feedback", "fix-review", "tickets", "link-ticket", "send"],
     },
     { command: "export" },
     { command: "workspaces" },
@@ -133,8 +134,8 @@ export function getShellCompletionCandidates(input) {
 function clearTerminal() {
     process.stdout.write("\x1Bc");
 }
-function printShellHelp() {
-    process.stdout.write(`${SHELL_HELP_TEXT}\n`);
+function printShellHelp(session) {
+    process.stdout.write(`${shellHelpText(hasAuditSetupBeta(session.me, session.company))}\n`);
 }
 export async function runInteractiveShell(client, cwd, initialFlags) {
     let shellFlags = { ...initialFlags };
@@ -192,7 +193,7 @@ async function runShellCommandWithTelemetry(client, cwd, parsed, shellFlags, ses
 async function runShellCommand(client, cwd, parsed, shellFlags, session) {
     switch (parsed.command) {
         case "help":
-            printShellHelp();
+            printShellHelp(session);
             return {};
         case "credits":
             await commandCredits(client, cwd, shellFlags);
@@ -224,6 +225,10 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
                 : mode
                     ? withFlag(shellFlags, "mode", mode)
                     : shellFlags;
+            if (commandFlags.setup !== undefined) {
+                await commandStartThreatModel(client, cwd, commandFlags);
+                return {};
+            }
             const result = await commandScan(client, cwd, commandFlags);
             return {
                 session: {
@@ -248,6 +253,24 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandScans(client, cwd, shellFlags);
             return {};
         case "findings": {
+            if (parsed.args[0] === "send") {
+                if (parsed.args.length !== 3)
+                    throw new Error("Usage: /findings send <finding-ref> <linear|jira>");
+                await commandFindingSend(client, cwd, shellFlags, parsed.args[1], parsed.args[2]);
+                return {};
+            }
+            if (parsed.args[0] === "tickets") {
+                if (parsed.args.length !== 2)
+                    throw new Error("Usage: /findings tickets <finding-ref>");
+                await commandFindingTickets(client, cwd, shellFlags, parsed.args[1]);
+                return {};
+            }
+            if (parsed.args[0] === "link-ticket") {
+                if (parsed.args.length !== 4)
+                    throw new Error("Usage: /findings link-ticket <finding-ref> <linear|jira> <issue-key|url>");
+                await commandFindingLinkTicket(client, cwd, shellFlags, parsed.args[1], parsed.args[2], parsed.args[3]);
+                return {};
+            }
             if (parsed.args[0] === "workspace") {
                 await commandWorkspaceFindings(client, cwd, parsed.args.length > 1
                     ? withFlag(shellFlags, "filter", parsed.args.slice(1))

package/dist/telemetry.js

@@ -11,6 +11,7 @@ const TELEMETRY_SESSION_ID = randomUUID();
 const TELEMETRY_TIMEOUT_MS = 750;
 const telemetryContext = new AsyncLocalStorage();
 const KNOWN_CLI_COMMANDS = [
+    "threat-model",
     "cancel-scan",
     "connect",
     "claim",
@@ -282,7 +283,7 @@ function sanitizeShellArgs(parsed) {
                     commentLengthBucket: bucketLength(parsed.args.slice(feedbackStatus === "invalid" ? 4 : 3).join(" ")),
                 };
             }
-            if (action === "fix-review") {
+            if (["fix-review", "tickets", "link-ticket", "send"].includes(action)) {
                 return {
                     findingRefProvided: Boolean(parsed.args[1]),
                 };
@@ -330,7 +331,7 @@ function safeCliSubcommand(parsed) {
         case "export":
             return safeEnum(subcommand, ["findings"]);
         case "findings":
-            return safeEnum(subcommand, ["comment", "feedback", "fix-review"]);
+            return safeEnum(subcommand, ["comment", "feedback", "fix-review", "tickets", "link-ticket", "send"]);
         case "setup":
             return safeEnum(subcommand, ["all", "codex", "claude", "copilot"]);
         case "service-key":
@@ -404,6 +405,7 @@ export function sanitizeMcpInput(input = {}) {
             "github",
             "gitlab",
         ]),
+        ticketProvider: safeEnum(typeof input.provider === "string" ? input.provider : null, ["linear", "jira"]),
         feedbackStatus: safeEnum(typeof input.status === "string" ? input.status : null, [
             "valid",
             "invalid",

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.27",
+  "version": "0.1.33",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -7,9 +7,11 @@ description: Use when a user wants to start Apex scans, inspect findings, bind w
 
 This skill is bundled with Apex CLI and can be installed into Codex with `apex setup codex` or GitHub Copilot CLI with `apex setup copilot`.
 
-Prefer the Apex MCP tools over running `apex` in the shell when the server is available.
+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 serverless, cron, or other HTTP-only integrations, use the hosted Apex REST API instead of CLI or stdio MCP. Its scan trigger, status, and findings contract is documented at https://ai.cantina.xyz/docs/apex-api.
+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.
 
 `apex setup codex` configures the MCP server with client attribution so Apex can distinguish Codex MCP usage from direct CLI usage. Users can inspect or disable anonymous local usage telemetry with `apex telemetry status` and `apex telemetry disable`.
 
@@ -60,11 +62,12 @@ Guidelines:
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
 - The MCP-only `apex-trial-status` tool may report local guest and claim deadlines, but it must never return a trial code or claim token. `claimAvailable` becomes false at a known passed deadline; missing or invalid local deadline metadata remains conservative and server-authoritative. There is intentionally no MCP redemption or claim tool.
 - When MCP remains available after a guest scan, remind the user to run `apex claim` on the same machine while `claimAvailable` is true; after a known passed deadline, continue with normal account login.
-- Service-key management has no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in an MCP call, tool result, source file, or log.
+- Service-key creation, listing, and revocation have no MCP tools. Never ask a user to paste a service key into a prompt, and never place one in a tool argument, tool result, source file, or log. Hosted MCP clients may read it from a secret-backed environment variable for the HTTP Authorization header.
 - If a user explicitly needs a new service key, tell them to run `apex login` if needed, then run `apex service-key create --name <name> --scope <scope[,scope]>` directly in their own terminal. Use only the required scopes: `scans:create` to query credit availability or trigger, `scans:read` to poll status, and `findings:read` to retrieve findings. A P1-only adapter can use `--scope scans:read,findings:read`; omitting `--scope` grants all three. The CLI automatically selects the company when only one is available and prompts when there are several; use `--company <id-or-handle>` to skip that prompt or resolve a non-interactive command. Service-key commands never initiate login, and the secret is shown once.
-- For a headless HTTP adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. A service key does not authenticate CLI or MCP commands; those use device login. Do not shell out to `apex` or launch MCP from the adapter.
+- For a hosted MCP client, connect to `https://ai.cantina.xyz/mcp` and send `APEX_SERVICE_KEY` as a Bearer header. The service key authenticates hosted MCP, but not the local CLI or stdio MCP; those use device login.
+- For a headless REST adapter, read the service key from the secret-backed `APEX_SERVICE_KEY` environment variable, send it as a bearer token to `/api/apex/v1`, and redact it from errors and logs. Do not shell out to `apex` or launch local MCP from the adapter.
 - Hosted API integrations can call `GET /api/apex/v1/credits` with `scans:create` scope to inspect the organization's current standard, audit, and Lite balances and effective scan-type availability. Treat the response as a point-in-time snapshot; scan creation remains authoritative.
-- Hosted API v1 remote-repository scans require the GitHub repository to be linked to an active Apex workspace and do not create or mutate workspaces; use optional `workspaceId` to disambiguate matches and treat zero or ambiguous matches as HTTP `409` setup errors. Local or non-Git scans use the documented source-upload flow, which can create or reuse a workspace; send `generateThreatModel: true` for the first scan of a newly created local workspace.
+- Hosted remote-repository scans require the GitHub repository to be connected to the service key's Apex organization. They reuse a linked active workspace or create and link one when no match exists; use optional `workspaceId` to disambiguate multiple matches and treat explicit workspace/repository mismatches as HTTP `409` setup errors. Local or non-Git REST scans use the documented source-upload flow; send `generateThreatModel: true` for the first scan of a newly created local workspace.
 - Hosted scan triggers require `Idempotency-Key`. Reuse one stable key only for an identical transport/timeout/5xx retry. After correcting a definitive 4xx response, or for any new intended scan, use a new key.
 - `apex-credits` reports standard credits plus audit, fix review, and Lite scan entitlements when Bedrock returns those balances.
 - `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.
@@ -77,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.
@@ -92,3 +96,22 @@ in a terminal, use MCP for scan/status/findings after redemption, then check the
 MCP-only `apex-trial-status` tool and remind the user to run `apex claim`
 locally while `claimAvailable` remains true. In a CLI-only flow, use the
 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.