@cantinasecurity/apex-cli 0.1.27 → 0.1.33

package/dist/commands.js

@@ -4,12 +4,12 @@ import { ApiError, formatApiError, getApiErrorCode, } from "./api-client.js";
 import { openInBrowser } from "./browser.js";
 import { getClaimProofState, isClaimProofAvailable, parseClaimDeadlineMs, } from "./claim-proof.js";
 import { loadConfig, updateConfig } from "./config.js";
-import { createFindingComment, fetchScanExport, fetchScanFindings, fetchWorkspaceFindings, isFindingUuid, normalizeFindingRef, resolveFindingSelection, resolveScanSelection, startFindingFixReviewScan, submitFindingFeedback, } from "./findings.js";
+import { createFindingComment, fetchFindingTickets, linkFindingTicket, sendFindingToIssueTracker, fetchScanExport, fetchScanFindings, fetchWorkspaceFindings, isFindingUuid, normalizeFindingRef, resolveFindingSelection, resolveScanSelection, startFindingFixReviewScan, submitFindingFeedback, } from "./findings.js";
 import { prepareLocalSourceArchives, prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-source-scan.js";
 import { logLine, printJson, withLoadingIndicator } from "./output.js";
 import { claimOnboardingSession, isProofOnlyOnboardingCredentials, redeemOnboardingCode, revokeGuestOnboardingSession, } from "./onboarding.js";
 import { confirm } from "./prompt.js";
-import { cancelScan, fetchScanProgress, fetchWorkspaceScans, findMostRelevantActiveScan, getScanDisplayLabel, getScanDisplayId, getTrackedScanId, isActiveScanStatus, matchesScanId, selectDefaultScanToCancel, } from "./scan.js";
+import { cancelScan, fetchScanProgress, fetchWorkspaceScans, findMostRelevantActiveScan, getScanDisplayLabel, getScanDisplayId, getTrackedScanId, isActiveScanStatus, matchesScanId, normalizeScanStartResponse, selectDefaultScanToCancel, } from "./scan.js";
 import { createServiceApiKey, isServiceApiScope, listServiceApiKeys, revokeServiceApiKey, SERVICE_API_SCOPES, } from "./service-keys.js";
 import { getServiceKeyCliAuthGuidance } from "./service-key-environment.js";
 import { chooseCompany, createWorkspaceBinding, ensureAuthenticated, planGuestWorkspaceSelection, remediateMissingConnections, resolveWorkspaceSelection, resolveWorkspaceSelectionLegacy, resolveWorkspaceAllowingMissingConnections, selectWorkspaceTarget, } from "./session.js";
@@ -620,7 +620,6 @@ async function findFallbackActiveScan(client, binding) {
         }
         return {
             scanId: progress.scanId,
-            kernelScanId: progress.kernelScanId,
             apexScanId: binding.lastScanId,
             bedrockScanId: null,
             displayName: null,
@@ -1084,6 +1083,9 @@ export async function commandConnect(client, cwd, flags, provider) {
     return { provider, company, url: response.url };
 }
 export async function commandScan(client, cwd, flags) {
+    if (flags.setup !== undefined) {
+        throw new Error("Audit Setup must use the threat-model preparation flow; a legacy scan was not started.");
+    }
     const requestedMode = normalizeRequestedScanMode(getFlagString(flags, "mode"));
     const prSelections = parsePrScanPullRequestSelections(flags);
     if (requestedMode !== "pr" && prSelections.length > 0) {
@@ -1159,7 +1161,8 @@ export async function commandScan(client, cwd, flags) {
         const prSource = resolvePrScanSource(legacyResolve.repositories);
         ensurePrSelectionsMatchSource(prSelections, prSource);
         prScanSource = prSource;
-        scan = await withLoadingIndicator("Starting PR scan...", flags, () => client.request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+        scan = await withLoadingIndicator("Starting PR scan...", flags, () => client
+            .request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
             method: "POST",
             json: {
                 mode: "pr",
@@ -1170,7 +1173,8 @@ export async function commandScan(client, cwd, flags) {
                     pullRequests: prSelections,
                 }),
             },
-        }));
+        })
+            .then(normalizeScanStartResponse));
     }
     else if (requestedMode === "audit" || requestedMode === "lite") {
         const modeLabel = requestedMode === "audit" ? "Audit" : "Lite";
@@ -1182,13 +1186,15 @@ export async function commandScan(client, cwd, flags) {
             throw new Error("Workspace resolution did not return a workspaceId.");
         }
         workspaceId = legacyResolve.workspaceId;
-        scan = await withLoadingIndicator(`Starting ${modeLabel.toLowerCase()} scan...`, flags, () => client.request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+        scan = await withLoadingIndicator(`Starting ${modeLabel.toLowerCase()} scan...`, flags, () => client
+            .request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
             method: "POST",
             json: {
                 mode: requestedMode,
                 force: forceRestart || flags.force === true,
             },
-        }));
+        })
+            .then(normalizeScanStartResponse));
     }
     else {
         try {
@@ -1200,7 +1206,7 @@ export async function commandScan(client, cwd, flags) {
                     detectedSources: result.sources,
                     preparedArchives,
                 });
-                return client.request(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
+                const response = await client.request(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
                     method: "POST",
                     json: {
                         mode: requestedMode,
@@ -1208,6 +1214,7 @@ export async function commandScan(client, cwd, flags) {
                         scanSources,
                     },
                 });
+                return normalizeScanStartResponse(response);
             });
         }
         finally {
@@ -1786,9 +1793,6 @@ export async function commandFindingFixReview(client, cwd, flags, requestedFindi
     }
     logLine(`Finding: ${selection.finding?.findingIdentifier ?? selection.findingId}`, flags);
     logLine(`Fix review scan: ${response.fixReview.status} (${response.fixReview.scanId})`, flags);
-    if (response.fixReview.kernelScanId) {
-        logLine(`Kernel scan: ${response.fixReview.kernelScanId}`, flags);
-    }
     if (response.fixReview.reviewTarget) {
         logLine(`Review target: ${formatFixReviewTarget(response.fixReview.reviewTarget)}`, flags);
     }
@@ -1873,3 +1877,52 @@ export async function openCurrentApexView(client, cwd, flags) {
     }
     return url;
 }
