@itenl/sec 0.0.0-stage → 0.1.0

package/lib/report.mjs

@@ -0,0 +1,210 @@
+import { repositoryDirectory, assertOutsideRepository, privateDirectory } from './config.mjs';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { projectPolicy, publishSummary } from './project.mjs';
+
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const inside = (root, path) => {
+  const rel = relative(root, path);
+  return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('../'));
+};
+const safeIdentifier = (value) =>
+  typeof value === 'string' && /^[a-zA-Z0-9._:-]{1,200}$/.test(value);
+
+export function rawReportDirectory(root, env) {
+  return join(repositoryDirectory(root, env), 'runs');
+}
+
+export function createReport(root, mode, head, tree, env) {
+  // UTC plus a UUID avoids collisions across machines and concurrent runs.
+  const startedAt = new Date().toISOString();
+  const runId = `${startedAt.replace(/[:.]/g, '-')}-${mode}-${randomUUID()}`;
+  const raw = join(rawReportDirectory(root, env), runId);
+  if (inside(root, raw))
+    throw new Error('Codex Security state/report directory must be outside the repository.');
+  assertOutsideRepository(root, raw);
+  privateDirectory(raw);
+  if (inside(realpathSync(root), realpathSync(raw)))
+    throw new Error('Raw report directory resolves inside the repository.');
+  const summary = join(raw, 'summary.md');
+  return { root, mode, head, tree, startedAt, runId, raw, summary };
+}
+
+export function readResult(run, expected) {
+  const policy = projectPolicy(run.project);
+  const manifest = JSON.parse(readFileSync(join(run.raw, 'scan-manifest.json'), 'utf8'));
+  const bytes = readFileSync(join(run.raw, 'findings.json'));
+  const document = JSON.parse(bytes);
+  const scan = manifest.scan;
+  if (
+    manifest.documentType !== 'codex-security.scan-manifest' ||
+    manifest.schemaVersion !== '1.0' ||
+    document.documentType !== 'codex-security.findings' ||
+    document.schemaVersion !== '1.0' ||
+    !safeIdentifier(scan?.id) ||
+    scan.status !== 'completed' ||
+    document.scanId !== scan.id ||
+    !Array.isArray(document.findings) ||
+    !scan.scope ||
+    !scan.target ||
+    !/^codex-security-snapshot\/v1:sha256:[a-f0-9]{64}$/.test(scan.target.snapshotDigest || '') ||
+    (scan.warnings != null && (!Array.isArray(scan.warnings) || scan.warnings.length > 0))
+  )
+    throw new Error('Incomplete or inconsistent security scan artifacts.');
+  if (run.mode === 'staged' || run.mode === 'branch') {
+    if (
+      scan.mode !== 'branch_diff' ||
+      scan.target.kind !== 'git_diff' ||
+      scan.target.baseRevision !== expected.base ||
+      scan.target.headRevision !== expected.target
+    ) {
+      throw new Error('Security scan artifacts do not match the requested diff snapshot.');
+    }
+  } else if (scan.mode !== 'repository' || scan.target.revision !== run.head) {
+    throw new Error('Security scan artifacts do not match the repository target.');
+  }
+  const artifact = scan.artifacts?.find((entry) => entry.path === 'findings.json');
+  if (!artifact || artifact.sha256 !== hash(bytes))
+    throw new Error('Security findings checksum mismatch.');
+  // Do not allow a zero exit code to hide an empty/truncated report set.
+  if (!readFileSync(join(run.raw, 'report.md'), 'utf8').trim())
+    throw new Error('Security report is missing or empty.');
+  const counts = Object.fromEntries(
+    [...policy.blockSeverities, ...policy.warnSeverities].map((level) => [level, 0])
+  );
+  for (const finding of document.findings) {
+    const severity = finding.severity?.level;
+    if (!Object.hasOwn(counts, severity))
+      throw new Error('Unknown security finding severity; refusing to pass.');
+    counts[severity]++;
+  }
+  return { scan, findings: document.findings, counts };
+}
+
+function locationText(locations) {
+  if (!Array.isArray(locations)) return '见私有原始报告';
+  return (
+    locations
+      .filter(
+        (location) =>
+          typeof location.path === 'string' &&
+          !isAbsolute(location.path) &&
+          !location.path.split(/[\\/]/).includes('..') &&
+          /^[a-zA-Z0-9_./@()[\] -]+$/.test(location.path) &&
+          Number.isInteger(location.startLine) &&
+          location.startLine > 0
+      )
+      .map((location) => `${location.path}:${location.startLine}`)
+      .join('；') || '见私有原始报告'
+  );
+}
+
+export function finishReport(run, result, status, scannerStatus) {
+  const policy = projectPolicy(run.project);
+  const conclusion = status === 0 ? '允许通过' : status === 1 ? '风险阻断' : '扫描未完成，阻断';
+  const lines = [
+    '# 自动安全扫描摘要',
+    '',
+    `- 规则版本：${policy.version}；时间：${run.startedAt}（${policy.timeZone}）。`,
+    `- 执行标识：${run.runId}`,
+    `- 模式：${run.mode}；命令：sec ${{ full: 'scan', staged: 'diff', branch: 'branch' }[run.mode]}`,
+    `- 扫描 HEAD：${run.head || '首次提交'}；暂存树：${run.tree || '不适用'}`,
+    ...(run.comparison
+      ? [
+          `- 比较目标：${JSON.stringify(run.comparison.baseRef)}；解析时提交：${run.comparison.baseTip}`,
+          `- 共同祖先：${run.comparison.mergeBase}；差异终点：${run.comparison.target}`
+        ]
+      : []),
+    `- 结论：${conclusion}；封装退出码：${status}；CLI 退出码：${scannerStatus ?? '未启动'}`,
+    `- 策略：${policy.blockSeverities.join('/')} 阻断；${policy.warnSeverities.join('/') || '无'} 警告放行；错误、取消或产物不完整阻断。`,
+    ...(run.project
+      ? [
+          `- 项目配置：sec.config.json；规范：${run.project.policyFile ?? '未指定'}；报告模板：${run.project.reportTemplate ?? '未指定'}。`,
+          `- 请求模型：${run.modelSettings?.model}；推理强度：${run.modelSettings?.effort}。`
+        ]
+      : []),
+    '- 原始产物：本机私有状态目录中同一执行标识下的 scan-manifest.json、findings.json、report.md、wrapper-result.json。',
+    run.project?.summaryDir
+      ? '- 本摘要的私有原件保存在仓库外；脱敏副本按项目配置输出。'
+      : '- 本文件保存在用户私有状态目录，不写入被扫描仓库。',
+    ''
+  ];
+  if (result) {
+    lines.push(
+      `- 扫描 ID：${result.scan.id}`,
+      `- 快照：${result.scan.target.snapshotDigest}`,
+      `- 最终状态：${result.scan.status}`,
+      '',
+      '## 本轮发现',
+      '',
+      ...Object.entries(result.counts).map(([level, count]) => `- ${level}：${count}`),
+      '',
+      '| 本轮序号 | 稳定编号 | 严重级别 | 置信度 | 代码位置 |',
+      '| --- | --- | --- | --- | --- |'
+    );
+    for (const [index, finding] of result.findings.entries()) {
+      const confidence = ['high', 'medium', 'low'].includes(finding.confidence?.level)
+        ? finding.confidence.level
+        : '未提供';
+      lines.push(
+        `| ${index + 1} | ${result.tracking?.[index]?.id || '未导入'} | ${finding.severity.level} | ${confidence} | ${locationText(finding.locations)} |`
+      );
+    }
+  } else {
+    lines.push(
+      '未取得可验证的完整扫描产物；发现数量未知。诊断见终端及本机原始产物，不能视为零漏洞。'
+    );
+  }
+  lines.push(
+    '',
+    '## 覆盖与限制',
+    '',
+    `请求范围：${
+      run.mode === 'branch'
+        ? '指定目标的共同祖先到 HEAD 的已提交差异；暂存、未暂存及未跟踪内容不在范围内'
+        : run.mode === 'staged'
+          ? 'HEAD 到 index 的差异；未暂存修改不在范围内'
+          : '当前项目全仓工作区'
+    }。`,
+    '文件清点数、完整审查数、实际纳入/排除路径及验证限制：以原始 scan-manifest.json 的 scope 与 report.md 为准；未从自由文本推算计数。',
+    result?.tracking
+      ? `稳定编号已关联到${run.project?.trackerFile ?? '本机私有台账'}；未再次报告不等于修复。关联不明确的新项需要人工复核。`
+      : '本轮发现未导入台账；未再次报告不等于修复。',
+    '自动摘要不复制漏洞载荷、源码、凭据或自由文本。影响、前提、证据和修复建议需在私有原始报告中复核，再按需要形成人工报告。',
+    '退出码 0 不代表整个项目无漏洞；本次扫描不自动修复、提交或推送。',
+    ''
+  );
+  mkdirSync(resolve(run.summary, '..'), { recursive: true });
+  writeFileSync(run.summary, lines.join('\n'), { flag: 'wx', mode: 0o600 });
+  writeFileSync(
+    join(run.raw, 'wrapper-result.json'),
+    JSON.stringify(
+      {
+        policyVersion: policy.version,
+        project: run.project ?? null,
+        projectInputs: run.projectInputs ?? [],
+        failOnSeverity: policy.failOnSeverity,
+        runId: run.runId,
+        mode: run.mode,
+        head: run.head,
+        tree: run.tree,
+        comparison: run.comparison ?? null,
+        modelSettings: run.modelSettings ?? null,
+        startedAt: run.startedAt,
+        completedAt: new Date().toISOString(),
+        status,
+        scannerStatus,
+        scanId: result?.scan.id ?? null,
+        counts: result?.counts ?? null,
+        tracking: result?.tracking ?? null
+      },
+      null,
+      2
+    ),
+    { flag: 'wx', mode: 0o600 }
+  );
+  publishSummary(run);
+  console.log(`Codex Security raw reports: ${run.raw}`);
+  console.log(`Codex Security 中文摘要: ${run.summary}`);
+}

