Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

61.3 KB
Raw Blame
import { resolve } from "node:path";
import { isDeepStrictEqual } from "node:util";
import {
  semgrepPlatformFindingBinding,
  semgrepPlatformReportScope,
  semgrepPlatformRepositoryReference,
  isSemgrepPlatformEvidence,
  semgrepReferenceMatches,
} from "./semgrep-platform-findings.js";
import {
  gitPathToHttpPath,
  gitServiceHostname,
  isPublicGitHost,
  gitTransportBytes,
  hostedRepositoryMatches,
  normalizeHostedGitRepositoryUrl,
} from "./hosted-git-repository.js";
import {
  checkRetainedTrivyProvider,
  checkTrivyReportProvider,
  matchTrivyCheckout,
} from "./trivy-import.js";
import {
  readGitRemoteNames,
  readHostedGitRemotes,
} from "./hosted-git-remotes.js";
import { CodexSecurityError } from "./errors.js";
import {
  externalImportDisposition,
  NoPublishableFindingsError,
  cloneImportPreview,
  reportForJson,
  snapshotImportOptions,
  snapshotNormalizedFindings,
  snapshotSourceRepositories,
  type ExternalFindings,
  type ExternalSourceRepository,
} from "./external-findings.js";
import {
  cloudRepositoryUrlKey,
  requireSafeJsonInteger,
  repositoryUrlKey,
  validateExternalEvidence,
} from "./external-import-contract.js";
import type {
  ExternalFindingEvidence,
  Provider,
} from "./external-import-models.js";
import {
  EXTERNAL_FINDINGS_PROVIDERS,
  EXTERNAL_FINDINGS_READERS,
  localFindingRepositories,
  semgrepSarifRepositories,
  LOCAL_ONLY_PROVIDERS,
} from "./external-findings-read.js";
import {
  tenableReportFormat,
  tenableSourceRepository,
} from "./tenable-findings.js";
import {
  crowdstrikeCheckout,
  crowdstrikeReportFormat,
} from "./crowdstrike-findings.js";
import {
  guardianFindingRepository,
  guardianSelectionFormat,
} from "./semgrep-guardian-findings.js";
import {
  hasGitMetadata,
  localGitProtectionRoots,
  commandGitProtectionRoots,
} from "./local-git-metadata.js";
import {
  blackDuckReportRepositories,
  projectedBlackDuckRepositoryUrl,
} from "./blackduck-findings.js";
import {
  azureReposHttpsUrl,
  isGitHubCloudHost,
  isGitHubSshOverHttps,
  isGitSsh,
  parseGitRemote,
} from "./git-remote.js";
import { checkmarxSelection } from "./checkmarx-repository.js";
import { continuumReportRepositories } from "./continuum-findings.js";
import { veracodeReportRepositories } from "./veracode-findings.js";
import { inspectorReportRepository } from "./inspector-findings.js";
import { declaredScannerRepositoryUrl } from "./scanner-repository-url.js";
import { armorCodeRepositoryUrl } from "./armorcode-findings.js";
import { sonarRepositoryUrls } from "./sonar-findings.js";
import { isRecord } from "./record.js";
import { dependabotRepository } from "./github-dependabot-findings.js";
import { retainedGitHubRepository } from "./github-findings.js";
import {
  type SnykIssuesFindings,
  snykRestImportRepository,
  snykRestCheckoutMatches,
} from "./snyk-rest-findings.js";
import {
  bundledPluginRoot,
  canonicalConfigPath,
  canonicalizeModelSafePath,
  resolveInputPath,
  resolveParentTraversal,
  requireOutputOutsideRepositories,
  runWorkbench,
  workbenchEnvironment,
  type WorkbenchCommandOptions,
} from "./runtime.js";
import {
  abortable,
  enclosingGitWorktreeRoot,
  gitOutput,
  normalizeRepository,
} from "./targets.js";

/** A scanner source record, independent of a Codex assessment or completed scan. */
export interface StoredExternalFinding {
  id: string;
  repository: string;
  provider: string;
  sourceKey: string;
  sourceFindingId: string;
  evidence: ExternalFindingEvidence;
  assessment: { state: "not_assessed" };
  version: number;
  createdAt: string;
  updatedAt: string;
  /** Reader context required to publish this version without the original file. */
  provenance?: ExternalFindingProvenance;
}

export interface ExternalFindingProvenance {
  sourceRepositories?: ExternalSourceRepository[];
  inspectorProjectMap?: [string, string][];
}

export type LocalExternalFindingSelection = { repository: string } & (
  | {
      importId: string;
      findings?: never;
      /** Return an empty selection if the import is missing or any pinned version has changed. */
      ifCurrent?: boolean;
    }
  | {
      findings: readonly Pick<StoredExternalFinding, "id" | "version">[];
      importId?: never;
    }
);

export interface SelectedLocalExternalFindings extends Omit<
  ExternalFindings,
  "findings"
> {
  findings: StoredExternalFinding[];
}

export interface StoredExternalImport {
  importId: string;
  createdAt: string;
  provider: string;
  sourceKey: string;
  count: number;
}

export interface LocalFindingReceipt {
  id: string;
  version: number;
  receiptId: string;
  outcome: "created" | "updated" | "unchanged" | "private_job";
  cloudFindingId?: string;
}

interface CloudFindingDestination {
  cloudApiUrl: string;
  accountId: string;
  destinationId: string;
}

export interface StoredFindingPublication
  extends LocalFindingReceipt, CloudFindingDestination {
  createdAt: string;
}

export interface NormalizedLocalImportOptions {
  /** Local checkout or source directory to associate with these records. */
  repository: string;
  provider: string;
  /** Stable scanner organization/project/branch namespace across imports. */
  sourceKey: string;
  /** Verified Git repository URL for readers that bind a finding to a checkout. */
  sourceRepositoryUrl?: string;
  /** Full Inspector project ARNs mapped to independently verified repository URLs. */
  inspectorProjectMap?: ReadonlyMap<string, string>;
}

export interface LocalExternalImportDependencies {
  environment?: NodeJS.ProcessEnv;
  signal?: AbortSignal;
  runWorkbench?: typeof runWorkbench;
  /** Repository references supplied by a reader outside its projected evidence. */
  sourceRepositories?: readonly ExternalSourceRepository[];
}

export interface LocalExternalImportPreview extends ExternalFindings {
  repository: string;
  source: {
    provider: string;
    source_key: string;
  };
}

export interface LocalExternalImportResult {
  /** Present when the import saved a nonempty selection, including unchanged rows. */
  importId?: string;
  repository: string;
  read: number;
  report?: ExternalFindings["report"];
  ready: number;
  excluded: ExternalFindings["excluded"];
  findings: StoredExternalFinding[];
  counts: { created: number; updated: number; unchanged: number };
}

export interface PreparedLocalExternalImport {
  /** Every declared source matched a configured Git remote of the checkout. */
  matchesRepositoryRemote: boolean;
  preview: LocalExternalImportPreview;
  import(): Promise<LocalExternalImportResult>;
}

function requireIdentity(
  value: unknown,
  field: string,
): asserts value is string {
  if (typeof value !== "string" || !value.trim() || value.includes("\0"))
    throw new CodexSecurityError(
      `${field} must be nonempty and contain no NUL characters.`,
    );
  if (!value.isWellFormed())
    throw new CodexSecurityError(`${field} must contain valid Unicode.`);
}

