@itenl/sec 0.0.0-stage → 0.1.0

package/lib/engine.mjs

@@ -0,0 +1,96 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { engineVersion, userDirectories, modelSettings } from './config.mjs';
+
+export function engineEnvironment(source = process.env) {
+  const { config, state } = userDirectories(source);
+  const env = {
+    ...source,
+    CODEX_HOME: join(config, 'engine-home'),
+    CODEX_SECURITY_STATE_DIR: join(state, 'engine')
+  };
+  delete env.CODEX_SECURITY_PROJECT_CONFIG;
+  return env;
+}
+export function engineCommand(env = process.env) {
+  const managed = join(userDirectories(env).config, 'runtime/node_modules/.bin/codex-security');
+  return existsSync(managed) ? managed : 'codex-security';
+}
+export function ensureEngine(env = process.env, run = execFileSync) {
+  let version;
+  try {
+    version = run(engineCommand(env), ['--version'], {
+      env,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 10000
+    }).trim();
+  } catch {
+    throw new Error('Scan engine unavailable. Run sec setup.');
+  }
+  if (!new RegExp(`(?:^|@|\\s)${engineVersion.replaceAll('.', '\\.')}($|\\s)`).test(version)) {
+    throw new Error(`Unsupported scan engine version. Run sec setup for version ${engineVersion}.`);
+  }
+  return version;
+}
+export function providerArguments(config, overrides = {}) {
+  const { model, effort } = modelSettings(config, overrides);
+  const args = [
+    '--codex',
+    `model=${JSON.stringify(model)}`,
+    '--codex',
+    `model_reasoning_effort=${JSON.stringify(effort)}`
+  ];
+  if (config.baseUrl) {
+    args.push(
+      '--codex',
+      'model_provider="custom"',
+      '--codex',
+      `model_providers.custom=${'{'}name="custom",base_url=${JSON.stringify(config.baseUrl)},wire_api="responses",requires_openai_auth=true}`
+    );
+  }
+  return args;
+}
+export function invokeEngine(args, { cwd, env, raw, capture = false }) {
+  return new Promise((resolveResult, reject) => {
+    const child = spawn(engineCommand(env), args, {
+      cwd,
+      env,
+      stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit'
+    });
+    let output = '',
+      diagnostics = '';
+    child.stdout?.on('data', (data) => {
+      output += data;
+    });
+    child.stderr?.on('data', (data) => {
+      diagnostics += data;
+    });
+    const interrupt = () => child.kill('SIGINT');
+    const terminate = () => child.kill('SIGTERM');
+    process.on('SIGINT', interrupt);
+    process.on('SIGTERM', terminate);
+    const cleanup = () => {
+      process.off('SIGINT', interrupt);
+      process.off('SIGTERM', terminate);
+    };
+    child.on('error', () => {
+      cleanup();
+      reject(new Error('Cannot start scan engine. Run sec doctor.'));
+    });
+    child.on('close', (code, signal) => {
+      cleanup();
+      if (capture && raw) {
+        writeFileSync(join(raw, 'verification.json'), output, { mode: 0o600 });
+        writeFileSync(join(raw, 'diagnostics.log'), diagnostics, {
+          mode: 0o600
+        });
+      }
+      resolveResult({
+        code: code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 2),
+        output
+      });
+    });
+  });
+}

package/lib/policy.mjs

@@ -0,0 +1,8 @@
+// Executable policy shared by discovery and repair verification.
+export const policy = Object.freeze({
+  version: 1,
+  blockSeverities: Object.freeze(['critical', 'high', 'medium']),
+  warnSeverities: Object.freeze(['low']),
+  failOnSeverity: 'medium',
+  timeZone: 'UTC'
+});

package/lib/project-init.mjs

