@cantinasecurity/apex-cli 0.1.28 → 0.1.34

package/.claude/skills/apex-cli/SKILL.md

@@ -13,7 +13,7 @@ This skill is bundled with Apex CLI and can be installed into the current reposi
 
 Use Apex through the MCP server when the `apex-*` tools are 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.
 
@@ -54,6 +54,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - A trial redeem with an ambiguous transport or response-loss failure may be retried exactly once with the same code, machine, HOME, and repository root. Never retry a typed server rejection or use `--replace` for response-loss recovery.
 - 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.
 - After a successful scan JSON response, inspect `localPersistence.workspaceBindingSaved`. If it is `false`, the server scan already started: capture and report `binding.lastScanId`, then STOP; do not run status or findings until local repository permissions are repaired.
+- Shared Standard-scan codes may be custom names such as `TEST100` (1-64 letters, numbers, underscores, or hyphens). Use CLI 0.1.34 or newer. One redemption provides either a guest Standard scan or 100% off one 200-credit checkout package, sharing the same cap. Never redeem both paths with a one-use code. Legacy `APEX-...` and `SPBT-...` codes remain accepted. Do not repeat the real code in output.
 - `apex-trial-status` is MCP-only; do not invoke it as a CLI command. In a CLI-only flow, use the `claimDeadline` returned by `apex redeem <code> --json` without repeating or persisting the secret code.
 - After a guest scan, tell the user to run `apex claim` on the same machine before that returned claim deadline. If the deadline is unavailable or uncertain, do not guess or start a replacement login; run `apex claim` and let the server validate the proof.
 - Claim moves the guest workspace, scans, and findings into the currently selected Cantina workspace when the account can run scans there. Personal workspace owners receive the trial in their existing workspace instead of a duplicate. If the selected workspace cannot run scans, tell the user to switch to one that can and retry before the claim deadline.
@@ -78,6 +79,7 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - `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` or `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.
 - 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. In CLI-only flows, use `apex findings --workspace --company <handle> --workspace-ref <ref> --finding-state open`.
 - 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.
 - Finding comments, feedback, and fix review scan starts use the same Apex device-login credentials as read tools. If a write tool reports missing auth, re-run `apex-auth-status`, check `apex-trial-status`, and complete `apex-auth-start` / `apex-auth-wait` only when no unexpired local claim proof is available. Never ask for browser cookies or `CANTINA_AUTH_TOKEN`; an error requiring that variable proves the MCP server is outdated, so update Apex CLI, re-run `apex setup <client>`, restart the client, and retry.
@@ -99,3 +101,18 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - Review all open workspace findings: call `apex-workspaces` with the company, then call `apex-workspace-findings` with the selected `workspaceRef` and `findingState: "open"`.
 - Leave review feedback: call `apex-finding-comment` to add a note, or `apex-finding-feedback` with `status` set to `valid` or `invalid`.
 - Run a Fix PR review: call `apex-finding-fix-review` with `fixPrUrls`, optionally after recording fixed feedback with `apex-finding-feedback`.
+
+## 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.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Cantina agent plugins for security review workflows.",
-    "version": "0.1.28"
+    "version": "0.1.34"
   },
   "plugins": [
     {
@@ -14,10 +14,10 @@
       "source": {
         "source": "npm",
         "package": "@cantinasecurity/apex-cli",
-        "version": "0.1.28"
+        "version": "0.1.34"
       },
       "description": "Run Apex security scans and review findings from Claude Code.",
-      "version": "0.1.28",
+      "version": "0.1.34",
       "author": {
         "name": "Cantina",
         "email": "support@cantina.xyz"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.28",
+  "version": "0.1.34",
   "description": "Run Apex security scans and review findings from Claude Code.",
   "author": {
     "name": "Cantina",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.28",
+  "version": "0.1.34",
   "description": "Run Apex security scans and review findings from Codex.",
   "author": {
     "name": "Cantina",

package/.mcp.claude.json

@@ -5,7 +5,7 @@
       "args": [
         "-y",
         "-p",
-        "@cantinasecurity/apex-cli@0.1.28",
+        "@cantinasecurity/apex-cli@0.1.34",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.28",
+      "@cantinasecurity/apex-cli@0.1.34",
       "apex-mcp"
     ],
     "env": {

package/MARKETPLACE.md

@@ -13,7 +13,7 @@ This package is prepared as both a Claude Code plugin and a Codex plugin. The pu
 The plugin MCP configs launch the pinned npm CLI package with:
 
 ```bash