package/lib/runtime.mjs

@@ -0,0 +1,83 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+const defaultCapture = (command, args) =>
+  execFileSync(command, args, { encoding: 'utf8', stdio: 'pipe' }).trim();
+
+export function prepareScanTemp(root, environment) {
+  const repository = realpathSync(root);
+  const inside = (path) => {
+    const rel = relative(repository, path);
+    return (
+      rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\'))
+    );
+  };
+  const probe = (candidate, create = false) => {
+    const path = resolve(candidate);
+    if (inside(path)) throw new Error('Temporary directory must be outside the repository.');
+    if (create) {
+      let ancestor = path;
+      while (!existsSync(ancestor)) ancestor = dirname(ancestor);
+      if (inside(resolve(realpathSync(ancestor), relative(ancestor, path)))) {
+        throw new Error('Temporary directory resolves inside the repository.');
+      }
+      mkdirSync(path, { recursive: true, mode: 0o700 });
+    }
+    const directory = realpathSync(path);
+    if (inside(directory)) throw new Error('Temporary directory resolves inside the repository.');
+    const test = mkdtempSync(join(directory, 'codex-security-temp-probe-'));
+    rmSync(test, { recursive: true });
+    return directory;
+  };
+  const preferred =
+    process.platform === 'win32'
+      ? environment.TEMP || environment.TMP || tmpdir()
+      : environment.TMPDIR || environment.TMP || environment.TEMP || tmpdir();
+  let directory;
+  let fallback = false;
+  try {
+    directory = probe(preferred);
+  } catch {
+    fallback = true;
+    const cache = environment.XDG_CACHE_HOME || join(environment.HOME || homedir(), '.cache');
+    try {
+      directory = probe(join(cache, 'sec/tmp'), true);
+    } catch {
+      throw new Error(
+        'No writable temporary directory outside the repository. Set TMPDIR to a writable directory and retry.'
+      );
+    }
+  }
+  // Node and Python use different precedence rules. Normalize all aliases for children only.
+  environment.TMPDIR = directory;
+  environment.TMP = directory;
+  environment.TEMP = directory;
+  return { directory, fallback };
+}
+
+export function findPython(environment = process.env, capture = defaultCapture) {
+  const candidates = [environment.PYTHON];
+  try {
+    candidates.push(capture('uv', ['python', 'find', '>=3.11']));
+  } catch {
+    // uv is optional; also accept a Python installation on PATH.
+  }
+  candidates.push('python3', 'python');
+  for (const candidate of candidates.filter(Boolean)) {
+    try {
+      capture(candidate, ['-c', 'import sys; assert sys.version_info >= (3, 10); import tomllib']);
+      return candidate;
+    } catch {
+      // Python 3.10 needs tomli instead of the standard-library tomllib.
+      try {
+        capture(candidate, ['-c', 'import sys; assert sys.version_info >= (3, 10); import tomli']);
+        return candidate;
+      } catch {
+        // Try the next interpreter.
+      }
+    }
+  }
+  throw new Error('Python >=3.10 is required (3.10 also needs tomli). Install Python or set PYTHON.');
+}