+async function resolveTicketFinding(client, cwd, flags, requestedFindingRef) {
+    const findingRef = normalizeFindingRefInput(requestedFindingRef);
+    const currentBinding = await loadWorkspaceBinding(cwd);
+    const binding = isFindingUuid(findingRef)
+        ? currentBinding : requireLoadedWorkspaceBinding(currentBinding);
+    if (!isFindingUuid(findingRef))
+        await ensureAuthenticated(client, flags);
+    return resolveFindingSelection({ client, binding, requestedFindingRef: findingRef,
+        requestedScanId: getFlagString(flags, "scan") });
+}
+export async function commandFindingTickets(client, cwd, flags, findingRef) {
+    const selection = await resolveTicketFinding(client, cwd, flags, findingRef);
+    const result = await fetchFindingTickets(client, selection.findingId);
+    const payload = { findingId: selection.findingId, findingRef: selection.findingRef, ...result };
+    if (isJsonMode(flags))
+        printJson(payload);
+    else if (result.tickets.length === 0)
+        logLine("No tickets linked to this finding.", flags);
+    else
+        for (const ticket of result.tickets)
+            logLine(`${ticket.provider}: ${ticket.issueKey ?? ticket.issueId} ${ticket.issueUrl}`, flags);
+    return payload;
+}
+export async function commandFindingLinkTicket(client, cwd, flags, findingRef, provider, issueRef) {
+    if ((provider !== "linear" && provider !== "jira") || !issueRef.trim() || issueRef.trim().length > 2048) {
+        throw new Error("Usage: apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url>");
+    }
+    const selection = await resolveTicketFinding(client, cwd, flags, findingRef);
+    const result = await linkFindingTicket(client, selection.findingId, { provider, issueRef: issueRef.trim() });
+    const payload = { findingId: selection.findingId, findingRef: selection.findingRef, ...result };
+    if (isJsonMode(flags))
+        printJson(payload);
+    else
+        logLine(`${result.linked ? "Linked" : "Already linked"}: ${result.ticket.issueKey ?? result.ticket.issueId} ${result.ticket.issueUrl}`, flags);
+    return payload;
+}
+export async function commandFindingSend(client, cwd, flags, findingRef, provider) {
+    if (provider !== "linear" && provider !== "jira") {
+        throw new Error("Usage: apex findings send <finding-ref> <linear|jira>");
+    }
+    const selection = await resolveTicketFinding(client, cwd, flags, findingRef);
+    const result = await sendFindingToIssueTracker(client, selection.findingId, provider);
+    const payload = { findingId: selection.findingId, findingRef: selection.findingRef, ...result };
+    if (isJsonMode(flags))
+        printJson(payload);
+    else
+        logLine(`${result.created ? "Created" : "Already sent"}: ${result.export.issueKey ?? result.export.issueId} ${result.export.issueUrl}`, flags);
+    return payload;
+}

package/dist/findings.js

@@ -1,11 +1,11 @@
-import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, } from "./scan.js";
+import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, stripKernelScanIdentifiers, } from "./scan.js";
 import { ApiError, CredentialGenerationChangedError, isTerminalGuestSessionError, } from "./api-client.js";
 const FINDING_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const WORKSPACE_FINDING_FILTER_PATTERN = /^!?(severity|scan|repo|review|impact|likelihood|status|validation|visibility|duplicate|source):[^:]+$/;
 const MAX_WORKSPACE_FINDING_FILTERS = 50;
 const MAX_WORKSPACE_FINDING_FILTER_LENGTH = 128;
 const CANTINA_AUTH_TOKEN_ENV = "CANTINA_AUTH_TOKEN";
