@cantinasecurity/apex-cli 0.1.1 → 0.1.2

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

@@ -19,6 +19,7 @@ Recommended workflow:
 4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
 6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
+7. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
 
 If the Apex MCP server is not configured, fall back to the local CLI:
 
@@ -27,14 +28,19 @@ If the Apex MCP server is not configured, fall back to the local CLI:
 - Use `--json` whenever structured output is helpful.
 - `apex credits` reports standard credits and audit scan entitlements when Bedrock returns both balances.
 - Work from the target repository directory so Apex can resolve `.apex/workspace.json`.
+- `apex scan` scans the current working directory by default; pass `--repo` only when the user asks to scan explicit alternate roots.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Plain local directories and dirty git worktrees can scan through local snapshot uploads without provider access.
 - Audit scans use `--mode audit` in user-facing CLI calls. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
+- Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
+- Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
+- Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit `scanId` when needed, or use the finding UUID directly.
 
 ## Examples
 
 - Start a scan for the current repository or directory: run `apex-doctor`, bind a workspace if needed, then call `apex-scan`.
 - Check an active scan: call `apex-status`, then `apex-findings` when the scan completes.
 - Export findings for review: call `apex-export-findings` with `format` set to `markdown`, `json`, or `gitlab-sast`.
+- Leave review feedback: call `apex-finding-comment` to add a note, or `apex-finding-feedback` with `status` set to `valid` or `invalid`.

package/README.md

@@ -101,6 +101,9 @@ Supported shell commands:
 - `/scan [standard|audit]`
 - `/scans`
 - `/findings [scan-id]`
+- `/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]`
 - `/export [scan-id]`
 - `/workspaces`
 - `/cancel-scan [scan-id]`
@@ -128,6 +131,8 @@ Supported shell commands:
 - `apex scan`
 - `apex scans`
 - `apex findings [--scan <scan-id>]`
+- `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]`
 - `apex export findings [--scan <scan-id>] [--format markdown|json|gitlab-sast] [--output <path>]`
 - `apex workspaces`
 - `apex workspace`
@@ -149,9 +154,31 @@ Helpful workspace flags:
 
 `apex credits` shows standard scan credits plus audit scan entitlements when the server returns them.
 
+## Finding Review Feedback
+
+Finding review collaboration now has explicit write commands:
+
+- `apex findings comment <finding-id|finding-identifier> --content "Needs auth check"`
+- `apex findings feedback <finding-id|finding-identifier> valid --comment "Reproduced on latest build"`
+- `apex findings feedback <finding-id|finding-identifier> invalid --dismissal-reason false-positive --comment "This path is unreachable"`
+- `/findings comment <finding-ref> <comment>`
+- `/findings feedback <finding-ref> valid [comment]`
+- `/findings feedback <finding-ref> invalid <false-positive|by-design|not-relevant> [comment]`
+
+Identifiers such as `KERN2-25` are resolved against the selected or latest scan for the current workspace binding. Pass `--scan <scan-id>` when you need a specific scan, or pass the finding UUID directly to skip workspace-based resolution.
+
+Finding comments and valid/invalid feedback currently require a Cantina web session token in `CANTINA_AUTH_TOKEN`. Set it to the value of your logged-in `auth_token` cookie before using the write commands or the corresponding MCP tools.
+
+Invalid feedback requires a dismissal reason. Valid feedback can include `--suggested-severity extreme|critical|high|medium|low|informational`.
+
+This is intentionally documented as a separate auth requirement because the current Apex read APIs and finding review write APIs do not accept the same credentials:
+
+- read operations such as `apex findings`, `apex export findings`, and `apex-findings` use the Apex CLI device-login bearer token
+- finding comments and feedback currently go through the Cantina web-app routes and require `CANTINA_AUTH_TOKEN`
+
 ## Local Source Scans
 
-`apex scan` now works against any local source root you point it at:
+`apex scan` now works against any local source root you point it at. By default, that source root is the current working directory:
 
 - clean GitHub or GitLab checkouts can stay on the remote-materialization path
 - dirty git worktrees fall back to a local snapshot upload by default
@@ -159,7 +186,7 @@ Helpful workspace flags:
 
 Useful flags:
 
-- `--repo <path>` to scan one or more explicit local roots
+- `--repo <path>` to scan one or more explicit local roots instead of the current directory
 - `--source-mode auto|remote|local` to control remote-first fallback behavior
 - `--mode standard|audit` to choose the scan mode
 
