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

9.8 KB
Raw Blame
import { parseJson } from "./value.js";
import { isLinearIssueIdentifier, linearIssueReference } from "./linear.js";
import { isRecord } from "./record.js";
import {
  linearPublicationArguments,
  type PreparedPublicationIssue,
  type PreparedScanPublication,
} from "./publication.js";

export const MISSING_PUBLICATION_IDENTIFIER_ERROR =
  "The connected Linear app did not return a created issue identifier.";

export interface PublicationClaim {
  kind: "identifier" | "entityId" | "url";
  value: string;
}

export type ClaimResolution =
  | { state: "absent"; claims: PublicationClaim[] }
  | { state: "conflicting"; claims: PublicationClaim[] }
  | {
      state: "resolved";
      claims: PublicationClaim[];
      issueIdentifier: string;
      url?: string;
    };

interface CreateEvidence {
  source: "event";
  rawLine: string;
  ownerFindingId?: string;
  argumentsValid: boolean;
  resolution: ClaimResolution;
}

export interface CompletedCreateEvidence extends CreateEvidence {
  status: "completed";
}

export interface FailedCreateEvidence extends CreateEvidence {
  status: "failed";
  error: string;
}

export type PublicationEventEvidence =
  CompletedCreateEvidence | FailedCreateEvidence;

export function collectPublicationEvents(
  output: string,
  publication: PreparedScanPublication,
  failureMessage: string,
): PublicationEventEvidence[] {
  const evidence: PublicationEventEvidence[] = [];

  for (const rawLine of output.split(/\r?\n/)) {
    if (rawLine.trim().length === 0) continue;
    const event = parseJson(() => rawLine);
    if (!isRecord(event) || event["type"] !== "item.completed") continue;
    const item = event["item"];
    if (!isLinearCreateCall(item)) continue;

    const arguments_ = item["arguments"];
    const owner = isRecord(arguments_)
      ? matchPublicationIssue(publication, arguments_)
      : undefined;
    const argumentsValid =
      owner !== undefined &&
      hasExpectedPublicationArguments(publication, owner, arguments_);
    const completed: CompletedCreateEvidence = {
      source: "event",
      status: "completed",
      rawLine,
      ...(owner === undefined ? {} : { ownerFindingId: owner.findingId }),
      argumentsValid,
      resolution: resolvePublicationClaims(item["result"]),
    };
    if (item["status"] === "completed") {
      evidence.push(completed);
    } else {
      const error = item["error"];
      evidence.push({
        ...completed,
        status: "failed",
        error:
          isRecord(error) && typeof error["message"] === "string"
            ? error["message"]
            : failureMessage,
      });
    }
  }

  return evidence;
}

export function hasExpectedPublicationArguments(
  publication: PreparedScanPublication,
  issue: PreparedPublicationIssue,
  actual: unknown,
): boolean {
  if (!isRecord(actual)) return false;
  const expected = linearPublicationArguments(publication.destination, issue);
  return (
    Object.keys(actual).length === Object.keys(expected).length &&
    Object.entries(expected).every(
      ([key, value]) =>
        Object.hasOwn(actual, key) && Object.is(actual[key], value),
    )
  );
}

export function matchPublicationIssue(
  publication: PreparedScanPublication,
  arguments_: Record<string, unknown>,
): PreparedPublicationIssue | undefined {
  const exactMatches = publication.issues.filter((issue) =>
    hasExpectedPublicationArguments(publication, issue, arguments_),
  );
  if (exactMatches.length === 1) return exactMatches[0];

  const description = arguments_["description"];
  if (typeof description !== "string") return undefined;
  const matches = publication.issues.filter(
    (issue) =>
      containsIdentifier(description, issue.findingId) &&
      containsIdentifier(description, issue.occurrenceId),
  );
  return matches.length === 1 ? matches[0] : undefined;
}

export function resolvePublicationClaims(value: unknown): ClaimResolution {
  const claims: PublicationClaim[] = [];
  collectPublicationClaims(value, claims);
  return resolveClaims(claims);
}

