@clear-capabilities/agentic-security-scanner 0.78.0 → 0.80.0

package/src/posture/sca-policy.js

@@ -0,0 +1,235 @@
+// SCA policy — declarative per-project rules for vulnerable_dep findings.
+// Phase 4 / Item 7 of the SCA improvement plan.
+//
+// Reads .agentic-security/sca-policy.yml. Three classes of rule:
+//
+//   accept-risk        — per-CVE or per-package suppression with reason +
+//                        optional expiry. Treated as "wont-fix" — the
+//                        finding still appears but is marked suppressed.
+//   sla                — per-severity / per-tier deadlines for remediation.
+//                        Findings older than the SLA are escalated.
+//   major-version-freeze — refuse automated major-version bumps per
+//                          ecosystem. /fix --sca consults this before
+//                          calling apply_sca_upgrade on a breaking change.
+//
+// Policy file shape:
+//
+//   accept-risk:
+//     - cve: CVE-2024-12345
+//       reason: "patched upstream; bundled vendor copy doesn't include affected code"
+//       expires: 2026-12-31
+//     - package: log4j-core
+//       version: 2.17.1
+//       reason: "we run on Java 21; JNDI lookup is disabled at runtime"
+//       expires: 2026-06-30
+//
+//   sla:
+//     critical-kev: 7d
+//     critical: 30d
+//     high: 90d
+//     medium: 180d
+//
+//   major-version-freeze:
+//     npm: [react, vue]            # never auto-upgrade these across majors
+//     pypi: [django]
+//
+// Default policy (no file) is permissive: nothing is suppressed and no
+// SLA is enforced. Users opt in by creating the file.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+
+const DEFAULT_POLICY = {
+  acceptRisk: [],
+  sla: {},
+  majorVersionFreeze: {},
+};
+
+export function loadScaPolicy(scanRoot) {
+  if (!scanRoot) return null;
+  for (const name of ['sca-policy.yml', 'sca-policy.yaml', 'sca-policy.json']) {
+    const p = path.join(scanRoot, '.agentic-security', name);
+    if (!fs.existsSync(p)) continue;
+    try {
+      const raw = fs.readFileSync(p, 'utf8');
+      const doc = name.endsWith('.json') ? JSON.parse(raw) : yaml.load(raw);
+      return _normalize(doc);
+    } catch (e) {
+      return { _error: `Failed to parse ${p}: ${e.message}` };
+    }
+  }
+  return null;
+}
+
+function _normalize(doc) {
+  return {
+    acceptRisk: Array.isArray(doc?.['accept-risk']) ? doc['accept-risk'].map(_normalizeAccept) : [],
+    sla: _normalizeSla(doc?.sla || {}),
+    majorVersionFreeze: _normalizeMajor(doc?.['major-version-freeze'] || {}),
+  };
+}
+
+function _normalizeAccept(entry) {
+  return {
+    cve: entry.cve ? String(entry.cve).toUpperCase() : null,
+    package: entry.package ? String(entry.package).toLowerCase() : null,
+    version: entry.version ? String(entry.version) : null,
+    ecosystem: entry.ecosystem ? String(entry.ecosystem).toLowerCase() : null,
+    reason: entry.reason || '',
+    expires: entry.expires || null,
+  };
+}
+
+function _normalizeSla(sla) {
+  const out = {};
+  for (const [k, v] of Object.entries(sla)) {
+    out[k.toLowerCase()] = _parseSlaDuration(v);
+  }
+  return out;
+}
+
+function _parseSlaDuration(v) {
+  if (typeof v === 'number') return v * 86400_000; // bare number = days
+  const m = String(v).match(/^(\d+)([dwmy])$/i);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  const unit = m[2].toLowerCase();
+  const factor = { d: 86400_000, w: 7 * 86400_000, m: 30 * 86400_000, y: 365 * 86400_000 }[unit];
+  return factor ? n * factor : null;
+}
+
+function _normalizeMajor(maj) {
+  const out = {};
+  for (const [eco, list] of Object.entries(maj)) {
+    if (Array.isArray(list)) out[eco.toLowerCase()] = list.map(s => String(s).toLowerCase());
+  }
+  return out;
+}
+
+// Check whether an accept-risk entry is currently active (not expired).
+function _accepted(entry, today = new Date()) {
+  if (!entry.expires) return true;
+  const exp = new Date(entry.expires);
+  if (Number.isNaN(+exp)) return true; // unparseable: treat as still active
+  return exp >= today;
+}
+
+// Match a finding against the accept-risk list. Returns the matching entry
+// or null.
+export function matchAcceptRisk(finding, policy, today = new Date()) {
+  if (!policy || !Array.isArray(policy.acceptRisk)) return null;
+  const cves = Array.isArray(finding.cveAliases) ? finding.cveAliases.map(c => String(c).toUpperCase()) : [];
+  if (finding.osvId) cves.push(String(finding.osvId).toUpperCase());
+  const pkgName = String(finding.name || '').toLowerCase();
+  for (const entry of policy.acceptRisk) {
+    if (!_accepted(entry, today)) continue;
+    if (entry.cve && cves.includes(entry.cve)) return entry;
+    if (entry.package && pkgName === entry.package) {
+      if (entry.version && finding.version && entry.version !== finding.version) continue;
+      if (entry.ecosystem && finding.ecosystem && entry.ecosystem !== finding.ecosystem) continue;
+      return entry;
+    }
+  }
+  return null;
+}
+
+// Apply policy to a list of SCA findings. Marks accept-risk hits as
+// suppressed; computes SLA deadlines; flags major-version-freeze packages
+// so /fix --sca knows not to auto-upgrade them.
+//
+// Returns { suppressed: number, slaTagged: number, frozen: number }.
+export function applyScaPolicy(findings, policy, scanTime = new Date()) {
+  const stats = { suppressed: 0, slaTagged: 0, frozen: 0 };
+  if (!policy || !Array.isArray(findings)) return stats;
+  for (const f of findings) {
+    if (!f || f.type !== 'vulnerable_dep') continue;
+    // Accept-risk suppression
+    const acceptance = matchAcceptRisk(f, policy, scanTime);
+    if (acceptance) {
+      f.suppressed = true;
+      f.suppressionReason = acceptance.reason || 'accepted-risk';
+      f.suppressionSource = 'sca-policy.yml';
+      f.suppressionExpires = acceptance.expires || null;
+      stats.suppressed++;
+      continue;
+    }
+    // SLA tag: pick the narrowest applicable bucket.
+    const slaKey = (f.kev || f.kevListed) && f.severity === 'critical' ? 'critical-kev'
+                 : f.severity;
+    if (policy.sla && policy.sla[slaKey]) {
+      const startMs = f.firstSeenAt ? Date.parse(f.firstSeenAt) : +scanTime;
+      const deadline = startMs + policy.sla[slaKey];
+      f.slaDeadline = new Date(deadline).toISOString();
+      f.slaOverdue = +scanTime > deadline;
+      stats.slaTagged++;
+    }
+    // Major-version freeze
+    if (policy.majorVersionFreeze
+        && Array.isArray(policy.majorVersionFreeze[f.ecosystem])
+        && policy.majorVersionFreeze[f.ecosystem].includes(String(f.name).toLowerCase())) {
+      f.majorVersionFrozen = true;
+      stats.frozen++;
+    }
+  }
+  return stats;
+}
+
+// Materialize a wont-fix triage decision into a new accept-risk entry.
+// Called by the triage → suppression bridge (Phase 4 / Item 7 of the SCA
+// plan): when a user marks a vulnerable_dep finding wont-fix, the policy
+// file is updated so future scans automatically suppress it.
+//
+// If the policy file doesn't exist, one is created with safe defaults.
+export function appendAcceptRiskFromTriage(scanRoot, finding, reason) {
+  if (!scanRoot || !finding) return { ok: false, reason: 'missing arguments' };
+  const dir = path.join(scanRoot, '.agentic-security');
+  const fp = path.join(dir, 'sca-policy.yml');
+  let policy = loadScaPolicy(scanRoot);
+  if (policy && policy._error) return { ok: false, reason: policy._error };
+  if (!policy) policy = { acceptRisk: [], sla: {}, majorVersionFreeze: {} };
+  // Defensive: even if a policy file existed, it may have been parsed into a
+  // value that shares references with DEFAULT_POLICY. Force a fresh array.
+  if (!Array.isArray(policy.acceptRisk)) policy.acceptRisk = [];
+
+  // De-dupe — don't add a second entry for the same CVE.
+  const cves = Array.isArray(finding.cveAliases) ? finding.cveAliases.map(c => String(c).toUpperCase()) : [];
+  if (finding.osvId) cves.push(String(finding.osvId).toUpperCase());
+  for (const entry of policy.acceptRisk) {
+    if (entry.cve && cves.includes(entry.cve)) return { ok: false, reason: 'CVE already in accept-risk list', cve: entry.cve };
+  }
+
+  const newEntry = {
+    cve: cves[0] || null,
+    package: finding.name ? String(finding.name).toLowerCase() : null,
+    version: finding.version || null,
+    ecosystem: finding.ecosystem || null,
+    reason: reason || `Marked wont-fix in triage on ${new Date().toISOString().slice(0, 10)}`,
+    expires: null,
+  };
+  policy.acceptRisk.push(newEntry);
+
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const serialized = yaml.dump({
+    'accept-risk': policy.acceptRisk.map(e => {
+      const o = {};
+      if (e.cve) o.cve = e.cve;
+      if (e.package) o.package = e.package;
+      if (e.version) o.version = e.version;
+      if (e.ecosystem) o.ecosystem = e.ecosystem;
+      o.reason = e.reason;
+      if (e.expires) o.expires = e.expires;
+      return o;
+    }),
+    sla: policy.sla && Object.keys(policy.sla).length ? Object.fromEntries(Object.entries(policy.sla).map(([k, v]) => [k, _formatSlaDuration(v)])) : undefined,
+    'major-version-freeze': policy.majorVersionFreeze && Object.keys(policy.majorVersionFreeze).length ? policy.majorVersionFreeze : undefined,
+  });
+  fs.writeFileSync(fp, serialized);
+  return { ok: true, entry: newEntry, path: fp };
+}
+
+function _formatSlaDuration(ms) {
+  if (typeof ms !== 'number') return ms;
+  const days = Math.round(ms / 86400_000);
+  return `${days}d`;
+}

