@cantinasecurity/apex-cli 0.1.37 → 0.1.38

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-black-start`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, and `apex-finding-send`.
+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-black-start`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, `apex-finding-send`, and `apex-finding-status`.
 
 OAuth-capable clients may instead use the hosted endpoint’s OAuth discovery and Cantina manager-consent flow. Let the client manage OAuth credentials; never pass them to tools, the REST API, or local CLI. Local stdio MCP continues to use device login.
 
@@ -160,3 +160,12 @@ Scan target and recovery rules:
 - Use Standard for local changes, files, plain directories, and public repositories without provider access. Lite and Audit still require connected provider sources; do not silently substitute another mode.
 - Unauthenticated headless CLI commands fail with explicit login guidance; they never start device login. Use the MCP auth tools for explicit MCP login. Retry transient refresh failures without clearing credentials.
 - Audit Setup is an explicit Standard/Audit beta flow using saved workspace repositories and context. It does not preserve local targets. Never automatically substitute setup after `AUDIT_SETUP_REQUIRED`; use the error's selected-workspace command only when that saved scope is intended. Draft operations require the ID returned by preparation; eligible accounts receive setup commands in CLI help. Lite and PR do not use `--setup`.
+
+Finding lifecycle:
+- Close resolved issues with `apex-finding-status` and `status: "fixed"`; reopen with `status: "open"`.
+- Local MCP takes `findingRef`, optional `cwd`/`scanId`, `note`, and `expectedUpdatedAt`, using device login. Hosted MCP takes `findingId` (UUID), no local paths, and requires explicit `findings:write`.
+- The scripted equivalent is `apex findings status <finding-ref> <open|fixed> --note "rationale" --json`. Other statuses: acknowledged, in_review, pending_merge, false_positive, wont_fix, skipped.
+- Status changes preserve scanner validity, severity, feedback, and linked ticket state. Invalid or duplicate findings cannot be reopened into the open queue until their classification is reviewed.
+- Read `remediationStatus` in workspace finding lists for the current lifecycle; `status` remains the scanner verdict. `open` and `acknowledged` stay distinct even though both use the `accepted` review state.
+- Use the finding updatedAt as expectedUpdatedAt when working from a prior snapshot. On FINDING_STATUS_CONFLICT, reload and review before retrying.
+- Linear sync is Linear-to-Apex: started becomes acknowledged, completed becomes fixed. Do not promise Apex-to-Linear status updates or automatic Linear reopening.

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apex-cli",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "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.37",
+  "version": "0.1.38",
   "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.37",