-const FINDING_WRITE_AUTH_ERROR = "Finding comments, feedback, and fix review scans require Apex authentication. Run `apex login` or use MCP `apex-auth-start` followed by `apex-auth-wait`, then retry.";
+const FINDING_WRITE_AUTH_ERROR = "Finding comments, feedback, ticket links, ticket creation, and fix review scans require Apex authentication. Run `apex login` or use MCP `apex-auth-start` followed by `apex-auth-wait`, then retry.";
 function parsePositiveInt(value) {
     if (!value)
         return null;
@@ -307,7 +307,7 @@ export async function startFindingFixReviewScan(client, findingId, input = {}) {
     const fixPrUrls = input.fixPrUrls
         ?.map((url) => url.trim())
         .filter((url) => url.length > 0) ?? [];
-    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/fix-review`, {
+    const response = await requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/fix-review`, {
         method: "POST",
         json: {
             ...(input.reviewTarget ? { reviewTarget: input.reviewTarget } : {}),
@@ -316,4 +316,16 @@ export async function startFindingFixReviewScan(client, findingId, input = {}) {
                 : {}),
         },
     });
+    return stripKernelScanIdentifiers(response);
+}
+export async function fetchFindingTickets(client, findingId) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/tickets`);
+}
+export async function linkFindingTicket(client, findingId, input) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/tickets`, {
+        method: "POST", json: input,
+    });
+}
+export async function sendFindingToIssueTracker(client, findingId, provider) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/issue-trackers/${provider}`, { method: "POST" });
 }

package/dist/help.js

@@ -5,6 +5,11 @@ export const CLI_HELP_TEXT = `Usage:
   apex scans                        List scans for the current workspace binding
   apex findings                     List findings for the latest or selected scan
   apex findings --workspace         List findings across the workspace browser scan set
+  apex findings send <finding-ref> <linear|jira>
+                                    Create a ticket using the connected integration and saved destination
+  apex findings tickets <finding-ref> List linked Linear and Jira tickets
+  apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url>
+                                    Link an existing ticket using a connected integration
   apex findings comment <finding-id|finding-identifier>
                                     Add a comment or note to a finding
   apex findings feedback <finding-id|finding-identifier> <valid|invalid>
@@ -38,12 +43,12 @@ export const CLI_HELP_TEXT = `Usage:
 Flags:
   --company <id-or-handle>          Override the automatically selected Apex company
   --name <name>                     Name a new service key
-  --scope <scope[,scope]>           Limit a service key to scans:create, scans:read, and/or findings:read
+  --scope <scope[,scope]>           Limit a service key to scans:create, scans:read, findings:read, and/or findings:write
   --expires-at <ISO-8601>           Set an optional service-key expiration time
   --workspace-name <name>           Set the Apex workspace name for this directory
   --scan <scan-id>                  Select a specific scan for status, findings, or export
   --workspace                       Use the cross-scan workspace findings view
-  --workspace-ref <name|prefix|id>  Select a workspace for apex findings --workspace only
+  --workspace-ref <name|prefix|id>  Select a workspace for cross-scan findings
   --finding-state all|open          Select all findings or only findings needing review
   --filter <[!]facet:value>         Filter workspace findings; repeat for multiple filters
   --status valid|invalid            Set the finding feedback status explicitly
@@ -81,6 +86,7 @@ Tips:
   audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
   Lite scans use --mode lite and require beta access plus provider-backed GitHub or GitLab sources.
   apex workspace use accepts a workspace name, prefix, or ID.
+  Scan selectors use the public Bedrock scan ID shown by Apex; Kernel execution IDs are private and are not accepted as aliases.
   Finding comments, feedback, and fix review scans use the same Apex login credentials as other CLI commands.
   Trial codes go only to apex redeem. Never echo, log, save, telemeter, or send them through MCP.
   Trial redemption, claim, and revocation require https://ai.cantina.xyz and reject other APEX_BASE_URL origins before sending secrets.
@@ -90,12 +96,17 @@ Tips:
   After a guest scan, run apex claim on the same machine within the displayed claim deadline to keep the results.
   Claim moves trial results into the selected Cantina workspace when you can run scans there, or into your existing personal workspace.
   Service-key commands require an existing login; run apex login first when needed.
-  APEX_SERVICE_KEY authenticates the hosted REST API only; it does not replace apex login for CLI commands.
+  APEX_SERVICE_KEY authenticates https://ai.cantina.xyz/mcp and hosted REST; it does not replace apex login for local CLI or stdio MCP commands.
   Apex automatically selects your company when only one is available. With multiple companies, choose one interactively or pass --company.
-  Service-key creation also requires --name and reveals the secret only once; omit --scope to grant all hosted API scopes.
+  Service-key creation also requires --name and reveals the secret only once; omit --scope to grant scans:create, scans:read, and findings:read only.
   Service-key management is available only in the scripted CLI, not the interactive shell or MCP server.
   Invalid finding feedback requires --dismissal-reason.
   Fix review scans use saved or supplied Fix PR URLs when present; otherwise they review the current repository when Bedrock has original scan repository context.
+  Ticket linking verifies the company's connected integration, never creates a ticket, and never replaces a link.
+  Sending creates a ticket with the same title, details, and Apex link as the frontend, using its saved destination.
+  Configure Linear routing or the Jira workspace destination in Apex first. Already sent or linked findings return the existing ticket.
+  After an ambiguous send failure, check the provider and apex findings tickets before retrying.
+  Hosted MCP ticket creation and linking require an explicitly granted findings:write service-key scope; default scopes stay unchanged.
   Finding identifiers such as KERN2-25 resolve against the selected scan; pass --scan or use the finding UUID directly when needed.
   Use apex findings --workspace --company <handle> --workspace-ref <ref> --finding-state open to retrieve findings needing review without changing the local binding.
   To run scans or exports against a different workspace, bind it first with apex workspace use <ref>.
@@ -105,6 +116,26 @@ Tips:
   Quote workspace names that contain spaces:
     apex workspace use "Core Platform"
 `;
