@itenl/sec 0.0.0-stage → 0.1.1

package/lib/verify.mjs

@@ -0,0 +1,388 @@
+import { engineEnvironment, providerArguments, ensureEngine, invokeEngine } from './engine.mjs';
+import {
+  readConfig,
+  assertOutsideRepository,
+  userDirectories,
+  repositoryModelSettings
+} from './config.mjs';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { createReport, rawReportDirectory } from './report.mjs';
+import {
+  readTracker,
+  saveTracker,
+  renderFindings,
+  trackerFile,
+  statusNames as names
+} from './tracker.mjs';
+export { readTracker } from './tracker.mjs';
+import {
+  readProjectConfig,
+  projectPath,
+  projectGuard,
+  projectPolicy,
+  preflightProject,
+  publishSummary
+} from './project.mjs';
+import { findPython, prepareScanTemp } from './runtime.mjs';
+
+const capture = (command, args, options = {}) =>
+  execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: 'pipe',
+    maxBuffer: 32 * 1024 * 1024,
+    ...options
+  }).trim();
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+
+// Snapshot binding includes all tracked/untracked nonignored source, HEAD and the real index.
+// No git add/reset/stash; ignored generated reports do not invalidate their own run.
+export function snapshot(root, env) {
+  const git = (...args) => execFileSync('git', ['-C', root, ...args], { env });
+  const hash = createHash('sha256');
+  try {
+    hash.update(git('rev-parse', '--verify', 'HEAD'));
+  } catch {
+    hash.update('unborn-head');
+  }
+  hash.update(git('write-tree'));
+  const paths = [
+    ...new Set(
+      git('ls-files', '-c', '-o', '--exclude-standard', '-z')
+        .toString('utf8')
+        .split('\0')
+        .filter(Boolean)
+    )
+  ].sort();
+  for (const path of paths) {
+    hash.update(JSON.stringify(path));
+    try {
+      const stat = lstatSync(join(root, path));
+      hash.update(`${stat.mode}:`);
+      hash.update(
+        stat.isSymbolicLink()
+          ? readlinkSync(join(root, path))
+          : stat.isFile()
+            ? readFileSync(join(root, path))
+            : 'directory'
+      );
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      hash.update('missing');
+    }
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+export function validateResponse(text, selected, root, code) {
+  const response = JSON.parse(text);
+  if (
+    realpathSync(response.repository) !== realpathSync(root) ||
+    !Array.isArray(response.results) ||
+    response.results.length !== selected.length
+  )
+    throw new Error('Verification response target or result count mismatch.');
+  for (const [index, result] of response.results.entries()) {
+    if (
+      result.id !== `finding-${index + 1}` ||
+      !['fixed', 'still_vulnerable', 'inconclusive'].includes(result.status) ||
+      typeof result.evidence !== 'string' ||
+      !result.evidence.trim()
+    )
+      throw new Error('Missing, unknown or evidence-free verification result.');
+  }
+  const expected = response.results.some((r) => r.status === 'inconclusive')
+    ? 2
+    : response.results.some((r) => r.status === 'still_vulnerable')
+      ? 1
+      : 0;
+  if (code !== expected) throw new Error('Verification exit code conflicts with its results.');
+  return response.results.map((result, index) => ({
+    ...result,
+    id: selected[index].id
+  }));
+}
+
+export function verificationEvidence(item, root, env) {
+  if (item.baseline.confirmation !== 'automatically_imported') return item.evidence;
+  const ref = item.evidenceRef;
+  if (
+    !ref ||
+    !/^\d{4}-\d{2}-\d{2}T[\d-]+Z-(full|staged|branch)-[a-f0-9-]{36}$/.test(ref.runId) ||
+    !Number.isSafeInteger(ref.index) ||
+    ref.index < 0 ||
+    !/^[a-f0-9]{64}$/.test(ref.sha256)
+  )
+    throw new Error(`Invalid private evidence reference for ${item.id}; verification not started.`);
+  let finding;
+  try {
+    const path = join(rawReportDirectory(root, env), ref.runId, 'findings.json');
+    if (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())
+      throw new Error('Not a regular file.');
+    const document = JSON.parse(readFileSync(path, 'utf8'));
+    if (
+      document.documentType !== 'codex-security.findings' ||
+      document.schemaVersion !== '1.0' ||
+      document.scanId !== ref.scanId
+    )
+      throw new Error('Wrong scan.');
+    finding = document.findings[ref.index];
+    if (!finding || digest(JSON.stringify(finding)) !== ref.sha256)
+      throw new Error('Evidence checksum mismatch.');
+  } catch {
+    throw new Error(
+      `Private evidence missing or invalid for ${item.id}; retain pending status. Restore the original private run directory, re-scan to refresh the reference, or have a reviewer curate sanitized evidence first.`
+    );
+  }
+  return finding;
+}
+
+export async function main(args = process.argv.slice(2)) {
+  if (args.includes('--help')) {
+    console.log(
+      'sec update SEC-001 [SEC-002 ...]：标记待验证，不调用模型。\nsec verify：复核全部待验证项。\nsec verify --list：列出全部状态。\nsec verify --pending SEC-001 [SEC-002 ...]：兼容排队入口。\nsec help：查看全部命令。'
+    );
+    return 0;
+  }
+  const env = { ...process.env };
+  const root = capture('git', ['rev-parse', '--show-toplevel'], { env });
+  const git = (...values) => capture('git', ['-C', root, ...values], { env });
+  const project = readProjectConfig(root);
+  const policy = projectPolicy(project);
+  const path = trackerFile(root, env);
+  const { tracker, text } = readTracker(path, true, project?.idPrefix ?? 'SEC');
+  if (args[0] === '--list' && args.length === 1) {
+    console.log(renderFindings(tracker, { all: true }));
+    return 0;
+  }
+  if (args[0] === '--pending' && args.length > 1) {
+    const ids = args.slice(1);
+    if (
+      new Set(ids).size !== ids.length ||
+      ids.some((id) => !tracker.findings.some((item) => item.id === id))
+    )
+      throw new Error('Unknown or duplicate finding ID; tracker not changed.');
+    for (const item of tracker.findings.filter((entry) => ids.includes(entry.id))) {
+      item.status = 'pending_verification';
+      item.queuedAt = new Date().toISOString();
+      item.queuedHead = git('rev-parse', 'HEAD');
+    }
+    if (project?.trackerFile) projectPath(root, project.trackerFile, { kind: 'file' });
+    saveTracker(path, tracker, text);
+    console.log(
+      `已标记待验证：${ids.join(', ')}。${project?.trackerFile ? '仅更新项目共享台账工作副本，未暂存' : '仅修改本机私有台账'}；运行 sec verify 开始复核全部待验证项。`
+    );
+    const queued = tracker.findings
+      .filter((item) => item.status === 'pending_verification')
+      .map((item) => item.id);
+    console.log(
+      `当前待验证队列：${queued.join(', ')}。本操作只追加指定项，不清空其他待验证项；复核期间请勿修改源码、台账或 Git 状态。`
+    );
+    return 0;
+  }
+  const { values } = parseArgs({
+    args,
+    options: { model: { type: 'string' }, effort: { type: 'string' } },
+    allowPositionals: false
+  });
+  const config = readConfig(env);
+  const settings = repositoryModelSettings(root, config, values);
+  const selected = tracker.findings.filter((item) => item.status === 'pending_verification');
+  if (!selected.length) {
+    console.log('没有待验证项，不调用模型。修复后用 sec update SEC-xxx 标记；sec help 查看用法。');
+    return 0;
+  }
+  preflightProject(root, project, git);
+  const guard = projectGuard(root, project);
+  if (git('ls-files', '-u')) throw new Error('Resolve Git conflicts before verification.');
+  const originalEnv = { ...env };
+  assertOutsideRepository(root, userDirectories(env).config);
+  prepareScanTemp(root, env);
+  env.PYTHON = findPython(env, (command, values) => capture(command, values, { env }));
+  Object.assign(env, engineEnvironment(env));
+  delete env.CODEX_SECURITY_PROJECT_CONFIG;
+  const overrides = providerArguments(config, settings);
+  const cliVersion = ensureEngine(env);
+  for (const name of git('rev-parse', '--local-env-vars').split('\n')) delete env[name];
+  const head = git('rev-parse', 'HEAD');
+  const before = snapshot(root, originalEnv);
+  const run = createReport(root, 'verify', head, null, env);
+  run.project = project;
+  run.projectInputs = guard.inputs;
+  let code = 2,
+    results = null;
+  const inputHashes = [];
+  try {
+    // Official CLI accepts regular input files. Keep private evidence out of argv.
+    const inputs = selected.map((item) => {
+      const { id, title, severity, baseline } = item;
+      const evidence = verificationEvidence(item, root, env);
+      const input = JSON.stringify({
+        id,
+        title,
+        severity,
+        baseline,
+        evidence,
+        ...(project?.policyFile
+          ? {
+              projectPolicy: readFileSync(
+                projectPath(root, project.policyFile, { kind: 'file', required: true }),
+                'utf8'
+              )
+            }
+          : {})
+      });
+      inputHashes.push({ id, sha256: digest(input) });
+      return input;
+    });
+    writeFileSync(
+      join(run.raw, 'verification-input.json'),
+      JSON.stringify(inputs.map(JSON.parse), null, 2),
+      {
+        mode: 0o600
+      }
+    );
+    const inputFiles = inputs.map((input, index) => {
+      const path = join(run.raw, `${selected[index].id}-input.json`);
+      writeFileSync(path, input, { flag: 'wx', mode: 0o600 });
+      return path;
+    });
+    guard.check();
+    console.log(
+      `Codex Security: 定向源码复核 ${selected.map((item) => item.id).join(', ')}；不执行全仓扫描，不运行应用/测试或线上请求。`
+    );
+    console.log(`复核模型：${settings.model}；推理强度：${settings.effort}。`);
+    const response = await invokeEngine(
+      ['verify-fix', ...inputFiles, '--verification-mode', 'static', '--json', ...overrides],
+      { cwd: root, env, raw: run.raw, capture: true }
+    );
+    if (![0, 1, 2].includes(response.code))
+      throw new Error(`Verification interrupted or failed (exit ${response.code}).`);
+    const parsed = validateResponse(response.output, selected, root, response.code);
+    if (snapshot(root, originalEnv) !== before)
+      throw new Error(
+        'Source, HEAD, index or tracker changed during verification; no statuses updated.'
+      );
+    preflightProject(root, project, git);
+    guard.check();
+    const mappings = {
+      fixed: 'verified_static',
+      still_vulnerable: 'open',
+      inconclusive: 'pending_verification'
+    };
+    for (const result of parsed) {
+      const item = tracker.findings.find((entry) => entry.id === result.id);
+      item.status = mappings[result.status];
+      item.lastVerification = {
+        runId: run.runId,
+        mode: 'static',
+        head,
+        sourceDigest: before,
+        verdict: result.status,
+        completedAt: new Date().toISOString(),
+        evidenceArtifact: 'verification.json',
+        inputSha256: inputHashes.find((entry) => entry.id === result.id).sha256
+      };
+    }
+    // Evidence text remains in the private report, not in a tracked JSON file.
+    if (project?.trackerFile) projectPath(root, project.trackerFile, { kind: 'file' });
+    saveTracker(path, tracker, text);
+    results = parsed;
+    code = parsed.some((r) => r.status === 'inconclusive')
+      ? 2
+      : parsed.some(
+            (r) =>
+              r.status === 'still_vulnerable' &&
+              policy.blockSeverities.includes(selected.find((item) => item.id === r.id).severity)
+          )
+        ? 1
+        : 0;
+    for (const result of parsed) console.log(`${result.id}: ${names[mappings[result.status]]}`);
+    if (
+      parsed.some(
+        (r) =>
+          r.status === 'still_vulnerable' &&
+          policy.warnSeverities.includes(selected.find((item) => item.id === r.id).severity)
+      )
+    ) {
+      console.warn(
+        `WARNING: ${policy.failOnSeverity === 'medium' ? '低危问题' : `低于 ${policy.failOnSeverity} 的问题`}仍存在，已记录且不阻断命令。`
+      );
+    }
+    return code;
+  } finally {
+    const metadata = {
+      runId: run.runId,
+      mode: 'static',
+      head,
+      sourceDigest: before,
+      inputHashes,
+      cliVersion,
+      modelSettings: settings,
+      project,
+      projectInputs: guard.inputs,
+      failOnSeverity: policy.failOnSeverity,
+      providerArgumentsDigest: digest(JSON.stringify(overrides)),
+      status: code,
+      results: results?.map(({ id, status }) => ({ id, status })) ?? null,
+      completedAt: new Date().toISOString()
+    };
+    writeFileSync(join(run.raw, 'wrapper-result.json'), JSON.stringify(metadata, null, 2), {
+      mode: 0o600
+    });
+    const lines = [
+      '# 定向修复源码复核',
+      '',
+      `- 执行标识：${run.runId}`,
+      `- HEAD：${head}`,
+      `- 请求模型：${JSON.stringify(settings.model)}；推理强度：${JSON.stringify(settings.effort)}`,
+      `- 源码/暂存快照：${before}`,
+      `- 退出码：${code}`,
+      '',
+      '| 编号 | 原扫描 ID | 原规则 | 本次结论 |',
+      '| --- | --- | --- | --- |',
+      ...selected.map(
+        (item) =>
+          `| ${item.id} | ${item.baseline.scanId} | ${item.baseline.ruleId} | ${results ? names[item.status] : '验证失败，未更新状态'} |`
+      ),
+      '',
+      '仅复核列出的历史漏洞及必要关联代码，不执行全仓发现。已通过源码复核不等于完成运行时/线上验证，也不代表整个项目安全。',
+      '完整证据保存在仓库外同一执行标识目录中的 verification.json；本摘要不复制自由文本、源码或载荷。',
+      `状态变更仅写${project?.trackerFile ?? '本机私有台账'}，不自动暂存、提交或修改旧报告。结论仅对上述快照有效；后续改动可能重新引入问题。`,
+      ...(project
+        ? [
+            `项目规范：${project.policyFile ?? '未指定'}；人工报告模板：${project.reportTemplate ?? '未指定'}。`
+          ]
+        : []),
+      ''
+    ];
+    mkdirSync(dirname(run.summary), { recursive: true });
+    writeFileSync(run.summary, lines.join('\n'), { flag: 'wx', mode: 0o600 });
+    publishSummary(run);
+    console.log(`Codex Security 原始验证证据：${run.raw}\n中文摘要：${run.summary}`);
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      console.error(
+        `Codex Security verification failed: ${error.message.startsWith('Command failed') ? 'External command failed; inspect private diagnostics.' : error.message}`
+      );
+      process.exitCode = 2;
+    });
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@itenl/sec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Security scanning CLI with project policies, shared findings and static fix verification",
+  "type": "module",
+  "bin": {
+    "sec": "bin/sec.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.13.0 || ^24.0.0 || ^26.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "packageManager": "pnpm@10.28.2",
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node scripts/check.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "prepack": "pnpm check",
+    "release:check": "node scripts/release-check.mjs",
+    "prepublishOnly": "pnpm release:check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itenl/sec.git"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/itenl/sec#readme",
+  "bugs": {
+    "url": "https://github.com/itenl/sec/issues"
+  },
+  "keywords": [
+    "security",
+    "cli",
+    "code-review",
+    "codex-security"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/templates/review-report.md

@@ -0,0 +1,27 @@
+# 安全复核报告
+
+## 扫描记录
+
+- 日期与时区：
+- 扫描 ID、执行标识：
+- 分支、HEAD、比较基线与快照：
+- 模式、命令、工具及引擎版本：
+- 规范版本、模型与推理强度：
+- 最终状态、退出码、门禁结论与警告：
+- 原始产物名称及扫描 ID（不填个人绝对路径）：
+
+## 范围与限制
+
+记录请求范围、实际覆盖、排除项、验证方法及未验证的部署条件。没有依据的计数不填写；未执行的步骤说明原因。
+
+## 本轮发现
+
+逐项记录稳定编号、状态、严重级别、置信度、仓库相对位置、影响、利用前提、证据、限制和建议。不包含凭据、完整敏感响应、源码摘录或可直接滥用的完整载荷。
+
+## 历史关联与修复复核
+
+区分新增、重复、历史未关闭、本轮未确认及指定快照已源码复核的项目。严重级别变化说明依据；未再次报告不自动关闭。记录仍需补充的证据与后续工作。
+
+## 交付状态
+
+记录实际改动、验证、待确认事项，以及是否暂存、提交或推送。人工复核后保存报告；自动摘要不能代替本报告。

package/templates/security-policy.md

@@ -0,0 +1,31 @@
+---
+name: project-security
+description: Review this repository's security boundaries and findings when a security scan or vulnerability review is requested.
+---
+
+# 项目安全审查规范
+
+这是一份通用起点。维护者应依据实际代码补充安全边界、部署约束和业务规则；未填写内容不能视为已确认的安全保障或风险豁免。
+
+## 项目上下文
+
+记录需要保护的数据与能力、调用方及权限角色、外部依赖与部署边界。列出关键代码入口，使用仓库相对路径。无法从源码确认的保障标为待核实。
+
+## 审查标准
+
+- 从不可信输入追踪到敏感操作，说明攻击者能力、利用前提、权限边界及实际影响。
+- 结合项目实际能力检查认证授权、输入处理、敏感信息、外部资源访问和输出边界；不因名称或搜索命中直接判定漏洞。
+- 区分源码推断、隔离的本地验证与部署验证；依赖或后端保障需要证据。
+- 严重级别与置信度分别记录。风险接受项须记录理由、适用范围和维护者确认，不自行假定。
+
+## 扫描与复核
+
+运行 sec branch --dry-run 确认范围，再按任务选择 sec branch、sec diff 或 sec scan。路径、门禁和模型以根目录 sec.config.json 及终端显示的有效设置为准。
+
+沿用共享台账编号。修复后用 sec update 指定编号排队，再用 sec verify 定向源码复核；新扫描未报告不等于修复。verified_static 只说明指定快照通过源码复核，不代表线上验证通过。
+
+扫描期间保持源码、Git 状态、规范、模板和台账不变。扫描本身不自动修复、暂存、提交、推送或进行线上操作。
+
+## 报告
+
+使用 sec.config.json 的 reportTemplate 指定的报告模板。报告记录快照、范围、证据和限制，区分本轮发现与历史未关闭项。项目内只保存允许共享的脱敏内容；原始证据及认证保存在仓库外。