function validateFindingIds(current: ExternalFindings) {
  const identities = new Set<string>();
  for (const finding of current.findings) {
    requireIdentity(finding.source_finding_id, "Source finding id");
    if (identities.has(finding.source_finding_id))
      throw new CodexSecurityError(
        `Duplicate source finding id ${JSON.stringify(finding.source_finding_id)}.`,
      );
    identities.add(finding.source_finding_id);
    if (!isRecord(finding.evidence))
      throw new CodexSecurityError("Imported evidence must be an object.");
    if (
      typeof finding.evidence.title !== "string" ||
      typeof finding.evidence.severity !== "string"
    )
      throw new CodexSecurityError(
        "Imported evidence requires a title and severity.",
      );
  }
}

function checkStoredNumber(value: number): void {
  if (!Number.isFinite(value))
    throw new TypeError(
      "Stored finding JSON cannot contain non-finite numbers.",
    );
  requireSafeJsonInteger(value, "Stored finding JSON");
}

const gitTransportPorts: Readonly<Record<string, string>> = {
  "http:": "80",
  "https:": "443",
  "ssh:": "22",
  "git+ssh:": "22",
  "ssh+git:": "22",
  "git:": "9418",
  "ftp:": "21",
  "ftps:": "990",
};

/** Compare transport forms without changing retained scanner evidence. */
interface RemoteRepositoryIdentity {
  key: string;
  account?: string;
  homeRelative?: boolean;
}

function sonarHostedHostname(hostname: string) {
  const name = gitServiceHostname(hostname.toLowerCase());
  return isPublicGitHost(name) ||
    ["ssh.github.com", "ssh.dev.azure.com", "dev.azure.com"].includes(name)
    ? name
    : undefined;
}

