@itenl/sec 0.0.0-stage → 0.1.0

package/lib/setup.mjs

@@ -0,0 +1,217 @@
+import { execFileSync } from 'node:child_process';
+import { constants, copyFileSync, existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+import { parseArgs } from 'node:util';
+import {
+  configFile,
+  defaultModel,
+  defaultEffort,
+  engineVersion,
+  privateDirectory,
+  readConfig,
+  saveConfig,
+  userDirectories,
+  validateConfig,
+  assertOutsideRepository
+} from './config.mjs';
+import { engineCommand, engineEnvironment, ensureEngine } from './engine.mjs';
+import { findPython } from './runtime.mjs';
+import { installAliases } from './aliases.mjs';
+
+export async function prompt(
+  question,
+  { secret = false, input = process.stdin, output = process.stdout } = {}
+) {
+  let muted = false;
+  const writer = new Writable({
+    write(chunk, encoding, callback) {
+      if (!muted) output.write(chunk, encoding);
+      callback();
+    }
+  });
+  const reader = createInterface({
+    input,
+    output: writer,
+    terminal: true,
+    historySize: 0
+  });
+  try {
+    if (secret) {
+      output.write(question);
+      muted = true;
+    }
+    return await new Promise((resolve, reject) => {
+      reader.once('SIGINT', () => reject(new Error('Setup cancelled.')));
+      reader.once('close', () => reject(new Error('Input closed before setup completed.')));
+      reader.question(secret ? '' : question, resolve);
+    });
+  } finally {
+    reader.close();
+    writer.end();
+    if (secret) output.write('\n');
+  }
+}
+export function setupOptions(args) {
+  return parseArgs({
+    args,
+    options: {
+      'api-key': { type: 'boolean' },
+      'base-url': { type: 'string' },
+      model: { type: 'string' },
+      effort: { type: 'string' },
+      base: { type: 'string' },
+      'no-aliases': { type: 'boolean' }
+    },
+    allowPositionals: false
+  }).values;
+}
+export async function main(
+  args = [],
+  {
+    env = { ...process.env },
+    ask = prompt,
+    run = execFileSync,
+    log = console.log,
+    tty = process.stdin.isTTY && process.stdout.isTTY
+  } = {}
+) {
+  const options = setupOptions(args);
+  if (!tty)
+    throw new Error(
+      'Run sec setup in an interactive terminal. API keys are accepted only through hidden input.'
+    );
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (!((major === 22 && minor >= 13) || major === 24 || major === 26))
+    throw new Error('Node 22.13+ (22.x), 24 or 26 is required.');
+  const directories = userDirectories(env);
+  // Setup is user-scoped and also works outside a Git repository.
+  let repository;
+  try {
+    repository = run('git', ['rev-parse', '--show-toplevel'], {
+      env,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+  } catch {
+    /* No repository needed. */
+  }
+  if (repository) {
+    assertOutsideRepository(repository, directories.config);
+    assertOutsideRepository(repository, directories.state);
+  }
+  const config = readConfig(env);
+  const baseUrl = (
+    options['base-url'] ??
+    (await ask(`API 服务地址（留空${config.baseUrl ? '保留当前地址' : '使用官方默认'}）：`))
+  ).trim();
+  if (baseUrl) config.baseUrl = baseUrl;
+  else if (options['base-url'] === '') delete config.baseUrl;
+  const model = (options.model ?? (await ask(`模型（留空使用 ${config.model || defaultModel}）：`))).trim();
+  config.model = model || config.model || defaultModel;
+  const effort = (
+    options.effort ?? (await ask(`推理强度（留空使用 ${config.effort || defaultEffort}）：`))
+  ).trim();
+  config.effort = effort || config.effort || defaultEffort;
+  if (options.base) config.baseRef = options.base;
+  validateConfig(config);
+  const childEnv = engineEnvironment(env);
+  // Key entry must not be masked by an ambient key or personal Codex login.
+  delete childEnv.OPENAI_API_KEY;
+  delete childEnv.CODEX_API_KEY;
+  findPython(childEnv, (command, argv) =>
+    run(command, argv, {
+      env: childEnv,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim()
+  );
+  let installed = true;
+  try {
+    ensureEngine(childEnv, run);
+  } catch {
+    installed = false;
+  }
+  privateDirectory(directories.config);
+  privateDirectory(directories.state);
+  privateDirectory(childEnv.CODEX_HOME);
+  if (!installed) {
+    const runtime = join(directories.config, 'runtime');
+    privateDirectory(runtime);
+    log(`安装独立扫描引擎 ${engineVersion}，不更换其他全局工具…`);
+    try {
+      run(
+        'npm',
+        [
+          'install',
+          '--prefix',
+          runtime,
+          '--no-audit',
+          '--no-fund',
+          '--ignore-scripts',
+          `@openai/codex-security@${engineVersion}`
+        ],
+        { env: childEnv, stdio: 'pipe' }
+      );
+      ensureEngine(childEnv, run);
+    } catch {
+      throw new Error(
+        'Cannot install the managed scan engine. Check npm access and permissions, then retry sec setup.'
+      );
+    }
+  }
+  let loggedIn = false;
+  if (!options['api-key']) {
+    try {
+      run(engineCommand(childEnv), ['login', 'status'], {
+        env: childEnv,
+        stdio: 'pipe',
+        timeout: 10000,
+        killSignal: 'SIGKILL'
+      });
+      loggedIn = true;
+    } catch (error) {
+      if (error.code === 'ETIMEDOUT' || error.signal === 'SIGKILL')
+        throw new Error('Login status timed out. Use sec setup --api-key to enter a key without this check.');
+    }
+  }
+  const replaceKey =
+    options['api-key'] ||
+    !loggedIn ||
+    /^y(es)?$/i.test((await ask('已有登录，是否更换 API key？[y/N] ')).trim());
+  if (replaceKey) {
+    let key = (await ask('API key（隐藏输入）：', { secret: true })).trim();
+    if (!key || /[\s\x00-\x1f\x7f]/.test(key)) throw new Error('Empty or invalid API key; nothing saved.');
+    try {
+      run(engineCommand(childEnv), ['login', '--with-api-key'], {
+        env: childEnv,
+        input: `${key}\n`,
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+    } catch {
+      throw new Error('API key could not be saved. Check engine access; credentials were not printed.');
+    } finally {
+      key = '';
+    }
+  }
+  const path = configFile(env);
+  if (existsSync(path)) copyFileSync(path, `${path}.backup-${randomUUID()}`, constants.COPYFILE_EXCL);
+  saveConfig(config, env);
+  log(`扫描与复核默认模型：${config.model}；推理强度：${config.effort}。可用单次 --model / --effort 覆盖。`);
+  log(
+    `用户级分支比较目标：${config.baseRef ?? 'origin/HEAD'}。以后可用 sec config set baseRef <ref> 修改，--local 仅针对当前仓库。`
+  );
+  log(`用户配置：${path}。API key 由独立的官方引擎登录目录保存。`);
+  if (env.OPENAI_API_KEY || env.CODEX_API_KEY)
+    log('当前终端环境中的 API key 会覆盖保存的登录；请自行确认来源。');
+  if (
+    !options['no-aliases'] &&
+    !/^n(o)?$/i.test((await ask('安装 sec:branch 等快捷命令到 zsh/bash 配置？[Y/n] ')).trim())
+  ) {
+    installAliases({ env, log });
+  }
+  log('Setup 完成，各项目可直接运行 sec branch。尚未请求模型，认证及模型权限以真实扫描为准。');
+  return 0;
+}

package/lib/tracker.mjs

@@ -0,0 +1,279 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { validPrefix, findingId } from './project.mjs';
+import {
+  closeSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname, isAbsolute } from 'node:path';
+
+export { trackerFile } from './config.mjs';
+export const severities = ['critical', 'high', 'medium', 'low'];
+export const statusNames = {
+  open: '待修复/调查',
+  pending_verification: '待验证',
+  verified_static: '已通过源码复核'
+};
+export const hash = (value) => createHash('sha256').update(value).digest('hex');
+const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9._:-]{1,200}$/.test(value);
+const fingerprint = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+
+// Only repository-relative locations enter tracked files or terminal tables.
+export function safeLocations(locations) {
+  return (Array.isArray(locations) ? locations : [])
+    .filter(
+      (location) =>
+        typeof location.path === 'string' &&
+        !isAbsolute(location.path) &&
+        !location.path.split(/[\\/]/).includes('..') &&
+        /^[a-zA-Z0-9_./@()[\] -]+$/.test(location.path) &&
+        Number.isSafeInteger(location.startLine) &&
+        location.startLine > 0
+    )
+    .map(({ path, startLine }) => ({ path, startLine }));
+}
+
+export function findingKey(finding) {
+  if (!identifier(finding.ruleId))
+    throw new Error('Finding rule ID is missing or invalid; tracker not updated.');
+  const locations = safeLocations(finding.locations);
+  if (!locations.length)
+    throw new Error('Finding has no safe repository location; tracker not updated.');
+  const roots = safeLocations(
+    finding.locations.filter((location) => location.role === 'root_control')
+  );
+  const paths = [
+    ...new Set((roots.length ? roots : locations).map((location) => location.path))
+  ].sort();
+  // Hash arbitrary anchor text: never copy model prose or payloads into the tracker.
+  // Without an anchor, do not guess that two occurrences in the same file are one issue.
+  const anchor = typeof finding.identity?.anchor === 'string' && finding.identity.anchor.trim();
+  return anchor ? hash(JSON.stringify([finding.ruleId, anchor, paths])) : null;
+}
+
+function assertRegularPath(path) {
+  // Refuse symlinks in the ledger and its managed parent directories.
+  for (let current = path, depth = 0; depth < 3; current = dirname(current), depth++) {
+    try {
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || (current === path && !stat.isFile()))
+        throw new Error(
+          'Findings tracker path must use regular files/directories, without symlinks.'
+        );
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+export function readTracker(path, allowMissing = false, prefix = 'SEC') {
+  assertRegularPath(path);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if (allowMissing && error.code === 'ENOENT')
+      return { text: null, tracker: { schemaVersion: 1, findings: [] } };
+    throw error;
+  }
+  const tracker = JSON.parse(text);
+  if (tracker.schemaVersion !== 1 || !Array.isArray(tracker.findings))
+    throw new Error('Invalid security findings tracker.');
+  const ids = new Set();
+  for (const item of tracker.findings) {
+    if (
+      !findingId(item.id) ||
+      (prefix !== null && item.id.slice(0, item.id.lastIndexOf('-')) !== prefix) ||
+      !Number.isSafeInteger(Number(item.id.slice(item.id.lastIndexOf('-') + 1))) ||
+      ids.has(item.id) ||
+      !Object.hasOwn(statusNames, item.status) ||
+      !severities.includes(item.severity) ||
+      !identifier(item.baseline?.scanId) ||
+      !identifier(item.baseline?.ruleId) ||
+      typeof item.title !== 'string' ||
+      !item.title.trim() ||
+      typeof item.evidence !== 'string' ||
+      !item.evidence.trim() ||
+      (item.identityKeys != null &&
+        (!Array.isArray(item.identityKeys) || !item.identityKeys.every(fingerprint)))
+    )
+      throw new Error('Invalid or duplicate security finding in tracker.');
+    ids.add(item.id);
+  }
+  return { tracker, text };
+}
+
+export function saveTracker(path, tracker, previous) {
+  assertRegularPath(path);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const lock = `${path}.lock`,
+    temp = `${path}.${randomUUID()}.tmp`;
+  let fd;
+  try {
+    try {
+      fd = openSync(lock, 'wx', 0o600);
+    } catch {
+      throw new Error('Findings tracker is locked by another operation; no updates saved.');
+    }
+    assertRegularPath(path);
+    let current = null;
+    try {
+      current = readFileSync(path, 'utf8');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (current !== previous)
+      throw new Error('Findings tracker changed during operation; no updates saved.');
+    writeFileSync(temp, `${JSON.stringify(tracker, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    renameSync(temp, path);
+  } finally {
+    rmSync(temp, { force: true });
+    if (fd !== undefined) {
+      closeSync(fd);
+      rmSync(lock, { force: true });
+    }
+  }
+}
+
+// Pure merge first, then one compare-and-swap write after scan/snapshot guards.
+export function inferPrefix(tracker) {
+  const prefixes = new Set(
+    tracker.findings.map((item) => item.id.slice(0, item.id.lastIndexOf('-')))
+  );
+  if (prefixes.size > 1)
+    throw new Error('Tracker has mixed ID prefixes; review before configuring a shared tracker.');
+  return [...prefixes][0] ?? 'SEC';
+}
+
+export function mergeFindings(original, result, run) {
+  const tracker = structuredClone(original);
+  const prefix = run.project?.idPrefix ?? 'SEC';
+  if (
+    !validPrefix(prefix) ||
+    tracker.findings.some(
+      (item) => !findingId(item.id) || item.id.slice(0, item.id.lastIndexOf('-')) !== prefix
+    )
+  )
+    throw new Error('Tracker prefix does not match project configuration.');
+  let next =
+    Math.max(0, ...tracker.findings.map((item) => Number(item.id.slice(prefix.length + 1)))) + 1;
+  const associations = [];
+  const incoming = result.findings.map((finding) => ({
+    finding,
+    key: findingKey(finding),
+    sha256: hash(JSON.stringify(finding))
+  }));
+  const keys = incoming.map((entry) => entry.key);
+  for (const [index, { finding, key, sha256 }] of incoming.entries()) {
+    const candidates = key
+      ? tracker.findings.filter((item) => item.identityKeys?.includes(key))
+      : [];
+    // A repeated occurrence from the same scan is always idempotent, even without a stable anchor.
+    const occurrences = tracker.findings.filter((item) =>
+      item.observations?.some(
+        (seen) => seen.scanId === result.scan.id && seen.findingSha256 === sha256
+      )
+    );
+    const ambiguous =
+      candidates.length > 1 || (key && keys.filter((value) => value === key).length > 1);
+    let item =
+      occurrences.length === 1
+        ? occurrences[0]
+        : !ambiguous && candidates.length === 1
+          ? candidates[0]
+          : null;
+    const created = !item;
+    if (!item) {
+      if (!Number.isSafeInteger(next)) throw new Error('Finding ID sequence exhausted.');
+      item = {
+        id: `${prefix}-${String(next++).padStart(3, '0')}`,
+        title: `扫描发现：${finding.ruleId}`,
+        status: 'open',
+        severity: finding.severity.level,
+        baseline: {
+          scanId: result.scan.id,
+          ruleId: finding.ruleId,
+          confirmation: 'automatically_imported'
+        },
+        evidence:
+          '自动导入的结构化发现；完整描述及证据见私有 findings.json，人工复核后可补充脱敏说明。',
+        identityKeys: key ? [key] : [],
+        association: ambiguous
+          ? 'manual_review_ambiguous'
+          : key
+            ? 'exact_identity'
+            : 'manual_review_no_anchor'
+      };
+      tracker.findings.push(item);
+    }
+    const alreadySeen = item.observations?.some(
+      (seen) => seen.scanId === result.scan.id && seen.findingSha256 === sha256
+    );
+    if (!alreadySeen) {
+      const observation = {
+        scanId: result.scan.id,
+        runId: run.runId,
+        mode: run.mode,
+        head: run.head,
+        snapshotDigest: result.scan.target.snapshotDigest,
+        severity: finding.severity.level,
+        findingSha256: sha256
+      };
+      item.observations = [...(item.observations || []), observation];
+      item.locations = safeLocations(finding.locations);
+      item.lastSeen = observation;
+      // Keep conservative severity and original baseline/evidence. Absence never closes an item.
+      if (severities.indexOf(finding.severity.level) < severities.indexOf(item.severity))
+        item.severity = finding.severity.level;
+      if (item.status === 'verified_static') item.status = 'open';
+      // A staged scan can precede worktree fixes; don't silently remove an explicit pending verification.
+      if (item.baseline.confirmation === 'automatically_imported')
+        item.evidenceRef = { runId: run.runId, scanId: result.scan.id, index, sha256 };
+    }
+    associations.push({ id: item.id, created, association: item.association || 'exact_identity' });
+  }
+  return { tracker, associations };
+}
+
+const cell = (value) =>
+  String(value)
+    .replace(/[\p{Cc}\p{Cf}]/gu, '')
+    .replaceAll('|', '/')
+    .replaceAll('`', "'");
+export function renderFindings(tracker, { severity, all = false } = {}) {
+  if (severity && !severities.includes(severity))
+    throw new Error('Severity must be critical, high, medium or low.');
+  const selected = tracker.findings.filter(
+    (item) =>
+      (all || item.status !== 'verified_static') && (!severity || item.severity === severity)
+  );
+  const lines = [
+    `${all ? '全部漏洞台账' : '未关闭项（待修复/调查 + 待验证）'}：${selected.length} 项`,
+    ''
+  ];
+  for (const level of severity ? [severity] : severities) {
+    const items = selected.filter((item) => item.severity === level);
+    lines.push(
+      `${{ critical: '严重', high: '高危', medium: '中危', low: '低危' }[level]} / ${level}：${items.length} 项`,
+      '',
+      '| 编号 | 状态 | 问题 | 代码位置 | 证据状态 |',
+      '| --- | --- | --- | --- | --- |'
+    );
+    for (const item of items)
+      lines.push(
+        `| ${item.id} | ${statusNames[item.status]} | ${cell(item.title)} | ${
+          safeLocations(item.locations)
+            .map((location) => `${location.path}:${location.startLine}`)
+            .join('；') || '见人工/私有报告'
+        } | ${item.lastSeen ? '扫描观察，见关联快照' : item.baseline.confirmation === 'historical_unconfirmed' ? '历史未确认' : '历史基线'}${item.association?.startsWith('manual_review') ? '；关联需人工复核' : ''} |`
+      );
+    lines.push('');
+  }
+  lines.push('只读取台账，不调用模型；历史项不代表当前代码仍可利用，未再次报告不等于已修复。');
+  return lines.join('\n');
+}