export function resolveClaims(
  claims: readonly PublicationClaim[],
): ClaimResolution {
  const normalized = new Map<string, PublicationClaim>();
  claims.forEach((claim) => {
    const trimmed = claim.value.trim();
    if (trimmed.length === 0) return;
    const value = isCanonicalUuid(trimmed) ? trimmed.toLowerCase() : trimmed;
    const kind = claim.kind;
    normalized.set(`${kind}\0${value}`, { kind, value });
  });
  const retained = [...normalized.values()].sort(compareClaims);
  const identifiers = new Set<string>();
  const entityIds = new Set<string>();
  const urls = new Set<string>();
  const byKind = { identifier: identifiers, entityId: entityIds, url: urls };
  for (const { kind, value } of retained) byKind[kind]?.add?.(value);
  const canonicalUrls = new Set([...urls].map(canonicalPublicationUrlClaim));
  const urlContradictsIdentifier =
    identifiers.size > 0 &&
    Array.from(urls, linearIssueReferenceFromUrl).some(
      (reference) => reference !== undefined && !identifiers.has(reference.id),
    );
  const overlappingIdentity = !identifiers.isDisjointFrom(entityIds);
  if (
    identifiers.size > 1 ||
    entityIds.size > 1 ||
    canonicalUrls.size > 1 ||
    urlContradictsIdentifier ||
    overlappingIdentity
  ) {
    return { state: "conflicting", claims: retained };
  }
  if (identifiers.size === 0) {
    return { state: "absent", claims: retained };
  }
  const url =
    [...urls].find((value) => /^https:\/\//iu.test(value)) ??
    urls.values().next().value;
  return {
    state: "resolved",
    claims: retained,
    issueIdentifier: identifiers.values().next().value!,
    ...(url === undefined ? {} : { url }),
  };
}

function isLinearCreateCall(item: unknown): item is Record<string, unknown> {
  return (
    isRecord(item) &&
    item["type"] === "mcp_tool_call" &&
    item["server"] === "codex_apps" &&
    (item["tool"] === "linear.save_issue" ||
      item["tool"] === "linear_save_issue")
  );
}

function collectPublicationClaims(
  value: unknown,
  claims: PublicationClaim[],
): void {
  const pending = isRecord(value) ? [value] : [];
  while (pending.length > 0) {
    const candidate = pending.pop()!;
    collectDirectClaims(candidate, claims);

    const data = candidate["data"];
    const nested: unknown[] = [
      candidate["structured_content"],
      candidate["structuredContent"],
      candidate["issue"],
      isRecord(data) ? data["issue"] : undefined,
    ];
    if (Array.isArray(candidate["content"])) {
      for (const content of candidate["content"]) {
        if (!isRecord(content) || typeof content["text"] !== "string") {
          continue;
        }
        const parsed = parseJson(() => content["text"] as string);
        if (isRecord(parsed)) nested.push(parsed);
      }
    }
    for (const child of nested.reverse()) {
      if (isRecord(child)) pending.push(child);
    }
  }
}

function collectDirectClaims(
  candidate: Record<string, unknown>,
  claims: PublicationClaim[],
): void {
  for (const field of ["identifier", "issueIdentifier", "key", "id"] as const) {
    const claim = classifyIdentityClaim(field, candidate[field]);
    if (claim !== undefined) claims.push(claim);
  }
  const url = candidate["url"];
  const normalizedUrl = normalizeNonemptyString(url);
  if (normalizedUrl !== undefined) {
    claims.push({ kind: "url", value: normalizedUrl });
  }
}

function classifyIdentityClaim(
  field: "identifier" | "issueIdentifier" | "key" | "id",
  value: unknown,
): PublicationClaim | undefined {
  const normalized = normalizeNonemptyString(value);
  if (normalized === undefined) return undefined;
  if (isCanonicalUuid(normalized)) {
    return { kind: "entityId", value: normalized };
  }
  if (field === "identifier" || field === "issueIdentifier") {
    return { kind: "identifier", value: normalized };
  }
  if (isLinearIssueIdentifier(normalized)) {
    return { kind: "identifier", value: normalized };
  }
  return field === "id" ? { kind: "entityId", value: normalized } : undefined;
}

function compareClaims(
  left: PublicationClaim,
  right: PublicationClaim,
): number {
  const order = { identifier: 0, entityId: 1, url: 2 } as const;
  const kindOrder = order[left.kind] - order[right.kind];
  if (kindOrder !== 0) return kindOrder;
  if (left.value === right.value) return 0;
  return left.value < right.value ? -1 : 1;
}

function isCanonicalUuid(value: string): boolean {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(
    value,
  );
}

function linearIssueReferenceFromUrl(
  value: string,
): { id: string; workspace: string } | undefined {
  // Recognize every scheme linearIssueReference parses, so a plain HTTP URL
  // still resolves to the issue it names instead of an unrecognized claim.
  try {
    const reference = linearIssueReference(value);
    return reference.workspace === undefined
      ? undefined
      : { id: reference.id, workspace: reference.workspace };
  } catch {
    return undefined;
  }
}

function canonicalPublicationUrlClaim(value: string): string {
  const reference = linearIssueReferenceFromUrl(value);
  return reference === undefined
    ? `raw:\0${value}`
    : `linear:\0${reference.workspace}\0${reference.id}`;
}

export function publicationClaimAliases(
  claim: PublicationClaim,
): PublicationClaim[] {
  if (claim.kind !== "url") return [claim];
  const reference = linearIssueReferenceFromUrl(claim.value);
  return reference === undefined
    ? [claim]
    : [claim, { kind: "identifier", value: reference.id }];
}

function normalizeNonemptyString(value: unknown): string | undefined {
  if (typeof value !== "string") return undefined;
  const normalized = value.trim();
  return normalized.length === 0 ? undefined : normalized;
}

function containsIdentifier(value: string, identifier: string): boolean {
  const escaped = identifier.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
  return new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`, "u").test(value);
}