function remoteRepository(
  value: string,
  provider: Provider,
  bound: boolean,
  platform: Provider = provider,
  possibleSshHost?: string,
): RemoteRepositoryIdentity | undefined {
  if (/^[A-Za-z]:[\\/]/u.test(value)) return undefined;
  const transport = bound
    ? /^(?:ssh|git\+ssh|ssh\+git|git):\/\/([^/]*)(.*)$/isu.exec(value)
    : null;
  const authority = transport?.[1];
  const http = bound && /^https?:\/\//iu.test(value.trimStart());
  // Git decodes the authority before locating its path. An encoded delimiter
  // cannot prove a match to another spelling through WHATWG URL's hostname.
  if (
    authority &&
    (/%2f|[?#]/iu.test(authority) ||
      authority.slice(authority.lastIndexOf("@") + 1).includes("%"))
  )
    return { key: value };
  let remote;
  try {
    remote = parseGitRemote(value);
  } catch {
    return transport || http ? { key: "\0" + value } : undefined;
  }
  if (!remote || !Object.hasOwn(gitTransportPorts, remote.url.protocol))
    return undefined;
  const { url, path, scpStyle } = remote;
  const ssh = isGitSsh(url.protocol);
  const protocol = url.protocol === "http:" ? "http:" : "https:";
  const hosted = sonarHostedHostname(url.hostname);
  if (provider === "sonar" && hosted) url.hostname = hosted;
  const githubSshOverHttps = isGitHubSshOverHttps(url);
  let hostname = githubSshOverHttps ? "github.com" : url.hostname;
  // An unresolved SSH name can be a local Host alias. Only substitute the
  // supplied hostname when checking the path of an unverified manual mapping.
  if (possibleSshHost && ssh && (!hosted || hosted === "dev.azure.com"))
    hostname = sonarHostedHostname(possibleSshHost) ?? possibleSshHost;
  const port =
    githubSshOverHttps || url.port === gitTransportPorts[url.protocol]
      ? ""
      : url.port;
  // A GitHub source identifies a case-insensitive repository on custom Enterprise
  // hosts too; other providers can refer to VCS hosts with case-sensitive paths.
  const key = platform === "github" ? cloudRepositoryUrlKey : repositoryUrlKey;
  const origin = `${protocol}//${hostname}${port ? `:${port}` : ""}/`;
  if (!bound) return { key: key(origin + path) };

  if (!ssh && url.protocol !== "git:") {
    if (url.protocol === "http:" || url.protocol === "https:") {
      // libcurl and WHATWG differ on backslashes and encoded dot segments.
      const raw = /^https?:\/\/[^/\\?#\s]+(\/[^\\?#]*)?(?:[?#].*)?$/iu.exec(
        value,
      );
      if (!raw || /\/(?:%2e|\.%2e|%2e\.|%2e%2e)(?:\/|$)/iu.test(raw[1] ?? ""))
        return { key: "\0" + value };
    }
    const suffix = /[?#].*$/su.exec(value)?.[0] ?? "";
    // HTTP sends the query and omits fragment text from repository requests.
    if (suffix && !["http:", "https:"].includes(url.protocol))
      return { key: key(origin + path) + "\0" };
    return {
      key:
        key(origin + path) + suffix.replace(/#.*$/su, "#").replace(/\/$/u, ""),
    };
  }

  // Git passes the original path (including dot segments, '?' and '#') to upload-pack.
  if (!scpStyle && !transport) return { key: value };
  const gitPath = gitTransportBytes(transport?.[2] ?? path, scpStyle);
  const login = scpStyle
    ? /^([^@/:\s?#]+)@/u.exec(value)?.[1]
    : /^(.*)@/u.exec(authority ?? "")?.[1];
  const homeRelative =
    /^\/?~(?:\/|$)/u.test(gitPath) || (scpStyle && !/^[~/]/u.test(gitPath));
  const suffix = /[?#].*$/su.exec(gitPath);
  // Express upload-pack bytes as a URL path for comparison with the HTTP source.
  const name = gitPathToHttpPath(gitPath.slice(0, suffix?.index));
  // Azure's generated SCP clone URL spells spaces as %20, even though Git sends SCP paths literally.
  const azure =
    (provider === "sonar" || provider === "checkmarx") &&
    !(scpStyle && path.startsWith("/"))
      ? azureReposHttpsUrl(
          url,
          scpStyle ? name.replace(/%2520/gu, "%20") : name,
        )
      : undefined;
  const repository = suffix
    ? key(origin + name + "?") +
      "\0" +
      suffix[0].replace(/\/$/u, "").replace(/\.git$/u, "")
    : key(azure ?? origin + name);
  return {
    key: repository,
    account: ssh && login ? gitTransportBytes(login, scpStyle) : undefined,
    // GitHub serves the same repository path through its SCP and SSH URLs.
    homeRelative:
      ssh && platform !== "github" && !isGitHubCloudHost(hostname.toLowerCase())
        ? homeRelative
        : undefined,
  };
}

function matchingRemote(
  left: RemoteRepositoryIdentity,
  right: RemoteRepositoryIdentity,
) {
  return (
    left.key === right.key &&
    (left.homeRelative === undefined ||
      right.homeRelative === undefined ||
      left.homeRelative === right.homeRelative) &&
    ((left.homeRelative === false && right.homeRelative === false) ||
      left.account === undefined ||
      right.account === undefined ||
      left.account === right.account)
  );
}

// Within one fetch key and home-relative mode, matchingRemote can use any
// account, the requested login, or an unspecified login.
function fetchAliasMatcher(
  rows: readonly { fetch: RemoteRepositoryIdentity }[],
) {
  const homes = Map.groupBy(rows, ({ fetch }) => fetch.homeRelative);
  const accounts = Array.from(
    homes.values(),
    (group) => new Map(group.map(({ fetch }) => [fetch.account, fetch])),
  );
  return (fetch: RemoteRepositoryIdentity) =>
    accounts.some((group) =>
      [
        group.values().next().value,
        group.get(fetch.account),
        group.get(undefined),
      ].some(
        (candidate) =>
          candidate !== undefined && matchingRemote(fetch, candidate),
      ),
    );
}

function fetchAliasMatchers<
  Row extends { fetch: RemoteRepositoryIdentity },
  Key,
>(rows: readonly Row[], key: (row: Row) => Key) {
  return new Map(
    Array.from(
      Map.groupBy(rows, key),
      ([name, group]) => [name, fetchAliasMatcher(group)] as const,
    ),
  );
}

/** A credential-free Sonar repository binding from a supported Git fetch transport. */
export function sonarRepositoryForRemote(origin: string): string | undefined {
  try {
    if (/[\s\\\p{Cc}?#]/u.test(origin)) return;
    const remote = parseGitRemote(origin);
    if (!remote) return;
    const { url } = remote;
    // Git dispatches remote helpers by the literal scheme, while URL lowercases it.
    if (!remote.scpStyle && !origin.startsWith(url.protocol + "//")) return;
    // Git passes literal SSH paths to upload-pack. URL.pathname collapses dot segments.
    const path = remote.scpStyle
      ? remote.path
      : /^[^:/]+:\/\/[^/]+\/(.+)$/u.exec(origin)?.[1];
    if (!path) return;
    const hostname = url.hostname.toLowerCase();
    let candidate: string | undefined;
    if (url.protocol === "http:" || url.protocol === "https:") {
      candidate = `${url.origin}/${path}`;
    } else if (url.username === "git" && isGitHubSshOverHttps(url)) {
      candidate = `https://github.com/${path}`;
    } else if (
      isGitSsh(url.protocol) &&
      url.username === "git" &&
      (!url.port || url.port === "22") &&
      isPublicGitHost(hostname)
    ) {
      candidate = `https://${hostname}/${path}`;
    } else {
      candidate = azureReposHttpsUrl(url, path);
    }
    if (!candidate) return;
    const source = declaredScannerRepositoryUrl(
      candidate.replace(/\.git$/iu, ""),
      "Sonar",
      "local",
    );
    const candidateRemote = remoteRepository(origin, "sonar", true);
    const target = remoteRepository(source, "sonar", true);
    if (isGitSsh(url.protocol) && candidateRemote?.account !== "git") return;
    return candidateRemote && target && matchingRemote(candidateRemote, target)
      ? source
      : undefined;
  } catch {
    return undefined;
  }
}

/** Use the same executable and configuration boundaries for every Git query proving a binding. */
export function boundSonarWorktree(
  repository: string,
  protectedRoots: string | readonly string[],
  environment: NodeJS.ProcessEnv | undefined,
  signal?: AbortSignal,
) {
  return enclosingGitWorktreeRoot(repository, signal, {
    requireIfPresent: true,
    readGit: (directory, args) =>
      gitOutput(
        directory,
        args,
        signal,
        undefined,
        undefined,
        "utf8",
        protectedRoots,
        environment,
      ),
  });
}

function localRepositoryPlatform(
  provider: Provider,
  sources: readonly ExternalSourceRepository[],
  bound: boolean,
) {
  const githubKey = (url: string) =>
    remoteRepository(url, provider, bound, "github")?.key;
  const githubRepositories = new Set(
    sources.flatMap((source) => {
      if (source.platform !== "github") return [];
      const key = githubKey(source.url);
      return key === undefined ? [] : [key];
    }),
  );
  return (source: ExternalSourceRepository): Provider => {
    if (source.platform === "github") return "github";
    if (githubRepositories.size === 0) return provider;
    const key = githubKey(source.url);
    return key !== undefined && githubRepositories.has(key)
      ? "github"
      : provider;
  };
}

function sameScannerRepositories(
  remotes: Iterable<RemoteRepositoryIdentity>,
): boolean {
  let known: RemoteRepositoryIdentity | undefined;
  for (const remote of remotes) {
    if (known && !matchingRemote(known, remote)) return false;
    // HTTPS does not specify the login or path interpretation carried by SSH.
    known = {
      key: remote.key,
      account: remote.account ?? known?.account,
      homeRelative: remote.homeRelative ?? known?.homeRelative,
    };
  }
  return true;
}

/** @internal */
export interface ConfiguredFetchRemote {
  name: string;
  url: string;
}

/** @internal Effective fetch URLs from the selected, protected checkout. */
export async function configuredFetchRemotes(
  repository: string,
  provider: Provider,
  protectedRoots: WorkbenchCommandOptions["protectedRoot"],
  environment: WorkbenchCommandOptions["environment"],
  signal?: AbortSignal,
): Promise<ConfiguredFetchRemote[]> {
  if (!(await hasGitMetadata(repository, signal))) return [];
  const gitProtectedRoots = [
    ...(typeof protectedRoots === "string"
      ? [protectedRoots]
      : (protectedRoots ?? [])),
  ];
  // The Sonar caller includes the discovered Git roots for both checkouts.
  if (provider !== "sonar")
    gitProtectedRoots.push(
      await abortable(() => canonicalConfigPath(process.cwd()), signal),
    );
  if (
    provider === "sonar" &&
    !(await boundSonarWorktree(
      repository,
      gitProtectedRoots,
      environment,
      signal,
    ))
  )
    return [];
  const readGit = (args: readonly string[]) =>
    abortable(
      () =>
        gitOutput(
          repository,
          args,
          signal,
          { LC_ALL: "C" },
          undefined,
          "utf8",
          gitProtectedRoots,
          environment,
        ),
      signal,
    );
  const remoteNames = await readGitRemoteNames(readGit, signal);
  if (remoteNames === undefined) return [];
  const remotes: ConfiguredFetchRemote[] = [];
  const firstUrlOnly = provider === "sonar" || provider === "checkmarx";
  for (const name of remoteNames.split(/\r?\n/u).filter(Boolean)) {
    if (firstUrlOnly) {
      // Git fetches from only the first URL, after insteadOf rewrites.
      const url = await readGit(["remote", "get-url", "--", name]);
      if (/[\r\n]/u.test(url))
        throw new CodexSecurityError(
          "A configured Git remote URL contains a line break. Configure each fetch URL as a separate Git value.",
        );
      remotes.push({ name, url });
    } else {
      const urls = await readGit(["remote", "get-url", "--all", "--", name]);
      for (const url of urls.split(/\r?\n/u)) remotes.push({ name, url });
    }
  }
  return remotes;
}

async function hostedCheckoutRemotes(
  repository: string,
  protectedRoots: readonly string[],
  environment: WorkbenchCommandOptions["environment"],
  signal?: AbortSignal,
) {
  if (!(await hasGitMetadata(repository, signal))) return undefined;
  return readHostedGitRemotes(
    repository,
    [...protectedRoots, await canonicalConfigPath(process.cwd())],
    environment,
    signal,
  );
}

async function requireMatchingRepository(
  repository: string,
  provider: Provider,
  sources: readonly ExternalSourceRepository[],
  strictSources: ReadonlyMap<string, Provider>,
  hostedSources: readonly ExternalSourceRepository[],
  platformFor: (source: ExternalSourceRepository, bound: boolean) => Provider,
  snyk: ReturnType<typeof snykRestImportRepository>,
  protectedRoots: string[],
  environment: WorkbenchCommandOptions["environment"],
  signal?: AbortSignal,
  possibleSshHost?: string,
  fetchRemotes?: readonly ConfiguredFetchRemote[],
  isCheckmarxSource?: (url: string) => boolean,
): Promise<boolean> {
  if (!snyk && sources.length === 0 && hostedSources.length === 0) return false;
  let allSourcesMatched = true;
  if (snyk || hostedSources.length) {
    const remotes = await hostedCheckoutRemotes(
      repository,
      protectedRoots,
      environment,
      signal,
    );
    if (snyk) {
      if (
        remotes &&
        !remotes.some((remote) => snykRestCheckoutMatches(snyk, remote))
      )
        throw new CodexSecurityError(
          `Imported repository ${JSON.stringify(snyk.url)} does not match a configured remote of ${repository}. Select the matching local repository.`,
        );
      return remotes !== undefined;
    }
    allSourcesMatched = remotes !== undefined;
    if (remotes) {
      for (const source of hostedSources)
        if (!remotes.some((remote) => hostedRepositoryMatches(source, remote)))
          throw new CodexSecurityError(
            `Imported repository ${JSON.stringify(source.url)} does not match a configured remote of ${repository}. Select the matching local repository.`,
          );
    }
    if (!sources.length) return allSourcesMatched;
  }
  const remoteProvider = (checkmarx?: boolean) =>
    checkmarx && provider !== "sonar" ? "checkmarx" : provider;
  const remotes =
    fetchRemotes ??
    (await configuredFetchRemotes(
      repository,
      remoteProvider(Boolean(isCheckmarxSource)),
      protectedRoots,
      environment,
      signal,
    ));
  const boundProvider =
    provider === "sonar" ||
    provider === "checkmarx" ||
    provider === "continuum" ||
    provider === "inspector" ||
    provider === "blackduck" ||
    provider === "veracode";
  const comparable: string[] = [];
  const unverified: string[] = [];
  for (const { url: remote } of remotes) {
    const verified =
      provider === "sonar" ? sonarRepositoryForRemote(remote) : remote;
    if (verified) comparable.push(verified);
    else if (!/[\s\\\p{Cc}?#]/u.test(remote)) unverified.push(remote);
  }
  for (const source of sources) {
    const bound = boundProvider || strictSources.has(source.url);
    const platform =
      strictSources.get(source.url) ?? platformFor(source, bound);
    const sourceProvider = remoteProvider(isCheckmarxSource?.(source.url));
    const identity = (url: string, fallbackHost?: string) =>
      remoteRepository(url, sourceProvider, bound, platform, fallbackHost);
    const targets = comparable.flatMap((remote) => identity(remote) ?? []);
    const target = identity(source.url);
    if (target && targets.some((remote) => matchingRemote(remote, target)))
      continue;
    allSourcesMatched = false;
    // A custom SSH upstream can agree with a manual mapping even when a
    // recognized HTTPS remote points at a fork. It cannot prove a Cloud binding.
    const configured = unverified.flatMap(
      (remote) => identity(remote, possibleSshHost) ?? [],
    );
    if (target && configured.some((remote) => matchingRemote(remote, target)))
      continue;
    if (targets.length || configured.length)
      throw new CodexSecurityError(
        `Imported repository ${JSON.stringify(source.url)} does not match a configured remote of ${repository}. Select the matching local repository.`,
      );
  }
  return allSourcesMatched;
}

export function sonarCheckoutMatchesSource(
  repository: string,
  url: string,
  protectedRoots: readonly string[],
  environment: NodeJS.ProcessEnv,
  signal?: AbortSignal,
) {
  return requireMatchingRepository(
    repository,
    "sonar",
    [{ url }],
    new Map(),
    [],
    () => "sonar",
    undefined,
    [...protectedRoots],
    environment,
    signal,
  );
}

/** @internal Resolve and protect the local checkout and workbench state directory. */
async function localContext(
  selectedRepository: string,
  dependencies: LocalExternalImportDependencies,
  mode: "import" | "read" = "import",
) {
  dependencies.signal?.throwIfAborted();
  const environment = workbenchEnvironment(
    dependencies.environment ?? process.env,
  );
  const requested = resolveInputPath(
    selectedRepository,
    process.cwd(),
    environment,
  );
  const path = await abortable(
    () => resolveParentTraversal(requested),
    dependencies.signal,
  );
  const repository =
    mode === "read"
      ? await abortable(() => canonicalConfigPath(path), dependencies.signal)
      : await normalizeRepository(path, dependencies.signal);
  const lexicalPath = resolve(requested);
  const lexicalRepository =
    lexicalPath === resolve(path)
      ? repository
      : await abortable(
          () => canonicalConfigPath(lexicalPath),
          dependencies.signal,
        );
  const protectedRoot = [
    ...new Set([
      repository,
      ...(mode === "read" ? [lexicalRepository] : []),
      ...(await abortable(
        () =>
          commandGitProtectionRoots(path, environment, dependencies.signal, {
            requestedPaths: [lexicalPath, lexicalRepository],
          }),
        dependencies.signal,
      )),
    ]),
  ];
  requireOutputOutsideRepositories(
    protectedRoot,
    await abortable(
      () => canonicalizeModelSafePath(environment.CODEX_SECURITY_STATE_DIR),
      dependencies.signal,
    ),
    "runtime",
  );
  return {
    repository,
    selectedPath: path,
    options: {
      pluginRoot: await abortable(
        () => bundledPluginRoot(),
        dependencies.signal,
      ),
      environment,
      protectedRoot,
      signal: dependencies.signal,
      failureMessage: "Could not access imported local findings",
    },
  };
}

/** Prepare scanner evidence without writing state or performing a security assessment. */
export async function prepareNormalizedLocalImport(
  input: ExternalFindings,
  options: NormalizedLocalImportOptions,
  dependencies: LocalExternalImportDependencies = {},
): Promise<PreparedLocalExternalImport> {
  const { signal } = dependencies;
  signal?.throwIfAborted();
  const settings = snapshotImportOptions(options);
  const reader = EXTERNAL_FINDINGS_READERS.find(
    (name) => name === settings.provider,
  );
  if (reader)
    return prepareLocalImport(
      input,
      { ...settings, provider: EXTERNAL_FINDINGS_PROVIDERS[reader] },
      dependencies,
    );

  const references = snapshotSourceRepositories(
    dependencies.sourceRepositories,
  );
  requireIdentity(settings.provider, "Provider");
  requireIdentity(settings.sourceKey, "Source key");
  const current = snapshotNormalizedFindings(input, checkStoredNumber);
  validateFindingIds(current);
  if (current.report !== undefined && !isRecord(current.report))
    throw new CodexSecurityError("Report metadata must be an object.");
  if (current.read !== current.findings.length + current.excluded.length)
    throw new CodexSecurityError(
      "Every source record must be accounted for by a finding or exclusion.",
    );
  const positions = new Set<number>();
  for (const { position, source_finding_id, reason } of current.excluded) {
    if (
      !Number.isSafeInteger(position) ||
      position < 1 ||
      position > current.read ||
      positions.has(position)
    )
      throw new CodexSecurityError(
        "An excluded position must be unique and within the reported record count.",
      );
    positions.add(position);
    requireIdentity(reason, "Exclusion reason");
    if (source_finding_id !== null)
      requireIdentity(source_finding_id, "Excluded source finding id");
  }

  const platform = references.find((ref) => ref.platform)?.platform;
  const urls = new Set(references.map(({ url }) => url));
  if (settings.sourceRepositoryUrl !== undefined)
    urls.add(settings.sourceRepositoryUrl);
  for (const finding of current.findings) {
    finding.evidence = validateExternalEvidence(finding.evidence, "local");
    const repository = finding.evidence.details?.repository;
    if (repository) urls.add(repository.url);
  }
  const sources = Array.from(urls, (url) => ({
    url: declaredScannerRepositoryUrl(url, settings.provider, "local"),
    platform,
  }));
  const [source] = sources;
  const context = await localContext(settings.repository, dependencies);
  let matched = false;
  if (source) {
    if (
      references.some((ref) => ref.platform && ref.platform !== platform) ||
      sources.some(({ url }) => !hostedRepositoryMatches(source, url))
    )
      throw new CodexSecurityError(
        "The findings declare conflicting source repositories.",
      );
    const remotes = await hostedCheckoutRemotes(
      context.repository,
      context.options.protectedRoot,
      context.options.environment,
      signal,
    );
    matched =
      remotes?.some((remote) => hostedRepositoryMatches(source, remote)) ??
      false;
    if (
      !matched &&
      remotes?.some((remote) =>
        /^https?:\/\//iu.test(
          normalizeHostedGitRepositoryUrl(
            remote,
            undefined,
            platform !== undefined,
          ),
        ),
      )
    )
      throw new CodexSecurityError(
        `Imported repository ${JSON.stringify(source.url)} does not match a configured fetch remote of ${context.repository}.`,
      );
  }
  return preparedLocalStorage(
    current,
    settings,
    context,
    dependencies,
    matched,
    { sourceRepositories: sources },
  );
}

// A scanner can repeat the same repository reference for every finding in a run.
export function distinctSourceRepositories(
  sources: readonly ExternalSourceRepository[],
) {
  const seen = new Map<ExternalSourceRepository["platform"], Set<string>>();
  return sources.filter(({ url, platform }) => {
    const urls = seen.get(platform) ?? new Set<string>();
    if (urls.has(url)) return false;
    urls.add(url);
    seen.set(platform, urls);
    return true;
  });
}

/** @internal Prepare evidence using settings captured by either local import entrypoint. */
export async function prepareLocalImport(
  input: ExternalFindings & Partial<SnykIssuesFindings>,
  options: NormalizedLocalImportOptions &
    (
      | { provider: "tenable" }
      | { provider: "crowdstrike" }
      | { provider: Provider }
    ),
  dependencies: LocalExternalImportDependencies,
  readerSources = distinctSourceRepositories(
    snapshotSourceRepositories(dependencies.sourceRepositories),
  ),
  parsedInput?: readonly ExternalSourceRepository[],
  fetchRemotes?: readonly ConfiguredFetchRemote[],
): Promise<PreparedLocalExternalImport> {
  requireIdentity(options.sourceKey, "Source key");
  const parsedSources = distinctSourceRepositories(parsedInput ?? []);
  // File readers interpret their source option while parsing. For normalized
  // input the caller declares one repository for the whole selection.
  const normalizedSource =
    parsedInput === undefined && options.sourceRepositoryUrl !== undefined
      ? declaredScannerRepositoryUrl(
          options.sourceRepositoryUrl,
          options.provider,
          "local",
        )
      : undefined;
  const current = snapshotNormalizedFindings(
    input,
    checkStoredNumber,
    "local",
    options.provider,
  );
  for (const [provider, format] of [
    ["tenable", tenableReportFormat],
    ["crowdstrike", crowdstrikeReportFormat],
  ] as const)
    if (
      options.provider !== provider &&
      (current.report?.["format"] === format ||
        current.findings.some(
          (row) => row.evidence?.source_data?.["format"] === format,
        ))
    )
      throw new CodexSecurityError(
        `Retained ${LOCAL_ONLY_PROVIDERS[provider]} evidence requires the ${provider} provider.`,
      );
  checkTrivyReportProvider(options.provider, current.report);
  let dependabotSource: string | undefined;
  validateFindingIds(current);
  for (const finding of current.findings) {
    checkRetainedTrivyProvider(options.provider, finding, "local");
    if (options.provider !== "github") continue;
    const native = dependabotRepository(finding);
    if (!native) continue;
    const claimed = finding.evidence.details?.repository?.url;
    if (
      claimed &&
      cloudRepositoryUrlKey(claimed) !== cloudRepositoryUrlKey(native)
    )
      throw new CodexSecurityError(
        "The normalized repository does not match the original Dependabot alert.",
      );
    if (dependabotSource && dependabotSource !== native)
      throw new CodexSecurityError(
        "Select Dependabot alerts from only one GitHub host and repository.",
      );
    dependabotSource = native;
  }
  const context = await localContext(options.repository, dependencies);
  // Neither report records the checkout, so check the operator's URL against its remotes.
  const requireFetchRemote = async (
    source: ExternalSourceRepository,
    provider: keyof typeof LOCAL_ONLY_PROVIDERS,
  ) => {
    const remotes = await hostedCheckoutRemotes(
      context.repository,
      context.options.protectedRoot,
      context.options.environment,
      dependencies.signal,
    );
    if (!remotes?.some((remote) => hostedRepositoryMatches(source, remote)))
      throw new CodexSecurityError(
        `${LOCAL_ONLY_PROVIDERS[provider]}'s source repository must match a configured Git fetch remote of the selected checkout.`,
      );
  };
  if (options.provider === "tenable") {
    const source = tenableSourceRepository(
      current,
      options.sourceRepositoryUrl,
      [...readerSources, ...parsedSources],
    );
    await requireFetchRemote(source, "tenable");
    return preparedLocalStorage(current, options, context, dependencies, true, {
      sourceRepositories: [source],
    });
  }
  if (options.provider === "crowdstrike") {
    const source = await crowdstrikeCheckout(
      current,
      options.sourceRepositoryUrl,
      [...readerSources, ...parsedSources],
      context.repository,
    );
    // FCS scans plain directories; only a Git checkout has remotes to compare.
    const bound =
      source !== undefined &&
      (await hasGitMetadata(context.repository, dependencies.signal));
    if (bound) await requireFetchRemote(source, "crowdstrike");
    return preparedLocalStorage(
      current,
      options,
      context,
      dependencies,
      bound,
      source ? { sourceRepositories: [source] } : {},
    );
  }
  const { repository, options: workbenchOptions } = context;
  const sources = new Map<string, ExternalSourceRepository>();
  const references = [...readerSources, ...parsedSources];
  const inspector = inspectorReportRepository(
    options.provider,
    current.findings,
    "local",
    options.inspectorProjectMap,
  );
  const checkmarx = checkmarxSelection(
    options.provider,
    current.findings,
    current.report,
    "local",
  );
  const projected = current.findings.filter(
    (finding) =>
      (options.provider !== "blackduck" &&
        projectedBlackDuckRepositoryUrl(finding, "local")) ||
      checkmarx.projections.has(finding),
  );
  const mixed = projected.length > 0 && readerSources.length > 0;
  const nativeSources = new Map(
    (mixed || normalizedSource ? current.findings : projected)
      .filter(
        ({ evidence }) =>
          options.provider !== "endor" ||
          isRecord(evidence.source_data?.["runContext"]),
      )
      .map(
        (finding) =>
          [
            finding,
            localFindingRepositories(options.provider, finding),
          ] as const,
      ),
  );
  const platformFor = localRepositoryPlatform(
    options.provider,
    options.inspectorProjectMap
      ? []
      : [
          ...references,
          ...Array.from(nativeSources.values()).flat(),
          ...(inspector ? [inspector] : []),
        ],
    true,
  );
  const identify = (url: string) =>
    remoteRepository(url, options.provider, true, platformFor({ url })) ?? {
      key: url,
    };
  // A hint from an independent reader applies across projected rows. A native
  // GitHub asset in one row only identifies the platform of that row's claims.
  const operatorPlatform = localRepositoryPlatform(
    options.provider,
    readerSources,
    true,
  );
  const sameRepositories = (urls: Iterable<string>) =>
    sameScannerRepositories(Array.from(urls, identify));
  const bound = blackDuckReportRepositories(
    options.provider,
    current.findings,
    "local",
    sameRepositories,
  );
  const checkmarxRepository = checkmarx.repositories(sameRepositories);
  for (const repositories of [
    veracodeReportRepositories,
    continuumReportRepositories,
  ]) {
    for (const source of repositories(
      options.provider,
      current.findings,
      "local",
      sameRepositories,
    ).values()) {
      sources.set(source.url, source);
    }
  }
  const strictSources = new Map<string, Provider>();
  const checkmarxKeys = new Set<string>();
  const hostedSources = new Map<string, ExternalSourceRepository>();
  const semgrepReportScope = semgrepPlatformReportScope(
    current,
    options.provider,
    readerSources,
  );
  const semgrepPlatformRepositoryUrl = semgrepReportScope?.url;
  function addSemgrepSource(url: string) {
    if (options.provider !== "semgrep")
      throw new CodexSecurityError(
        "Use the semgrep provider for Semgrep Platform findings.",
      );
    const source = semgrepPlatformRepositoryReference(url, readerSources);
    if (
      semgrepPlatformRepositoryUrl &&
      semgrepPlatformRepositoryUrl !== url &&
      !semgrepReferenceMatches(source, semgrepPlatformRepositoryUrl)
    )
      throw new CodexSecurityError(
        "The Semgrep report repository does not match the native finding's project.",
      );
    hostedSources.set(source.url, source);
  }
  function addGuardianSource(value: unknown) {
    if (options.provider !== "semgrep")
      throw new CodexSecurityError(
        "Use the semgrep provider for Guardian findings.",
      );
    const url = declaredScannerRepositoryUrl(value, "Guardian", "local");
    const source =
      hostedSources.get(url) ??
      semgrepPlatformRepositoryReference(url, readerSources);
    hostedSources.set(url, source);
    return source;
  }
  const guardianReport =
    current.report?.["format"] === guardianSelectionFormat
      ? addGuardianSource(current.report["repositoryUrl"])
      : undefined;
  if (semgrepPlatformRepositoryUrl)
    addSemgrepSource(semgrepPlatformRepositoryUrl);
  const known = new Set<string>(parsedSources.map(({ url }) => url));
  const hasPlatformEvidence =
    options.provider === "semgrep" &&
    (semgrepReportScope !== undefined ||
      current.findings.some((row) =>
        isSemgrepPlatformEvidence(row, options.provider),
      ));
  let hasOrdinaryRows = false;
  let ordinaryRowNeedsReferences = false;
  for (const finding of current.findings) {
    const retained =
      bound.get(finding.source_finding_id) ?? checkmarxRepository(finding);
    const native = nativeSources.get(finding) ?? [];
    const sarif =
      hasPlatformEvidence ||
      (normalizedSource && options.provider === "semgrep")
        ? semgrepSarifRepositories(finding)
        : [];
    if (normalizedSource) for (const source of sarif) known.add(source.url);
    const semgrep = semgrepPlatformFindingBinding(
      finding,
      options.provider,
      readerSources,
      semgrepReportScope,
      [retained, ...native, ...sarif],
    );
    if (semgrep) {
      addSemgrepSource(semgrep.url);
      if (semgrep.sourceData) finding.evidence.source_data = semgrep.sourceData;
      if (semgrep.migration) Object.assign(finding.evidence, semgrep.migration);
    }
    const { evidence } = finding;
    if (options.provider === "armorcode") {
      const nativeUrl = armorCodeRepositoryUrl(evidence.source_data, "local");
      if (nativeUrl) sources.set(nativeUrl, { url: nativeUrl });
    }
    if (options.provider === "github") {
      const source = retainedGitHubRepository(
        finding,
        (url) => identify(url).key,
      );
      if (source) sources.set(source, { url: source, platform: "github" });
    }
    const guardian = guardianFindingRepository(finding, "local");
    const url = evidence.details?.repository?.url;
    if (guardian) {
      const source = addGuardianSource(guardian);
      if (
        (guardianReport &&
          !semgrepReferenceMatches(guardianReport, source.url)) ||
        (url &&
          !semgrepReferenceMatches(
            source,
            declaredScannerRepositoryUrl(url, "Guardian", "local"),
          ))
      )
        throw new CodexSecurityError(
          "The Guardian finding repository does not match its recorded selection.",
        );
    } else if (!semgrep) {
      hasOrdinaryRows = true;
      if (url) sources.set(url, { url });
    }
    if (
      hasPlatformEvidence &&
      !semgrep &&
      !guardian &&
      !retained &&
      !native.length
    ) {
      for (const source of sarif) sources.set(source.url, source);
      if (!url && !sarif.length) ordinaryRowNeedsReferences = true;
      if (!url && references.length) {
        for (const source of sarif) {
          const claim = identify(source.url);
          if (
            !references.some((ref) => matchingRemote(claim, identify(ref.url)))
          )
            throw new CodexSecurityError(
              `The reader must supply the projected Semgrep SARIF repository ${JSON.stringify(source.url)} for the configured remote.`,
            );
        }
      }
    }
    const projectedCheckmarx = checkmarx.projections.has(finding);
    if (retained || (projectedCheckmarx && native.length)) {
      const rowSources = retained ? [retained, ...native] : native;
      const claims = [
        ...rowSources.map((ref) => ref.url),
        ...(url ? [url] : []),
      ];
      const rowPlatform = (claim: string) =>
        options.provider !== "wiz"
          ? platformFor({ url: claim })
          : native.some((source) => source.platform === "github")
            ? "github"
            : operatorPlatform({ url: claim });
      if (
        !sameScannerRepositories(
          claims.map(
            (claim) =>
              remoteRepository(
                claim,
                options.provider,
                true,
                rowPlatform(claim),
              ) ?? {
                key: claim,
              },
          ),
        )
      )
        throw new CodexSecurityError(
          "The retained scanner repository does not match the original provider finding.",
        );
      for (const source of rowSources) sources.set(source.url, source);
      for (const claim of claims) {
        if (projectedCheckmarx) checkmarxKeys.add(identify(claim).key);
        const platform = rowPlatform(claim);
        if (!strictSources.has(claim) || platform !== "github")
          strictSources.set(claim, platform);
      }
    }
    for (const source of native) known.add(source.url);
  }
  // Match references for native Platform rows using their hosted Git identity.
  const hosted = Array.from(hostedSources.values());
  const hostedReferences = new Set(
    references.filter((ref) =>
      hosted.some((source) => semgrepReferenceMatches(source, ref.url)),
    ),
  );
  const sharedReferences = new Set<ExternalSourceRepository>();
  const ordinaryReferences = new Set<ExternalSourceRepository>();
  if (hostedReferences.size) {
    const readerPlatform = localRepositoryPlatform(
      options.provider,
      [...sources.values(), ...references],
      false,
    );
    const ordinaryIdentity = (url: string) =>
      remoteRepository(
        url,
        options.provider,
        false,
        readerPlatform({ url }),
      ) ?? { key: url };
    const aliases = references.map((ref) => ({
      ref,
      fetch: identify(ref.url),
      ordinary: ordinaryIdentity(ref.url).key,
    }));
    const claims = Map.groupBy(
      Array.from(sources.keys(), (url) => ({
        fetch: identify(url),
        ordinary: strictSources.has(url)
          ? undefined
          : ordinaryIdentity(url).key,
      })),
      (claim) => claim.fetch.key,
    );
    for (const [key, refs] of Map.groupBy(
      aliases,
      (alias) => alias.fetch.key,
    )) {
      const hosted = refs.filter(({ ref }) => hostedReferences.has(ref));
      const group = claims.get(key);
      if (!hosted.length || !group) continue;
      const shared = fetchAliasMatcher(group);
      const readers = fetchAliasMatchers(refs, (alias) => alias.ordinary);
      // Keep a sole fetch alias subject to checkout validation. A redundant
      // Platform spelling can be dropped when another reference serves the reader.
      const required = fetchAliasMatchers(group, ({ fetch, ordinary }) =>
        ordinary !== undefined && readers.get(ordinary)?.(fetch)
          ? ordinary
          : undefined,
      );
      for (const alias of hosted) {
        if (!shared(alias.fetch)) continue;
        sharedReferences.add(alias.ref);
        if (
          required.get(undefined)?.(alias.fetch) ||
          required.get(alias.ordinary)?.(alias.fetch)
        )
          ordinaryReferences.add(alias.ref);
      }
    }
  }
  if (mixed) {
    // Other caller references must identify an ordinary row or one of its Git aliases.
    const rows = [...sources.keys(), ...known].map(identify);
    const byKey = Map.groupBy(rows, (remote) => remote.key);
    const represented = new Set(rows.map((remote) => JSON.stringify(remote)));
    const aliases = readerSources
      .filter((ref) => !hostedReferences.has(ref) || sharedReferences.has(ref))
      .map(({ url }) => identify(url))
      .filter((remote) => !represented.has(JSON.stringify(remote)));
    for (const [key, group] of Map.groupBy(aliases, (remote) => remote.key)) {
      const candidates = byKey.get(key);
      if (!candidates || !sameScannerRepositories([...candidates, ...group]))
        throw new CodexSecurityError(
          "Reader repository does not match a source in the normalized findings.",
        );
    }
  }
  if (strictSources.size && options.provider !== "blackduck") {
    const keys = new Set(
      Array.from(strictSources.keys(), (url) => identify(url).key),
    );
    for (const source of references)
      if (
        !strictSources.has(source.url) &&
        keys.has(identify(source.url).key)
      ) {
        strictSources.set(source.url, platformFor(source));
        if (sharedReferences.has(source)) ordinaryReferences.add(source);
      }
  }
  if (inspector) {
    const platform =
      inspector.platform === "github" ? "github" : options.provider;
    const native = remoteRepository(
      inspector.url,
      options.provider,
      true,
      platform,
    );
    for (const url of sources.keys()) {
      if (
        !native ||
        remoteRepository(url, options.provider, true, platform)?.key !==
          native.key
      )
        throw new CodexSecurityError(
          `Imported repository ${JSON.stringify(url)} does not match the retained Inspector repository ${JSON.stringify(inspector.url)}.`,
        );
    }
  }
  if (
    readerSources.length &&
    hosted.length &&
    ((!hasOrdinaryRows &&
      !readerSources.every((ref) => hostedReferences.has(ref))) ||
      hosted.some(
        (source) =>
          !readerSources.some((ref) =>
            semgrepReferenceMatches(source, ref.url),
          ),
      ))
  )
    throw new CodexSecurityError(
      "The reader's source repository does not match the selected Semgrep project.",
    );
  for (const source of [...(inspector ? [inspector] : []), ...references]) {
    if (
      !ordinaryRowNeedsReferences &&
      hostedReferences.has(source) &&
      !ordinaryReferences.has(source)
    )
      continue;
    // A reader's platform must not loosen an operator-supplied Inspector map.
    if (sources.get(source.url)?.platform !== "github")
      sources.set(
        source.url,
        options.inspectorProjectMap ? { url: source.url } : source,
      );
  }
  const reportUrl = checkmarx.reportUrl;
  if (reportUrl) {
    const source = sources.get(reportUrl) ?? { url: reportUrl };
    sources.set(reportUrl, source);
    checkmarxKeys.add(identify(reportUrl).key);
    if (!strictSources.has(reportUrl))
      strictSources.set(reportUrl, platformFor(source));
  }
  if (
    ((options.provider === "checkmarx" || reportUrl) &&
      !sameRepositories(sources.keys())) ||
    (reportUrl &&
      hosted.some((source) => !semgrepReferenceMatches(source, reportUrl)))
  )
    throw new Error(
      "The retained Checkmarx report repository does not match the finding repository.",
    );
  if (options.provider === "armorcode") {
    if (options.sourceRepositoryUrl !== undefined) {
      const url = declaredScannerRepositoryUrl(
        options.sourceRepositoryUrl,
        "ArmorCode",
        "local",
      );
      sources.set(url, { url });
    }
    if (!sameRepositories(sources.keys()))
      throw new CodexSecurityError(
        "ArmorCode findings must belong to a single source repository.",
      );
  }
  const sonarSources = sonarRepositoryUrls(
    options.provider,
    current.findings,
    current.report,
    "local",
  );
  const manualSource =
    options.provider === "sonar" && options.sourceRepositoryUrl
      ? declaredScannerRepositoryUrl(
          options.sourceRepositoryUrl,
          "Sonar",
          "local",
        )
      : undefined;
  if (manualSource) sonarSources.add(manualSource);
  for (const url of sonarSources)
    if (!sources.has(url)) sources.set(url, { url });
  if (sonarSources.size && !sameRepositories(sources.keys()))
    throw new CodexSecurityError(
      manualSource
        ? "The Sonar evidence does not match the declared source repository."
        : "The retained Sonar repository does not match the other source repository claims.",
    );
  if (
    options.provider === "blackduck" &&
    current.findings.length &&
    sources.size > 1 &&
    !sameScannerRepositories(Array.from(sources.keys(), identify))
  )
    throw new CodexSecurityError(
      "Black Duck occurrences must belong to the same project version and source repository.",
    );
  if (dependabotSource)
    sources.set(dependabotSource, {
      url: dependabotSource,
      platform: "github",
    });
  const snyk = snykRestImportRepository(
    current,
    options.provider,
    [
      ...sources.keys(),
      ...(options.sourceRepositoryUrl === undefined
        ? []
        : [options.sourceRepositoryUrl]),
    ],
    readerSources,
    (finding, source) => {
      finding.evidence.source_data = source;
    },
  );
  if (snyk) {
    // Preserve reader display fields while validating their complete native evidence.
    for (const { evidence } of current.findings)
      validateExternalEvidence(structuredClone(evidence), "local");
  } else if (options.provider === "snyk" && current.sourceRepositoryUrl) {
    const declared = { url: current.sourceRepositoryUrl };
    const native = current.findings.flatMap((finding) =>
      localFindingRepositories("snyk", finding),
    );
    for (const source of [declared, ...native])
      if (!sources.has(source.url)) sources.set(source.url, source);
    if (!sameRepositories(sources.keys()))
      throw new CodexSecurityError(
        "The normalized repository does not match the Snyk reader's repository.",
      );
  }
  if (normalizedSource && !snyk) {
    if (
      !sameRepositories([normalizedSource, ...sources.keys(), ...known]) ||
      hosted.some(
        (source) => !semgrepReferenceMatches(source, normalizedSource),
      )
    )
      throw new CodexSecurityError(
        "The declared repository does not match the normalized finding source.",
      );
    if (!hosted.length && !sources.size)
      sources.set(normalizedSource, { url: normalizedSource });
  }
  const ordinarySources = [...sources.values()];
  // A reader can identify the VCS for both a hosted project and an ordinary row.
  const loosePlatformFor = localRepositoryPlatform(
    options.provider,
    [...ordinarySources, ...hostedReferences],
    false,
  );
  const selected = manualSource ? new URL(manualSource) : undefined;
  const matchesRepositoryRemote =
    options.provider === "trivy"
      ? await matchTrivyCheckout(
          repository,
          current,
          references,
          workbenchOptions,
        )
      : await requireMatchingRepository(
          repository,
          options.provider,
          ordinarySources,
          strictSources,
          hosted,
          (source, bound) =>
            bound ? platformFor(source) : loosePlatformFor(source),
          snyk,
          workbenchOptions.protectedRoot,
          workbenchOptions.environment,
          dependencies.signal,
          selected?.protocol === "https:" ? selected.hostname : undefined,
          fetchRemotes,
          checkmarx.projections.size
            ? (url) => checkmarxKeys.has(identify(url).key)
            : undefined,
        );
  let storedSources = [...references, ...ordinarySources, ...hosted];
  const [project] = hosted;
  if (
    options.provider === "semgrep" &&
    !hasOrdinaryRows &&
    !ordinarySources.length &&
    hosted.length === 1 &&
    project &&
    references.every(({ url }) => url === project.url)
  ) {
    // A typed hint and a bare URL can be two witnesses for the same native
    // project. Keep the hint if any stored occurrence needs it to verify its scope.
    storedSources = [project];
    const native = semgrepPlatformRepositoryReference(project.url, []);
    if (native.platform !== project.platform) {
      try {
        if (
          current.findings.every((finding) => {
            const binding = semgrepPlatformFindingBinding(finding, "semgrep", [
              native,
            ]);
            return (
              binding?.url === native.url &&
              !binding.migration &&
              isDeepStrictEqual(
                binding.sourceData,
                finding.evidence.source_data,
              )
            );
          })
        )
          storedSources = [native];
      } catch {
        // A private SCM alias or SSH mapping can require the reader's platform.
      }
    }
  }
  if (snyk)
    storedSources.push({
      url: snyk.url,
      platform:
        snyk.platform === "github"
          ? "github"
          : snyk.gitlab
            ? "gitlab"
            : undefined,
    });
  return preparedLocalStorage(
    current,
    options,
    context,
    dependencies,
    matchesRepositoryRemote,
    {
      sourceRepositories: distinctSourceRepositories(storedSources),
      inspectorProjectMap: options.inspectorProjectMap
        ? [...options.inspectorProjectMap]
        : undefined,
    },
  );
}

/** @internal Prepare the transactional write after validating the report and repository. */
function preparedLocalStorage(
  current: ExternalFindings,
  { provider, sourceKey }: NormalizedLocalImportOptions,
  {
    repository,
    options: workbenchOptions,
  }: Awaited<ReturnType<typeof localContext>>,
  dependencies: LocalExternalImportDependencies,
  matchesRepositoryRemote: boolean,
  provenance: ExternalFindingProvenance,
): PreparedLocalExternalImport {
  dependencies.signal?.throwIfAborted();
  const preview = {
    ...cloneImportPreview(current),
    repository,
    source: { provider, source_key: sourceKey },
  };
  const payload = JSON.stringify({
    repository,
    provider,
    sourceKey,
    read: current.read,
    excluded: current.excluded,
    report: reportForJson(current.report),
    provenance,
    findings: current.findings.map(({ source_finding_id, evidence }) => ({
      source_finding_id,
      evidence,
    })),
  });
  return {
    matchesRepositoryRemote,
    preview,
    async import() {
      dependencies.signal?.throwIfAborted();
      const disposition = externalImportDisposition(current);
      if (disposition === "failed")
        throw new NoPublishableFindingsError(cloneImportPreview(current));
      const summary = {
        repository,
        read: current.read,
        ...(current.report === undefined
          ? {}
          : snapshotNormalizedFindings({ report: current.report })),
        ready: current.findings.length,
        excluded: structuredClone(current.excluded),
      };
      if (disposition !== "ready") {
        return {
          ...summary,
          findings: [],
          counts: { created: 0, updated: 0, unchanged: 0 },
        };
      }
      const protectedRoot = [
        ...new Set([
          ...workbenchOptions.protectedRoot,
          ...(await abortable(
            () =>
              localGitProtectionRoots(
                process.cwd(),
                workbenchOptions.environment,
                dependencies.signal,
              ),
            dependencies.signal,
          )),
        ]),
      ];
      requireOutputOutsideRepositories(
        protectedRoot,
        await abortable(
          () =>
            canonicalizeModelSafePath(
              workbenchOptions.environment.CODEX_SECURITY_STATE_DIR,
            ),
          dependencies.signal,
        ),
        "runtime",
      );
      const result = await abortable(() => {
        dependencies.signal?.throwIfAborted();
        return (dependencies.runWorkbench ?? runWorkbench)(
          { ...workbenchOptions, protectedRoot },
          ["store-external-findings"],
          payload,
        );
      }, dependencies.signal);
      return {
        ...summary,
        importId: result["importId"] as string,
        findings: result["findings"] as unknown as StoredExternalFinding[],
        counts: result["counts"] as LocalExternalImportResult["counts"],
      };
    },
  };
}

/** Read imported source records, including evidence that has not been assessed by Codex. */
export async function listLocalExternalFindings(
  selection: { repository: string; id?: string },
  dependencies: LocalExternalImportDependencies = {},
): Promise<StoredExternalFinding[]> {
  return (await readLocalExternalFindings(selection, dependencies)).findings;
}

export async function readLocalExternalFindings(
  selection: { repository: string; id?: string },
  dependencies: LocalExternalImportDependencies,
) {
  dependencies.signal?.throwIfAborted();
  if (selection.id !== undefined) requireIdentity(selection.id, "Finding id");
  const { selectedPath, result } = await runLocalFindingWorkbench(
    selection.repository,
    "read-external-findings",
    { id: selection.id },
    dependencies,
  );
  return {
    repository: selectedPath,
    findings: result["findings"] as unknown as StoredExternalFinding[],
  };
}

/** Read the precise versions selected by the caller or captured by an earlier import. */
export async function selectLocalExternalFindings(
  selection: LocalExternalFindingSelection,
  dependencies: LocalExternalImportDependencies = {},
): Promise<SelectedLocalExternalFindings> {
  const { repository, importId, findings } = selection;
  if ((importId === undefined) === (findings === undefined))
    throw new CodexSecurityError(
      "Select one import ID or a list of versioned findings.",
    );
  const { result } = await runLocalFindingWorkbench(
    repository,
    "read-external-findings",
    importId !== undefined
      ? { importId, ifCurrent: selection.ifCurrent }
      : { findings: findings!.map(({ id, version }) => ({ id, version })) },
    dependencies,
  );
  return result as unknown as SelectedLocalExternalFindings;
}

/** List this checkout's nonempty imports, most recent first. */
export async function listLocalExternalImports(
  { repository }: { repository: string },
  dependencies: LocalExternalImportDependencies = {},
): Promise<StoredExternalImport[]> {
  const { result } = await runLocalFindingWorkbench(
    repository,
    "list-external-imports",
    {},
    dependencies,
  );
  return result["imports"] as unknown as StoredExternalImport[];
}

/** @internal Attach Cloud acknowledgements to the versions that were submitted. */
export async function recordExternalFindingPublications(
  input: CloudFindingDestination & {
    repository: string;
    entries: LocalFindingReceipt[];
  },
  dependencies: LocalExternalImportDependencies = {},
): Promise<void> {
  const { repository, ...receipt } = input;
  await runLocalFindingWorkbench(
    repository,
    "record-external-finding-publications",
    receipt,
    dependencies,
  );
}

/** Read the destination and receipt for each acknowledged finding version. */
export async function listLocalFindingPublications(
  { repository, id }: { repository: string; id?: string },
  dependencies: LocalExternalImportDependencies = {},
): Promise<StoredFindingPublication[]> {
  const { result } = await runLocalFindingWorkbench(
    repository,
    "list-external-finding-publications",
    { id },
    dependencies,
  );
  return result["publications"] as unknown as StoredFindingPublication[];
}

/** @internal Run a command against the workbench for the selected checkout. */
async function runLocalFindingWorkbench(
  path: string,
  command: string,
  selection: Record<string, unknown>,
  dependencies: LocalExternalImportDependencies,
) {
  const { repository, selectedPath, options } = await localContext(
    path,
    dependencies,
    "read",
  );
  const result = await abortable(() => {
    dependencies.signal?.throwIfAborted();
    return (dependencies.runWorkbench ?? runWorkbench)(
      options,
      [command],
      JSON.stringify({ repository, ...selection }),
    );
  }, dependencies.signal);
  return { selectedPath, result };
}