+        "@cantinasecurity/apex-cli@0.1.38",
         "apex-mcp"
       ],
       "env": {

package/.mcp.codex.json

@@ -4,7 +4,7 @@
     "args": [
       "-y",
       "-p",
-      "@cantinasecurity/apex-cli@0.1.37",
+      "@cantinasecurity/apex-cli@0.1.38",
       "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.37 apex-mcp
+npx -y -p @cantinasecurity/apex-cli@0.1.38 apex-mcp
 ```
 
 That keeps marketplace installs independent of a user's global `apex` install.

package/README.md

@@ -158,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.37 to start one free standard security scan of this repository immediately.
+Install and run Cantina Apex CLI 0.1.38 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.37 apex
+  npx -y -p @cantinasecurity/apex-cli@0.1.38 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.37 apex redeem <TRIAL_CODE> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.38 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.37 apex scan --mode standard --non-interactive --no-open --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.38 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.37 apex status --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.38 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.37 apex findings --scan <SCAN_ID> --json
+     npx -y -p @cantinasecurity/apex-cli@0.1.38 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.37 apex claim
+     npx -y -p @cantinasecurity/apex-cli@0.1.38 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.
@@ -222,6 +222,7 @@ Supported shell commands:
 - `/findings send <finding-ref> <linear|jira>`
 - `/findings link-ticket <finding-ref> <linear|jira> <issue-key|url>`
 - `/findings comment <finding-id|finding-identifier> <comment>`
+- `/findings status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped> [note]`
 - `/findings feedback <finding-id|finding-identifier> valid [comment]`
 - `/findings feedback <finding-id|finding-identifier> invalid <false-positive|by-design|not-relevant> [comment]`
 - `/findings fix-review <finding-id|finding-identifier>`
@@ -260,6 +261,7 @@ Supported shell commands:
 - `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 status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped> [--note <rationale>] [--expected-updated-at <timestamp>] [--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>]`
 - `apex export findings [--scan <scan-id>] [--format markdown|json|gitlab-sast] [--output <path>]`
@@ -310,7 +312,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 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`.
+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. Finding status changes and ticket management additionally require 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.
 
@@ -356,7 +358,7 @@ Claude Code can expand the same environment variable from `.mcp.json`:
 }
 ```
 
-The hosted server exposes `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-black-start`, `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. Hosted operations are scoped to the authenticated organization. Repository scans use connected GitHub repositories; Apex Black scans use explicitly authorized HTTPS origins. 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-black-start`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, `apex-finding-send`, and `apex-finding-status`. Ticket creation and linking require an explicit `findings:write` scope and a connected Linear/Jira integration. Hosted operations are scoped to the authenticated organization. Repository scans use connected GitHub repositories; Apex Black scans use explicitly authorized HTTPS origins. Use local stdio MCP for device auth, local filesystem/archive access, provider connection, setup, comments, feedback, fix reviews, and trial flows.
 
 Apex Black is hosted-only: use `apex-black-start` when the connected deployment advertises it and the organization has Apex Black beta access. Check `apex-credits` first. Supply 1–16 exact HTTPS origins, a stable `idempotencyKey`, and `authorizationAccepted: true` only when the user has authorized every target and accepted the 200 Standard credit cost; honor authorization already provided in the session. Use the returned Bedrock `scanId` with `apex-status` and `apex-findings`. An identical retry replays a stored start failure, including `APEX_BLACK_START_FAILED`; retain its durable IDs and contact support before trying another request. Local CLI and stdio MCP do not expose this web-scan tool or a Black scan mode.
 
@@ -617,6 +619,7 @@ The local stdio MCP server exposes Apex-specific tools for:
 - cross-scan workspace findings through `apex-workspace-findings`, including direct workspace selection, first-class open state, web UI lifecycle fields, and server-side filters
 - Lite scan start by calling `apex-scan` with `mode: "lite"`
 - PR scan start by calling `apex-scan` with `mode: "pr"` and `pullRequests`
+- close/reopen findings with `apex-finding-status`, preserving scanner validity and feedback
 - 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`
@@ -684,7 +687,7 @@ Telemetry event posts do not include bearer tokens. The telemetry endpoint is `P
     {
       "schemaVersion": 1,
       "event": "apex.invocation.completed",
-      "cliVersion": "0.1.37",
+      "cliVersion": "0.1.38",
       "invocation": {
         "surface": "mcp",
         "command": "apex-scan",
@@ -715,7 +718,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.37 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.38 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.
 
@@ -785,3 +788,35 @@ Keep `policy.version` at `3.1`. Supply a name, instructions, and all eight metri
 allowed value and nonempty guidance for each allowed value. Omit disallowed
 values. If Audit Setup or another workspace update is active, wait for it to
 finish before saving again.
+
+### Close and reopen findings
+
+Use `apex-finding-status` to manage remediation directly from either MCP transport.
+Local MCP accepts `findingRef` and optional `cwd`/`scanId` using device login.
+Hosted MCP accepts `findingId` (UUID) and requires explicitly granted `findings:write`.
+Pass `status: "fixed"` to close an issue or `status: "open"` to reopen it.
+
+```sh
+apex findings status KERN2-25 fixed --note "Resolved in PR #123" --json
+apex findings status KERN2-25 open --note "Regression reproduced" --json
+```
+
+Other statuses are `acknowledged`, `in_review`, `pending_merge`, `false_positive`,
+`wont_fix`, and `skipped`. Reopening stores `accepted`, retaining the fact that the
+finding was reviewed. Status changes preserve scanner validity, severity, and
+valid/invalid feedback; invalid or duplicate findings must have their classification
+reviewed before they can enter the open queue.
+
+REST integrations call `PATCH /api/apex/v1/findings/{findingId}/status` with
+`{"status":"fixed","note":"Resolved in PR #123"}` and a bearer service key with
+`findings:write`. Each change is audited. The response includes `findingId`,
+`status`, `reviewState`, `fromReviewState`, `updatedAt`, and `changed`.
+Workspace finding lists expose `remediationStatus`, keeping `open` and `acknowledged`
+distinct from the scanner `status` and the persisted `reviewState`.
+Pass the current finding `updatedAt` as `expectedUpdatedAt` (CLI:
+`--expected-updated-at`) to reject stale edits with `FINDING_STATUS_CONFLICT` (409).
+Reload and review the latest state before retrying a conflict.
+
+Linear sync currently runs from Linear to Apex: started tickets become acknowledged
+and completed tickets become fixed. Apex status changes do not update linked Linear
+or Jira tickets. Use the direct status operation to manage issues from MCP or REST.

package/dist/apex.js

@@ -3,7 +3,7 @@ import { commandStartThreatModel, commandThreatModel, hasAuditSetupBeta, threatM
 import { getMe } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.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 { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingStatus, 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";
@@ -109,6 +109,12 @@ async function dispatch(parsed) {
             await commandWorkspace(cwd, parsed.flags);
             return;
         case "findings":
+            if (parsed.subcommand === "status") {
+                if (parsed.args.length !== 2)
+                    throw new Error("Usage: apex findings status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped> [--note <rationale>]");
+                await commandFindingStatus(client, cwd, parsed.flags, parsed.args[0], parsed.args[1], typeof parsed.flags.note === "string" ? parsed.flags.note : undefined, typeof parsed.flags["expected-updated-at"] === "string" ? parsed.flags["expected-updated-at"] : undefined);
+                return;
+            }
             if (parsed.subcommand === "send") {
                 if (parsed.args.length !== 2)
                     throw new Error("Usage: apex findings send <finding-ref> <linear|jira>");

package/dist/args.js

@@ -14,6 +14,7 @@ export const KNOWN_CLI_FLAG_NAMES = [
     "content",
     "dismissal-reason",
     "expires-at",
+    "expected-updated-at",
     "fix-pr-url",
     "force",
     "format",
@@ -25,6 +26,7 @@ export const KNOWN_CLI_FLAG_NAMES = [
     "limit",
     "mode",
     "name",
+    "note",
     "no-open",
     "non-interactive",
     "output",

package/dist/commands.js

@@ -4,7 +4,8 @@ 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, fetchFindingTickets, linkFindingTicket, sendFindingToIssueTracker, 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, setFindingStatus, } from "./findings.js";
+import { FINDING_LIFECYCLE_STATUSES } from "./types.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";
@@ -1896,7 +1897,7 @@ export async function openCurrentApexView(client, cwd, flags) {
     }
     return url;
 }
-async function resolveTicketFinding(client, cwd, flags, requestedFindingRef) {
+async function resolveCommandFinding(client, cwd, flags, requestedFindingRef) {
     const findingRef = normalizeFindingRefInput(requestedFindingRef);
     const currentBinding = await loadWorkspaceBinding(cwd);
     const binding = isFindingUuid(findingRef)
@@ -1907,7 +1908,7 @@ async function resolveTicketFinding(client, cwd, flags, requestedFindingRef) {
         requestedScanId: getFlagString(flags, "scan") });
 }
 export async function commandFindingTickets(client, cwd, flags, findingRef) {
-    const selection = await resolveTicketFinding(client, cwd, flags, findingRef);
+    const selection = await resolveCommandFinding(client, cwd, flags, findingRef);
     const result = await fetchFindingTickets(client, selection.findingId);
     const payload = { findingId: selection.findingId, findingRef: selection.findingRef, ...result };
     if (isJsonMode(flags))
@@ -1923,7 +1924,7 @@ export async function commandFindingLinkTicket(client, cwd, flags, findingRef, p
     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 selection = await resolveCommandFinding(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))
@@ -1936,7 +1937,7 @@ export async function commandFindingSend(client, cwd, flags, findingRef, provide
     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 selection = await resolveCommandFinding(client, cwd, flags, findingRef);
     const result = await sendFindingToIssueTracker(client, selection.findingId, provider);
     const payload = { findingId: selection.findingId, findingRef: selection.findingRef, ...result };
     if (isJsonMode(flags))
@@ -1945,3 +1946,29 @@ export async function commandFindingSend(client, cwd, flags, findingRef, provide
         logLine(`${result.created ? "Created" : "Already sent"}: ${result.export.issueKey ?? result.export.issueId} ${result.export.issueUrl}`, flags);
     return payload;
 }
+export async function commandFindingStatus(client, cwd, flags, findingRef, status, note, expectedUpdatedAt) {
+    if (!FINDING_LIFECYCLE_STATUSES.includes(status)) {
+        throw new Error(`Usage: apex findings status <finding-ref> <${FINDING_LIFECYCLE_STATUSES.join("|")}> [--note <rationale>]`);
+    }
+    const trimmedNote = note?.trim();
+    if (trimmedNote && trimmedNote.length > 1000)
+        throw new Error("Status notes must be 1000 characters or less.");
+    if (expectedUpdatedAt && (!/^\d{4}-\d{2}-\d{2}T/.test(expectedUpdatedAt) || !Number.isFinite(Date.parse(expectedUpdatedAt)))) {
+        throw new Error("--expected-updated-at must be an ISO timestamp from the finding's updatedAt.");
+    }
+    const selection = await resolveCommandFinding(client, cwd, flags, findingRef);
+    const result = await setFindingStatus(client, selection.findingId, {
+        status: status,
+        ...(trimmedNote ? { note: trimmedNote } : {}),
+        ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
+    });
+    const payload = { ...result, findingRef: selection.findingRef };
+    if (isJsonMode(flags))
+        printJson(payload);
+    else {
+        logLine(`Finding: ${selection.findingRef}`, flags);
+        logLine(`Status: ${result.status} (${result.reviewState})${result.changed ? "" : " — already set"}`, flags);
+        logLine("Scanner validity and review feedback are unchanged.", flags);
+    }
+    return payload;
+}

package/dist/findings.js

@@ -5,7 +5,7 @@ const WORKSPACE_FINDING_FILTER_PATTERN = /^!?(severity|scan|repo|review|impact|l
 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, 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.";
+const FINDING_WRITE_AUTH_ERROR = "Finding comments, feedback, status changes, 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;
@@ -321,6 +321,11 @@ export async function startFindingFixReviewScan(client, findingId, input = {}) {
 export async function fetchFindingTickets(client, findingId) {
     return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/tickets`);
 }