package/src/posture/sca-upgrade.js

@@ -0,0 +1,259 @@
+// SCA upgrade engine: dry-run plan + worktree-isolated apply.
+//
+// Phase 3 / Item 5 of the SCA improvement plan. The MCP `apply_fix` path
+// refuses to write manifest files (package.json, *-lock.*, poetry.lock,
+// Cargo.lock, etc.) for safety. SCA findings need a separate path that:
+//   1. Generates an upgrade *plan* via the ecosystem's native dry-run
+//      command (npm install --dry-run, pip install --dry-run, etc.).
+//   2. Applies the upgrade via the package manager itself, with a backup
+//      + test-gate so a peer-dep break or test regression rolls back.
+//
+// Caller pattern: plan first (read-only), inspect the breaking-change
+// flag / peer warnings, then apply with confirm:true.
+
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { statePath } from './state-dir.js';
+
+const execFileAsync = promisify(execFile);
+
+// Per-ecosystem command/manifest map. Add ecosystems by extending this
+// table — every other place in the module reads it.
+const ECOSYSTEM = {
+  npm: {
+    manifests: ['package.json', 'package-lock.json'],
+    altManifests: [['yarn.lock'], ['pnpm-lock.yaml']],
+    dryRun: (pkg, ver) => ({ cmd: 'npm', args: ['install', `${pkg}@${ver}`, '--dry-run', '--json'] }),
+    apply:  (pkg, ver) => ({ cmd: 'npm', args: ['install', `${pkg}@${ver}`, '--save'] }),
+    parseDryRun(stdout) {
+      try {
+        const j = JSON.parse(stdout);
+        const peerDeps = Array.isArray(j.warnings) ? j.warnings.filter(w => /peer dep/i.test(w)) : [];
+        const transitiveImpact = (j.added || []).length + (j.updated || []).length + (j.removed || []).length;
+        return { peerDeps, transitiveImpact, rawSummary: { added: (j.added || []).length, updated: (j.updated || []).length, removed: (j.removed || []).length } };
+      } catch { return { peerDeps: [], transitiveImpact: 0, rawSummary: null }; }
+    },
+  },
+  pypi: {
+    manifests: ['requirements.txt', 'pyproject.toml'],
+    altManifests: [['poetry.lock'], ['Pipfile.lock']],
+    dryRun: (pkg, ver) => ({ cmd: 'pip', args: ['install', '--dry-run', `${pkg}==${ver}`] }),
+    apply:  (pkg, ver) => ({ cmd: 'pip', args: ['install', '--upgrade', `${pkg}==${ver}`] }),
+    parseDryRun() {
+      // pip --dry-run output is human-readable; we don't parse it for v1.
+      return { peerDeps: [], transitiveImpact: 0, rawSummary: null };
+    },
+  },
+  cargo: {
+    manifests: ['Cargo.toml', 'Cargo.lock'],
+    altManifests: [],
+    dryRun: (pkg, _ver) => ({ cmd: 'cargo', args: ['update', '--package', pkg, '--dry-run'] }),
+    apply:  (pkg, _ver) => ({ cmd: 'cargo', args: ['update', '--package', pkg] }),
+    parseDryRun() { return { peerDeps: [], transitiveImpact: 0, rawSummary: null }; },
+  },
+  golang: {
+    manifests: ['go.mod', 'go.sum'],
+    altManifests: [],
+    dryRun: (_pkg, _ver) => null,   // `go get` has no dry-run flag; we skip dry-run in v1.
+    apply:  (pkg, ver) => ({ cmd: 'go', args: ['get', `${pkg}@v${ver}`] }),
+    parseDryRun() { return { peerDeps: [], transitiveImpact: 0, rawSummary: null }; },
+  },
+  // Other ecosystems (rubygems, packagist, pub, maven) return a structured
+  // "manual" plan in v1 — no native dry-run + the install side-effects
+  // (gem build artifacts, composer cache) are easier for the user to
+  // confirm interactively.
+};
+
+function _majorVersion(v) {
+  const m = String(v || '').match(/^(\d+)/);
+  return m ? parseInt(m[1], 10) : null;
+}
+
+function _detectTestCommand(scanRoot) {
+  try {
+    const pkg = path.join(scanRoot, 'package.json');
+    if (fs.existsSync(pkg)) {
+      const j = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+      if (j.scripts?.test && !/no test specified/i.test(j.scripts.test)) {
+        return { cmd: 'npm', args: ['test'] };
+      }
+    }
+  } catch {}
+  if (fs.existsSync(path.join(scanRoot, 'Cargo.toml'))) return { cmd: 'cargo', args: ['test'] };
+  if (fs.existsSync(path.join(scanRoot, 'go.mod'))) return { cmd: 'go', args: ['test', './...'] };
+  if (fs.existsSync(path.join(scanRoot, 'pyproject.toml'))) return { cmd: 'pytest', args: [] };
+  return null;
+}
+
+// Produce a structured upgrade plan WITHOUT modifying anything on disk.
+// Safe to call repeatedly; runs the ecosystem's --dry-run command.
+export async function planScaUpgrade({ scanRoot, finding }) {
+  if (!finding || finding.type !== 'vulnerable_dep') {
+    return { ok: false, reason: 'not a vulnerable_dep finding' };
+  }
+  const eco = ECOSYSTEM[finding.ecosystem];
+  if (!eco) {
+    return {
+      ok: true,
+      mode: 'manual',
+      reason: `ecosystem '${finding.ecosystem}' has no automated upgrade in v1`,
+      package: finding.name, currentVersion: finding.version,
+      targetVersion: (finding.fixedVersions && finding.fixedVersions[0]) || null,
+      command: null,
+    };
+  }
+  const target = (finding.fixedVersions && finding.fixedVersions[0]) || null;
+  if (!target) {
+    return { ok: false, reason: 'no fixed version in OSV record' };
+  }
+  const isBreaking = (_majorVersion(target) ?? 0) > (_majorVersion(finding.version) ?? 0);
+  const apply = eco.apply(finding.name, target);
+  const dryRunSpec = eco.dryRun(finding.name, target);
+  let peerDeps = [], transitiveImpact = 0, rawSummary = null, dryRunOk = null;
+  if (dryRunSpec) {
+    try {
+      const r = await execFileAsync(dryRunSpec.cmd, dryRunSpec.args, {
+        cwd: scanRoot, timeout: 60_000, maxBuffer: 8 * 1024 * 1024,
+      });
+      const parsed = eco.parseDryRun(r.stdout);
+      peerDeps = parsed.peerDeps;
+      transitiveImpact = parsed.transitiveImpact;
+      rawSummary = parsed.rawSummary;
+      dryRunOk = true;
+    } catch (e) {
+      // Dry-run failed (e.g. peer-dep resolution conflict). Surface the
+      // error structurally so the caller can decide whether to proceed.
+      dryRunOk = false;
+      const stderr = (e && e.stderr) || (e && e.message) || '';
+      peerDeps = /peer dep/i.test(stderr) ? [String(stderr).slice(0, 500)] : [];
+    }
+  }
+  return {
+    ok: true,
+    mode: 'auto',
+    ecosystem: finding.ecosystem,
+    package: finding.name,
+    currentVersion: finding.version,
+    targetVersion: target,
+    isBreaking,
+    command: `${apply.cmd} ${apply.args.join(' ')}`,
+    manifestFiles: eco.manifests,
+    dryRun: { ok: dryRunOk, command: dryRunSpec ? `${dryRunSpec.cmd} ${dryRunSpec.args.join(' ')}` : null, peerDeps, transitiveImpact, rawSummary },
+    testCommand: (() => { const t = _detectTestCommand(scanRoot); return t ? `${t.cmd} ${t.args.join(' ')}` : null; })(),
+  };
+}
+
+// Apply the upgrade. Backs up affected manifests, runs the install, runs
+// the project's test command if detected, and ROLLS BACK on failure.
+// Audit-logged via the MCP audit layer at the call site.
+export async function applyScaUpgrade({ scanRoot, finding, runTests = true }) {
+  const plan = await planScaUpgrade({ scanRoot, finding });
+  if (!plan.ok) return { applied: false, reason: plan.reason };
+  if (plan.mode === 'manual') {
+    return { applied: false, reason: plan.reason, plan };
+  }
+  const eco = ECOSYSTEM[finding.ecosystem];
+  const target = plan.targetVersion;
+
+  // Backup pass — record original contents of every relevant manifest so
+  // we can restore on test failure. node_modules / vendor dirs are NOT
+  // backed up (too big); they'll be rebuilt by re-running the install on
+  // restore.
+  const stateDir = statePath(scanRoot, 'sca-upgrade-history');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const upgradeId = crypto.randomBytes(8).toString('hex');
+  const backups = {};
+  for (const mf of eco.manifests) {
+    const abs = path.join(scanRoot, mf);
+    if (!fs.existsSync(abs)) continue;
+    const content = await fsp.readFile(abs, 'utf8');
+    const backupPath = path.join(stateDir, `${upgradeId}-${mf.replace(/[\/\\]/g, '_')}.bak`);
+    await fsp.writeFile(backupPath, content);
+    backups[mf] = { abs, backupPath };
+  }
+  if (!Object.keys(backups).length) {
+    return { applied: false, reason: `no ${finding.ecosystem} manifest files found in scan root` };
+  }
+
+  // Run the install.
+  const apply = eco.apply(finding.name, target);
+  let installOutput = '';
+  try {
+    const r = await execFileAsync(apply.cmd, apply.args, {
+      cwd: scanRoot, timeout: 300_000, maxBuffer: 16 * 1024 * 1024,
+    });
+    installOutput = (r.stdout || '') + (r.stderr || '');
+  } catch (e) {
+    // Install failed; restore backups (manifests may have been touched).
+    for (const { abs, backupPath } of Object.values(backups)) {
+      try { await fsp.copyFile(backupPath, abs); } catch {}
+    }
+    return {
+      applied: false,
+      reason: `install failed: ${(e && e.message) || e}`.slice(0, 600),
+      installOutput: ((e && e.stdout) || '').slice(0, 1500),
+      restored: true,
+      upgradeId,
+    };
+  }
+
+  // Optionally run the project's test command. On failure, restore.
+  let testResult = null;
+  if (runTests) {
+    const test = _detectTestCommand(scanRoot);
+    if (test) {
+      try {
+        const r = await execFileAsync(test.cmd, test.args, {
+          cwd: scanRoot, timeout: 600_000, maxBuffer: 16 * 1024 * 1024,
+        });
+        testResult = { ok: true, command: `${test.cmd} ${test.args.join(' ')}`, output: ((r.stdout || '') + (r.stderr || '')).slice(0, 2000) };
+      } catch (e) {
+        // Tests failed — restore manifests so the working tree is clean.
+        for (const { abs, backupPath } of Object.values(backups)) {
+          try { await fsp.copyFile(backupPath, abs); } catch {}
+        }
+        return {
+          applied: false,
+          reason: `tests failed after upgrade: ${(e && e.message) || e}`.slice(0, 300),
+          testOutput: ((e && e.stdout) || '').slice(0, 2000),
+          restored: true,
+          upgradeId,
+        };
+      }
+    }
+  }
+
+  // Success path — write a log entry so the user can audit / undo.
+  const logEntry = {
+    id: upgradeId,
+    timestamp: new Date().toISOString(),
+    ecosystem: finding.ecosystem,
+    package: finding.name,
+    from: finding.version,
+    to: target,
+    backups: Object.fromEntries(Object.entries(backups).map(([k, v]) => [k, v.backupPath])),
+    testResult,
+    isBreaking: plan.isBreaking,
+    finding: { id: finding.id, osvId: finding.osvId, cveAliases: finding.cveAliases },
+  };
+  const logFp = path.join(stateDir, 'log.json');
+  let log = [];
+  try { log = JSON.parse(fs.readFileSync(logFp, 'utf8')); } catch {}
+  log.push(logEntry);
+  fs.writeFileSync(logFp, JSON.stringify(log, null, 2));
+
+  return {
+    applied: true,
+    upgradeId,
+    package: finding.name,
+    from: finding.version,
+    to: target,
+    isBreaking: plan.isBreaking,
+    testResult,
+    installOutput: installOutput.slice(0, 1500),
+  };
+}