@@ -237,6 +264,7 @@ The MCP server exposes Apex-specific tools for:
 - doctor, credits, and provider connection URLs
 - workspace inspection and workspace binding
 - scan start, status, cancellation, findings, and findings export
+- finding comments and valid/invalid feedback with `apex-finding-comment` and `apex-finding-feedback`
 
 For repository-scoped operations, pass `cwd` explicitly so the server can resolve the right `.apex/workspace.json` binding and repository roots.
 

package/dist/apex.js

@@ -1,6 +1,6 @@
 import { ApexApiClient, formatApiError } from "./api-client.js";
 import { parseArgs } from "./args.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { runMcpServer } from "./mcp.js";
 import { runInteractiveShell } from "./shell.js";
@@ -63,6 +63,32 @@ async function main() {
             await commandWorkspace(cwd, parsed.flags);
             return;
         case "findings":
+            if (parsed.subcommand === "comment") {
+                const findingRef = parsed.args[0] ?? "";
+                const content = parsed.args.slice(1).join(" ").trim() || String(parsed.flags.content ?? "");
+                await commandFindingComment(client, cwd, parsed.flags, findingRef, content, typeof parsed.flags["parent-comment"] === "string"
+                    ? parsed.flags["parent-comment"]
+                    : null);
+                return;
+            }
+            if (parsed.subcommand === "feedback") {
+                const findingRef = parsed.args[0] ?? "";
+                const feedbackType = parsed.args[1] ??
+                    (typeof parsed.flags.status === "string"
+                        ? parsed.flags.status
+                        : undefined);
+                if (feedbackType !== "valid" && feedbackType !== "invalid") {
+                    throw new Error("Usage: apex findings feedback <finding-id|finding-identifier> <valid|invalid> [--dismissal-reason false-positive|by-design|not-relevant]");
+                }
+                await commandFindingFeedback(client, cwd, parsed.flags, {
+                    requestedFindingRef: findingRef,
+                    feedbackType,
+                    comment: parsed.args.slice(2).join(" ").trim() || getFlagValue(parsed.flags.comment),
+                    suggestedSeverity: getFlagValue(parsed.flags["suggested-severity"]),
+                    dismissalReason: getFlagValue(parsed.flags["dismissal-reason"]),
+                });
+                return;
+            }
             await commandFindings(client, cwd, parsed.flags);
             return;
         case "export":
@@ -84,6 +110,9 @@ async function main() {
             throw new Error(`Unknown command: ${parsed.command}`);
     }
 }