+const AUDIT_SETUP_CLI_HELP = `
+Audit Setup beta:
+  apex scan --workspace-ref <ref> --mode standard|audit --setup guided|auto
+                                    Prepare a threat model for an enabled workspace
+  apex threat-model <action>        Read, answer, review, and approve a prepared model
+  --draft <uuid>                    Select an Audit Setup draft
+  --file <path|->                   Read answer JSON, message, or revision text (stdin: -)
+  --attachment <path>               Attach a file to an answer or message (repeatable)
+  --sha256 <hash>                   Select the exact reviewed model
+  --start-scan                      Confirm scan launch when approving a model
+  --request-id <uuid>               Reuse an operation ID when retrying
+  --no-feedback-context             Exclude prior feedback from this setup
+  --wait                            Wait for the next actionable setup state
+  --timeout <seconds>               Bound next --wait (default 60, maximum 3600)
+`;
+export function cliHelpText(auditSetupEnabled) {
+    return auditSetupEnabled
+        ? `${CLI_HELP_TEXT.trimEnd()}\n${AUDIT_SETUP_CLI_HELP}`
+        : CLI_HELP_TEXT;
+}
 export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common arguments.
 
 Commands:
@@ -116,6 +147,11 @@ Commands:
   /findings [scan-id]     List findings for the latest or selected scan
   /findings workspace [filter...]
                           List workspace findings; for example review:unreviewed
+  /findings send <finding-ref> <linear|jira>
+                          Create a ticket using the connected integration and saved destination
+  /findings tickets <finding-ref> List linked Linear and Jira tickets
+  /findings link-ticket <finding-ref> <linear|jira> <issue-key|url>
+                          Link an existing ticket using a connected integration
   /findings comment <finding-ref> <comment>
                           Add a comment or note to a finding
   /findings feedback <finding-ref> valid [comment]
@@ -161,6 +197,7 @@ Tips:
   audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
   Lite scans require beta access plus provider-backed GitHub or GitLab sources.
   /workspace use accepts a workspace name, prefix, or ID.
+  Scan selectors use the public Bedrock scan ID shown by Apex; Kernel execution IDs are private and are not accepted as aliases.
   /findings comment, /findings feedback, and /findings fix-review use the current Apex login.
   For first-class open state or a workspace that is not locally bound, use scripted
   apex findings --workspace --company <handle> --workspace-ref <ref> --finding-state open.