package/lib/scan.mjs

@@ -0,0 +1,322 @@
+import { engineEnvironment, providerArguments, ensureEngine, invokeEngine } from './engine.mjs';
+import {
+  readConfig,
+  assertOutsideRepository,
+  userDirectories,
+  repositoryModelSettings,
+  branchBaseRef
+} from './config.mjs';
+import { snapshot as sourceSnapshot } from './verify.mjs';
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { findPython, prepareScanTemp } from './runtime.mjs';
+import {
+  readProjectConfig,
+  projectInputs,
+  projectGuard,
+  projectPolicy,
+  preflightProject,
+  projectPath
+} from './project.mjs';
+import { createReport, finishReport, readResult } from './report.mjs';
+import { mergeFindings, readTracker, saveTracker, trackerFile } from './tracker.mjs';
+
+const environment = { ...process.env };
+const capture = (command, args, options = {}) =>
+  execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: environment,
+    ...options
+  }).trim();
+const git = (cwd, ...args) => capture('git', ['-C', cwd, ...args]);
+
+export async function main(mode = 'staged', args = []) {
+  if (!['full', 'staged', 'branch'].includes(mode))
+    throw new Error('Usage: sec scan|diff|branch [--base <ref>] [--dry-run]');
+  const { values } = parseArgs({
+    args,
+    options: {
+      ...(mode === 'branch' ? { base: { type: 'string' }, 'dry-run': { type: 'boolean' } } : {}),
+      model: { type: 'string' },
+      effort: { type: 'string' },
+      'knowledge-base': { type: 'string', multiple: true }
+    },
+    allowPositionals: false
+  });
+  const config = readConfig();
+  const root = git(process.cwd(), 'rev-parse', '--show-toplevel');
+  const project = readProjectConfig(root);
+  const settings = repositoryModelSettings(root, config, values);
+  const policy = projectPolicy(project);
+  const guard = projectGuard(root, project);
+  preflightProject(root, project, (...args) => git(root, ...args));
+  if (project)
+    console.log(
+      `项目配置：sec.config.json；规范：${project.policyFile ?? '未指定'}；模型：${settings.model} / ${settings.effort}；门禁：${policy.failOnSeverity}。`
+    );
+  const baseRef = mode === 'branch' ? branchBaseRef(root, config, values.base, environment) : null;
+  if (mode === 'branch' && (!baseRef || baseRef.startsWith('-')))
+    throw new Error(
+      'Invalid branch target. Use sec branch [--base <ref>] [--dry-run] (default: origin/HEAD).'
+    );
+  // Git hooks can set GIT_INDEX_FILE and other repository-specific variables.
+  // Resolve the real index first, then keep those variables out of the isolated repository.
+  const tree = mode === 'staged' ? git(root, 'write-tree') : null;
+  let head = null;
+  try {
+    head = git(root, 'rev-parse', '--verify', 'HEAD');
+  } catch {
+    /* Initial commit. */
+  }
+  let comparison = null;
+  if (mode === 'branch') {
+    if (!head) throw new Error('Branch scans require a committed HEAD.');
+    for (const operation of [
+      'MERGE_HEAD',
+      'CHERRY_PICK_HEAD',
+      'REVERT_HEAD',
+      'rebase-merge',
+      'rebase-apply',
+      'sequencer'
+    ]) {
+      if (existsSync(resolve(root, git(root, 'rev-parse', '--git-path', operation))))
+        throw new Error(
+          'Finish the active merge, cherry-pick, revert or rebase before scanning branch changes.'
+        );
+    }
+    if (git(root, 'ls-files', '--unmerged'))
+      throw new Error('Resolve Git conflicts before scanning branch changes.');
+    let baseTip;
+    let bases;
+    try {
+      baseTip = git(root, 'rev-parse', '--verify', '--end-of-options', `${baseRef}^{commit}`);
+      bases = git(root, 'merge-base', '--all', baseTip, head).split('\n').filter(Boolean);
+    } catch {
+      throw new Error(
+        `Cannot resolve target ${JSON.stringify(baseRef)} or find shared history. Fetch the target ref/history and retry.`
+      );
+    }
+    if (bases.length !== 1)
+      throw new Error('Expected one merge base; resolve ambiguous Git history before scanning.');
+    comparison = { baseRef, baseTip, mergeBase: bases[0], target: head };
+    console.log(`Codex Security branch target: ${JSON.stringify(baseRef)} (${baseTip})`);
+    console.log(
+      `Codex Security branch range: ${comparison.mergeBase}..${head} (committed changes only)`
+    );
+    console.log(
+      'Codex Security: local refs only; no automatic fetch. Index and working changes are excluded.'
+    );
+    if (
+      git(root, 'rev-parse', `${comparison.mergeBase}^{tree}`) ===
+      git(root, 'rev-parse', `${head}^{tree}`)
+    ) {
+      console.log('Codex Security: no committed branch changes.');
+      return 0;
+    }
+    console.log(git(root, 'diff', '--stat', comparison.mergeBase, head, '--'));
+    if (values['dry-run']) {
+      console.log(
+        'Codex Security: dry run only; scanner not invoked and no reports or tracker updates written.'
+      );
+      return 0;
+    }
+  }
+  if (mode === 'staged' && head && tree === git(root, 'rev-parse', `${head}^{tree}`)) {
+    console.log('Codex Security: no staged changes.');
+    return 0;
+  }
+  const ledgerPath = trackerFile(root, environment);
+  assertOutsideRepository(root, userDirectories(environment).config);
+  const sourceBefore = mode === 'full' ? sourceSnapshot(root, environment) : null;
+  const previousTracker = readTracker(ledgerPath, true, project?.idPrefix ?? 'SEC');
+  Object.assign(environment, engineEnvironment(environment));
+  delete environment.CODEX_SECURITY_PROJECT_CONFIG;
+  const originalGitEnvironment = { ...environment };
+  for (const name of git(root, 'rev-parse', '--local-env-vars').split('\n'))
+    delete environment[name];
+  const run = createReport(root, mode, head, tree, environment);
+  run.comparison = comparison;
+  run.modelSettings = settings;
+  run.project = project;
+  run.projectInputs = guard.inputs;
+  let temp;
+  let scannerStatus;
+  let result;
+  let status = 2;
+  try {
+    const temporary = prepareScanTemp(root, environment);
+    if (temporary.fallback) {
+      console.warn(
+        `Codex Security: inherited temporary directory is unavailable or inside the repository; using ${temporary.directory}`
+      );
+    }
+    ensureEngine(environment);
+    const suppliedContext = projectInputs(root, project).filter(
+      ({ absolute }) =>
+        !project?.reportTemplate || absolute !== projectPath(root, project.reportTemplate)
+    );
+    const knowledgePaths = suppliedContext.map(({ absolute }, index) => {
+      const copy = join(run.raw, 'context', String(index));
+      mkdirSync(join(run.raw, 'context'), { recursive: true, mode: 0o700 });
+      // Preserve extensions for official document format detection.
+      const destination = `${copy}-${absolute.split('/').at(-1)}`;
+      cpSync(absolute, destination, {
+        recursive: true,
+        dereference: false,
+        errorOnExist: true,
+        force: false
+      });
+      return destination;
+    });
+    guard.check();
+    const commonArgs = [
+      ...knowledgePaths.flatMap((path) => ['--knowledge-base', path]),
+      ...providerArguments(config, settings),
+      ...(values['knowledge-base'] || []).flatMap((path) => [
+        '--knowledge-base',
+        resolve(process.cwd(), path)
+      ]),
+      '--output-dir',
+      run.raw,
+      '--fail-on-severity',
+      policy.failOnSeverity,
+      '--python',
+      findPython(environment, capture),
+      '--headless',
+      '--codex',
+      'approval_policy="never"'
+    ];
+    let snapshot = root;
+    let expected = {};
+    let rangeArgs = [];
+    if (mode === 'staged' || mode === 'branch') {
+      temp = mkdtempSync(join(temporary.directory, 'sec-snapshot-'));
+      snapshot = join(temp, 'repository');
+      mkdirSync(snapshot);
+      git(snapshot, 'init', '--quiet');
+      git(snapshot, 'config', 'core.hooksPath', '/dev/null');
+      // Share read-only object access; temporary commits stay in the isolated repository.
+      const objects = resolve(root, git(root, 'rev-parse', '--git-path', 'objects'));
+      writeFileSync(join(snapshot, '.git/objects/info/alternates'), `${objects}\n`);
+      const commitEnv = {
+        ...environment,
+        GIT_AUTHOR_NAME: 'Codex Security',
+        GIT_AUTHOR_EMAIL: 'security@localhost',
+        GIT_COMMITTER_NAME: 'Codex Security',
+        GIT_COMMITTER_EMAIL: 'security@localhost'
+      };
+      const commit = (args) =>
+        capture('git', ['-C', snapshot, '-c', 'commit.gpgsign=false', 'commit-tree', ...args], {
+          env: commitEnv
+        });
+      const base =
+        comparison?.mergeBase ??
+        head ??
+        commit([git(snapshot, 'mktree'), '-m', 'Empty security scan baseline']);
+      const target =
+        mode === 'branch'
+          ? head
+          : commit([tree, '-p', base, '-m', 'Staged security scan snapshot']);
+      expected = { base, target };
+      git(snapshot, 'checkout', '--quiet', '--detach', target);
+      rangeArgs = ['--diff', base, '--head', target];
+    }
+    console.log(
+      `Codex Security: ${policy.blockSeverities.join('/')} block; ${policy.warnSeverities.join('/') || 'none'} warn; scan errors block.`
+    );
+    console.log(`扫描模型：${settings.model}；推理强度：${settings.effort}。`);
+    scannerStatus = (
+      await invokeEngine(['scan', snapshot, ...rangeArgs, ...commonArgs], {
+        cwd: snapshot,
+        env: environment
+      })
+    ).code;
+    if (![0, 1].includes(scannerStatus)) {
+      status = scannerStatus;
+      console.error(`Security scanner did not complete (exit ${scannerStatus}).`);
+      return status;
+    }
+    result = readResult(run, expected);
+    const blocked = policy.blockSeverities.some((level) => result.counts[level] > 0);
+    if (scannerStatus === 1 && !blocked)
+      throw new Error('Scanner exit code conflicts with the severity policy.');
+    status = blocked ? 1 : 0;
+    if (policy.warnSeverities.some((level) => result.counts[level] > 0)) {
+      console.warn(
+        `WARNING: Findings below ${policy.failOnSeverity} remain in the report; review them even though the gate allows them.`
+      );
+    }
+    if (blocked)
+      console.error(`Codex Security: ${policy.failOnSeverity} or higher findings fail this check.`);
+  } catch (error) {
+    if ([0, 1].includes(status)) status = 2;
+    throw error;
+  } finally {
+    try {
+      // Check the original index (including GIT_INDEX_FILE), even after scanner failure.
+      const currentTree =
+        mode === 'staged'
+          ? capture('git', ['-C', root, 'write-tree'], {
+              env: originalGitEnvironment
+            })
+          : null;
+      let currentHead = null;
+      try {
+        currentHead = capture('git', ['-C', root, 'rev-parse', '--verify', 'HEAD'], {
+          env: originalGitEnvironment
+        });
+      } catch {
+        /* Initial commit. */
+      }
+      if (
+        currentTree !== tree ||
+        currentHead !== head ||
+        (mode === 'full' && sourceSnapshot(root, originalGitEnvironment) !== sourceBefore)
+      ) {
+        throw new Error(
+          'The staged content or HEAD changed during the security scan. Review and retry the scan.'
+        );
+      }
+      preflightProject(root, project, (...args) => git(root, ...args));
+      guard.check();
+      if (result && [0, 1].includes(status)) {
+        const merged = mergeFindings(previousTracker.tracker, result, run);
+        // Do not create an empty tracker just for a clean scan. Existing files still
+        // get a CAS check so concurrent edits cannot be silently ignored.
+        if (previousTracker.text !== null || merged.tracker.findings.length) {
+          if (project?.trackerFile) projectPath(root, project.trackerFile, { kind: 'file' });
+          saveTracker(ledgerPath, merged.tracker, previousTracker.text);
+        }
+        result.tracking = merged.associations;
+        console.log(
+          `Codex Security: 本轮 ${merged.associations.length} 项已关联稳定编号（新增 ${merged.associations.filter((entry) => entry.created).length} 项）；${project?.trackerFile ? '已更新项目共享台账工作副本，未暂存' : '保存在本机私有台账'}。`
+        );
+      }
+    } catch (error) {
+      status = 2;
+      throw error;
+    } finally {
+      if (temp) rmSync(temp, { recursive: true, force: true });
+      finishReport(run, result, status, scannerStatus);
+    }
+  }
+  return status;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv[2], process.argv.slice(3))
+    .then((status) => {
+      process.exitCode = status;
+    })
+    .catch((error) => {
+      console.error(`Codex Security: ${error.message}`);
+      console.error(
+        'Security check did not complete. Resolve the error and retry; incomplete scans fail closed.'
+      );
+      process.exitCode = 2;
+    });
+}