@cantinasecurity/apex-cli 0.1.36 → 0.1.38

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";
@@ -332,6 +333,8 @@ function formatLiteScanBalance(scanBalance) {
     return `Lite scan credits: ${detailParts.join(", ")}`;
 }
 function normalizeRequestedScanMode(value) {
+    if (value === null || value === "standard")
+        return "standard";
     if (value === "ultra" || value === "audit") {
         return "audit";
     }
@@ -341,7 +344,7 @@ function normalizeRequestedScanMode(value) {
     if (value === "lite") {
         return "lite";
     }
-    return "standard";
+    throw new Error("--mode must be standard, audit, ultra, lite, or pr.");
 }
 function getFlagValues(flags, key) {
     const values = getFlagList(flags, key);
@@ -1074,7 +1077,7 @@ export async function commandConnect(client, cwd, flags, provider) {
     if (!isJsonMode(flags)) {
         logLine(`Connection URL for ${provider}: ${response.url}`, flags);
     }
-    if (flags["no-open"] !== true) {
+    if (flags["no-open"] !== true && canPromptInteractively(flags)) {
         await openInBrowser(response.url);
     }
     if (isJsonMode(flags)) {
@@ -1097,7 +1100,23 @@ export async function commandScan(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     const authState = await getCommandAuthState(client, me);
     setTelemetryAuthKind(authState.authKind);
+    if (authState.authKind === "guest" && requestedMode !== "standard") {
+        throw new Error("Guest trials support standard scans only. Use --mode standard, or run `apex claim` before choosing another mode.");
+    }
+    const guestLocalSourceGuidance = "Guest trials require local snapshot uploads. Clone remote repositories locally, then scan a local path without --source-mode remote.";
+    if (authState.authKind === "guest" && getFlagString(flags, "source-mode") === "remote") {
+        throw new Error(guestLocalSourceGuidance);
+    }
     let selection = await selectWorkspaceTarget(cwd, me, flags);
+    if (authState.authKind === "guest" && selection.sources.some((source) => source.absolutePath === null)) {
+        throw new Error(guestLocalSourceGuidance);
+    }
+    const requiresLocalSnapshot = selection.sourceMode === "local" ||
+        selection.sources.some((source) => source.kind !== "git_candidate" ||
+            (selection.sourceMode !== "remote" && source.dirty));
+    if ((requestedMode === "audit" || requestedMode === "lite") && requiresLocalSnapshot) {
+        throw new Error(`${requestedMode === "audit" ? "Audit" : "Lite"} scans require provider-backed repositories without local changes. Use --mode standard for files, directories, or local changes.`);
+    }
     let preparedArchives = null;
     if (authState.authKind === "guest" && requestedMode === "standard") {
         preparedArchives = await withLoadingIndicator("Preparing local source archive...", flags, () => prepareLocalSourceArchives({
@@ -1139,6 +1158,21 @@ export async function commandScan(client, cwd, flags) {
     let workspaceId = resolvedWorkspaceId;
     let scan;
     let prScanSource = null;
+    const requestScanStart = async (endpoint, json) => {
+        try {
+            return normalizeScanStartResponse(await client.request(endpoint, { method: "POST", json }));
+        }
+        catch (error) {
+            if (error instanceof ApiError && getApiErrorCode(error) === "AUDIT_SETUP_REQUIRED") {
+                const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+                const mode = requestedMode === "audit" ? "audit" : "standard";
+                const command = `apex scan --company ${quote(result.company.id)} --workspace-ref ${quote(workspaceId)} --mode ${mode} --setup guided`;
+                const message = `This backend requires Audit Setup. For this workspace's saved repositories, run: ${command}. Setup uses saved workspace sources and does not preserve local target selections. An explicit Standard source scan requires an updated client and backend; contact support if it still returns AUDIT_SETUP_REQUIRED.`;
+                throw new ApiError(message, error.status, { code: "AUDIT_SETUP_REQUIRED", error: message });
+            }
+            throw error;
+        }
+    };
     if (requestedMode === "pr") {
         let legacyResolve = await withLoadingIndicator("Preparing PR scan...", flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
         if (!legacyResolve.workspaceId) {
@@ -1161,40 +1195,30 @@ 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`, {
-            method: "POST",
-            json: {
-                mode: "pr",
-                scanType: "pr",
-                force: forceRestart || flags.force === true,
-                repositories: buildPrScanRepositoriesPayload({
-                    source: prSource,
-                    pullRequests: prSelections,
-                }),
-            },
-        })
-            .then(normalizeScanStartResponse));
+        scan = await withLoadingIndicator("Starting PR scan...", flags, () => requestScanStart(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+            mode: "pr",
+            scanType: "pr",
+            force: forceRestart || flags.force === true,
+            repositories: buildPrScanRepositoriesPayload({
+                source: prSource,
+                pullRequests: prSelections,
+            }),
+        }));
     }
     else if (requestedMode === "audit" || requestedMode === "lite") {
         const modeLabel = requestedMode === "audit" ? "Audit" : "Lite";
         if (!supportsLegacyRemoteFlow(result.resolve.plannedSources)) {
-            throw new Error(`${modeLabel} scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks.`);
+            throw new Error(`${modeLabel} scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks. Use --mode standard for local snapshots or public repositories without a provider connection.`);
         }
         const legacyResolve = await withLoadingIndicator(`Preparing ${modeLabel.toLowerCase()} scan...`, flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
         if (!legacyResolve.workspaceId) {
             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`, {
-            method: "POST",
-            json: {
-                mode: requestedMode,
-                force: forceRestart || flags.force === true,
-            },
-        })
-            .then(normalizeScanStartResponse));
+        scan = await withLoadingIndicator(`Starting ${modeLabel.toLowerCase()} scan...`, flags, () => requestScanStart(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+            mode: requestedMode,
+            force: forceRestart || flags.force === true,
+        }));
     }
     else {
         try {
@@ -1206,15 +1230,11 @@ export async function commandScan(client, cwd, flags) {
                     detectedSources: result.sources,
                     preparedArchives,
                 });
-                const response = await client.request(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
-                    method: "POST",
-                    json: {
-                        mode: requestedMode,
-                        force: forceRestart || flags.force === true,
-                        scanSources,
-                    },
+                return requestScanStart(`/api/cli/v2/local-workspaces/${encodeURIComponent(resolvedWorkspaceId)}/scan`, {
+                    mode: requestedMode,
+                    force: forceRestart || flags.force === true,
+                    scanSources,
                 });
-                return normalizeScanStartResponse(response);
             });
         }
         finally {
@@ -1877,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)
@@ -1888,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))
@@ -1904,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))
@@ -1917,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))
@@ -1926,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

@@ -1,7 +1,7 @@
 export const CLI_HELP_TEXT = `Usage:
   apex                              Open the interactive Apex shell
   apex credits                      Show standard, audit, fix review, and Lite scan entitlements for the active company
-  apex scan                         Create or resolve a workspace for this directory and start a scan
+  apex scan [target...]             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 --workspace         List findings across the workspace browser scan set
@@ -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
@@ -75,7 +79,7 @@ Flags:
   --source-mode auto|remote|local   Control remote-vs-local source materialization
   --force                           Start an overlapping non-PR scan, or confirm destructive guest logout
   --replace                         Revoke and replace an existing guest trial session
-  --repo <path>                     Include one or more explicit local source roots
+  --repo <path-or-url>              Select a file, directory, or HTTPS repository (repeatable)
   --json                            Print machine-readable JSON output
   --no-open                         Do not open browser flows automatically
   --non-interactive                 Disable prompts and browser-dependent UX
@@ -83,7 +87,9 @@ 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.
+  apex scan defaults to the current directory; positional targets or --repo select files, directories, or HTTPS GitHub/GitLab repositories.
+  A file target scans only that file. Use --mode standard for local changes and public repositories without a provider connection.
+  Headless and --json commands require an existing session; run apex login explicitly first.
   PR scans require --mode pr and at least one --pr selection for a GitHub repository.
   audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
   Lite scans use --mode lite and require beta access plus provider-backed GitHub or GitLab sources.
@@ -132,6 +138,9 @@ Audit Setup beta:
   --no-feedback-context             Exclude prior feedback from this setup
   --wait                            Wait for the next actionable setup state
   --timeout <seconds>               Bound next --wait (default 60, maximum 3600)
+  Setup uses saved workspace repositories and context, not local target selections.
+  Use the draft ID returned by setup: apex threat-model status --draft <uuid>.
+  Lite and PR scans do not use --setup.
 `;
 export function cliHelpText(auditSetupEnabled) {
     return auditSetupEnabled
@@ -142,7 +151,7 @@ export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common ar
 
 Commands:
   /credits                Show standard, audit, fix review, and Lite scan entitlements for the active company
-  /scan [standard|audit|lite]
+  /scan [standard|audit|lite] [target...]
                            Start a new Apex scan for this workspace
   /scan pr <pr-number>    Start a PR scan for this workspace
   /scans                  List scans for this workspace
@@ -158,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/local-source-scan.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { createReadStream } from "node:fs";
-import { lstat, mkdtemp, readFile, readdir, readlink, rm, stat, } from "node:fs/promises";
+import { lstat, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -11,6 +11,8 @@ const execFileAsync = promisify(execFile);
 const MAX_ARCHIVE_ENTRIES = 100_000;
 const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
 const BUILTIN_IGNORE_PATTERNS = [
+    ".apex",
+    ".apex/**",
     ".git",
     ".git/**",
     "node_modules",
@@ -89,6 +91,9 @@ async function buildIgnoreMatcher(rootPath) {
             throw new Error(".apexignore is not valid UTF-8.");
         }
         matcher.add(decoded);
+        // Local CLI state is never scan input, even when a broad negation in the
+        // user's ignore file re-includes ordinary generated files.
+        matcher.add([".apex", ".apex/**"]);
     }
     catch (error) {
         if (error.code !== "ENOENT") {
@@ -207,10 +212,19 @@ async function collectDirectoryEntries(rootPath, matcher) {
     return entries;
 }
 async function collectArchiveEntries(source) {
+    if (!source.absolutePath) {
+        throw new Error("A remote repository URL cannot use a local snapshot. Connect its provider or clone it locally, then retry.");
+    }
+    const resolvedRoot = await realpath(source.absolutePath);
+    if (resolvedRoot.split(path.sep).some((segment) => segment.toLowerCase() === ".apex")) {
+        throw new Error("Apex local state (.apex) cannot be selected as scan input. Select your source files or repository instead.");
+    }
     const matcher = await buildIgnoreMatcher(source.absolutePath);
     const gitEntries = await collectGitEntries(source.absolutePath);
-    const rawEntries = gitEntries ??
-        await collectDirectoryEntries(source.absolutePath, matcher);
+    const selectedFiles = source.kind === "directory_candidate" ? source.selectedFiles : undefined;
+    const rawEntries = selectedFiles
+        ? selectedFiles.filter((entry) => !gitEntries || gitEntries.includes(entry))
+        : gitEntries ?? await collectDirectoryEntries(source.absolutePath, matcher);
     const fileEntries = new Set();
     let uncompressedBytes = 0;
     for (const entry of rawEntries.sort(compareArchivePaths)) {
@@ -305,7 +319,13 @@ async function inspectCreatedArchive(archivePath, sourceRoot, expectedFiles, dis
     return { entryCount, uncompressedBytes };
 }
 async function createDeterministicArchive(params) {
+    const sourceRoot = params.source.absolutePath;
+    if (!sourceRoot)
+        throw new Error("Remote repository targets require remote materialization.");
     const { files, uncompressedBytes } = await collectArchiveEntries(params.source);
+    if (files.length === 0) {
+        throw new Error(`No scannable files found in ${params.source.displayName}. Check the target and ignore rules.`);
+    }
     if (files.length > MAX_ARCHIVE_ENTRIES) {
         throw new Error(`Apex local snapshots support at most ${MAX_ARCHIVE_ENTRIES.toLocaleString()} entries per source.`);
     }
@@ -313,7 +333,7 @@ async function createDeterministicArchive(params) {
         throw new Error(`Archive for ${params.source.displayName} exceeds the uncompressed upload limit.`);
     }
     await tar.create({
-        cwd: params.source.absolutePath,
+        cwd: sourceRoot,
         file: params.archivePath,
         gzip: true,
         portable: true,
@@ -334,7 +354,7 @@ async function createDeterministicArchive(params) {
             entry.gname = "root";
         },
     }, files);
-    const observedArchive = await inspectCreatedArchive(params.archivePath, params.source.absolutePath, files, params.source.displayName, params.maxUncompressedBytes);
+    const observedArchive = await inspectCreatedArchive(params.archivePath, sourceRoot, files, params.source.displayName, params.maxUncompressedBytes);
     const manifest = await createArchiveManifest(params.archivePath);
     return {
         ...manifest,

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,11 +24,11 @@ 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:
-- Pass cwd explicitly for repository-specific operations.
+- Pass cwd explicitly for repository-specific operations. repoPaths accepts exact files, directories, or HTTPS repository URLs; remote URLs never fall back to uploading cwd. Use Standard for local changes and unconnected public repositories.
 - Tool calls are always non-interactive and never auto-open a browser.
 - Finding write tools use the same Apex device-login credentials as read tools. Never ask for browser cookies or CANTINA_AUTH_TOKEN. An error requiring CANTINA_AUTH_TOKEN proves the MCP server is outdated; update Apex CLI, re-run apex setup for this client, restart it, and retry.
 - Organization service-key creation, listing, and revocation are intentionally scripted-CLI-only and are not exposed as MCP tools. Never ask a user to paste a service key into a prompt or tool argument. A hosted MCP client supplies it only as the HTTP Authorization header.
@@ -42,6 +43,8 @@ const AUDIT_SETUP_MCP_GUIDE = `
 
 Audit Setup beta:
 - Use apex-scan-setup for a configured workspace, then apex-threat-model.
+- Setup uses saved workspace repositories and context, not repoPaths or local file selections. Never substitute setup for an explicit source scan after AUDIT_SETUP_REQUIRED.
+- Use the draft ID returned by setup for apex-threat-model; setup supports Standard and Audit, not Lite or PR.
 - Read the complete model and get explicit approval before approve with the reviewed sha256 and startScan true.
 - These tools use the local device account. Hosted service-key MCP does not expose Audit Setup.`;
 function mcpWorkflowGuide(auditSetupEnabled) {
@@ -540,7 +543,7 @@ function registerTools(server, auditSetupEnabled = false) {
         }, value => `Threat-model draft ${String(value.draftId)}: ${String(value.state)}.`, input));
     server.registerTool("apex-scan", {
         title: "Start Apex Scan",
-        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths only to scan explicit alternate local roots. Use mode audit for audit scans, mode lite for beta-gated provider-backed Lite scans, and mode pr for GitHub pull request scans.",
+        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths to select exact files, directories, or HTTPS GitHub/GitLab repository URLs. Remote URLs use the default branch; files never include siblings. Use mode audit for audit scans, mode lite for beta-gated provider-backed Lite scans, and mode pr for GitHub pull request scans.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
@@ -753,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/repo-discovery.js

@@ -7,6 +7,8 @@ const execFileAsync = promisify(execFile);
 async function runGit(cwd, args) {
     const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
         encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+        timeout: 30_000,
     });
     return stdout.trim();
 }
@@ -49,18 +51,39 @@ async function chooseRemote(directory) {
         return firstFetch.url;
     return remotes[0]?.url ?? null;
 }
-async function ensureDirectoryCandidate(cwd, directory) {
-    const stats = await lstat(directory).catch(() => null);
-    if (!stats) {
-        throw new Error(`Path does not exist: ${path.relative(cwd, directory) || "."}`);
+function inspectRemoteTarget(value) {
+    if (!/^(?:[a-z][a-z0-9+.-]*:\/\/|git@|(?:github|gitlab)\.com\/)/i.test(value))
+        return null;
+    const target = value.replace(/^(github|gitlab)\.com\//i, "https://$1.com/");
+    let url;
+    try {
+        url = new URL(target);
     }
-    if (stats.isDirectory()) {
-        return directory;
+    catch {
+        throw new Error("Remote scan targets must be HTTPS GitHub or GitLab repository URLs.");
     }
-    if (stats.isFile()) {
-        return path.dirname(directory);
+    const segments = url.pathname.replace(/\/+$/, "").split("/").filter(Boolean);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.port ||
+        !["github.com", "gitlab.com"].includes(url.hostname) || segments.length < 2 ||
+        (url.hostname === "github.com" && segments.length !== 2) || segments.includes("-")) {
+        throw new Error("Remote scan targets must be HTTPS GitHub or GitLab repository URLs without credentials, query strings, or file/tree paths.");
     }
-    throw new Error(`Path is not a directory: ${path.relative(cwd, directory) || "."}`);
+    const metadata = extractCanonicalRepoMetadata(url.href);
+    if (!metadata)
+        throw new Error("Unsupported remote repository target.");
+    return {
+        kind: "git_candidate",
+        path: `remote/${metadata.provider}/${segments.join("/").replace(/\.git$/i, "")}`,
+        absolutePath: null,
+        displayName: metadata.repoName,
+        repoUrl: metadata.repoUrl,
+        provider: metadata.provider,
+        branch: null,
+        commitSha: null,
+        dirty: false,
+        isRoot: false,
+        sourceType: "branch",
+    };
 }
 function normalizeSelectedRoots(cwd, selectedPaths) {
     const resolved = selectedPaths
@@ -86,7 +109,7 @@ async function inspectGitRepository(rootCwd, directory) {
     const metadata = remoteUrl ? extractCanonicalRepoMetadata(remoteUrl) : null;
     const branchName = await runGit(directory, ["rev-parse", "--abbrev-ref", "HEAD"]).catch(() => "HEAD");
     const commitSha = await runGit(directory, ["rev-parse", "HEAD"]).catch(() => null);
-    const dirtyOutput = await runGit(directory, ["status", "--porcelain"]).catch(() => "");
+    const dirtyOutput = await runGit(directory, ["status", "--porcelain", "--", ".", ":(exclude).apex"]).catch(() => null);
     const relativePath = path.relative(rootCwd, directory) || ".";
     const detached = !branchName || branchName === "HEAD";
     return {
@@ -98,13 +121,31 @@ async function inspectGitRepository(rootCwd, directory) {
         provider: metadata?.provider ?? null,
         branch: detached ? null : branchName,
         commitSha: commitSha && commitSha.length > 0 ? commitSha : null,
-        dirty: dirtyOutput.length > 0,
+        // Unknown working-tree state must use a snapshot, never assume the remote
+        // commit contains the user's current files.
+        dirty: dirtyOutput === null || dirtyOutput.length > 0,
         isRoot: relativePath === ".",
         sourceType: detached ? "commit" : "branch",
     };
 }
 async function inspectSource(rootCwd, requestedDirectory) {
-    const directory = await ensureDirectoryCandidate(rootCwd, requestedDirectory);
+    const stats = await lstat(requestedDirectory).catch(() => null);
+    const requestedPath = path.relative(rootCwd, requestedDirectory) || ".";
+    if (!stats)
+        throw new Error(`Path does not exist: ${requestedPath}`);
+    if (stats.isFile()) {
+        return {
+            kind: "directory_candidate",
+            path: requestedPath,
+            absolutePath: path.dirname(requestedDirectory),
+            displayName: path.basename(requestedDirectory),
+            isRoot: false,
+            selectedFiles: [path.basename(requestedDirectory)],
+        };
+    }
+    if (!stats.isDirectory())
+        throw new Error(`Path is not a regular file or directory: ${requestedPath}`);
+    const directory = requestedDirectory;
     const relativePath = path.relative(rootCwd, directory) || ".";
     const gitTopLevel = await getGitTopLevel(directory);
     const comparableDirectory = await resolveComparablePath(directory);
@@ -120,10 +161,22 @@ async function inspectSource(rootCwd, requestedDirectory) {
     };
 }
 export async function discoverSources(cwd, selectedPaths = []) {
-    const discoveredRoots = selectedPaths.length > 0
-        ? normalizeSelectedRoots(cwd, selectedPaths)
-        : [cwd];
-    const sources = await Promise.all(discoveredRoots.map((root) => inspectSource(cwd, root)));
+    const remoteSources = [];
+    const localPaths = [];
+    for (const target of selectedPaths) {
+        const remote = inspectRemoteTarget(target);
+        if (remote) {
+            if (!remoteSources.some((source) => source.path === remote.path))
+                remoteSources.push(remote);
+        }
+        else
+            localPaths.push(target);
+    }
+    const discoveredRoots = selectedPaths.length === 0 ? [cwd] : normalizeSelectedRoots(cwd, localPaths);
+    const sources = [...remoteSources, ...await Promise.all(discoveredRoots.map((root) => inspectSource(cwd, root)))];
+    if (new Set(sources.map((source) => source.path)).size !== sources.length) {
+        throw new Error("Scan targets have conflicting source paths. Select them in separate scans.");
+    }
     sources.sort((left, right) => left.path.localeCompare(right.path));
     return { sources, scanned: discoveredRoots };
 }