+function getFlagValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
 main().catch((error) => {
     if (error instanceof Error && error.reported) {
         process.exitCode = 1;

package/dist/commands.js

@@ -3,7 +3,7 @@ import { logout } from "./auth.js";
 import { ApiError } from "./api-client.js";
 import { openInBrowser } from "./browser.js";
 import { loadConfig, saveConfig } from "./config.js";
-import { fetchScanExport, fetchScanFindings, resolveScanSelection } from "./findings.js";
+import { createFindingComment, fetchScanExport, fetchScanFindings, isFindingUuid, normalizeFindingRef, requireCantinaAuthToken, resolveFindingSelection, resolveScanSelection, submitFindingFeedback, } from "./findings.js";
 import { prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-source-scan.js";
 import { logLine, printJson, withLoadingIndicator } from "./output.js";
 import { confirm } from "./prompt.js";
@@ -18,6 +18,19 @@ import path from "node:path";
 const WORKSPACE_USE_PATTERN = "<workspace-name|workspace-prefix|workspace-id>";
 const WORKSPACE_BINDING_GUIDANCE = "Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const WORKSPACE_SELECTION_GUIDANCE = "Run `apex workspaces` to list available workspace names, prefixes, and IDs, then retry `apex workspace use \"<workspace name>\"`.";
+const FINDING_FEEDBACK_SEVERITIES = [
+    "extreme",
+    "critical",
+    "high",
+    "medium",
+    "low",
+    "informational",
+];
+const FINDING_DISMISSAL_REASONS = [
+    "false-positive",
+    "by-design",
+    "not-relevant",
+];
 async function saveCompanyDefault(companyId) {
     const config = await loadConfig();
     if (config.defaultCompanyId !== companyId) {
@@ -67,6 +80,33 @@ function formatAuditScanBalance(scanBalance) {
 function normalizeRequestedScanMode(value) {
     return value === "ultra" || value === "audit" ? "ultra" : "standard";
 }
+function normalizeFindingRefInput(value) {
+    const trimmed = normalizeFindingRef(value);
+    if (!trimmed) {
+        throw new Error("A finding ID or finding identifier is required.");
+    }
+    return trimmed;
+}
+function normalizeFeedbackSeverity(value) {
+    const normalized = value?.trim() ?? "";
+    if (!normalized) {
+        return null;
+    }
+    if (FINDING_FEEDBACK_SEVERITIES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Suggested severity must be one of: ${FINDING_FEEDBACK_SEVERITIES.join(", ")}.`);
+}
+function normalizeDismissalReason(value) {
+    const normalized = value?.trim() ?? "";
+    if (!normalized) {
+        return null;
+    }
+    if (FINDING_DISMISSAL_REASONS.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Dismissal reason must be one of: ${FINDING_DISMISSAL_REASONS.join(", ")}.`);
+}
 async function requireWorkspaceBinding(cwd) {
     const binding = await loadWorkspaceBinding(cwd);
     if (binding) {
@@ -74,6 +114,27 @@ async function requireWorkspaceBinding(cwd) {
     }
     throw new Error(`This directory is not bound to an Apex workspace yet. ${WORKSPACE_BINDING_GUIDANCE}`);
 }
+function requireLoadedWorkspaceBinding(binding) {
+    if (binding) {
+        return binding;
+    }
+    throw new Error(`This directory is not bound to an Apex workspace yet. ${WORKSPACE_BINDING_GUIDANCE}`);
+}
+async function maybePersistFindingSelectionBinding(params) {
+    if (!params.binding || !params.scan) {
+        return params.binding;
+    }
+    const nextBinding = {
+        ...params.binding,
+        lastScanId: getScanDisplayId(params.scan),
+        lastScanUrl: params.response?.scan.scanUrl ??
+            params.scan.scanUrl ??
+            params.binding.lastScanUrl ??
+            null,
+    };
+    await saveWorkspaceBinding(params.cwd, nextBinding);
+    return nextBinding;
+}
 function canPromptForConfirmation(flags) {
     return !isNonInteractive(flags) && process.stdin.isTTY && process.stdout.isTTY;
 }
@@ -599,6 +660,122 @@ export async function commandFindings(client, cwd, flags) {
     }
     return payload;
 }
+export async function commandFindingComment(client, cwd, flags, requestedFindingRef, content, parentCommentId) {
+    const findingRef = normalizeFindingRefInput(requestedFindingRef);
+    const trimmedContent = content.trim();
+    if (!trimmedContent) {
+        throw new Error("Usage: apex findings comment <finding-id|finding-identifier> --content \"<markdown>\"");
+    }
+    requireCantinaAuthToken();
+    const currentBinding = await loadWorkspaceBinding(cwd);
+    const needsWorkspaceResolution = !isFindingUuid(findingRef);
+    const binding = needsWorkspaceResolution
+        ? requireLoadedWorkspaceBinding(currentBinding)
+        : currentBinding;
+    if (needsWorkspaceResolution) {
+        await ensureAuthenticated(client, flags);
+    }
+    const selection = await withLoadingIndicator("Resolving finding...", flags, () => resolveFindingSelection({
+        client,
+        binding,
+        requestedFindingRef: findingRef,
+        requestedScanId: getFlagString(flags, "scan"),
+    }));
+    const response = await withLoadingIndicator("Adding finding comment...", flags, () => createFindingComment(client, selection.findingId, {
+        content: trimmedContent,
+        parentCommentId: parentCommentId?.trim() || null,
+    }));
+    const nextBinding = await maybePersistFindingSelectionBinding({
+        cwd,
+        binding,
+        scan: selection.scan,
+        response: selection.response,
+    });
+    const payload = {
+        binding: nextBinding,
+        scan: selection.scan,
+        findingId: selection.findingId,
+        findingRef: selection.findingRef,
+        finding: selection.finding,
+        comment: response.comment,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Finding: ${selection.finding?.findingIdentifier ?? selection.findingId}`, flags);
+    logLine(`Comment: added (${response.comment.id})`, flags);
+    logLine(`Author: ${response.comment.user.name}`, flags);
+    logLine(`Created: ${response.comment.createdAt}`, flags);
+    return payload;
+}
+export async function commandFindingFeedback(client, cwd, flags, params) {
+    const findingRef = normalizeFindingRefInput(params.requestedFindingRef);
+    const suggestedSeverity = normalizeFeedbackSeverity(params.suggestedSeverity);
+    const dismissalReason = normalizeDismissalReason(params.dismissalReason);
+    if (params.feedbackType === "valid" &&
+        dismissalReason) {
+        throw new Error("Dismissal reasons are only valid for invalid feedback.");
+    }
+    if (params.feedbackType === "invalid" &&
+        suggestedSeverity) {
+        throw new Error("Suggested severity is only valid for valid feedback.");
+    }
+    if (params.feedbackType === "invalid" && !dismissalReason) {
+        throw new Error("Invalid feedback requires a dismissal reason.");
+    }
+    requireCantinaAuthToken();
+    const currentBinding = await loadWorkspaceBinding(cwd);
+    const needsWorkspaceResolution = !isFindingUuid(findingRef);
+    const binding = needsWorkspaceResolution
+        ? requireLoadedWorkspaceBinding(currentBinding)
+        : currentBinding;
+    if (needsWorkspaceResolution) {
+        await ensureAuthenticated(client, flags);
+    }
+    const selection = await withLoadingIndicator("Resolving finding...", flags, () => resolveFindingSelection({
+        client,
+        binding,
+        requestedFindingRef: findingRef,
+        requestedScanId: getFlagString(flags, "scan"),
+    }));
+    const response = await withLoadingIndicator("Submitting finding feedback...", flags, () => submitFindingFeedback(client, selection.findingId, {
+        feedbackType: params.feedbackType,
+        comment: params.comment?.trim() || null,
+        suggestedSeverity,
+        dismissalReason,
+    }));
+    const nextBinding = await maybePersistFindingSelectionBinding({
+        cwd,
+        binding,
+        scan: selection.scan,
+        response: selection.response,
+    });
+    const payload = {
+        binding: nextBinding,
+        scan: selection.scan,
+        findingId: selection.findingId,
+        findingRef: selection.findingRef,
+        finding: selection.finding,
+        feedback: response.feedback,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Finding: ${selection.finding?.findingIdentifier ?? selection.findingId}`, flags);
+    logLine(`Feedback: ${response.feedback.feedbackType ?? params.feedbackType}`, flags);
+    if (response.feedback.suggestedSeverity) {
+        logLine(`Suggested severity: ${response.feedback.suggestedSeverity}`, flags);
+    }
+    if (response.feedback.dismissalReason) {
+        logLine(`Dismissal reason: ${response.feedback.dismissalReason}`, flags);
+    }
+    if (response.feedback.comment) {
+        logLine("Comment: saved", flags);
+    }
+    return payload;
+}
 export async function commandExportFindings(client, cwd, flags) {
     await ensureAuthenticated(client, flags);
     const binding = await requireWorkspaceBinding(cwd);

package/dist/findings.js

@@ -1,4 +1,8 @@
 import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, } from "./scan.js";
+import { ApiError } 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 CANTINA_AUTH_TOKEN_ENV = "CANTINA_AUTH_TOKEN";
+const CANTINA_AUTH_TOKEN_ERROR = "Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` from a logged-in Cantina/Apex browser session. Export `CANTINA_AUTH_TOKEN` and retry.";
 function parsePositiveInt(value) {
     if (!value)
         return null;
@@ -8,6 +12,77 @@ function parsePositiveInt(value) {
     }
     return Math.floor(parsed);
 }
+async function parseWebRouteResponse(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return response.json().catch(() => null);
+    }
+    return response.text().catch(() => "");
+}
+function normalizeCantinaAuthToken(value) {
+    if (!value) {
+        return null;
+    }
+    let token = value.trim();
+    if (!token) {
+        return null;
+    }
+    if (token.toLowerCase().startsWith("auth_token=")) {
+        token = token.slice("auth_token=".length).trim();
+    }
+    return token.length > 0 ? token : null;
+}
+export function requireCantinaAuthToken() {
+    const token = normalizeCantinaAuthToken(process.env[CANTINA_AUTH_TOKEN_ENV]);
+    if (!token) {
+        throw new Error(CANTINA_AUTH_TOKEN_ERROR);
+    }
+    return token;
+}
+export function isFindingUuid(value) {
+    return FINDING_UUID_PATTERN.test(value.trim());
+}
+export function normalizeFindingRef(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    try {
+        const url = new URL(trimmed);
+        const segments = url.pathname.split("/").filter(Boolean);
+        return segments[segments.length - 1] ?? trimmed;
+    }
+    catch {
+        return trimmed;
+    }
+}
+function matchesFindingRef(finding, findingRef) {
+    const normalizedRef = findingRef.trim().toLowerCase();
+    return [finding.id, finding.findingIdentifier]
+        .filter((value) => typeof value === "string")
+        .some((value) => value.trim().toLowerCase() === normalizedRef);
+}
+async function requestFindingAppRoute(client, path, options = {}) {
+    const token = requireCantinaAuthToken();
+    const baseUrl = await client.getBaseUrl();
+    const headers = new Headers(options.headers ?? {});
+    // These routes still authenticate through the web app cookie, not Apex CLI bearer auth.
+    headers.set("Cookie", `auth_token=${token}`);
+    headers.set("Accept", "application/json");
+    if (options.json !== undefined) {
+        headers.set("Content-Type", "application/json");
+    }
+    const response = await fetch(new URL(path, baseUrl), {
+        ...options,
+        headers,
+        body: options.json !== undefined ? JSON.stringify(options.json) : options.body,
+    });
+    const body = await parseWebRouteResponse(response);
+    if (!response.ok) {
+        throw new ApiError(`Request failed with ${response.status}`, response.status, body);
+    }
+    return body;
+}
 export async function fetchScanFindings(client, scanId, limit) {
     const params = new URLSearchParams();
     const parsedLimit = parsePositiveInt(limit);
@@ -48,3 +123,60 @@ export async function resolveScanSelection(params) {
 export function describeScanSelection(scan) {
     return scan.scanUrl ?? getScanDisplayId(scan);
 }
+export async function resolveFindingSelection(params) {
+    const findingRef = normalizeFindingRef(params.requestedFindingRef);
+    if (!findingRef) {
+        throw new Error("A finding ID or finding identifier is required.");
+    }
+    if (isFindingUuid(findingRef)) {
+        return {
+            findingId: findingRef,
+            findingRef,
+            finding: null,
+            scan: null,
+            response: null,
+        };
+    }
+    if (!params.binding) {
+        throw new Error("A workspace binding is required to resolve finding identifiers. Bind this directory first or use the finding UUID directly.");
+    }
+    const scan = await resolveScanSelection({
+        client: params.client,
+        binding: params.binding,
+        requestedScanId: params.requestedScanId,
+    });
+    const response = await fetchScanFindings(params.client, scan.scanId, "1000");
+    const finding = response.findings.find((item) => matchesFindingRef(item, findingRef)) ?? null;
+    if (!finding) {
+        throw new Error(`Could not find finding "${findingRef}" in ${describeScanSelection(scan)}. Re-run with --scan to target a different scan, or use the finding UUID directly.`);
+    }
+    return {
+        findingId: finding.id,
+        findingRef,
+        finding,
+        scan,
+        response,
+    };
+}
+export async function createFindingComment(client, findingId, input) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/comments`, {
+        method: "POST",
+        json: {
+            content: input.content,
+            ...(input.parentCommentId ? { parentId: input.parentCommentId } : {}),
+        },
+    });
+}
+export async function submitFindingFeedback(client, findingId, input) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/feedback`, {
+        method: "POST",
+        json: {
+            status: input.feedbackType,
+            ...(input.comment ? { comment: input.comment } : {}),
+            ...(input.suggestedSeverity
+                ? { suggestedSeverity: input.suggestedSeverity }
+                : {}),
+            ...(input.dismissalReason ? { dismissalReason: input.dismissalReason } : {}),
+        },
+    });
+}

package/dist/help.js

@@ -4,6 +4,10 @@ export const CLI_HELP_TEXT = `Usage:
   apex scan                         Create or resolve a workspace for this directory and start a scan
   apex scans                        List scans for the current workspace binding
   apex findings                     List findings for the latest or selected scan
+  apex findings comment <finding-id|finding-identifier>
+                                    Add a comment or note to a finding
+  apex findings feedback <finding-id|finding-identifier> <valid|invalid>
+                                    Leave feedback; invalid requires --dismissal-reason
   apex export findings              Export findings for the latest or selected scan
   apex workspaces                   List accessible workspaces for the active company
   apex workspace                    Show the workspace currently bound to this directory
@@ -24,6 +28,14 @@ Flags:
   --company <id-or-handle>          Choose the Apex company to use
   --workspace-name <name>           Set the Apex workspace name for this directory
   --scan <scan-id>                  Select a specific scan for findings or export
+  --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
+  --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
+  --dismissal-reason false-positive|by-design|not-relevant
+                                    Explain why invalid feedback is being left
   --format markdown|json|gitlab-sast
                                     Choose the export format for findings
   --output <path>                   Write exported findings to this file path
@@ -39,8 +51,12 @@ Flags:
 
 Tips:
   apex scan uses the current directory name as the default workspace name unless you pass --workspace-name.
+  apex scan uses the current directory as the default source root unless you pass --repo.
   audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
   apex workspace use accepts a workspace name, prefix, or ID.
+  Finding comments and feedback currently require CANTINA_AUTH_TOKEN from a logged-in Cantina/Apex browser session.
+  Invalid finding feedback requires --dismissal-reason.
+  Finding identifiers such as KERN2-25 resolve against the selected scan; pass --scan or use the finding UUID directly when needed.
   Quote workspace names that contain spaces:
     apex workspace use "Core Platform"
 `;
@@ -51,6 +67,12 @@ Commands:
   /scan [standard|audit]  Start a new Apex scan for this workspace
   /scans                  List scans for this workspace
   /findings [scan-id]     List findings for the latest or selected scan
+  /findings comment <finding-ref> <comment>
+                          Add a comment or note to a finding
+  /findings feedback <finding-ref> valid [comment]
+                          Leave valid feedback on a finding
+  /findings feedback <finding-ref> invalid <reason> [comment]
+                          Leave invalid feedback; reason is false-positive, by-design, or not-relevant
   /export [scan-id]       Export findings for the latest or selected scan
   /workspaces             List accessible workspaces for the active company
   /cancel-scan [scan-id]  Cancel a running or most recent scan
@@ -73,5 +95,8 @@ Commands:
 Tips:
   audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
   /workspace use accepts a workspace name, prefix, or ID.
+  /findings comment and /findings feedback require CANTINA_AUTH_TOKEN in the shell environment.
+  Invalid finding feedback requires a dismissal reason.
+  Use scripted CLI flags for advanced feedback options such as suggested severity or dismissal reason.
   Quote workspace names that contain spaces: /workspace use "Core Platform"
 `;

package/dist/mcp.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { z } from "zod";
 import { getMe, logout, startDeviceLogin, waitForDeviceLoginApproval } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { APEX_CLI_VERSION } from "./version.js";
 const MCP_WORKFLOW_GUIDE = `Use Apex through these tools instead of shelling out to the CLI.
@@ -15,6 +15,7 @@ Suggested workflow:
 3. Call apex-doctor for the target repository cwd.
 4. If the directory is not bound to the right workspace, call apex-workspaces and apex-workspace-use.
 5. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings.
+6. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
 
 Notes:
 - Pass cwd explicitly for repository-specific operations.
@@ -321,7 +322,7 @@ function registerTools(server) {
     }, (value) => `Bound ${String(value.cwd)} to an Apex workspace.`));
     server.registerTool("apex-scan", {
         title: "Start Apex Scan",
-        description: "Start a new Apex scan for any local repository or directory. Pass cwd explicitly for reliable workspace resolution. Use mode audit for audit scans.",
+        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths only to scan explicit alternate local roots. Use mode audit for audit scans.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
@@ -418,6 +419,61 @@ function registerTools(server) {
             ...payload,
         };
     }, (value) => `Fetched Apex findings for ${String(value.cwd)}.`));
+    server.registerTool("apex-finding-comment", {
+        title: "Add Apex Finding Comment",
+        description: "Add a comment or note to an Apex finding. Requires CANTINA_AUTH_TOKEN in the MCP server environment.",
+        inputSchema: {
+            cwd: z.string().optional(),
+            findingRef: z.string(),
+            content: z.string().min(1),
+            parentCommentId: z.string().optional(),
+            scanId: z.string().optional(),
+        },
+    }, async ({ cwd, findingRef, content, parentCommentId, scanId }) => runTool("apex-finding-comment", async () => {
+        const client = new ApexApiClient();
+        const targetCwd = resolveCwd(cwd);
+        const payload = await commandFindingComment(client, targetCwd, buildFlags({
+            scanId,
+        }), findingRef, content, parentCommentId);
+        return {
+            cwd: targetCwd,
+            ...payload,
+        };
+    }, (value) => `Added a finding comment for ${String(value.findingRef)}.`));
+    server.registerTool("apex-finding-feedback", {
+        title: "Leave Apex Finding Feedback",
+        description: "Leave valid or invalid feedback on an Apex finding. Requires CANTINA_AUTH_TOKEN in the MCP server environment.",
+        inputSchema: {
+            cwd: z.string().optional(),
+            findingRef: z.string(),
+            status: z.enum(["valid", "invalid"]),
+            comment: z.string().optional(),
+            suggestedSeverity: z
+                .enum(["extreme", "critical", "high", "medium", "low", "informational"])
+                .optional(),
+            dismissalReason: z
+                .enum(["false-positive", "by-design", "not-relevant"])
+                .optional(),
+            scanId: z.string().optional(),
+        },
+    }, async ({ cwd, findingRef, status, comment, suggestedSeverity, dismissalReason, scanId, }) => runTool("apex-finding-feedback", async () => {
+        const client = new ApexApiClient();
+        const targetCwd = resolveCwd(cwd);
+        const payload = await commandFindingFeedback(client, targetCwd, buildFlags({
+            scanId,
+        }), {
+            requestedFindingRef: findingRef,
+            feedbackType: status,
+            comment,
+            suggestedSeverity,
+            dismissalReason,
+        });
+        return {
+            cwd: targetCwd,
+            ...payload,
+        };
+    }, (value) => `Submitted ${String((value.feedback?.feedbackType ??
+        "finding"))} feedback for ${String(value.findingRef)}.`));
     server.registerTool("apex-export-findings", {
         title: "Export Apex Findings",
         description: "Export findings for the latest or selected Apex scan to a file on disk.",

package/dist/repo-discovery.js

@@ -1,37 +1,15 @@
 import { execFile } from "node:child_process";
-import { lstat, readdir, realpath } from "node:fs/promises";
+import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { extractCanonicalRepoMetadata } from "./repo-url.js";
 const execFileAsync = promisify(execFile);
-const IGNORED_DIRECTORIES = new Set([
-    ".git",
-    ".next",
-    "node_modules",
-    "dist",
-    "build",
-    "coverage",
-    ".turbo",
-    ".cache",
-    ".pnpm-store",
-    "tmp",
-    "vendor",
-]);
 async function runGit(cwd, args) {
     const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
         encoding: "utf8",
     });
     return stdout.trim();
 }
-async function isGitRepository(directory) {
-    try {
-        await runGit(directory, ["rev-parse", "--is-inside-work-tree"]);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 async function getGitTopLevel(directory) {
     try {
         const topLevel = await runGit(directory, ["rev-parse", "--show-toplevel"]);
@@ -103,25 +81,6 @@ function normalizeSelectedRoots(cwd, selectedPaths) {
     }
     return disjoint;
 }
-export async function findGitRepositoryRoots(cwd) {
-    const discovered = new Set();
-    async function walk(directory) {
-        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
-        const hasGitMarker = entries.some((entry) => entry.name === ".git");
-        if (hasGitMarker && (await isGitRepository(directory))) {
-            discovered.add(directory);
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            if (IGNORED_DIRECTORIES.has(entry.name))
-                continue;
-            await walk(path.join(directory, entry.name));
-        }
-    }
-    await walk(cwd);
-    return Array.from(discovered).sort((left, right) => left.length - right.length);
-}
 async function inspectGitRepository(rootCwd, directory) {
     const remoteUrl = await chooseRemote(directory);
     const metadata = remoteUrl ? extractCanonicalRepoMetadata(remoteUrl) : null;
@@ -163,7 +122,7 @@ async function inspectSource(rootCwd, requestedDirectory) {
 export async function discoverSources(cwd, selectedPaths = []) {
     const discoveredRoots = selectedPaths.length > 0
         ? normalizeSelectedRoots(cwd, selectedPaths)
-        : await findGitRepositoryRoots(cwd).then((gitRoots) => gitRoots.length > 0 ? gitRoots : [cwd]);
+        : [cwd];
     const sources = await Promise.all(discoveredRoots.map((root) => inspectSource(cwd, root)));
     sources.sort((left, right) => left.path.localeCompare(right.path));
     return { sources, scanned: discoveredRoots };

package/dist/session.js

@@ -70,6 +70,52 @@ function getSourceMode(flags) {
     const value = getFlagString(flags, "source-mode");
     return value === "remote" || value === "local" ? value : "auto";
 }
+function buildFallbackLocalArchivePlan(source, sourceMode) {
+    const reason = sourceMode === "local"
+        ? "user_requested_local_snapshot"
+        : source.kind === "directory_candidate"
+            ? "non_git_directory"
+            : source.dirty
+                ? "dirty_worktree"
+                : source.repoUrl
+                    ? "remote_access_unavailable"
+                    : "missing_remote";
+    return {
+        path: source.path,
+        displayName: source.displayName,
+        relativePath: source.path,
+        sourceKind: "local_archive",
+        archiveRequired: true,
+        reason,
+        git: source.kind === "git_candidate"
+            ? {
+                repoUrl: source.repoUrl,
+                provider: source.provider,
+                branch: source.branch,
+                commitSha: source.commitSha,
+                dirty: source.dirty,
+            }
+            : {
+                repoUrl: null,
+                provider: null,
+                branch: null,
+                commitSha: null,
+                dirty: false,
+            },
+    };
+}
+function ensurePlannedSources(selection, resolve) {
+    if (resolve.plannedSources.length > 0) {
+        return resolve;
+    }
+    if (selection.sourceMode === "remote") {
+        throw new Error("Workspace resolution did not return any remote scan sources.");
+    }
+    return {
+        ...resolve,
+        plannedSources: selection.sources.map((source) => buildFallbackLocalArchivePlan(source, selection.sourceMode)),
+    };
+}
 export async function ensureAuthenticated(client, flags) {
     return login(client, {
         noOpen: flags["no-open"] === true,
@@ -99,7 +145,7 @@ export async function selectWorkspaceTarget(cwd, me, flags) {
     };
 }
 export async function resolveWorkspaceSelection(client, selection) {
-    const resolve = await client.request("/api/cli/v2/local-workspaces/resolve", {
+    const rawResolve = await client.request("/api/cli/v2/local-workspaces/resolve", {
         method: "POST",
         json: {
             companyId: selection.company.id,
@@ -124,6 +170,7 @@ export async function resolveWorkspaceSelection(client, selection) {
                 }),
         },
     });
+    const resolve = ensurePlannedSources(selection, rawResolve);
     return {
         company: selection.company,
         workspaceName: selection.workspaceName,

package/dist/shell.js

@@ -1,5 +1,5 @@
 import { SHELL_HELP_TEXT } from "./help.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindings, commandLogout, commandScan, commandScans, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandLogout, commandScan, commandScans, commandStatus, 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";
@@ -8,7 +8,7 @@ const SHELL_COMPLETIONS = [
     { command: "credits" },
     { command: "scan", args: ["standard", "audit", "ultra"] },
     { command: "scans" },
-    { command: "findings" },
+    { command: "findings", args: ["comment", "feedback"] },
     { command: "export" },
     { command: "workspaces" },
     { command: "cancel-scan" },
@@ -200,6 +200,43 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandScans(client, cwd, shellFlags);
             return {};
         case "findings": {
+            if (parsed.args[0] === "comment") {
+                if (parsed.args.length < 3) {
+                    process.stderr.write("Usage: /findings comment <finding-id|finding-identifier> <comment>\n");
+                    return {};
+                }
+                await commandFindingComment(client, cwd, shellFlags, parsed.args[1], parsed.args.slice(2).join(" "));
+                return {};
+            }
+            if (parsed.args[0] === "feedback") {
+                const findingRef = parsed.args[1];
+                const feedbackType = parsed.args[2];
+                if (!findingRef ||
+                    (feedbackType !== "valid" && feedbackType !== "invalid")) {
+                    process.stderr.write("Usage: /findings feedback <finding-id|finding-identifier> <valid|invalid> [comment]\n");
+                    return {};
+                }
+                const dismissalReason = feedbackType === "invalid" ? parsed.args[3] : null;
+                if (feedbackType === "invalid" &&
+                    !["false-positive", "by-design", "not-relevant"].includes(dismissalReason ?? "")) {
+                    process.stderr.write("Usage: /findings feedback <finding-id|finding-identifier> invalid <false-positive|by-design|not-relevant> [comment]\n");
+                    return {};
+                }
+                await commandFindingFeedback(client, cwd, shellFlags, {
+                    requestedFindingRef: findingRef,
+                    feedbackType,
+                    comment: parsed.args
+                        .slice(feedbackType === "invalid" ? 4 : 3)
+                        .join(" ")
+                        .trim() || null,
+                    ...(dismissalReason
+                        ? {
+                            dismissalReason: dismissalReason,
+                        }
+                        : {}),
+                });
+                return {};
+            }
             if (parsed.args.length > 1) {
                 process.stderr.write("Usage: /findings [scan-id]\n");
                 return {};

package/package.json

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

package/skills/apex-cli/SKILL.md

@@ -17,11 +17,13 @@ Workflow:
 4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
 6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
+7. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
 
 Guidelines:
 
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
 - `apex-credits` reports standard credits and audit scan entitlements when Bedrock returns both balances.
+- `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Apex can scan plain local directories and dirty git worktrees without provider connections by using local snapshot uploads.
 - Audit scans use `mode: "audit"` in user-facing instructions. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
@@ -29,3 +31,6 @@ Guidelines:
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
 - Use `force: true` on `apex-scan` only when the user explicitly wants to replace or overlap an active scan.
 - Prefer `apex-findings` for quick inspection and `apex-export-findings` when the user needs a file artifact.
+- Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
+- Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
+- Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit scan when needed, or use the finding UUID directly.