+export async function setFindingStatus(client, findingId, input) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/status`, {
+        method: "PATCH", json: input,
+    });
+}
 export async function linkFindingTicket(client, findingId, input) {
     return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/tickets`, {
         method: "POST", json: input,

package/dist/help.js

@@ -14,6 +14,8 @@ export const CLI_HELP_TEXT = `Usage:
                                     Add a comment or note to a finding
   apex findings feedback <finding-id|finding-identifier> <valid|invalid>
                                     Leave feedback; invalid requires --dismissal-reason
+  apex findings status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped>
+                                    Close, reopen, or update client remediation status
   apex findings fix-review <finding-id|finding-identifier>
                                     Start a fix review scan for a Fix PR or current repository
   apex export findings              Export findings for the latest or selected scan
@@ -56,6 +58,8 @@ Flags:
   --status valid|invalid            Set the finding feedback status explicitly
   --content <markdown>              Supply comment content for apex findings comment
   --comment <markdown>              Supply rationale for apex findings feedback
+  --note <rationale>                Audit note for a finding status change (max 1000 characters)
+  --expected-updated-at <timestamp>  Reject a status change if the finding has changed since this updatedAt
   --parent-comment <comment-id>     Reply to an existing finding comment
   --suggested-severity extreme|critical|high|medium|low|informational
                                     Attach a suggested severity to valid feedback
@@ -163,6 +167,8 @@ Commands:
                           Add a comment or note to a finding
   /findings feedback <finding-ref> valid [comment]
                           Leave valid feedback on a finding
+  /findings status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped> [note]
+                          Close, reopen, or update client remediation status
   /findings feedback <finding-ref> invalid <reason> [comment]
                           Leave invalid feedback; reason is false-positive, by-design, or not-relevant
   /findings fix-review <finding-ref>

package/dist/mcp.js

@@ -6,11 +6,12 @@ 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, commandFindingTickets, commandFindingLinkTicket, commandFindingSend, commandFindingFeedback, commandFindingFixReview, commandFindings, commandWorkspaceFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingStatus, 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";
+import { FINDING_LIFECYCLE_STATUSES } from "./types.js";
 const MCP_WORKFLOW_GUIDE = `Use Apex through these tools instead of shelling out to the CLI.
 
 Suggested workflow:
@@ -23,7 +24,7 @@ Suggested workflow:
 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. 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.
+10. Close or reopen findings with apex-finding-status using status fixed or open. This changes remediation, not scanner validity or feedback. Leave 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:
@@ -755,6 +756,22 @@ function registerTools(server, auditSetupEnabled = false) {
         parentCommentId,
         scanId,
     }));