@@ -0,0 +1,111 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { parseArgs } from 'node:util';
+import { branchBaseRef, defaultModel, defaultEffort, readConfig } from './config.mjs';
+import {
+  projectPaths,
+  projectConfigFile,
+  projectPath,
+  readProjectConfig,
+  saveProjectConfig,
+  validateProjectConfig
+} from './project.mjs';
+import { inferPrefix, readTracker } from './tracker.mjs';
+
+function readTemplate(name) {
+  try {
+    return readFileSync(new URL(`../templates/${name}`, import.meta.url), 'utf8');
+  } catch {
+    throw new Error(`Bundled template missing or unreadable: ${name}. Reinstall sec.`);
+  }
+}
+export function main(
+  args = [],
+  { env = process.env, cwd = process.cwd(), log = console.log } = {}
+) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: { 'dry-run': { type: 'boolean' } },
+    allowPositionals: true
+  });
+  if (positionals.length !== 1 || positionals[0] !== 'project')
+    throw new Error('Use sec init project [--dry-run].');
+  const root = execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
+    env,
+    encoding: 'utf8',
+    stdio: 'pipe'
+  }).trim();
+  const previous = readProjectConfig(root);
+  const previousText = previous ? readFileSync(projectConfigFile(root), 'utf8') : null;
+  const config = {
+    schemaVersion: 1,
+    ...projectPaths,
+    knowledgeBase: [],
+    idPrefix: 'SEC',
+    baseRef: branchBaseRef(root, readConfig(env), undefined, env),
+    model: defaultModel,
+    effort: defaultEffort,
+    failOnSeverity: 'medium',
+    ...previous
+  };
+  const ledgerPath = projectPath(root, config.trackerFile, { kind: 'file' });
+  if (existsSync(ledgerPath) && !previous?.idPrefix)
+    config.idPrefix = inferPrefix(readTracker(ledgerPath, false, null).tracker);
+  validateProjectConfig(config, root);
+  if (existsSync(ledgerPath)) readTracker(ledgerPath, false, config.idPrefix);
+  const plan = [
+    [config.policyFile, readTemplate('security-policy.md')],
+    [config.reportTemplate, readTemplate('review-report.md')],
+    [config.trackerFile, `${JSON.stringify({ schemaVersion: 1, findings: [] }, null, 2)}\n`]
+  ];
+  for (const [path] of plan) projectPath(root, path, { kind: 'file' });
+  for (const key of ['summaryDir', 'reviewDir'])
+    projectPath(root, config[key], { kind: 'directory' });
+  const ignore = projectPath(root, '.gitignore', { kind: 'file' });
+  const oldIgnore = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+  // Literal Git ignore patterns, including spaces and glob metacharacters in custom paths.
+  const escape = (path) => path.replace(/[\\*?\[\]#! ]/g, '\\$&');
+  const summaryRelative = relative(root, projectPath(root, config.summaryDir));
+  const trackerRelative = relative(root, ledgerPath);
+  const rules = [
+    `/${escape(summaryRelative)}/`,
+    `/${escape(trackerRelative)}.lock`,
+    `/${escape(trackerRelative)}.*.tmp`,
+    '/sec.config.json.lock',
+    '/sec.config.json.*.tmp'
+  ];
+  const missingRules = rules.filter((rule) => !oldIgnore.split(/\r?\n/).includes(rule));
+  for (const [path] of plan) log(`${existsSync(join(root, path)) ? '保留' : '创建'} ${path}`);
+  log(`${previous ? '保留已有配置并补齐缺少的默认项' : '创建'} sec.config.json`);
+  if (missingRules.length) log('补充 .gitignore：自动摘要与台账临时文件');
+  log(`报告目录：${config.summaryDir}（自动摘要）、${config.reviewDir}（人工报告）`);
+  if (values['dry-run']) {
+    log('仅预览；未写文件、未调用模型。');
+    return 0;
+  }
+  for (const [path, content] of plan)
+    if (!existsSync(join(root, path))) {
+      const target = projectPath(root, path, { kind: 'file' });
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, content, { flag: 'wx', mode: 0o644 });
+    }
+  for (const key of ['summaryDir', 'reviewDir'])
+    mkdirSync(projectPath(root, config[key], { kind: 'directory' }), { recursive: true });
+  if (!previous || JSON.stringify(previous) !== JSON.stringify(config))
+    saveProjectConfig(root, config, previousText);
+  if (missingRules.length) {
+    if ((existsSync(ignore) ? readFileSync(ignore, 'utf8') : '') !== oldIgnore)
+      throw new Error(
+        '.gitignore changed during initialization; inspect generated files before retrying.'
+      );
+    writeFileSync(
+      ignore,
+      `${oldIgnore}${oldIgnore && !oldIgnore.endsWith('\n') ? '\n' : ''}\n# sec generated summaries and tracker temporary files\n${missingRules.join('\n')}\n`,
+      { mode: 0o644 }
+    );
+  }
+  log('项目已初始化；请维护者检查通用规范和模板。已有文件未覆盖，未暂存、提交、联网或请求模型。');
+  log('配置与规范随业务仓库共享；凭据和完整原始证据保存在仓库外。本机旧私有台账不自动合并。');
+  return 0;
+}