-npx -y -p @cantinasecurity/apex-cli@0.1.28 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.34 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -93,13 +93,19 @@ APEX_BASE_URL=https://bedrock.customer.example pnpm apex
 
 ## Try Apex With A Trial Code
 
+Shared Standard-scan codes (including custom names such as `TEST100`) work with
+Apex CLI 0.1.34 or newer. They provide either one guest Standard scan or 100% off
+one 200-credit checkout package. Both paths share the code's redemption limit;
+a one-use code cannot fund both. Previously issued `APEX-...` and `SPBT-...` codes
+remain accepted. Code eligibility and remaining uses are checked by Bedrock.
+
 A Cantina-issued trial code can start a temporary guest scan without a Cantina
 account, browser, or device login. Redeem it from the repository root, run the
 normal scan lifecycle, and create a Cantina account only after reviewing the
 findings:
 
 ```bash
-apex redeem SPBT-DEVREL-XXXXXXXX --json
+apex redeem <code> --json
 apex scan --non-interactive --json
 apex status --json
 apex findings --json
@@ -152,30 +158,30 @@ unclaimed local trial proof so `apex claim` can still use it.
 Agent-safe copy/paste prompt (substitute the issued code):
 
 ```text
-Install and run Cantina Apex CLI 0.1.28 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.34 to start one free standard security scan of this repository immediately.
 
 Use this trial code only where <TRIAL_CODE> appears below: SPBT-DEVREL-XXXXXXXX
 
 Run the commands yourself from the repository root; do not stop after setup or only explain the steps. Use terminal CLI commands only. Do not use an Apex MCP tool or run `apex setup`, `apex mcp`, `apex login`, `apex-auth-start`, or `apex-auth-wait`. Never use `--replace` or `--force`.
 
 Use this exact command prefix for every Apex command:
-  npx -y -p @cantinasecurity/apex-cli@0.1.28 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.34 apex
 
 1. Before redeeming, confirm every command will use the same persistent, user-accessible machine or container, HOME, filesystem, and repository root. Confirm Node.js 20+ and npx are available. If `APEX_BASE_URL` is set, continue only when its origin is `https://ai.cantina.xyz`. Run the exact prefix with `--help` and continue only if help lists both `redeem` and `claim`. If any check fails, STOP before sending the code; do not install system packages.
 2. Redeem, with at most one response-loss recovery retry:
-     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.34 apex redeem <TRIAL_CODE> --json
    This terminal command is the only allowed tool call containing the code. Never echo or restate the code, store it in a file or environment variable, put it in a URL or MCP call, or include it in your response. Parse the JSON from stdout only; do not merge stderr into stdout, because npm may write warnings to stderr. Continue when the command exits 0 and stdout is JSON with `redeemed: true` and `outcome` equal to `redeemed` or `idempotent`. `idempotent` means the existing guest session resumed and it may already own a workspace. If and only if the first attempt ends with an ambiguous transport/connection failure or an interrupted/missing response and no typed server error code, retry this exact same command once on the same machine, HOME, and repository root. Never retry a typed server rejection and never make more than one recovery retry. If the allowed retry does not return a successful JSON outcome, STOP.
 3. Immediately start exactly one scan; do not wait for another instruction:
-     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.34 apex scan --mode standard --non-interactive --no-open --json
    The CLI validates the complete guest local archive before it reserves a workspace. An unbound renamed checkout may recover only the sole empty guest workspace when no explicit workspace name was supplied. On any error or nonzero exit, STOP. After a successful scan JSON response, inspect `localPersistence.workspaceBindingSaved`. If it is `false`, the server scan already started: capture and report `binding.lastScanId`, then STOP; do not run status or findings until local repository permissions are repaired. Otherwise capture `binding.lastScanId` from the JSON as <SCAN_ID>; if it is absent, STOP.
 4. About every 60 seconds, poll that exact scan:
-     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.34 apex status --scan <SCAN_ID> --json
    Read `progress.progress.status`. Wait while it is `created`, `pending`, `queued`, `starting`, `running`, `in_progress`, or `processing`. Continue on `completed`. STOP on `failed`, `cancelled`, a missing or unknown status, or a command failure.
 5. Fetch that exact scan's findings:
-     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.34 apex findings --scan <SCAN_ID> --json
    On success, summarize findings by severity, most severe first, including identifier, title, status, and confidence. This command does not return file locations, so do not invent them. On failure, STOP.
 6. Do not claim automatically. Tell me the claim deadline from step 2 and remind me to run this exact command myself from the same repository root, machine, and HOME:
-     npx -y -p @cantinasecurity/apex-cli@0.1.28 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.34 apex claim
    It may open a browser so I can create or sign in to a Cantina account and keep the results. Claim moves the trial into the currently selected Cantina workspace when I can run scans there, or into my existing personal workspace. If the selected workspace cannot run scans, tell me to switch to one that can and retry before the claim deadline.
 
 Never paste raw command transcripts. For any failure, report only the step, exit code, and sanitized error. Redact the trial code and every `apex_at_`, `apex_rt_`, or `apex_ct_` value from all reports.
@@ -212,6 +218,9 @@ Supported shell commands:
 - `/scans`
 - `/findings [scan-id]`
 - `/findings workspace [filter...]`
+- `/findings tickets <finding-ref>`
+- `/findings send <finding-ref> <linear|jira>`
+- `/findings link-ticket <finding-ref> <linear|jira> <issue-key|url>`
 - `/findings comment <finding-id|finding-identifier> <comment>`
 - `/findings feedback <finding-id|finding-identifier> valid [comment]`
 - `/findings feedback <finding-id|finding-identifier> invalid <false-positive|by-design|not-relevant> [comment]`
@@ -247,6 +256,9 @@ Supported shell commands:
 - `apex scans`
 - `apex findings [--scan <scan-id>]`
 - `apex findings --workspace [--company <handle>] [--workspace-ref <name|prefix|id>] [--finding-state all|open] [--filter <[!]facet:value>]`
+- `apex findings tickets <finding-ref> [--scan <scan-id>] [--json]`
+- `apex findings send <finding-ref> <linear|jira> [--scan <scan-id>] [--json]`
+- `apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url> [--scan <scan-id>] [--json]`
 - `apex findings comment <finding-id|finding-identifier> --content <markdown> [--parent-comment <comment-id>] [--scan <scan-id>]`
 - `apex findings feedback <finding-id|finding-identifier> <valid|invalid> [comment] [--comment <markdown>] [--scan <scan-id>] [--suggested-severity extreme|critical|high|medium|low|informational] [--dismissal-reason false-positive|by-design|not-relevant] [--label acknowledged|fixed] [--fix-pr-url <github-pr-url>]`
 - `apex findings fix-review <finding-id|finding-identifier> [--scan <scan-id>] [--review-target pull-request|repository-current] [--fix-pr-url <github-pr-url>]`
@@ -296,7 +308,7 @@ The CLI automatically uses your company when only one is available. If you belon
 
 The secret is returned only by `create` and cannot be retrieved later. Store it directly in a secret manager and do not put it in source control, prompts, chat messages, or logs. `--json` also includes the shown-once secret so it can be captured programmatically; handle that output as a credential.
 
-Service keys are organization-level credentials. Grant only the scopes the integration needs: `scans:create` reads credit availability and triggers scans, `scans:read` polls status, and `findings:read` retrieves findings. Omit `--scope` to grant all three scopes. For a P1-only adapter that reads manually started scans, create a read-only key with `--scope scans:read,findings:read`.
+Service keys are organization-level credentials. Grant only the scopes the integration needs: `scans:create` reads credit availability and triggers scans, `scans:read` polls status, and `findings:read` retrieves findings. Omit `--scope` to grant those three default scopes. Ticket linking additionally requires explicitly requesting `findings:write`. For a P1-only adapter that reads manually started scans, create a read-only key with `--scope scans:read,findings:read`.
 
 A key with `findings:read` can retrieve unpublished draft findings for scans in its organization so an external hub can perform triage. Give the key only to systems that are allowed to handle those drafts.
 