@@ -174,3 +211,13 @@ Tips:
   Anonymous usage telemetry can be disabled with /telemetry disable or APEX_TELEMETRY_DISABLED=1.
   Quote workspace names that contain spaces: /workspace use "Core Platform"
 `;
+const AUDIT_SETUP_SHELL_HELP = `
+Audit Setup beta:
+  Start the shell with --setup guided|auto and --mode standard|audit to prepare
+  the active workspace's threat model before explicitly approving its scan.
+`;
+export function shellHelpText(auditSetupEnabled) {
+    return auditSetupEnabled
+        ? `${SHELL_HELP_TEXT.trimEnd()}\n${AUDIT_SETUP_SHELL_HELP}`
+        : SHELL_HELP_TEXT;
+}

package/dist/mcp.js

@@ -1,3 +1,4 @@
+import { commandStartThreatModel, commandThreatModel, hasAuditSetupBeta } from "./threat-model.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import path from "node:path";
@@ -5,8 +6,8 @@ import { z } from "zod";
 import { getMe, logout, readStableDeviceLoginState, startDeviceLogin, waitForDeviceLoginApproval, } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.js";
 import { getClaimProofState, isClaimProofAvailable, } from "./claim-proof.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
-import { CLI_HELP_TEXT } from "./help.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingTickets, commandFindingLinkTicket, commandFindingSend, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { cliHelpText } from "./help.js";
 import { getLocalTrialStatus, isProofOnlyOnboardingCredentials, revokeGuestOnboardingSession, } from "./onboarding.js";
 import { createMcpServerTelemetryInvocation, createMcpTelemetryInvocation, emitInvocationCompleted, emitInvocationStarted, emitMcpServerStarted, withTelemetryContext, } from "./telemetry.js";
 import { APEX_CLI_VERSION } from "./version.js";
@@ -21,20 +22,31 @@ Suggested workflow:
 6. If a repository operation needs a different local binding, call apex-workspaces and apex-workspace-use.
 7. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings. For cross-scan review queues, call apex-workspace-findings with company, workspaceRef, and findingState "open"; this direct selection does not require or change a local binding.
 8. For PR scans, call apex-scan with mode "pr" and one or more pullRequests.
-9. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
-10. To review a fix, call apex-finding-fix-review. Pass fixPrUrls for PR-based fix reviews, or omit them to review the current repository state when Bedrock has original scan repository context.
+9. Send findings to Linear/Jira with apex-finding-send to create tickets using the frontend's saved destination. Link existing tickets with apex-finding-link-ticket and inspect links with apex-finding-tickets. The company integration must already be connected.
+10. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
+11. To review a fix, call apex-finding-fix-review. Pass fixPrUrls for PR-based fix reviews, or omit them to review the current repository state when Bedrock has original scan repository context.
 
 Notes:
 - Pass cwd explicitly for repository-specific operations.
 - Tool calls are always non-interactive and never auto-open a browser.
 - Finding write tools use the same Apex device-login credentials as read tools. Never ask for browser cookies or CANTINA_AUTH_TOKEN. An error requiring CANTINA_AUTH_TOKEN proves the MCP server is outdated; update Apex CLI, re-run apex setup for this client, restart it, and retry.
-- Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into an MCP prompt or tool call.
-- HTTP-only serverless and cron integrations should use the hosted API documented at https://ai.cantina.xyz/docs/apex-api instead of launching this stdio server.
+- Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into a prompt or tool argument. A hosted MCP client supplies it only as the HTTP Authorization header.
+- Production agents that do not need local filesystem access can connect to https://ai.cantina.xyz/mcp over Streamable HTTP with Authorization: Bearer <service-key>. Serverless and cron applications can instead use the REST API documented at https://ai.cantina.xyz/docs/apex-api. This local stdio server continues to use device login.
 - Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias. Use mode "lite" only for beta-enabled provider-backed Lite scans, and mode "pr" for GitHub pull request scans.
+- Use only the public Bedrock scanId returned by Apex for scan inputs. Kernel execution IDs are private and are neither returned nor accepted as aliases.
 - Starting a PR scan may run alongside active workspace scans and does not require force. Starting any non-PR scan still treats every active scan, including a PR scan, as a blocker; use force only when the user explicitly wants that overlap.
 - Doctor is read-only for guest sessions and reports the local snapshot plan without reserving a workspace.
 - Guest standard scans validate the complete local archive before resolving or reserving a workspace. For an unbound renamed checkout, Apex may recover only the sole empty guest workspace when no explicit workspace name was supplied.
 - When terminal redemption returns JSON, parse stdout only and keep stderr warnings separate. An idempotent outcome resumes the existing guest session, which may already own a workspace.`;
+const AUDIT_SETUP_MCP_GUIDE = `
+
+Audit Setup beta:
+- Use apex-scan-setup for a configured workspace, then apex-threat-model.
+- Read the complete model and get explicit approval before approve with the reviewed sha256 and startScan true.
+- These tools use the local device account. Hosted service-key MCP does not expose Audit Setup.`;
+function mcpWorkflowGuide(auditSetupEnabled) {
+    return auditSetupEnabled ? `${MCP_WORKFLOW_GUIDE}${AUDIT_SETUP_MCP_GUIDE}` : MCP_WORKFLOW_GUIDE;
+}
 const WORKSPACE_BINDING_ERROR = "This directory is not bound to an Apex workspace yet. Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const MISSING_PROVIDER_CONNECTIONS_ERROR = "Missing provider connections. Re-run interactively or pre-connect providers.";
 const PR_MISSING_PROVIDER_CONNECTIONS_ERROR_PREFIX = "PR scans require connected provider access for ";
@@ -190,7 +202,7 @@ async function requireAuthenticated(client) {
     }
     return me;
 }