package/lib/project.mjs

@@ -0,0 +1,305 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+  copyFileSync,
+  constants,
+  openSync,
+  closeSync,
+  accessSync
+} from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { policy } from './policy.mjs';
+
+export const projectPaths = Object.freeze({
+  policyFile: '.agents/skills/project-security/SKILL.md',
+  reportTemplate: '.agents/skills/project-security/references/report-template.md',
+  trackerFile: 'docs/security/findings.json',
+  summaryDir: 'docs/security/reviews/generated',
+  reviewDir: 'docs/security/reviews'
+});
+export const projectKeys = [
+  ...Object.keys(projectPaths),
+  'knowledgeBase',
+  'idPrefix',
+  'baseRef',
+  'model',
+  'effort',
+  'failOnSeverity'
+];
+export const levels = ['critical', 'high', 'medium', 'low'];
+export const projectConfigFile = (root) => join(root, 'sec.config.json');
+export const validPrefix = (prefix) =>
+  typeof prefix === 'string' &&
+  /^[A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)*$/.test(prefix) &&
+  prefix.length <= 60;
+export const findingId = (id) =>
+  typeof id === 'string' && /^([A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)*)-(\d{3,})$/.test(id);
+
+// Project paths are data, never executable modules or machine-specific locations.
+export function projectPath(root, value, { kind, required = false } = {}) {
+  if (
+    typeof value !== 'string' ||
+    !value ||
+    isAbsolute(value) ||
+    /^[A-Za-z]:/.test(value) ||
+    /[\\\x00-\x1f\x7f]/.test(value) ||
+    value.split('/').some((part) => part === '..' || part === '.git')
+  )
+    throw new Error(
+      'Project paths must be repository-relative, without traversal or .git components.'
+    );
+  const path = resolve(root, value),
+    rel = relative(root, path);
+  if (!rel || rel.startsWith('../') || isAbsolute(rel))
+    throw new Error('Project paths must stay inside the repository.');
+  let current = resolve(root);
+  for (const part of rel.split('/')) {
+    current = join(current, part);
+    try {
+      if (lstatSync(current).isSymbolicLink())
+        throw new Error('Project paths must not contain symlinks.');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  if (existsSync(path)) {
+    const stat = lstatSync(path);
+    if (
+      (kind === 'file' && !stat.isFile()) ||
+      (kind === 'directory' && !stat.isDirectory()) ||
+      (!kind && !stat.isFile() && !stat.isDirectory())
+    )
+      throw new Error(`Invalid project path type: ${value}`);
+  } else if (required)
+    throw new Error(
+      `Missing project input: ${value}. Run sec init project or correct sec config --project.`
+    );
+  return path;
+}
+export function validateProjectConfig(config, root) {
+  if (
+    !config ||
+    Array.isArray(config) ||
+    config.schemaVersion !== 1 ||
+    Object.keys(config).some((key) => !['schemaVersion', ...projectKeys].includes(key))
+  )
+    throw new Error(
+      'Unsupported project configuration fields/version. Credentials and provider URLs belong outside the repository.'
+    );
+  for (const key of ['baseRef', 'model', 'effort']) {
+    if (
+      config[key] !== undefined &&
+      (typeof config[key] !== 'string' ||
+        !config[key] ||
+        /[\x00-\x20\x7f]/.test(config[key]) ||
+        config[key].startsWith('-'))
+    )
+      throw new Error(`Invalid project ${key}.`);
+  }
+  if (config.idPrefix !== undefined && !validPrefix(config.idPrefix))
+    throw new Error('Invalid finding ID prefix. Use uppercase segments such as SEC or TEAM-SEC.');
+  if (config.failOnSeverity !== undefined && !levels.includes(config.failOnSeverity))
+    throw new Error('Invalid failOnSeverity.');
+  if (
+    config.knowledgeBase !== undefined &&
+    (!Array.isArray(config.knowledgeBase) ||
+      config.knowledgeBase.some((path) => typeof path !== 'string'))
+  )
+    throw new Error('knowledgeBase must be a JSON array of repository-relative paths.');
+  for (const key of Object.keys(projectPaths))
+    if (config[key] !== undefined)
+      projectPath(root, config[key], { kind: key.endsWith('Dir') ? 'directory' : 'file' });
+  for (const value of config.knowledgeBase || []) projectPath(root, value);
+  const files = [
+    'sec.config.json',
+    ...['policyFile', 'reportTemplate', 'trackerFile']
+      .filter((key) => config[key])
+      .map((key) => config[key])
+  ].map((p) => resolve(root, p));
+  if (new Set(files).size !== files.length)
+    throw new Error('Project configuration, policy, template and tracker must use distinct files.');
+  for (const file of files)
+    for (const other of files)
+      if (file !== other && file.startsWith(`${other}/`))
+        throw new Error('Project file paths must not contain other managed files.');
+  for (const key of ['summaryDir', 'reviewDir'])
+    if (config[key]) {
+      const directory = resolve(root, config[key]);
+      for (const file of files)
+        if (
+          directory === file ||
+          directory.startsWith(`${file}/`) ||
+          file.startsWith(`${directory}/`)
+        )
+          throw new Error(
+            'Report directories must not overlap configuration, policy, template or tracker files.'
+          );
+    }
+  if (
+    config.summaryDir &&
+    config.reviewDir &&
+    resolve(root, config.summaryDir) === resolve(root, config.reviewDir)
+  )
+    throw new Error('Automatic summaries and reviewed reports must use distinct directories.');
+  return config;
+}
+export function readProjectConfig(root) {
+  const path = projectPath(root, 'sec.config.json', { kind: 'file' });
+  if (!existsSync(path)) return null;
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error('Cannot parse sec.config.json.');
+  }
+  return validateProjectConfig(config, root);
+}
+export function saveProjectConfig(root, config, previous) {
+  validateProjectConfig(config, root);
+  const path = projectPath(root, 'sec.config.json', { kind: 'file' });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  let lock;
+  try {
+    lock = openSync(`${path}.lock`, 'wx', 0o600);
+    const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    if (current !== previous) throw new Error('Project configuration changed; no update saved.');
+    writeFileSync(temp, `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx', mode: 0o644 });
+    if (previous === null) copyFileSync(temp, path, constants.COPYFILE_EXCL);
+    else renameSync(temp, path);
+  } finally {
+    rmSync(temp, { force: true });
+    if (lock !== undefined) {
+      closeSync(lock);
+      rmSync(`${path}.lock`, { force: true });
+    }
+  }
+}
+export function projectPolicy(config) {
+  const failOnSeverity = config?.failOnSeverity ?? policy.failOnSeverity;
+  return {
+    version: policy.version,
+    failOnSeverity,
+    timeZone: policy.timeZone,
+    blockSeverities: levels.slice(0, levels.indexOf(failOnSeverity) + 1),
+    warnSeverities: levels.slice(levels.indexOf(failOnSeverity) + 1)
+  };
+}
+export function projectInputs(root, config) {
+  if (!config) return [];
+  const paths = [config.policyFile, config.reportTemplate, ...(config.knowledgeBase || [])].filter(
+    Boolean
+  );
+  return [...new Set(paths)].map((path) => {
+    const absolute = projectPath(root, path, { required: true });
+    if ([config.policyFile, config.reportTemplate].includes(path) && !lstatSync(absolute).isFile())
+      throw new Error('Policy and template must be regular text files.');
+    return { path: relative(root, absolute), absolute };
+  });
+}
+function inputDigest(path) {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink()) throw new Error('Knowledge inputs must not contain symlinks.');
+  if (stat.isFile()) return createHash('sha256').update(readFileSync(path)).digest('hex');
+  if (!stat.isDirectory())
+    throw new Error('Knowledge inputs must be regular files or directories.');
+  return createHash('sha256')
+    .update(
+      JSON.stringify(
+        readdirSync(path)
+          .sort()
+          .map((name) => [name, inputDigest(join(path, name))])
+      )
+    )
+    .digest('hex');
+}
+export function projectGuard(root, config) {
+  if (JSON.stringify(readProjectConfig(root)) !== JSON.stringify(config))
+    throw new Error('Project configuration changed before scanning.');
+  const initial = [
+    { path: 'sec.config.json', absolute: projectConfigFile(root) },
+    ...projectInputs(root, config)
+  ];
+  const manifest = () =>
+    initial.map(({ path, absolute }) => ({
+      path,
+      sha256: existsSync(absolute) ? inputDigest(absolute) : null
+    }));
+  const before = JSON.stringify(manifest());
+  return {
+    inputs: JSON.parse(before),
+    check() {
+      projectPath(root, 'sec.config.json', { kind: 'file' });
+      projectInputs(root, config);
+      if (JSON.stringify(manifest()) !== before)
+        throw new Error(
+          'Project configuration, policy, template or knowledge inputs changed during the scan; no tracker update saved.'
+        );
+    }
+  };
+}
+export function publishSummary(run) {
+  if (!run.project?.summaryDir) return;
+  const directory = `${run.project.summaryDir}/${run.startedAt.slice(0, 10)}`;
+  let path;
+  try {
+    path = projectPath(run.root, `${directory}/${run.runId}.md`, { kind: 'file' });
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, readFileSync(run.summary), { flag: 'wx', mode: 0o644 });
+  } catch (error) {
+    const metadataPath = join(run.raw, 'wrapper-result.json');
+    const metadata = JSON.parse(readFileSync(metadataPath, 'utf8'));
+    metadata.status = 2;
+    metadata.summaryExportError =
+      'Failed to publish project summary; private artifacts preserved. Tracker may already have been updated.';
+    writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+    throw new Error(
+      `Project summary export failed; private artifacts remain in ${run.raw}. Tracker may already be updated. ${error.code ?? ''}`
+    );
+  }
+  console.log(`Codex Security 项目中文摘要: ${path}`);
+}
+
+export function preflightProject(root, config, git) {
+  projectInputs(root, config);
+  if (!config) return;
+  for (const path of [
+    projectConfigFile(root),
+    ...(config.trackerFile ? [projectPath(root, config.trackerFile)] : [])
+  ]) {
+    if (existsSync(`${path}.lock`))
+      throw new Error(
+        'Project configuration or tracker is locked by another operation; retry after it finishes.'
+      );
+  }
+  for (const key of ['trackerFile', 'summaryDir', 'reviewDir'])
+    if (config[key])
+      projectPath(root, config[key], { kind: key === 'trackerFile' ? 'file' : 'directory' });
+  for (const key of ['trackerFile', 'summaryDir'])
+    if (config[key]) {
+      const target = projectPath(root, config[key]);
+      let parent = dirname(target);
+      while (!existsSync(parent)) parent = dirname(parent);
+      accessSync(parent, constants.W_OK);
+      if (existsSync(target)) accessSync(target, constants.W_OK);
+    }
+  if (config.summaryDir) {
+    try {
+      git('check-ignore', '--quiet', '--no-index', '--', `${config.summaryDir}/sec-preflight.md`);
+    } catch {
+      throw new Error(
+        'Automatic summary directory must be ignored by Git. Run sec init project or update .gitignore before scanning.'
+      );
+    }
+    if (git('ls-files', '--', config.summaryDir))
+      throw new Error(
+        'Automatic summary directory contains tracked files; choose an ignored output directory before scanning.'
+      );
+  }
+}