@@ -340,7 +352,7 @@ Claude Code can expand the same environment variable from `.mcp.json`:
 }
 ```
 
-The hosted server exposes `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-status`, `apex-cancel-scan`, `apex-findings`, and `apex-workspace-findings`. It operates only on repositories and workspaces available to the service key's organization. Use local stdio MCP for device auth, local filesystem/archive access, provider connection, setup, comments, feedback, fix reviews, and trial flows.
+The hosted server exposes `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`. Ticket creation and linking require an explicit `findings:write` scope and a connected Linear/Jira integration. It operates only on repositories and workspaces available to the service key's organization. Use local stdio MCP for device auth, local filesystem/archive access, provider connection, setup, comments, feedback, fix reviews, and trial flows.
 
 ### Hosted REST API
 
@@ -423,6 +435,29 @@ The matching MCP flow is `apex-finding-fix-review` with optional `fixPrUrls`. Ag
 
 The matching CLI and MCP flows intentionally use the same device-login session so agents should not ask users to paste browser cookies or auth tokens.
 
+Send a finding to Linear or Jira to create a ticket, just as in the frontend:
+
+```bash
+apex findings send KERN2-25 linear --json
+apex findings send KERN2-25 jira --json
+```
+
+Connect the integration and configure its destination in Apex first. Sending uses the same finding title, details, severity, Apex link, and saved routing as the frontend: workspace Linear project/labels (or the company default), or the workspace Jira site/project/issue type. The response contains `created` and `export` with the ticket key and URL. Already sent or linked findings return their existing ticket with `created: false`; active exports return a conflict. If a send times out, inspect `apex findings tickets` and the provider before retrying; the CLI never automatically repeats an uncertain creation.
+
+Local MCP exposes `apex-finding-send` with `findingRef`, `provider`, and optional `cwd`/`scanId`. Hosted MCP uses `findingId` (UUID) and `provider`, with explicit `findings:write`. REST clients call `POST /api/apex/v1/findings/{findingId}/issue-trackers/{provider}` with no body. Provider is `linear` or `jira`. These paths all reuse the frontend's ticket-creation service.
+
+Link an existing ticket after connecting Linear or Jira in company settings:
+
+```bash
+apex findings link-ticket KERN2-25 linear SEC-123 --json
+apex findings link-ticket KERN2-25 jira https://acme.atlassian.net/browse/SEC-123 --json
+apex findings tickets KERN2-25 --json
+```
+
+Use a finding UUID directly, or resolve its identifier/URL from the bound workspace and optional `--scan`. Ticket keys and HTTPS issue URLs are accepted; Linear also accepts an issue UUID. When Jira has several accessible sites, use a full issue URL or configure the workspace destination. Apex verifies the ticket through the company's existing integration and uses the same link shown in the frontend. One ticket per provider can be linked to a finding. Repeating the same link is safe; a different existing link or an in-progress export returns a conflict. This operation does not create or modify provider tickets.
+
+Local MCP exposes `apex-finding-link-ticket` with `findingRef`, `provider`, `issueRef`, and optional `cwd`/`scanId`; `apex-finding-tickets` lists links. Both use device login. Hosted MCP exposes the same tool names with `findingId` (the finding UUID), without local filesystem arguments. Hosted writes require the explicit `findings:write` scope; reads require `findings:read`. Existing keys and omitted-scope defaults retain the original three scopes. Create a dedicated key in your own terminal with `apex service-key create --name "Ticket linking" --scope findings:read,findings:write` and keep the secret in your secret manager. REST clients use `GET`/`POST /api/apex/v1/findings/{findingId}/tickets`; POST accepts `{"provider":"linear","issueRef":"SEC-123"}`.
+
 ## Local Source Scans
 
 `apex scan` now works against any local source root you point it at. By default, that source root is the current working directory:
@@ -447,6 +482,8 @@ Lite scans use `lite` as the scan mode and require the Lite Scan beta feature pl
 
 PR scans require exactly one provider-backed GitHub repository. If the current directory resolves to multiple sources, pass `--repo <path>` to select the one that contains the pull request.
 
+CLI and MCP scan results use the public Bedrock `scanId`. Kernel execution IDs are internal implementation details and are neither returned nor accepted as scan aliases.
+
 ## LLM / MCP Usage
 
 Apex has two MCP transports:
@@ -560,6 +597,8 @@ The local stdio MCP server exposes Apex-specific tools for:
 - Lite scan start by calling `apex-scan` with `mode: "lite"`
 - PR scan start by calling `apex-scan` with `mode: "pr"` and `pullRequests`
 - finding comments and valid/invalid feedback with `apex-finding-comment` and `apex-finding-feedback`
+- Create Linear/Jira tickets with `apex-finding-send` using the saved frontend destination
+- Link existing Linear/Jira tickets with `apex-finding-link-ticket` and inspect links with `apex-finding-tickets`
 - Fix PR and current-repository fix review scans with `apex-finding-fix-review`, optionally after `apex-finding-feedback`
 
 Neither MCP surface exposes trial redemption, trial claim, or service-key creation, listing, or revocation as tools. When a user supplies a Cantina trial code, run `apex redeem <code>` in a terminal instead of starting device login or putting the code in an MCP call. Production MCP clients should connect to `https://ai.cantina.xyz/mcp`; HTTP applications can use the [hosted Apex REST API](https://ai.cantina.xyz/docs/apex-api) directly. Do not launch the local stdio server as an HTTP adapter.
