argusqa-os 9.8.1 → 9.9.0

package/src/utils/aegis-vault.js

@@ -0,0 +1,251 @@
+/**
+ * Aegis — local re-hydration vault (Step 8 of REDACTION_BOUNDARY_MAX_PLAN.md).
+ *
+ * OPTIONAL, default OFF (ARGUS_REDACT_VAULT=1 to enable). Implements the enterprise
+ * "smart redaction" reversible-tokenization pattern (plan §5.3): a sensitive span is
+ * replaced on egress (scrubText's `token` mode) by a deterministic, information-free
+ * token (`AEGIS_<hmac16>`), and the token→original mapping is written to a LOCAL,
+ * gitignored, 0600 vault file. The token that crosses the trust boundary reveals
+ * NOTHING; only an operator on THIS machine — who holds the per-machine key and the
+ * vault files — can re-hydrate via `npm run report:rehydrate`.
+ *
+ * SECURITY POSTURE — fail CLOSED (consistent with the rest of Aegis):
+ *   - The token is an HMAC tag → it cannot contain the secret. A leak of the egress
+ *     artifact discloses no plaintext.
+ *   - If the vault is NOT enabled / wired, scrubText's `token` mode falls back to
+ *     MASK (never the raw value) — see secret-patterns.js maskValue.
+ *   - The vault key + mapping files are written 0600 and live under
+ *     reports/.aegis-vault/ (gitignored). The audit trail is secret-free (token only).
+ *
+ * Crypto note (plan §5.3 / §13.6): the default token is HMAC-SHA256 — NOT
+ * format-preserving, so it needs no cipher. If a shape-preserving token is ever
+ * required, use NIST FF1 (SP 800-38G); FF3/FF3-1 were WITHDRAWN by NIST in Feb 2025
+ * and must not be used.
+ *
+ * This module is the ONLY place Aegis does filesystem I/O. secret-patterns.js stays
+ * pure — it receives `tokenFor` through the setVaultTokenizer injection seam.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { childLogger } from './logger.js';
+import { getCurrentBranch } from './baseline-manager.js';
+import { setVaultTokenizer } from './secret-patterns.js';
+
+const logger = childLogger('aegis-vault');
+
+const TOKEN_PREFIX = 'AEGIS_';
+const TOKEN_HEX_LEN = 16;                  // 64-bit HMAC tag
+// Matches exactly what computeToken emits — used by rehydrate to find tokens.
+const TOKEN_RE = /AEGIS_[0-9a-f]{16}/g;
+
+let _key = null;        // cached per-machine key (Buffer)
+let _branch = null;     // cached branch name (avoid repeated git calls)
+let _wired = false;     // setVaultTokenizer registered?
+const _seen = new Set(); // tokens persisted this process (in-run dedup)
+
+/** True when the operator opted into the reversible vault. */
+export function vaultEnabled() {
+  return process.env.ARGUS_REDACT_VAULT === '1';
+}
+
+/** Base vault dir (overridable for tests/operators via ARGUS_REDACT_VAULT_DIR). */
+function vaultDir() {
+  return process.env.ARGUS_REDACT_VAULT_DIR || path.join('reports', '.aegis-vault');
+}
+
+/** Secret-free provenance/audit dir (sibling of the vault). */
+function auditDir() {
+  return process.env.ARGUS_REDACT_AUDIT_DIR || path.join('reports', '.aegis-audit');
+}
+
+function keyFile() {
+  return path.join(vaultDir(), 'key');
+}
+
+function ensureDir(dir) {
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* best-effort */ }
+}
+
+/**
+ * Per-machine HMAC key. Read from reports/.aegis-vault/key if present, else
+ * generated (32 random bytes) and persisted 0600. Cached in-process. On a write
+ * failure an ephemeral key is used (tokens stay valid within the run).
+ * @returns {Buffer}
+ */
+export function getKey() {
+  if (_key) return _key;
+  const file = keyFile();
+  try {
+    if (fs.existsSync(file)) {
+      const hex = fs.readFileSync(file, 'utf8').trim();
+      if (/^[0-9a-f]{64}$/i.test(hex)) { _key = Buffer.from(hex, 'hex'); return _key; }
+    }
+  } catch { /* fall through and regenerate */ }
+
+  ensureDir(vaultDir());
+  const key = crypto.randomBytes(32);
+  try {
+    // Owner-only (0600) — the key seeds every reversible token. chmod after write is
+    // best-effort (no-op on Windows, where access is ACL-based, not POSIX mode bits).
+    fs.writeFileSync(file, key.toString('hex'), { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(file, 0o600); } catch { /* mode bits unsupported on this platform */ }
+  } catch (err) {
+    logger.warn(`[ARGUS] Aegis vault: could not persist key — using an ephemeral key: ${err.message}`);
+  }
+  _key = key;
+  return _key;
+}
+
+function currentBranch() {
+  if (_branch) return _branch;
+  try { _branch = getCurrentBranch() || 'default'; } catch { _branch = 'default'; }
+  return _branch;
+}
+
+function vaultFile() {
+  return path.join(vaultDir(), `${currentBranch()}.jsonl`);
+}
+
+/**
+ * Deterministic, information-free token for a value (HMAC-SHA256 tag). Same value ⇒
+ * same token on this machine, so the external artifact stays diff-stable. Does NOT
+ * persist a mapping — use tokenFor for that.
+ * @param {*} value
+ * @returns {string}
+ */
+export function computeToken(value) {
+  const v = String(value ?? '');
+  const tag = crypto.createHmac('sha256', getKey()).update(v).digest('hex').slice(0, TOKEN_HEX_LEN);
+  return TOKEN_PREFIX + tag;
+}
+
+/**
+ * Append a secret-free provenance line for an egress action. The audit trail
+ * records WHAT token was minted, never the plaintext (the token is information-free).
+ * Gives the NIST-RMF "traceability" trail without itself storing a secret.
+ * @param {object} entry
+ */
+export function appendAudit(entry) {
+  ensureDir(auditDir());
+  const file = path.join(auditDir(), `${currentBranch()}.jsonl`);
+  const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + '\n';
+  try {
+    fs.appendFileSync(file, line, { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(file, 0o600); } catch { /* unsupported on Windows */ }
+  } catch { /* audit is best-effort; never break egress */ }
+}
+
+/**
+ * Persist a token→value mapping to the vault file (0600). In-run dedup keeps the
+ * file from growing per duplicate span within a single process.
+ * @param {string} token
+ * @param {*} value
+ */
+export function storeMapping(token, value) {
+  if (_seen.has(token)) return;
+  _seen.add(token);
+  ensureDir(vaultDir());
+  const line = JSON.stringify({ token, value: String(value ?? ''), ts: new Date().toISOString() }) + '\n';
+  try {
+    fs.appendFileSync(vaultFile(), line, { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(vaultFile(), 0o600); } catch { /* unsupported on Windows */ }
+  } catch (err) {
+    logger.warn(`[ARGUS] Aegis vault: mapping write failed: ${err.message}`);
+  }
+  // Secret-free provenance (the token, not the value).
+  appendAudit({ action: 'tokenize', token });
+}
+
+/**
+ * Token for a value: compute the deterministic token AND persist its mapping. This
+ * is the function wired into scrubText's `token` mode (via setVaultTokenizer).
+ * @param {*} value
+ * @returns {string}
+ */
+export function tokenFor(value) {
+  const token = computeToken(value);
+  storeMapping(token, value);
+  return token;
+}
+
+/**
+ * Load every token→value mapping from the vault dir (all *.jsonl, merged) into a
+ * Map. Branch-agnostic so rehydrate works regardless of which branch minted a token.
+ * @returns {Map<string,string>}
+ */
+export function loadVault() {
+  const map = new Map();
+  const dir = vaultDir();
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')); } catch { return map; }
+  for (const f of files) {
+    let raw;
+    try { raw = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    for (const line of raw.split('\n')) {
+      const s = line.trim();
+      if (!s) continue;
+      try {
+        const { token, value } = JSON.parse(s);
+        if (typeof token === 'string') map.set(token, value);
+      } catch { /* skip a malformed line */ }
+    }
+  }
+  return map;
+}
+
+/**
+ * Re-inflate a redacted object/string by swapping every AEGIS_ token back to its
+ * original from the vault. Unknown tokens (no mapping) are left untouched. Returns a
+ * BRAND-NEW value — never mutates the input.
+ * @param {*} obj
+ * @param {Map<string,string>} [vault]
+ * @returns {*}
+ */
+export function rehydrate(obj, vault) {
+  const map = vault || loadVault();
+  const walk = (v) => {
+    if (typeof v === 'string') {
+      return v.replace(TOKEN_RE, (tok) => (map.has(tok) ? map.get(tok) : tok));
+    }
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object') {
+      const out = {};
+      for (const k of Object.keys(v)) out[k] = walk(v[k]);
+      return out;
+    }
+    return v;
+  };
+  return walk(obj);
+}
+
+/**
+ * Wire (or un-wire) the scrubText `token` mode seam. When the vault is enabled,
+ * registers tokenFor as the tokenizer; otherwise ensures the seam is OFF so token
+ * mode falls back to mask (fail-closed). Idempotent + cheap — the egress path calls
+ * this before redacting in token mode.
+ * @returns {boolean} whether the vault is now wired
+ */
+export function ensureVaultWired() {
+  if (vaultEnabled()) {
+    if (!_wired) { setVaultTokenizer(tokenFor); _wired = true; }
+    return true;
+  }
+  if (_wired) { setVaultTokenizer(null); _wired = false; }
+  return false;
+}
+
+/** Test seam — clears cached key/branch/dedup/wiring. NOT for production use. */
+export function _resetVaultForTests() {
+  _key = null;
+  _branch = null;
+  _wired = false;
+  _seen.clear();
+  setVaultTokenizer(null);
+}
+
+// Wire on import when the env var is already set (the production case, where the
+// process is launched with ARGUS_REDACT_VAULT=1). The egress path additionally calls
+// ensureVaultWired() lazily, so an env var set after import is still honoured.
+ensureVaultWired();

package/src/utils/github-reporter.js

@@ -29,6 +29,7 @@
 import { childLogger } from './logger.js';
 import { parsePrUrl } from './pr-diff-analyzer.js';
 import { githubFetch } from './github-api.js';
+import { redactForEgress, redactReport, buildRedactionRider } from './sensitivity-classifier.js';
 
 const logger = childLogger('github-reporter');
 
@@ -130,6 +131,12 @@ export function formatPrComment(report, diff) {
     `**Base URL**: ${baseUrl}  `,
     `**Run time**: ${runDate}  `,
     '',
+    // Aegis (Step 6): when findings were redacted at the egress boundary, say so — the
+    // reader sees titles/types, never the raw exploit detail. Additive + gated, so a report
+    // that carries no `redaction` rider (every pre-Aegis caller / opt-out) renders unchanged.
+    ...(report.redaction && report.redaction.redacted > 0
+      ? [`> 🔒 ${report.redaction.redacted} finding(s) redacted at the boundary — full detail in the local report`, '']
+      : []),
     ...(report.prValidation ? prValidationBanner(report.prValidation) : []),
     '| | 🔴 Critical | 🟡 Warning | 🔵 Info | Total |',
     '|---|---|---|---|---|',
@@ -524,9 +531,20 @@ export function isGitHubConfigured() {
 export async function reportToGitHub(report, diff) {
   const tasks = [];
 
+  // Aegis egress guard (Step 6): GitHub (PR comment, Check Run, commit status) is a
+  // third-party sink read by anyone with repo access (A2). Project the WHOLE report once
+  // through redactReport — every finding array reduced to the deny-by-default allowlist, a
+  // `redaction` rider attached (drives the comment's 🔒 notice), metadata + severity counts
+  // preserved (so buildStatusPayload's merge gate is unchanged). The findings are already
+  // step-3c-tagged in the runCrawl path, so redactReport honours each finding's `sensitive`
+  // flag + the report-level `_aegisFailClosed`. ARGUS_REDACT_SENSITIVE=0 ⇒ raw passthrough.
+  const guarded = process.env.ARGUS_REDACT_SENSITIVE === '0'
+    ? report
+    : redactReport(report, { localReportPath: process.env.ARGUS_REPORT_URL || null });
+
   if (process.env.GITHUB_PR_NUMBER) {
     tasks.push(
-      postPrComment(report, diff).catch(err =>
+      postPrComment(guarded, diff).catch(err =>
         logger.warn(`[ARGUS] C2: PR comment failed — ${err.message}`)
       )
     );
@@ -535,7 +553,7 @@ export async function reportToGitHub(report, diff) {
   if (process.env.GITHUB_SHA) {
     // Commit status (fast, minimal)
     tasks.push(
-      setCommitStatus(report, diff).catch(err =>
+      setCommitStatus(guarded, diff).catch(err =>
         logger.warn(`[ARGUS] C2: Commit status failed — ${err.message}`)
       )
     );
@@ -543,7 +561,7 @@ export async function reportToGitHub(report, diff) {
     // Check Run (rich output — created and completed in sequence)
     tasks.push(
       createCheckRun(undefined, process.env.GITHUB_SHA)
-        .then(id => completeCheckRun(id, report, diff))
+        .then(id => completeCheckRun(id, guarded, diff))
         .catch(err =>
           logger.warn(`[ARGUS] C2: Check run failed — ${err.message}`)
         )
@@ -690,7 +708,18 @@ export async function reportPrValidation(result, { prUrl } = {}) {
     return { posted: false, checked: false, skipped: true, reason: 'no resolvable repo / PR number — PR reporting skipped' };
   }
 
-  const report = prResultToReport(result);
+  // Aegis egress guard (Step 6): the PR-Validator path reaches here with RAW findings (it does
+  // not run report-processor step 3c). Project them through redactForEgress BEFORE prResultToReport
+  // builds the comment, so the posted PR comment / Check Run carry titles + scrubbed messages, never
+  // exploit detail (A1/A2). The block decision was already computed upstream on the RAW findings.
+  // Attach a `redaction` rider so formatPrComment renders the 🔒 notice. Opt-out ⇒ raw passthrough.
+  const guardedResult = process.env.ARGUS_REDACT_SENSITIVE === '0'
+    ? result
+    : { ...result, findings: redactForEgress(result?.findings ?? []) };
+  const report = prResultToReport(guardedResult);
+  if (process.env.ARGUS_REDACT_SENSITIVE !== '0') {
+    report.redaction = buildRedactionRider(result?.findings ?? [], { localReportPath: null });
+  }
   // Non-first diff so findings render (not treated as a baseline-establishing first run). The
   // new/persisting split rides on each finding's `isNew` tag (set in the PR-validate paths via
   // tagFindingNovelty); `resolvedCount` comes from the head-vs-base diff (Phase B2) so the

package/src/utils/html-reporter.js

@@ -21,9 +21,27 @@ import fs   from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { childLogger } from './logger.js';
+import { redactReport } from './sensitivity-classifier.js';
 
 const logger = childLogger('html-reporter');
 
+/**
+ * Aegis (Step 7): decide whether an HTML report crosses the trust boundary and must be
+ * redacted. The default LOCALLY-opened report keeps 100% fidelity; a hosted/shared report
+ * (CI artifact, shared link) is projected through redactForEgress. Precedence:
+ *   ARGUS_REDACT_SENSITIVE=0 → never (global opt-out) · opts.external → always ·
+ *   ARGUS_REDACT_HTML=1 → always · ARGUS_REDACT_HTML=0 → never · else default ON under CI.
+ * @param {{ external?: boolean }} [opts]
+ * @returns {boolean}
+ */
+function shouldRedactHtml(opts = {}) {
+  if (process.env.ARGUS_REDACT_SENSITIVE === '0') return false;
+  if (opts.external === true) return true;
+  if (process.env.ARGUS_REDACT_HTML === '1') return true;
+  if (process.env.ARGUS_REDACT_HTML === '0') return false;
+  return process.env.CI === 'true' || process.env.CI === '1';
+}
+
 const __dirname   = path.dirname(fileURLToPath(import.meta.url));
 const REPORTS_DIR = path.resolve(__dirname, '../../reports');
 
@@ -441,15 +459,22 @@ function buildHtml(report) {
  * Called automatically by crawl-and-report.js when Slack is not configured (D7.7).
  *
  * @param {string} reportPath - Absolute or relative path to the JSON report file
+ * @param {{ external?: boolean }} [opts] - external:true forces egress redaction (hosted/shared
+ *        report); default keeps full local fidelity unless ARGUS_REDACT_HTML/CI apply (shouldRedactHtml)
  * @returns {string} Absolute path to the written report.html
  */
-export function generateHtmlReport(reportPath) {
+export function generateHtmlReport(reportPath, opts = {}) {
   let report;
   try {
     report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
   } catch (err) {
     throw new Error(`[ARGUS] Failed to parse report JSON at ${reportPath}: ${err.message}`);
   }
+  // Aegis egress guard (Step 7): a hosted/shared HTML report is a third-party sink (A2). When this
+  // render is external, project the parsed report through redactReport BEFORE buildHtml — the
+  // on-disk JSON at reportPath is left untouched (full local fidelity). The locally-opened default
+  // render stays raw. fail-CLOSED is honoured via report._aegisFailClosed inside redactReport.
+  if (shouldRedactHtml(opts)) report = redactReport(report, { localReportPath: reportPath });
   const html    = buildHtml(report);
   const outPath = path.join(path.dirname(path.resolve(reportPath)), 'report.html');