-function registerResources(server) {
+function registerResources(server, auditSetupEnabled = false) {
     server.registerResource("apex-cli-help", "apex://help/cli", {
         title: "Apex CLI Help",
         description: "Command reference for the Apex CLI.",
@@ -199,7 +211,7 @@ function registerResources(server) {
         contents: [
             {
                 uri: uri.href,
-                text: CLI_HELP_TEXT,
+                text: cliHelpText(auditSetupEnabled),
             },
         ],
     }));
@@ -211,12 +223,12 @@ function registerResources(server) {
         contents: [
             {
                 uri: uri.href,
-                text: MCP_WORKFLOW_GUIDE,
+                text: mcpWorkflowGuide(auditSetupEnabled),
             },
         ],
     }));
 }
-function registerTools(server) {
+function registerTools(server, auditSetupEnabled = false) {
     server.registerTool("apex-auth-status", {
         title: "Apex Auth Status",
         description: "Check whether Apex is already authenticated on this machine.",
@@ -494,6 +506,38 @@ function registerTools(server) {
         company,
         workspaceRef,
     }));
+    if (auditSetupEnabled)
+        server.registerTool("apex-scan-setup", {
+            title: "Prepare a scan threat model",
+            description: "Use an existing configured workspace to prepare a Standard or Audit threat model. Preparation can use paid setup compute. Always pause for explicit user model approval before starting the analysis scan.",
+            inputSchema: { cwd: z.string().optional(), company: z.string().optional(), workspaceRef: z.string(), mode: z.enum(["standard", "audit"]), setup: z.enum(["guided", "auto"]), includeFeedbackContext: z.boolean().default(true), requestId: z.string().uuid().optional() },
+        }, async (input) => runTool("apex-scan-setup", async () => {
+            const flags = { json: true, "non-interactive": true, "workspace-ref": input.workspaceRef, mode: input.mode, setup: input.setup };
+            if (input.company)
+                flags.company = input.company;
+            if (input.requestId)
+                flags["request-id"] = input.requestId;
+            if (!input.includeFeedbackContext)
+                flags["no-feedback-context"] = true;
+            return commandStartThreatModel(new ApexApiClient(), resolveCwd(input.cwd), flags, false);
+        }, value => `Threat-model draft ${String(value.draftId)}: ${String(value.state)}.`, input));
+    if (auditSetupEnabled)
+        server.registerTool("apex-threat-model", {
+            title: "Read or respond to an Audit Setup draft",
+            description: "Read status or the full model, answer an exact pending question, submit context, request changes, or explicitly approve the reviewed SHA-256 and start its scan. Auto preparation is never approval. For answer, input is JSON containing questionEventId, questionAnswers and optional text/clientMessageId. For message and request-changes, input is plain text.",
+            inputSchema: { cwd: z.string().optional(), draftId: z.string().uuid(), action: z.enum(["status", "next", "show", "answer", "message", "request-changes", "approve"]), input: z.string().optional(), sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(), startScan: z.boolean().optional(), requestId: z.string().uuid().optional(), wait: z.boolean().optional() },
+        }, async (input) => runTool("apex-threat-model", async () => {
+            const flags = { json: true, "non-interactive": true, draft: input.draftId };
+            if (input.sha256)
+                flags.sha256 = input.sha256;
+            if (input.startScan)
+                flags["start-scan"] = true;
+            if (input.requestId)
+                flags["request-id"] = input.requestId;
+            if (input.wait)
+                flags.wait = true;
+            return commandThreatModel(new ApexApiClient(), resolveCwd(input.cwd), flags, input.action, input.input, false);
+        }, value => `Threat-model draft ${String(value.draftId)}: ${String(value.state)}.`, input));
     server.registerTool("apex-scan", {
         title: "Start Apex Scan",
         description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths only to scan explicit alternate local roots. Use mode audit for audit scans, mode lite for beta-gated provider-backed Lite scans, and mode pr for GitHub pull request scans.",
@@ -649,6 +693,39 @@ function registerTools(server) {
             ...payload,
         };
     }, (value) => `Fetched Apex workspace findings for ${String(value.cwd)}.`, { cwd, company, workspaceRef, findingState, filters }));
+    server.registerTool("apex-finding-tickets", {
+        title: "List Apex Finding Tickets",
+        description: "List the Linear and Jira tickets linked to a finding. Uses the current Apex device login.",
+        inputSchema: { cwd: z.string().optional(), findingRef: z.string(), scanId: z.string().optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ cwd, findingRef, scanId }) => runTool("apex-finding-tickets", async () => {
+        const targetCwd = resolveCwd(cwd);
+        return { cwd: targetCwd, ...await commandFindingTickets(new ApexApiClient(), targetCwd, buildFlags({ scanId }), findingRef) };
+    }, () => "Loaded finding ticket links.", { cwd, findingRef, scanId }));
+    server.registerTool("apex-finding-link-ticket", {
+        title: "Link an Existing Ticket to an Apex Finding",
+        description: "Verify and link an existing Linear or Jira ticket using the company's connected integration. Accepts an issue key or HTTPS issue URL; does not create a ticket or replace a link. Uses the current Apex device login.",
+        inputSchema: {
+            cwd: z.string().optional(), findingRef: z.string(), scanId: z.string().optional(),
+            provider: z.enum(["linear", "jira"]), issueRef: z.string().trim().min(1).max(2048),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ cwd, findingRef, scanId, provider, issueRef }) => runTool("apex-finding-link-ticket", async () => {
+        const targetCwd = resolveCwd(cwd);
+        return { cwd: targetCwd, ...await commandFindingLinkTicket(new ApexApiClient(), targetCwd, buildFlags({ scanId }), findingRef, provider, issueRef) };
+    }, () => "Linked existing ticket to finding.", { cwd, findingRef, scanId, provider, issueRef }));
+    server.registerTool("apex-finding-send", {
+        title: "Send an Apex Finding to Linear or Jira",
+        description: "Create a Linear or Jira ticket from a finding, using the connected company integration and the same saved destination, title, details, and Apex link as the frontend. Returns an existing ticket if already sent or linked. Configure the destination in Apex first. After a timeout, inspect ticket links and the provider before retrying. Uses device login.",
+        inputSchema: {
+            cwd: z.string().optional(), findingRef: z.string(), scanId: z.string().optional(),
+            provider: z.enum(["linear", "jira"]),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async ({ cwd, findingRef, scanId, provider }) => runTool("apex-finding-send", async () => {
+        const targetCwd = resolveCwd(cwd);
+        return { cwd: targetCwd, ...await commandFindingSend(new ApexApiClient(), targetCwd, buildFlags({ scanId }), findingRef, provider) };
+    }, () => "Sent finding to issue tracker.", { cwd, findingRef, scanId, provider }));
     server.registerTool("apex-finding-comment", {
         title: "Add Apex Finding Comment",
         description: "Add a comment or note to an Apex finding using the current Apex login.",
@@ -818,8 +895,12 @@ export async function runMcpServer() {
         version: APEX_CLI_VERSION,
     });
     const invocation = createMcpServerTelemetryInvocation();
-    registerResources(server);
-    registerTools(server);
+    const me = await getMe(new ApexApiClient(), {
+        signal: AbortSignal.timeout(1_500),
+    }).catch(() => null);
+    const auditSetupEnabled = hasAuditSetupBeta(me);
+    registerResources(server, auditSetupEnabled);
+    registerTools(server, auditSetupEnabled);
     const transport = new StdioServerTransport();
     emitMcpServerStarted(invocation);
     await server.connect(transport);
@@ -831,5 +912,6 @@ export const testing = {
     requireAuthenticated,
     resolveCwd,
     runTool,
+    mcpWorkflowGuide,
     workflowGuide: MCP_WORKFLOW_GUIDE,
 };

package/dist/scan.js

@@ -11,6 +11,19 @@ const ACTIVE_SCAN_STATUSES = new Set([
 function asRecord(value) {
     return value && typeof value === "object" ? value : null;
 }
+const KERNEL_SCAN_IDENTIFIER_KEY = /^kernel_?scan_?id$/i;
+export function stripKernelScanIdentifiers(value) {
+    if (Array.isArray(value)) {
+        return value.map(stripKernelScanIdentifiers);
+    }
+    const record = asRecord(value);
+    if (!record) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(record)
+        .filter(([key]) => !KERNEL_SCAN_IDENTIFIER_KEY.test(key))
+        .map(([key, entry]) => [key, stripKernelScanIdentifiers(entry)]));
+}
 function readString(...values) {
     for (const value of values) {
         if (typeof value === "string" && value.trim().length > 0) {
@@ -30,6 +43,14 @@ function readNumber(...values) {
     }
     return null;
 }
+function readBoolean(...values) {
+    for (const value of values) {
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return null;
+}
 function readScanMode(...values) {
     const mode = readString(...values);
     return mode === "ultra" ? "audit" : mode;
@@ -55,13 +76,12 @@ function normalizeScanRecord(payload) {
     if (!record) {
         return null;
     }
-    const scanId = readString(record.scanId, record.id, record.apexScanId, record.bedrockScanId, record.kernelScanId);
+    const scanId = readString(record.scanId, record.id, record.apexScanId, record.bedrockScanId);
     if (!scanId) {
         return null;
     }
     return {
         scanId,
-        kernelScanId: readString(record.kernelScanId, record.kernel_scan_id),
         apexScanId: readString(record.apexScanId, record.apex_scan_id),
         bedrockScanId: readString(record.bedrockScanId, record.bedrock_scan_id),
         displayName: readString(record.displayName, record.display_name, record.name),
@@ -75,6 +95,29 @@ function normalizeScanRecord(payload) {
         finishedAt: readTimestamp(record, "finishedAt", "finished_at", "completedAt", "completed_at", "cancelledAt", "cancelled_at"),
     };
 }
+export function normalizeScanStartResponse(payload) {
+    const record = asRecord(stripKernelScanIdentifiers(payload));
+    if (!record) {
+        throw new Error("Scan response was not a JSON object.");
+    }
+    const scanId = readString(record.apexScanId, record.apex_scan_id, record.bedrockScanId, record.bedrock_scan_id, record.scanId, record.scan_id);
+    const workspaceId = readString(record.workspaceId, record.workspace_id);
+    const apexScanId = readString(record.apexScanId, record.apex_scan_id);
+    const bedrockScanId = readString(record.bedrockScanId, record.bedrock_scan_id);
+    const scanUrl = readString(record.scanUrl, record.scan_url);
+    const fullScanRecommended = readBoolean(record.fullScanRecommended);
+    const fullScanRecommendation = readString(record.fullScanRecommendation);
+    return {
+        ...(workspaceId ? { workspaceId } : {}),
+        ...(scanId ? { scanId } : {}),
+        ...(apexScanId ? { apexScanId } : {}),
+        ...(bedrockScanId ? { bedrockScanId } : {}),
+        status: readString(record.status) ?? "unknown",
+        ...(scanUrl ? { scanUrl } : {}),
+        ...(fullScanRecommended !== null ? { fullScanRecommended } : {}),
+        ...(fullScanRecommendation ? { fullScanRecommendation } : {}),
+    };
+}
 async function requestWithFallbacks(client, attempts) {
     let lastApiError = null;
     for (const attempt of attempts) {
@@ -95,7 +138,7 @@ async function requestWithFallbacks(client, attempts) {
     throw new Error("No scan routes were available.");
 }
 export function getTrackedScanId(scan) {
-    const trackedScanId = readString(scan.apexScanId, scan.bedrockScanId, scan.scanId, scan.kernelScanId);
+    const trackedScanId = readString(scan.apexScanId, scan.bedrockScanId, scan.scanId);
     if (!trackedScanId) {
         throw new Error("Scan response did not include an Apex scan id.");
     }
@@ -129,7 +172,6 @@ function mergeScanProgress(scan, progress) {
         : scan.finishedAt;
     return {
         ...scan,
-        kernelScanId: progress.kernelScanId ?? scan.kernelScanId,
         status,
         startedAt,
         finishedAt,
@@ -152,7 +194,7 @@ export function findMostRelevantActiveScan(scans) {
     return scans.find((scan) => isActiveScanStatus(scan.status)) ?? null;
 }
 export function matchesScanId(scan, scanId) {
-    return [scan.scanId, scan.apexScanId, scan.bedrockScanId, scan.kernelScanId].includes(scanId);
+    return [scan.scanId, scan.apexScanId, scan.bedrockScanId].includes(scanId);
 }
 export function selectDefaultScanToCancel(scans, lastScanId) {
     const activeScans = scans.filter((scan) => isActiveScanStatus(scan.status));
@@ -179,7 +221,8 @@ export async function fetchWorkspaceScans(client, workspaceId) {
     return Promise.all(scans.map((scan) => reconcileActiveScanStatus(client, scan)));
 }
 export async function fetchScanProgress(client, scanId) {
-    return client.request(`/api/cli/v1/scans/${encodeURIComponent(scanId)}/progress`);
+    const response = await client.request(`/api/cli/v1/scans/${encodeURIComponent(scanId)}/progress`);
+    return stripKernelScanIdentifiers(response);
 }
 export async function cancelScan(client, scanId) {
     const encodedScanId = encodeURIComponent(scanId);
@@ -205,7 +248,6 @@ export async function cancelScan(client, scanId) {
     }
     return {
         scanId,
-        kernelScanId: null,
         apexScanId: null,
         bedrockScanId: null,
         displayName: null,

package/dist/service-key-environment.js

@@ -14,9 +14,9 @@ export function getServiceKeyCliAuthGuidance(env = process.env) {
         return null;
     }
     const legacyVariableGuidance = variableName === "APEX_API_KEY"
-        ? " For REST API examples, rename APEX_API_KEY to APEX_SERVICE_KEY."
+        ? " For hosted MCP and REST examples, rename APEX_API_KEY to APEX_SERVICE_KEY."
         : "";
-    return (`Apex service key detected in ${variableName}, but service keys authenticate the hosted REST API, not the Apex CLI. ` +
-        "Use `apex login` for CLI device authentication, or use the REST API for a headless/service-account integration: https://ai.cantina.xyz/docs/apex-api." +
+    return (`Apex service key detected in ${variableName}, but service keys authenticate the hosted MCP and REST endpoints, not the local Apex CLI. ` +
+        "Use `apex login` for local CLI device authentication, or use https://ai.cantina.xyz/mcp or the REST API for a headless/service-account integration: https://ai.cantina.xyz/docs/apex-api." +
         legacyVariableGuidance);
 }