@clear-capabilities/agentic-security-scanner 0.172.1 → 0.173.0

package/dist/1621.index.js

@@ -0,0 +1,311 @@
+export const id = 1621;
+export const ids = [1621,6995];
+export const modules = {
+
+/***/ 66995:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   addLegalHold: () => (/* binding */ addLegalHold),
+/* harmony export */   isUnderHold: () => (/* binding */ isUnderHold),
+/* harmony export */   listLegalHolds: () => (/* binding */ listLegalHolds),
+/* harmony export */   loadLegalHolds: () => (/* binding */ loadLegalHolds),
+/* harmony export */   removeLegalHold: () => (/* binding */ removeLegalHold)
+/* harmony export */ });
+/* unused harmony export LEGAL_HOLD_FILE */
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(73024);
+/* harmony import */ var _state_dir_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(69259);
+/* harmony import */ var _artifact_registry_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(81734);
+// FR-707 (assurance-hardening PRD): "Support legal hold and policy-
+// authorized retention exceptions | Legal hold is identity-bound, reasoned,
+// time-bounded where applicable, and auditable."
+//
+// A third instance of the recurring {owner, reason, expires_at} exception
+// shape this codebase already uses twice — `posture/suppressions.js`'s
+// pro-tier exception (scoped to a FINDING) and `posture/compliance-policy.js`'s
+// structured `not-applicable` (scoped to a COMPLIANCE CONTROL). Per D-0025,
+// these are deliberately distinct mechanisms serving different subjects, not
+// one shared module — this file is the third subject: a STATE ARTIFACT.
+//
+// Field naming matches the existing two schemas' snake_case convention
+// (`owner`, `reason`, `expires_at`) rather than inventing a fourth style.
+//
+//   identity-bound   -> `owner` (required, who placed the hold and is
+//                        accountable for lifting it)
+//   reasoned         -> `reason` (required — "we might need this later" is
+//                        not a reason; same discipline suppressions.js
+//                        already enforces for its own exceptions)
+//   time-bounded
+//     where applicable -> `expires_at` is OPTIONAL: a null/absent value is
+//                        an INDEFINITE hold, which the acceptance
+//                        criterion's own "where applicable" phrase
+//                        explicitly allows (a genuine legal matter may have
+//                        no known end date) — an ISO date value behaves
+//                        exactly like FR-506/FR-1004's own expiring
+//                        exceptions: once past, the hold is no longer
+//                        active and the artifact is exposed to its normal
+//                        retention TTL again.
+//   auditable        -> persisted as a single JSON array under
+//                        `.agentic-security/legal-holds.json` (itself
+//                        registered as operator-config — an operator/legal
+//                        team's own input, never scanner-written from scan
+//                        results), readable via `listLegalHolds`.
+//
+// Consulted from TWO places, not one: `retention-policy.js#findExpiredArtifacts`
+// (defense in depth for any caller reaching it directly) AND `cmdReset`
+// itself for its PLAIN (non-`--expired`) path, which deletes every
+// registered 'generated' artifact unconditionally and would otherwise blow
+// through a hold that only gated TTL expiry.
+
+
+
+
+
+const LEGAL_HOLD_FILE = 'legal-holds.json';
+
+function _loadRaw(scanRoot) {
+  let fp;
+  try { fp = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.statePath)(scanRoot, LEGAL_HOLD_FILE); } catch { return []; }
+  let raw;
+  try { raw = node_fs__WEBPACK_IMPORTED_MODULE_0__.readFileSync(fp, 'utf8'); } catch { return []; }
+  try {
+    const doc = JSON.parse(raw);
+    return Array.isArray(doc) ? doc : [];
+  } catch { return []; }
+}
+
+/**
+ * All legal holds ever recorded for this project, malformed entries
+ * dropped rather than throwing. Never filters by expiry — see
+ * `isUnderHold`/`listLegalHolds` for that.
+ */
+function loadLegalHolds(scanRoot) {
+  return _loadRaw(scanRoot).filter(h => h && typeof h === 'object' && typeof h.artifact === 'string' && typeof h.owner === 'string' && typeof h.reason === 'string');
+}
+
+/**
+ * Is `artifactName` currently protected by an active (non-expired) hold?
+ * Returns the matching hold record, or null. Multiple holds on the same
+ * artifact are permitted (e.g. two independent legal matters); the first
+ * still-active one found is returned.
+ */
+function isUnderHold(artifactName, holds, now = Date.now()) {
+  for (const h of holds) {
+    if (h.artifact !== artifactName) continue;
+    if (!h.expires_at) return h; // indefinite hold — always active
+    const t = Date.parse(h.expires_at);
+    if (!Number.isFinite(t) || t >= now) return h;
+  }
+  return null;
+}
+
+/**
+ * Active (non-expired) holds only, unless `includeExpired`. For
+ * `legal-hold list` / auditing.
+ */
+function listLegalHolds(scanRoot, { includeExpired = false, now = Date.now() } = {}) {
+  const holds = loadLegalHolds(scanRoot);
+  if (includeExpired) return holds;
+  return holds.filter(h => {
+    if (!h.expires_at) return true;
+    const t = Date.parse(h.expires_at);
+    return !Number.isFinite(t) || t >= now;
+  });
+}
+
+/**
+ * Add a legal hold. Validates identity-bound + reasoned up front (both
+ * required, non-empty) and that `expires_at`, if given, is a parseable
+ * date in the future — an already-expired hold would be a hold that
+ * protects nothing, which is never a legitimate request. `artifact` must
+ * name a real registered artifact (artifact-registry.js) — a hold on an
+ * unrecognised name can never protect anything and almost always means a
+ * typo. Returns `{ok:true, hold}` or `{ok:false, reason}`; never throws.
+ */
+function addLegalHold(scanRoot, { artifact, owner, reason, expires_at } = {}) {
+  if (!artifact || typeof artifact !== 'string') return { ok: false, reason: '--artifact is required' };
+  if (!(0,_artifact_registry_js__WEBPACK_IMPORTED_MODULE_2__/* .isRegisteredArtifact */ .Jl)(artifact)) return { ok: false, reason: `"${artifact}" is not a registered state artifact` };
+  if (!owner || typeof owner !== 'string') return { ok: false, reason: '--owner is required (identity-bound)' };
+  if (!reason || typeof reason !== 'string') return { ok: false, reason: '--reason is required (reasoned)' };
+  if (expires_at) {
+    const t = Date.parse(expires_at);
+    if (!Number.isFinite(t)) return { ok: false, reason: 'expires_at must be a parseable date' };
+    if (t < Date.now()) return { ok: false, reason: 'expires_at is in the past — a hold that already expired protects nothing' };
+  }
+  const hold = { artifact, owner, reason, expires_at: expires_at || null, created_at: new Date().toISOString() };
+  const holds = _loadRaw(scanRoot);
+  holds.push(hold);
+  const fp = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.statePath)(scanRoot, LEGAL_HOLD_FILE);
+  if (!(0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.safeWriteState)(fp, JSON.stringify(holds, null, 2) + '\n')) {
+    return { ok: false, reason: 'state writes are disabled (--no-state) or this is not a safe state directory' };
+  }
+  return { ok: true, hold };
+}
+
+/**
+ * Remove every hold on `artifact` (lifting a hold, not letting it expire).
+ * Returns the number removed. A no-op (0) if none existed — never an error.
+ */
+function removeLegalHold(scanRoot, artifact) {
+  const holds = _loadRaw(scanRoot);
+  const remaining = holds.filter(h => !(h && h.artifact === artifact));
+  const removedCount = holds.length - remaining.length;
+  if (removedCount > 0) {
+    const fp = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.statePath)(scanRoot, LEGAL_HOLD_FILE);
+    (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.safeWriteState)(fp, JSON.stringify(remaining, null, 2) + '\n');
+  }
+  return removedCount;
+}
+
+
+/***/ }),
+
+/***/ 11621:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   findExpiredArtifacts: () => (/* binding */ findExpiredArtifacts)
+/* harmony export */ });
+/* unused harmony exports RETENTION_DEFAULTS, loadRetentionPolicy, effectiveTtlDays */
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(73024);
+/* harmony import */ var _util_yaml_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(32469);
+/* harmony import */ var _state_dir_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(69259);
+/* harmony import */ var _artifact_registry_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(81734);
+/* harmony import */ var _legal_hold_js__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(66995);
+// Retention policy: default and maximum TTL by artifact class (assurance-
+// hardening PRD FR-702).
+//
+// "Enforce default and maximum TTL by artifact class | Expired caches,
+// scans, evidence, tickets, and backups are purged or archived according
+// to policy."
+//
+// TWO NUMBERS PER CLASS, ON PURPOSE
+// --------------------------------------------------------------------------
+// `defaultDays` is what applies when nobody configures anything — a
+// reasonable, disclosed starting point, not a regulatory citation (an
+// operator with a real compliance regime should configure their own via
+// the policy file below). `maxDays` is a CEILING an operator's own
+// configuration cannot exceed: the literal "default AND maximum" wording
+// asks for both a floor-free default and a hard cap, not just a knob. An
+// operator who wants indefinite retention for `evidence` for their own
+// audit reasons should say so in their own retention program — this
+// module will not silently allow a TTL past its built-in ceiling for a
+// class, because "TTL" than can be configured to "never" is not a TTL.
+//
+// PURGE, NOT ARCHIVE
+// --------------------------------------------------------------------------
+// The acceptance criterion allows either. This implements PURGE (delete)
+// only — the simpler, safer, and more directly verifiable of the two.
+// "Archive" implies a defined export format and destination, which is
+// FR-706's own separate scope (manifest-based export); an operator who
+// wants to archive before purging already has the tool for it once FR-706
+// exists, or can back up `.agentic-security/` by their own means before
+// running the enforcement command.
+//
+// WHICH ARTIFACTS THIS APPLIES TO
+// --------------------------------------------------------------------------
+// Only 'generated' artifacts carrying a `retentionClass` in
+// artifact-registry.js — deliberately a SUBSET of all generated artifacts
+// (see that module's own header for which ones were left classless and
+// why). An 'operator-config' artifact is NEVER touched by this module,
+// regardless of age, matching FR-703's own "reset preserves operator-
+// authored configuration" precedent.
+
+
+
+
+
+
+
+const POLICY_FILE = 'retention-policy.yml';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// Engineering defaults, not a regulatory claim — see the header above.
+const RETENTION_DEFAULTS = {
+  cache: { defaultDays: 7, maxDays: 30 },
+  scan: { defaultDays: 90, maxDays: 365 },
+  evidence: { defaultDays: 365, maxDays: 1095 },
+  ticket: { defaultDays: 180, maxDays: 730 },
+  backup: { defaultDays: 30, maxDays: 180 },
+};
+
+/**
+ * Load an operator's `.agentic-security/retention-policy.yml`. Never
+ * throws — a missing or malformed file degrades to "no overrides," the
+ * same no-op-until-configured convention this repo uses for every other
+ * policy surface. Shape:
+ *   cache: { defaultDays: 3 }
+ *   evidence: { defaultDays: 730 }
+ * A class not mentioned, or a file not present at all, uses
+ * RETENTION_DEFAULTS unmodified.
+ */
+function loadRetentionPolicy(scanRoot) {
+  if (!scanRoot) return null;
+  let fp;
+  try { fp = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__.statePath)(scanRoot, POLICY_FILE); } catch { return null; }
+  let raw;
+  try { raw = node_fs__WEBPACK_IMPORTED_MODULE_0__.readFileSync(fp, 'utf8'); } catch { return null; }
+  try {
+    const doc = _util_yaml_js__WEBPACK_IMPORTED_MODULE_1__/* .load */ .Hh(raw);
+    if (!doc || typeof doc !== 'object') return null;
+    return doc;
+  } catch { return null; }
+}
+
+/**
+ * The TTL (in days) actually in effect for a class, after applying any
+ * operator override and clamping it to the class's own maxDays — an
+ * override CANNOT raise retention past the ceiling, only lower it (or
+ * leave it at the default). An unrecognised class (should not happen —
+ * only artifact-registry.js's own 5 named classes are ever passed in)
+ * degrades to null, meaning "not subject to a TTL."
+ */
+function effectiveTtlDays(retentionClass, policy) {
+  const bounds = RETENTION_DEFAULTS[retentionClass];
+  if (!bounds) return null;
+  const override = policy?.[retentionClass]?.defaultDays;
+  if (typeof override === 'number' && Number.isFinite(override) && override >= 0) {
+    return Math.min(override, bounds.maxDays);
+  }
+  return bounds.defaultDays;
+}
+
+/**
+ * Which registered, retention-classed artifacts under `scanRoot`'s state
+ * dir are currently past their effective TTL. Never throws — a missing
+ * state dir or an artifact that does not exist on disk is simply absent
+ * from the result, not an error.
+ *
+ * @returns {Array<{name: string, isDir: boolean, retentionClass: string,
+ *   ageDays: number, ttlDays: number}>}
+ */
+function findExpiredArtifacts(scanRoot, { now = Date.now() } = {}) {
+  const dir = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__/* .stateDir */ .Pn)(scanRoot);
+  let dirExists = true;
+  try { node_fs__WEBPACK_IMPORTED_MODULE_0__.accessSync(dir); } catch { dirExists = false; }
+  if (!dirExists) return [];
+  const policy = loadRetentionPolicy(scanRoot);
+  // FR-707: an artifact under an active legal hold is NEVER reported as
+  // expired, regardless of TTL — checked here (not just in cmdReset) so
+  // any future caller of this function inherits the same guarantee.
+  const holds = (0,_legal_hold_js__WEBPACK_IMPORTED_MODULE_4__.loadLegalHolds)(scanRoot);
+  const expired = [];
+  for (const artifact of (0,_artifact_registry_js__WEBPACK_IMPORTED_MODULE_3__/* .listArtifactsWithRetentionClass */ .U_)()) {
+    const ttlDays = effectiveTtlDays(artifact.retentionClass, policy);
+    if (ttlDays === null) continue;
+    if ((0,_legal_hold_js__WEBPACK_IMPORTED_MODULE_4__.isUnderHold)(artifact.name, holds, now)) continue;
+    const p = `${dir}/${artifact.name}`;
+    let st;
+    try { st = node_fs__WEBPACK_IMPORTED_MODULE_0__.statSync(p); } catch { continue; } // not present — nothing to expire
+    const ageDays = (now - st.mtimeMs) / MS_PER_DAY;
+    if (ageDays > ttlDays) {
+      expired.push({ name: artifact.name, isDir: st.isDirectory(), retentionClass: artifact.retentionClass, ageDays, ttlDays });
+    }
+  }
+  return expired;
+}
+
+
+/***/ })
+
+};