@@ -624,7 +663,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.28",
+      "cliVersion": "0.1.34",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -655,7 +694,7 @@ The npm package also includes marketplace-ready plugin artifacts:
 - `.claude-plugin/plugin.json` and `.mcp.claude.json` for Claude Code plugin installs
 - `.claude-plugin/marketplace.json` for a Claude marketplace entry backed by the public npm package
 
-These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.28 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
+These plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.34 apex-mcp`, so users do not need to install `apex` globally before enabling the plugin.
 
 The repository also includes `.agents/plugins/marketplace.json` for local Codex marketplace testing from a checkout.
 

package/dist/apex.js

@@ -1,21 +1,24 @@
+import { commandStartThreatModel, commandThreatModel, hasAuditSetupBeta, threatModelExitCode, terminalText } from "./threat-model.js";
+import { getMe } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.js";
-import { parseArgs, validateCommandFlags } from "./args.js";
-import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandLogin, commandLogout, commandRedeem, commandScan, commandScans, commandServiceKeyCreate, commandServiceKeyList, commandServiceKeyRevoke, commandSetup, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, getRedeemExitCode, } from "./commands.js";
-import { CLI_HELP_TEXT } from "./help.js";
+import { isAuditSetupInvocation, parseArgs, validateCommandFlags } from "./args.js";
+import { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingTickets, commandFindingLinkTicket, commandFindingSend, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandLogin, commandLogout, commandRedeem, commandScan, commandScans, commandServiceKeyCreate, commandServiceKeyList, commandServiceKeyRevoke, commandSetup, commandStatus, commandTelemetry, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, getRedeemExitCode, } from "./commands.js";
+import { cliHelpText } from "./help.js";
 import { runMcpServer } from "./mcp.js";
 import { runInteractiveShell } from "./shell.js";
 import { createCliTelemetryInvocation, emitInvocationCompleted, emitInvocationStarted, withTelemetryContext, } from "./telemetry.js";
 import { maybePromptForUpdate } from "./update.js";
 async function dispatch(parsed) {
+    const client = new ApexApiClient();
     if (parsed.flags.help === true || parsed.command === "help") {
-        process.stdout.write(CLI_HELP_TEXT);
+        const me = await getMe(client, { signal: AbortSignal.timeout(1_500) }).catch(() => null);
+        process.stdout.write(cliHelpText(hasAuditSetupBeta(me)));
         return;
     }
     if (parsed.command === "mcp") {
         await runMcpServer();
         return;
     }
-    const client = new ApexApiClient();
     const cwd = process.cwd();
     if (await maybePromptForUpdate(parsed.flags, parsed.command)) {
         return;
@@ -25,7 +28,13 @@ async function dispatch(parsed) {
             await runInteractiveShell(client, cwd, parsed.flags);
             return;
         case "scan":
-            await commandScan(client, cwd, parsed.flags);
+            if (parsed.flags.setup !== undefined)
+                await commandStartThreatModel(client, cwd, parsed.flags);
+            else
+                await commandScan(client, cwd, parsed.flags);
+            return;
+        case "threat-model":
+            await commandThreatModel(client, cwd, parsed.flags, parsed.subcommand);
             return;
         case "scans":
             await commandScans(client, cwd, parsed.flags);
@@ -94,6 +103,24 @@ async function dispatch(parsed) {
             await commandWorkspace(cwd, parsed.flags);
             return;
         case "findings":
+            if (parsed.subcommand === "send") {
+                if (parsed.args.length !== 2)
+                    throw new Error("Usage: apex findings send <finding-ref> <linear|jira>");
+                await commandFindingSend(client, cwd, parsed.flags, parsed.args[0], parsed.args[1]);
+                return;
+            }
+            if (parsed.subcommand === "tickets") {
+                if (parsed.args.length !== 1)
+                    throw new Error("Usage: apex findings tickets <finding-ref>");
+                await commandFindingTickets(client, cwd, parsed.flags, parsed.args[0]);
+                return;
+            }
+            if (parsed.subcommand === "link-ticket") {
+                if (parsed.args.length !== 3)
+                    throw new Error("Usage: apex findings link-ticket <finding-ref> <linear|jira> <issue-key|url>");
+                await commandFindingLinkTicket(client, cwd, parsed.flags, parsed.args[0], parsed.args[1], parsed.args[2]);
+                return;
+            }
             if (parsed.subcommand === "comment") {
                 const findingRef = parsed.args[0] ?? "";
                 const content = parsed.args.slice(1).join(" ").trim() || String(parsed.flags.content ?? "");
@@ -152,8 +179,10 @@ async function dispatch(parsed) {
             throw new Error(`Unknown command: ${parsed.command}`);
     }
 }
+let parsedInvocation = null;
 async function main() {
     const parsed = parseArgs(process.argv.slice(2));
+    parsedInvocation = parsed;
     validateCommandFlags(parsed);
     const invocation = createCliTelemetryInvocation(parsed);
     emitInvocationStarted(invocation);
@@ -184,6 +213,10 @@ main().catch((error) => {
         process.exitCode = 1;
         return;
     }
-    process.stderr.write(`${formatApiError(error)}\n`);
-    process.exitCode = 1;
+    const setupCommand = isAuditSetupInvocation(parsedInvocation);
+    if (setupCommand && process.argv.includes("--json"))
+        process.stdout.write(`${JSON.stringify({ error: formatApiError(error), exitCode: threatModelExitCode(error) })}\n`);
+    else
+        process.stderr.write(`${setupCommand ? terminalText(formatApiError(error)) : formatApiError(error)}\n`);
+    process.exitCode = setupCommand ? threatModelExitCode(error) : 1;
 });

package/dist/args.js

@@ -1,4 +1,14 @@
 export const KNOWN_CLI_FLAG_NAMES = [
+    "setup",
+    "draft",
+    "file",
+    "sha256",
+    "request-id",
+    "wait",
+    "timeout",
+    "start-scan",
+    "no-feedback-context",
+    "attachment",
     "comment",
     "company",
     "content",
@@ -35,6 +45,7 @@ export const KNOWN_CLI_FLAG_NAMES = [
 ];
 const KNOWN_CLI_FLAGS = new Set(KNOWN_CLI_FLAG_NAMES);
 const BOOLEAN_FLAGS = new Set([
+    "wait", "start-scan", "no-feedback-context",
     "force",
     "non-interactive",
     "json",
@@ -44,6 +55,7 @@ const BOOLEAN_FLAGS = new Set([
     "help",
 ]);
 const REPEATABLE_VALUE_FLAGS = new Set([
+    "attachment",
     "repo",
     "pr",
     "pr-path",
@@ -96,10 +108,14 @@ export function validateCommandFlags(parsed) {
     const isWorkspaceFindings = parsed.command === "findings" &&
         parsed.subcommand === null &&
         parsed.flags.workspace === true;
-    if (!isWorkspaceFindings) {
+    const isSetupScan = parsed.command === "scan" && parsed.flags.setup !== undefined;
+    if (!isWorkspaceFindings && !isSetupScan) {
         throw new Error("--workspace-ref is only supported with `apex findings --workspace`. To change the local workspace used by scans or exports, run `apex workspace use <workspace-ref>` first.");
     }
 }
+export function isAuditSetupInvocation(parsed) {
+    return (parsed?.command === "threat-model" || parsed?.flags.setup !== undefined);
+}
 export function isJsonMode(flags) {
     return flags.json === true;
 }

package/dist/auth.js

@@ -78,9 +78,9 @@ async function waitForDeviceLoginCredentials(client, options) {
         expiresAt,
     };
 }
-export async function getMe(client) {
+export async function getMe(client, options = {}) {
     try {
-        return await client.request("/api/cli/v1/me");
+        return await client.request("/api/cli/v1/me", options);
     }
     catch (error) {
         if (error instanceof ApiError && error.status === 401) {

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" });
 }