package/src/posture/security-trend.js

@@ -6,12 +6,12 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { statePath, safeWriteState } from './state-dir.js';
 
-const HISTORY_FILE = '.agentic-security/scan-history.json';
 const MAX_HISTORY = 30; // rolling window
 
 function _readHistory(scanRoot) {
-  const histPath = scanRoot ? path.join(scanRoot, HISTORY_FILE) : HISTORY_FILE;
+  const histPath = statePath(scanRoot, 'scan-history.json');
   try {
     return JSON.parse(fs.readFileSync(histPath, 'utf8'));
   } catch {
@@ -20,11 +20,8 @@ function _readHistory(scanRoot) {
 }
 
 function _writeHistory(scanRoot, history) {
-  const histPath = scanRoot ? path.join(scanRoot, HISTORY_FILE) : HISTORY_FILE;
-  try {
-    fs.mkdirSync(path.dirname(histPath), { recursive: true });
-    fs.writeFileSync(histPath, JSON.stringify(history.slice(-MAX_HISTORY), null, 2));
-  } catch {}
+  const histPath = statePath(scanRoot, 'scan-history.json');
+  safeWriteState(histPath, JSON.stringify(history.slice(-MAX_HISTORY), null, 2));
 }
 
 function _snapshotFromScan(scan, label) {

package/src/posture/state-dir.js

@@ -0,0 +1,124 @@
+// Project-root resolver for .agentic-security/ state.
+//
+// BUG HISTORY: Previously, state-writing code used the pattern
+//   `path.join(scanRoot || process.cwd(), '.agentic-security', ...)`
+// When `scanRoot` was null/undefined and the scanner was invoked from
+// a subdirectory (e.g., migrations/, config/), this created
+// `.agentic-security/` folders inside those subdirectories — breaking
+// the user's build (one report: DB migration system saw the folder as
+// a migration file). One user uninstalled the plugin entirely.
+//
+// FIX: All state writes go through this module. process.cwd() is NEVER
+// trusted directly. We walk upward from cwd looking for project markers
+// (.git, package.json, etc.) and write state there. A safety check
+// refuses to write if no marker is found.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const PROJECT_MARKERS = [
+  '.git',
+  'package.json',
+  'pyproject.toml',
+  'go.mod',
+  'Cargo.toml',
+  'pom.xml',
+  'build.gradle',
+  'composer.json',
+  'Gemfile',
+  '.agentic-security',
+];
+
+function _findProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const visited = new Set();
+  while (dir && !visited.has(dir)) {
+    visited.add(dir);
+    for (const m of PROJECT_MARKERS) {
+      try {
+        if (fs.existsSync(path.join(dir, m))) return dir;
+      } catch { /* ignore */ }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function resolveProjectRoot(scanRoot) {
+  // Prefer caller-provided scanRoot when it points to an existing directory
+  if (scanRoot && typeof scanRoot === 'string') {
+    try {
+      const resolved = path.resolve(scanRoot);
+      if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+        return resolved;
+      }
+    } catch { /* fall through */ }
+  }
+  // Walk upward from cwd looking for project markers
+  const fromCwd = _findProjectRoot(process.cwd());
+  if (fromCwd) return fromCwd;
+  // No project markers found — return cwd but caller should check via isSafeStateDir
+  return process.cwd();
+}
+
+export function stateDir(scanRoot) {
+  return path.join(resolveProjectRoot(scanRoot), '.agentic-security');
+}
+
+export function statePath(scanRoot, ...parts) {
+  return path.join(stateDir(scanRoot), ...parts);
+}
+
+// Safety check: refuse to create .agentic-security/ unless the parent
+// directory has at least one project marker. Prevents littering when
+// resolution falls through to a non-project directory.
+export function isSafeStateDir(dir) {
+  if (!dir) return false;
+  const parent = path.dirname(dir);
+  for (const m of PROJECT_MARKERS) {
+    if (m === '.agentic-security') continue; // would be circular
+    try {
+      if (fs.existsSync(path.join(parent, m))) return true;
+    } catch { /* ignore */ }
+  }
+  return false;
+}
+
+// Safe mkdir: only creates .agentic-security/ if the parent has a project marker.
+// Returns the dir on success, null if refused. Logs a warning when refused.
+export function ensureStateDir(scanRoot) {
+  const dir = stateDir(scanRoot);
+  if (!isSafeStateDir(dir)) {
+    if (process.env.AGENTIC_SECURITY_DEBUG === '1') {
+      process.stderr.write(`[agentic-security] refusing to create state dir at ${dir} — no project marker in parent\n`);
+    }
+    return null;
+  }
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  } catch {
+    return null;
+  }
+}
+
+// Safe write: only writes if isSafeStateDir(parent) returns true.
+// Returns true on success, false if refused or errored.
+export function safeWriteState(filePath, content) {
+  const dir = path.dirname(filePath);
+  if (!isSafeStateDir(dir)) {
+    if (process.env.AGENTIC_SECURITY_DEBUG === '1') {
+      process.stderr.write(`[agentic-security] refusing to write state file at ${filePath} — no project marker in parent of ${dir}\n`);
+    }
+    return false;
+  }
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, content);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/posture/streak.js

@@ -11,6 +11,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { isSafeStateDir } from './state-dir.js';
 
 function _streakPath(stateDir) {
   return path.join(stateDir, 'streak.json');
@@ -115,6 +116,7 @@ function _computeAchievements(streak, scan) {
 
 // Public — invoked by the CLI after every full scan.
 export function recordScan(stateDir, scan) {
+  if (!isSafeStateDir(stateDir)) return null;
   try { fs.mkdirSync(stateDir, { recursive: true }); } catch {}
   const prev = loadStreak(stateDir);
   const today = _todayUTC();
@@ -182,6 +184,7 @@ export function recordScan(stateDir, scan) {
 
 // Mark "launch check passed 10/10" — called from /security-launch-check
 export function markLaunchCheckPassed(stateDir) {
+  if (!isSafeStateDir(stateDir)) return null;
   const prev = loadStreak(stateDir);
   const next = { ...prev, launchCheckPassedAt: new Date().toISOString() };
   next.achievements = _computeAchievements(next, { findings: [] });