package/dist/1751.index.js

@@ -0,0 +1,160 @@
+export const id = 1751;
+export const ids = [1751];
+export const modules = {
+
+/***/ 71751:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   loadFreshLineageGraph: () => (/* binding */ loadFreshLineageGraph),
+/* harmony export */   loadSignedGraph: () => (/* binding */ loadSignedGraph)
+/* harmony export */ });
+/* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(73024);
+/* harmony import */ var _posture_state_dir_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(69259);
+/* harmony import */ var _posture_integrity_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(37455);
+// graph-loader.js — Milestone 3, sub-project Server, increment 1.
+//
+// Reads and VERIFIES the `.agentic-security/lineage-graph.json` artifact
+// before `explore` is allowed to serve a single byte of it. Reuses
+// `posture/integrity.js`'s `verifyLastScan` DIRECTLY (per the plan and the
+// root CLAUDE.md's own instruction) — this module does not implement any
+// signature comparison of its own. `verifyLastScan` already uses
+// `crypto.timingSafeEqual` internally.
+//
+// Loaded ONCE at server startup (see bin/agentic-security.js's cmdExplore)
+// and held in memory for the life of the process — this is a read-only,
+// single-scan-snapshot server; a change to the graph on disk mid-session is
+// out of scope for this increment (threat-model doc's own "P0 is
+// read-only" framing).
+
+
+
+
+
+/**
+ * @param {string} scanRoot
+ * @returns {{ok:true, graph:object} | {ok:false, reason:'missing'|'unsigned'|'tampered'|'malformed', message:string}}
+ *
+ * Four, and only four, distinct failure reasons — each with its own clear
+ * message so an operator knows exactly what to do next:
+ *   - 'missing'  — no lineage-graph.json at all. Run a scan with
+ *                  AGENTIC_SECURITY_LINEAGE_DEEP=1 first.
+ *   - 'unsigned' — the graph exists but its .sig sibling does not
+ *                  (verifyLastScan returns null). Refuse to serve an
+ *                  unverifiable graph.
+ *   - 'tampered' — the graph exists and has a .sig, but the signature does
+ *                  not match the body (verifyLastScan returns false). The
+ *                  file was modified after signing, or signed under a
+ *                  different install key.
+ *   - 'malformed' — the body passed signature verification but is not
+ *                  valid JSON. Should not happen from a normal scan; the
+ *                  file may be corrupted on disk after signing.
+ */
+function loadSignedGraph(scanRoot) {
+  const graphPath = (0,_posture_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.statePath)(scanRoot, 'lineage-graph.json');
+  const sigPath = graphPath + '.sig';
+
+  if (!node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(graphPath)) {
+    return {
+      ok: false,
+      reason: 'missing',
+      message: `No lineage graph found at ${graphPath}. Run a scan with AGENTIC_SECURITY_LINEAGE_DEEP=1 first (e.g. \`AGENTIC_SECURITY_LINEAGE_DEEP=1 agentic-security scan\`), then re-run \`agentic-security explore\`.`,
+    };
+  }
+
+  let body;
+  try {
+    body = node_fs__WEBPACK_IMPORTED_MODULE_0__.readFileSync(graphPath, 'utf8');
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'missing',
+      message: `Lineage graph found at ${graphPath} but could not be read: ${e && e.message ? e.message : e}.`,
+    };
+  }
+
+  const verified = (0,_posture_integrity_js__WEBPACK_IMPORTED_MODULE_2__/* .verifyLastScan */ .Ef)(body, sigPath);
+  if (verified === null) {
+    return {
+      ok: false,
+      reason: 'unsigned',
+      message: `Lineage graph at ${graphPath} has no signature file (${sigPath} is missing). Refusing to serve an unverifiable graph. Re-run the scan (AGENTIC_SECURITY_LINEAGE_DEEP=1) to regenerate both files together.`,
+    };
+  }
+  if (verified === false) {
+    return {
+      ok: false,
+      reason: 'tampered',
+      message: `Lineage graph at ${graphPath} FAILED signature verification — its contents do not match ${sigPath}. The file may have been modified after the scan, or signed under a different install key. Refusing to serve a tampered graph. Re-run the scan to regenerate it.`,
+    };
+  }
+
+  let graph;
+  try {
+    graph = JSON.parse(body);
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'malformed',
+      message: `Lineage graph at ${graphPath} passed signature verification but is not valid JSON (${e && e.message ? e.message : e}). This should not happen from a normal scan — the file may be corrupted. Re-run the scan to regenerate it.`,
+    };
+  }
+
+  return { ok: true, graph };
+}
+
+/**
+ * Load .agentic-security/lineage-graph.json ONLY when it is genuinely
+ * fresh for THIS scan — never merely because a file happens to exist on
+ * disk. Shared by every caller that signs or narrates a graph:-derived
+ * compliance claim (M4 sub-project 6c's final whole-branch review found
+ * the identical staleness gap independently reachable from
+ * `attest --obligations` AND `compliance --walkthrough`, and required
+ * this predicate to live in exactly one place rather than being
+ * copy-pasted per caller — a safety check that drifts between two
+ * near-identical inline copies is worse than one shared bug).
+ *
+ * `.agentic-security/lineage-graph.json` is only rewritten when a scan
+ * actually finishes building a graph (`if (scan.lineageGraph)` in
+ * bin/agentic-security.js's persistence code) — an ordinary non-deep
+ * rescan, or a deep scan whose lineage build fails, leaves whatever file
+ * was there from an earlier successful deep scan untouched. Loading that
+ * stale graph and joining it to the CURRENT scan's other data would let a
+ * caller assert a graph-derived fact (e.g. "transit protected") about
+ * code that has since changed.
+ *
+ * `enabled: true` in `scan.scanHealth.lineageAnalysis` does NOT by itself
+ * mean the build succeeded — engine.js sets it the moment
+ * AGENTIC_SECURITY_LINEAGE_DEEP=1 is read, before the build even starts,
+ * and leaves it `true` even when the build later throws (only `failure`
+ * gets set in that case). `requested && enabled` alone therefore still
+ * accepts a stale graph after a failed rebuild — reproduced live via the
+ * scan's own already-shipped fault-injection fixture
+ * (test/lineage-fault-injection.test.js) before this `failure === null`
+ * check was added.
+ *
+ * @param {string} scanRoot
+ * @param {object} scan - the parsed last-scan.json for the CURRENT scan
+ * @returns {{graph:object|null, fresh:boolean, loaded:ReturnType<typeof loadSignedGraph>}}
+ *   `fresh` is true only when a signed graph loaded successfully AND this
+ *   scan's own scanHealth confirms lineage analysis was requested,
+ *   enabled, and did not fail. `graph` is `loaded.graph` when fresh, else
+ *   `null` — never the stale file, even when one exists on disk.
+ *   `loaded` is the raw `loadSignedGraph` result, so a caller can still
+ *   distinguish "no file at all" from "a file exists but isn't fresh" for
+ *   its own disclosure message.
+ */
+function loadFreshLineageGraph(scanRoot, scan) {
+  const la = scan?.scanHealth?.lineageAnalysis;
+  const requested = la?.requested === true;
+  const enabled = la?.enabled === true;
+  const failure = la?.failure ?? null;
+  const loaded = loadSignedGraph(scanRoot);
+  const fresh = loaded.ok && requested && enabled && failure === null;
+  return { graph: fresh ? loaded.graph : null, fresh, loaded };
+}
+
+
+/***/ })
+
+};