+    server.registerTool("apex-finding-status", {
+        title: "Change Apex Finding Status",
+        description: "Close a finding with fixed or reopen it with open. Changes client remediation only, preserving scanner validity, severity, feedback, and linked ticket status. Invalid or duplicate findings cannot be reopened until their classification is reviewed. Uses device login. Hosted MCP exposes the same tool with findingId and explicit findings:write. Optional expectedUpdatedAt prevents overwriting a newer edit.",
+        inputSchema: {
+            cwd: z.string().optional(),
+            findingRef: z.string(),
+            status: z.enum(FINDING_LIFECYCLE_STATUSES),
+            note: z.string().trim().max(1000).optional(),
+            expectedUpdatedAt: z.iso.datetime({ offset: true }).optional(),
+            scanId: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ cwd, findingRef, status, note, expectedUpdatedAt, scanId }) => runTool("apex-finding-status", async () => {
+        const targetCwd = resolveCwd(cwd);
+        return { cwd: targetCwd, ...await commandFindingStatus(new ApexApiClient(), targetCwd, buildFlags({ scanId }), findingRef, status, note, expectedUpdatedAt) };
+    }, (value) => `Set finding ${String(value.findingRef)} to ${String(value.status)}.`, { cwd, findingRef, status, note, expectedUpdatedAt, scanId }));
     server.registerTool("apex-finding-feedback", {
         title: "Leave Apex Finding Feedback",
         description: "Leave valid or invalid feedback on an Apex finding using the current Apex login. To attach a fix PR, send status valid with label fixed and fixPrUrls.",

package/dist/shell.js

@@ -1,6 +1,6 @@
 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 { commandCancelScan, commandClaim, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingStatus, 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";
@@ -13,7 +13,7 @@ const SHELL_COMPLETIONS = [
     { command: "scans" },
     {
         command: "findings",
-        args: ["workspace", "comment", "feedback", "fix-review", "tickets", "link-ticket", "send"],
+        args: ["workspace", "status", "comment", "feedback", "fix-review", "tickets", "link-ticket", "send"],
     },
     { command: "export" },
     { command: "workspaces" },
@@ -254,6 +254,12 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandScans(client, cwd, shellFlags);
             return {};
         case "findings": {
+            if (parsed.args[0] === "status") {
+                if (parsed.args.length < 3)
+                    throw new Error("Usage: /findings status <finding-ref> <open|fixed|acknowledged|in_review|pending_merge|false_positive|wont_fix|skipped> [note]");
+                await commandFindingStatus(client, cwd, shellFlags, parsed.args[1], parsed.args[2], parsed.args.slice(3).join(" ") || undefined);
+                return {};
+            }
             if (parsed.args[0] === "send") {
                 if (parsed.args.length !== 3)
                     throw new Error("Usage: /findings send <finding-ref> <linear|jira>");

package/dist/telemetry.js

@@ -283,7 +283,7 @@ function sanitizeShellArgs(parsed) {
                     commentLengthBucket: bucketLength(parsed.args.slice(feedbackStatus === "invalid" ? 4 : 3).join(" ")),
                 };
             }
-            if (["fix-review", "tickets", "link-ticket", "send"].includes(action)) {
+            if (["status", "fix-review", "tickets", "link-ticket", "send"].includes(action)) {
                 return {
                     findingRefProvided: Boolean(parsed.args[1]),
                 };
@@ -331,7 +331,7 @@ function safeCliSubcommand(parsed) {
         case "export":
             return safeEnum(subcommand, ["findings"]);
         case "findings":
-            return safeEnum(subcommand, ["comment", "feedback", "fix-review", "tickets", "link-ticket", "send"]);
+            return safeEnum(subcommand, ["comment", "feedback", "status", "fix-review", "tickets", "link-ticket", "send"]);
         case "setup":
             return safeEnum(subcommand, ["all", "codex", "claude", "copilot"]);
         case "service-key":

package/dist/types.js

@@ -1 +1,4 @@
-export {};
+export const FINDING_LIFECYCLE_STATUSES = [
+    "open", "fixed", "acknowledged", "in_review", "pending_merge",
+    "false_positive", "wont_fix", "skipped",
+];

package/package.json

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

package/skills/apex-cli/SKILL.md

@@ -9,7 +9,7 @@ This skill is bundled with Apex CLI and can be installed into Codex with `apex s
 
 Prefer the Apex MCP tools over running `apex` in the shell when the server is available. The tools installed by `apex setup` use the local stdio server and device login.
 
-For a production MCP client that does not need local filesystem access, use the hosted Streamable HTTP endpoint at `https://ai.cantina.xyz/mcp`. Read the organization service key from `APEX_SERVICE_KEY` and supply it only as `Authorization: Bearer <TOKEN>`; never put the raw key in a tool argument, result, prompt, source file, or log. The hosted tools are `apex-credits`, `apex-workspaces`, `apex-scan`, `apex-black-start`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, and `apex-finding-send`.
+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-black-start`, `apex-status`, `apex-cancel-scan`, `apex-findings`, `apex-workspace-findings`, `apex-finding-tickets`, `apex-finding-link-ticket`, `apex-finding-send`, and `apex-finding-status`.
 
 OAuth-capable clients may instead use the hosted endpoint’s OAuth discovery and Cantina manager-consent flow. Let the client manage OAuth credentials; never pass them to tools, the REST API, or local CLI. Local stdio MCP continues to use device login.
 
@@ -160,3 +160,12 @@ Scan target and recovery rules:
 - Use Standard for local changes, files, plain directories, and public repositories without provider access. Lite and Audit still require connected provider sources; do not silently substitute another mode.
 - Unauthenticated headless CLI commands fail with explicit login guidance; they never start device login. Use the MCP auth tools for explicit MCP login. Retry transient refresh failures without clearing credentials.
 - Audit Setup is an explicit Standard/Audit beta flow using saved workspace repositories and context. It does not preserve local targets. Never automatically substitute setup after `AUDIT_SETUP_REQUIRED`; use the error's selected-workspace command only when that saved scope is intended. Draft operations require the ID returned by preparation; eligible accounts receive setup commands in CLI help. Lite and PR do not use `--setup`.
+
+Finding lifecycle:
+- Close resolved issues with `apex-finding-status` and `status: "fixed"`; reopen with `status: "open"`.
+- Local MCP takes `findingRef`, optional `cwd`/`scanId`, `note`, and `expectedUpdatedAt`, using device login. Hosted MCP takes `findingId` (UUID), no local paths, and requires explicit `findings:write`.
+- The scripted equivalent is `apex findings status <finding-ref> <open|fixed> --note "rationale" --json`. Other statuses: acknowledged, in_review, pending_merge, false_positive, wont_fix, skipped.
+- Status changes preserve scanner validity, severity, feedback, and linked ticket state. Invalid or duplicate findings cannot be reopened into the open queue until their classification is reviewed.
+- Read `remediationStatus` in workspace finding lists for the current lifecycle; `status` remains the scanner verdict. `open` and `acknowledged` stay distinct even though both use the `accepted` review state.
+- Use the finding updatedAt as expectedUpdatedAt when working from a prior snapshot. On FINDING_STATUS_CONFLICT, reload and review before retrying.
+- Linear sync is Linear-to-Apex: started becomes acknowledged, completed becomes fixed. Do not promise Apex-to-Linear status updates or automatic Linear reopening.