@bongos/core 1.18.19 → 1.19.3

package/modules/security/artifact-scan/sanitize.js

@@ -0,0 +1,317 @@
+// modules/security/artifact-scan/sanitize.js — the sanitize landing
+// (task 1002548, goal 1000055).
+//
+// The sanitize offer is the narrowest of the three landings, and every one of
+// its gates is ARITHMETIC over recorded evidence — the same rule as the
+// reducer. planSanitize() decides eligibility from the reducer's components
+// and the findings themselves; no model opinion, no narrative, no override.
+// The owner's four gates, verbatim from the task:
+//
+//   1. NO MALICE INDICATOR — any critical finding anywhere (floor or panel),
+//      or a dangerous floor/verdict, kills the offer. A sanitized copy of a
+//      malicious artifact is a laundered artifact.
+//   2. WHOLE-NODE REMOVALS ONLY — every finding must name a concrete manifest
+//      file that can be removed entire. We never edit inside a file: a
+//      line-level "fix" of hostile code is a claim of understanding the scan
+//      cannot honestly make.
+//   3. FULL COVERAGE — nothing skipped, nothing unscannable, no unfetched
+//      dependencies or submodules. Static analysis cannot vouch for a copy it
+//      never fully read. Read off the reducer's coverage_cap, which is why
+//      fetch-stage findings must reach the floor report (runFloor's
+//      extraFindings) — routed anywhere else, this gate cannot see them.
+//   4. CLEAN RE-SCAN BY FRESH SUBAGENTS — enforced by the SKILL, which
+//      re-runs the whole pipeline (manifest → mirror → floor → panel) over
+//      the sanitized copy in a SECOND quarantine with fresh contexts. This
+//      module only produces the copy; it never blesses it.
+//
+// buildSanitizedCopy() writes ONLY inside the quarantine — the sanitized tree
+// lands at <quarantine>/sanitized/ and the diff at <quarantine>/sanitize-diff.md.
+// The sanitized copy is PRISTINE-CLASS: raw artifact bytes (it must stay
+// byte-identical to install), so no model may read it — the re-scan mirrors
+// it first, same as any fetch. File reads follow the mirror.js confinement
+// discipline: lexical check before any fs call, realpath verified inside the
+// pen, read the verified resolved path.
+
+'use strict';
+
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const { isInside } = require('./quarantine');
+const { excerpt } = require('./detectors/shared');
+
+const SANITIZED_DIRNAME = 'sanitized';
+const DIFF_BASENAME = 'sanitize-diff.md';
+
+// The cap detectors/shared.finding() applies to a finding's `file`. A finding
+// carries the SCRUBBED, capped form of a manifest path; the manifest carries
+// the raw bytes. Matching one against the other directly is the collision bug
+// below — this constant is what makes the two comparable.
+const PATH_MAX_CHARS = 300;
+const CODE_MAX_CHARS = 64;
+const MAX_REASON_CODES = 20;
+
+function allFindings(floorReport = {}, lenses = []) {
+  const floor = Array.isArray(floorReport.findings) ? floorReport.findings : [];
+  const panel = [];
+  for (const lens of lenses) {
+    for (const f of (Array.isArray(lens && lens.findings) ? lens.findings : [])) panel.push(f);
+  }
+  return { floor, panel };
+}
+
+// Gate 1 as its own testable piece: is there any indicator of actual malice?
+// Arithmetic on purpose — any critical-severity finding, from the floor or
+// from any lens, or a dangerous floor verdict. Severity is the one field the
+// pipeline already treats as evidence; a separate "looks malicious" judgment
+// would reintroduce the opinion the reducer exists to exclude.
+function hasMaliceIndicator(floorReport = {}, lenses = []) {
+  const { floor, panel } = allFindings(floorReport, lenses);
+  // Codes are model-authored on panel findings and artifact-derived on floor
+  // ones, and they flow into reasons[] which the skill relays to chat — so they
+  // pass the same scrub + one-line + cap every report string does.
+  const codes = [...floor, ...panel]
+    .filter((f) => f && f.severity === 'critical')
+    .map((f) => excerpt(String(f.code || 'unlabeled'), CODE_MAX_CHARS));
+  if (floorReport.floor_verdict === 'dangerous' && codes.length === 0) codes.push('floor_verdict_dangerous');
+  return { malicious: codes.length > 0, codes };
+}
+
+// The eligibility decision. Takes the REDUCER RESULT (never a narrative) plus
+// the raw findings and the manifest entries, and returns
+// { eligible, reasons, removals, unremovable, provenance }. `removals` is the
+// sorted set of RAW manifest paths whose removal addresses every finding; a
+// finding that names no concrete manifest file (e.g. file '(floor)', an
+// off-box surface, or a path the manifest does not carry) is unremovable and
+// kills the offer — fail closed, gate 2.
+//
+// PATH IDENTITY (review finding). A finding's `file` has been through
+// scrubUntrusted + whitespace-collapse + a 300-char cap; a manifest path has
+// not. Joining them directly let an artifact ship two files whose names differ
+// only by a scrubbed codepoint — the removal set then named the benign twin
+// while the flagged file was copied into sanitized/. So the join runs on the
+// SCRUBBED form of both sides, and a scrubbed name that maps to more than one
+// raw manifest entry is AMBIGUOUS: it becomes unremovable rather than a guess,
+// because deleting the wrong file is exactly the failure this gate exists to
+// prevent.
+//
+// PROVENANCE (review finding, split verdict). A panel finding's `file` is
+// model-authored text, so it is both evidence AND a destructive instruction.
+// The gates cannot verify it, so they LABEL it: `provenance` reports which
+// removals a code-computed floor finding backs and which rest on panel text
+// alone. The blast radius stays bounded by three things that do not trust the
+// panel — removals are whole files inside the quarantine only, the human reads
+// the diff, and the copy must pass a fresh-subagent re-scan (gate 4).
+function planSanitize({ reduced, floorReport = {}, lenses = [], entries = [] } = {}) {
+  if (!reduced || !reduced.components) {
+    throw new Error('planSanitize requires the reducer result — sanitize eligibility is arithmetic, never a narrative');
+  }
+  const reasons = [];
+
+  const malice = hasMaliceIndicator(floorReport, lenses);
+  if (malice.malicious) reasons.push(`malice_indicator: ${malice.codes.join(', ')}`);
+  if (reduced.verdict === 'dangerous') reasons.push('verdict_dangerous');
+
+  if (reduced.components.coverage_cap !== 'clean') {
+    reasons.push(`coverage_incomplete: ${(reduced.coverage_reasons || []).join('; ') || 'coverage cap held'}`);
+  }
+  // Gates 1–3 are about what THIS scan proved, so the scan must have been a
+  // full one: a panel-bearing tier (low never ran a real panel) and a panel
+  // that completed healthy. The clean re-scan (gate 4) is the skill's job.
+  if (reduced.components.tier_clamp !== 'clean') reasons.push('tier_ran_no_full_panel');
+  if (reduced.components.lens_health !== 'clean') reasons.push('panel_unhealthy_or_absent');
+
+  const { floor, panel } = allFindings(floorReport, lenses);
+  const findings = [...floor.map((f) => ({ f, from: 'floor' })), ...panel.map((f) => ({ f, from: 'panel' }))];
+  if (findings.length === 0) reasons.push('nothing_to_remove');
+
+  // Scrubbed manifest name → the entries that render to it. EVERY kind is
+  // indexed, not just files: a symlink whose scrubbed name collides with a
+  // real file must make that name ambiguous, or a finding about the symlink
+  // schedules the innocent file for deletion (verification finding).
+  const byScrubbed = new Map();
+  for (const e of entries) {
+    if (!e || typeof e.path !== 'string') continue;
+    const key = excerpt(e.path, PATH_MAX_CHARS);
+    // A name that scrubs away to nothing (all-whitespace, all-zero-width) can
+    // never identify anything. Indexing it would let it match every finding
+    // that carries no file at all — the fail-open this gate exists to prevent.
+    if (key === '') continue;
+    if (!byScrubbed.has(key)) byScrubbed.set(key, []);
+    byScrubbed.get(key).push(e);
+  }
+
+  const removals = new Set();
+  const backedByFloor = new Set();
+  const unremovable = [];
+  for (const { f, from } of findings) {
+    const claimed = f && typeof f.file === 'string' ? excerpt(f.file, PATH_MAX_CHARS) : '';
+    const matches = claimed === '' ? [] : (byScrubbed.get(claimed) || []);
+    if (matches.length === 1 && matches[0].kind === 'file') {
+      removals.add(matches[0].path);
+      if (from === 'floor') backedByFloor.add(matches[0].path);
+      continue;
+    }
+    let reason = 'no_manifest_file';
+    if (matches.length > 1) reason = 'ambiguous_path';
+    else if (matches.length === 1) reason = 'not_a_regular_file';
+    unremovable.push({
+      code: excerpt(String((f && f.code) || 'unlabeled'), CODE_MAX_CHARS),
+      file: claimed,
+      reason,
+    });
+  }
+  if (unremovable.length > 0) {
+    // Count-capped as well as per-item capped: a hostile panel returning
+    // thousands of findings must not build one unbounded reason string.
+    const codes = unremovable.slice(0, MAX_REASON_CODES).map((u) => u.code).join(', ');
+    const more = unremovable.length > MAX_REASON_CODES ? ` (+${unremovable.length - MAX_REASON_CODES} more)` : '';
+    reasons.push(`not_whole_node_removable: ${codes}${more}`);
+  }
+
+  // removals[] carries RAW manifest paths because buildSanitizedCopy needs the
+  // real bytes to find the file on disk — so it is NOT display-safe and must
+  // never be printed. provenance carries the scrubbed rendering of the same
+  // paths and is what a human is shown (verification finding: a bidi override
+  // or an embedded newline in a filename otherwise forges the approval
+  // display at the exact moment deletions are approved).
+  const sorted = [...removals].sort();
+  const display = (p) => excerpt(p, PATH_MAX_CHARS);
+  return {
+    eligible: reasons.length === 0,
+    reasons,
+    removals: sorted,
+    unremovable,
+    provenance: {
+      floor_backed: sorted.filter((p) => backedByFloor.has(p)).map(display),
+      panel_only: sorted.filter((p) => !backedByFloor.has(p)).map(display),
+    },
+  };
+}
+
+// Copy the pristine tree minus the removals into <quarantine>/sanitized/, and
+// write the diff (whole files removed — nothing else changed) next to it.
+// Writes ONLY inside the quarantine; kept files are copied byte-identical.
+// Refuses stale state (an existing sanitized/ dir) and any removal path the
+// manifest does not carry — a typo'd removal must never silently keep a file
+// the plan meant to drop.
+//
+// Every kept file is re-hashed against its manifest sha256 before it is
+// written (review finding): the diff's promise that kept files are
+// "byte-identical to the scanned pristine copy" was previously prose the code
+// never tested, so anything that changed the pen between the scan and the
+// sanitize — a concurrent process, another tool, a shared build box — was
+// copied in under a provenance claim. Now a mismatch aborts.
+//
+// On ANY failure the partial sanitized/ tree is removed before the error
+// propagates: a directory that looks like a finished sanitized copy but is
+// silently missing files, with no diff beside it, is worse than no directory
+// (and the non-recursive mkdir would otherwise refuse every retry).
+async function buildSanitizedCopy({ pristineDir, quarantineRoot, entries, removals } = {}) {
+  if (!pristineDir || !quarantineRoot || !Array.isArray(entries) || !Array.isArray(removals) || removals.length === 0) {
+    throw new Error('buildSanitizedCopy requires pristineDir, quarantineRoot, manifest entries[], and a non-empty removals[].');
+  }
+  const fileEntries = new Map(entries.filter((e) => e && e.kind === 'file').map((e) => [e.path, e]));
+  for (const r of removals) {
+    if (!fileEntries.has(r)) throw new Error(`Removal "${excerpt(String(r), 300)}" is not a manifest file — refusing a plan the manifest does not vouch for.`);
+  }
+
+  const realQuarantine = await fsp.realpath(quarantineRoot);
+  const sanitizedDir = path.join(realQuarantine, SANITIZED_DIRNAME);
+  await fsp.mkdir(sanitizedDir); // non-recursive: an existing sanitized/ is stale state, refuse
+
+  const remove = new Set(removals);
+  const removed = [];
+  const skippedNonFile = [];
+  let copied = 0;
+  const madeDirs = new Set();
+
+  try {
+    for (const entry of entries) {
+      if (!entry || entry.kind !== 'file') {
+        if (entry) skippedNonFile.push(entry.path);
+        continue;
+      }
+      const rel = entry.path;
+      if (remove.has(rel)) {
+        removed.push({ path: rel, size: entry.size, sha256: entry.sha256 || null });
+        continue;
+      }
+
+      // Confinement, same discipline as mirror.js: lexical first, then physical.
+      if (typeof rel !== 'string' || rel.length === 0 || path.isAbsolute(rel)
+        || !isInside(pristineDir, path.resolve(pristineDir, ...rel.split('/')))) {
+        throw new Error(`Manifest path "${excerpt(String(rel), 300)}" escapes the pristine tree — refusing to build a sanitized copy over it.`);
+      }
+      const abs = path.resolve(pristineDir, ...rel.split('/'));
+      const real = await fsp.realpath(abs);
+      if (!isInside(realQuarantine, real)) {
+        throw new Error(`"${excerpt(rel, 300)}" resolves outside the quarantine — refusing.`);
+      }
+      const st = await fsp.lstat(abs);
+      if (st.isSymbolicLink()) {
+        throw new Error(`"${excerpt(rel, 300)}" is a symlink on disk though the manifest calls it a file — refusing.`);
+      }
+      const buf = await fsp.readFile(real); // the verified resolved path, not abs
+
+      // The diff claims every kept file is byte-identical to what was scanned.
+      // Prove it against the manifest hash rather than asserting it in prose.
+      if (!entry.sha256) {
+        throw new Error(`"${excerpt(rel, 300)}" has no manifest sha256 — refusing to claim byte-identity the manifest cannot vouch for.`);
+      }
+      const fresh = crypto.createHash('sha256').update(buf).digest('hex');
+      if (fresh !== entry.sha256) {
+        throw new Error(`"${excerpt(rel, 300)}" changed since the scan (manifest sha256 ${excerpt(String(entry.sha256), 64)}, on disk ${fresh}) — refusing to copy bytes nobody reviewed.`);
+      }
+
+      const dest = path.resolve(sanitizedDir, ...rel.split('/'));
+      if (!isInside(sanitizedDir, dest)) {
+        throw new Error(`"${excerpt(rel, 300)}" would land outside sanitized/ — refusing.`);
+      }
+      const destDir = path.dirname(dest);
+      if (!madeDirs.has(destDir)) {
+        await fsp.mkdir(destDir, { recursive: true });
+        madeDirs.add(destDir);
+      }
+      await fsp.writeFile(dest, buf);
+      copied++;
+    }
+
+    // The diff: whole files removed, nothing else touched. Paths and hashes are
+    // artifact-controlled strings, so they pass through the same scrub+cap every
+    // report string does.
+    const diffLines = [
+      '# Sanitize diff',
+      '',
+      'Whole-file removals only — every kept file was re-hashed against its manifest sha256 before being copied.',
+      `Removed ${removed.length} file(s); copied ${copied} file(s) into ${SANITIZED_DIRNAME}/.`,
+      '',
+    ];
+    for (const r of removed) {
+      diffLines.push(`- REMOVED ${excerpt(r.path, 300)} (${Number(r.size) || 0} bytes, sha256 ${excerpt(String(r.sha256 || '(none)'), 64)})`);
+    }
+    if (skippedNonFile.length > 0) {
+      diffLines.push('');
+      diffLines.push(`Not copied (non-file manifest entries, never reviewed): ${skippedNonFile.map((p) => excerpt(String(p), 120)).join(', ')}`);
+    }
+    const diff = diffLines.join('\n');
+    const diffPath = path.join(realQuarantine, DIFF_BASENAME);
+    await fsp.writeFile(diffPath, diff, 'utf8');
+
+    return { sanitizedDir, diffPath, diff, copied, removed, skippedNonFile };
+  } catch (err) {
+    // No half-built tree survives a failure — see the header. Best-effort so a
+    // cleanup problem can never mask the real error.
+    await fsp.rm(sanitizedDir, { recursive: true, force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+module.exports = {
+  SANITIZED_DIRNAME,
+  DIFF_BASENAME,
+  hasMaliceIndicator,
+  planSanitize,
+  buildSanitizedCopy,
+};

package/modules/security/migrations/security_001_tool_scans.sql

@@ -0,0 +1,145 @@
+-- security_001_tool_scans.sql — the durable record of an external-artifact scan.
+--
+-- One row per `/scan-before-install` run, so a scan is queryable across builders
+-- rather than living only in one session's chat and one file on one laptop. The
+-- builder most likely to install a shiny new tool is the newest one, so the read
+-- side of this table exists to let one builder's scan warn the next.
+--
+-- STRUCTURE ONLY, NEVER TARGET CONTENT. The row carries the verdict, the tier,
+-- the pinned SHA, the content hash, per-severity counts, and one-line finding
+-- claims — never quoted bytes from the artifact. Two reasons: a scanned artifact
+-- is hostile input, and anything stored here is later rendered to whoever reads
+-- the table, so a quoted payload would make this table a delivery mechanism for
+-- the very injection the scan exists to catch. The `findings_summary` size cap
+-- below is the DB-layer half of that rule; the route validates it too.
+--
+-- AN ABORTED SCAN IS RECORDABLE. `completion` distinguishes a finished scan from
+-- one that died (clone timeout, cap exceeded, host resolved private). That is
+-- deliberate: a scan that produced no verdict must be visible as "aborted, here
+-- is why" rather than being indistinguishable from silence — otherwise a failed
+-- scan reads like a clean one.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is security_-prefixed, there is no down-migration, and the filename is
+-- security_-prefixed (ADR 0108 §5) so its stem never collides across repos.
+-- `scripts/migrate.sh` discovers + applies this when the security module is
+-- enabled (default:true). Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS security_tool_scans (
+  id                    bigserial PRIMARY KEY,
+
+  -- What was scanned. target_url is the https URL as validated; target_host is
+  -- split out so "have we seen anything from this host" is an index-able question.
+  target_url            text NOT NULL,
+  target_host           text,
+  -- 'repo' (a plain GitHub repo) | 'plugin' | 'marketplace'. Text plus a CHECK
+  -- rather than a Postgres enum TYPE: the constraint pins today's known kinds
+  -- fail-closed, and widening to a new kind is a one-line constraint change in a
+  -- later security_* migration — not an enum-type migration.
+  artifact_kind         text NOT NULL,
+
+  -- The pinned commit. NULL only when the scan aborted before resolving HEAD.
+  -- A branch or tag is never an install source; only this SHA is.
+  resolved_sha          text,
+  -- sha256 over the sorted (path, kind, size, sha256) manifest. The dedupe key
+  -- for "we already scanned these exact bytes", and what the install offer
+  -- re-checks so the artifact cannot change between scanning and installing.
+  content_hash          text,
+  file_count            integer,
+  total_bytes           bigint,
+
+  -- Thoroughness the scan ran at. The low tier can never reach a clean verdict,
+  -- so tier is load-bearing context for reading `verdict`, not decoration.
+  tier                  text NOT NULL,
+  -- clean | caution | dangerous. NULL when completion <> 'complete' — an
+  -- unfinished scan has no verdict, and must never be read as a passing one.
+  verdict               text,
+  completion            text NOT NULL DEFAULT 'complete',
+  -- the abort's finding code (clone_timeout, cap_max_bytes, host_resolves_private…)
+  abort_code            text,
+
+  findings_critical     integer NOT NULL DEFAULT 0,
+  findings_high         integer NOT NULL DEFAULT 0,
+  findings_medium       integer NOT NULL DEFAULT 0,
+  findings_low          integer NOT NULL DEFAULT 0,
+  -- One-line claims only (code, severity, file, short message). The full report
+  -- with evidence lives in the builder's own user directory, never here and
+  -- never in the repo: a scan report is a timestamped accusation about a named
+  -- third party, and docs/ is a public AGPL tree indexed by /recall.
+  findings_summary      jsonb NOT NULL DEFAULT '[]'::jsonb,
+
+  -- What the builder did with the verdict: none | install_command_printed |
+  -- sanitized_copy | rebuild_spec | declined. Note the scanner never installs;
+  -- the strongest value here is that a command was PRINTED for the user to run.
+  action_taken          text,
+  -- engine version that produced this row, so an old row is never mistaken for
+  -- a verdict the current detector set would reach.
+  engine_version        text NOT NULL,
+
+  scanned_by_builder_id bigint REFERENCES builders(id) ON DELETE SET NULL,
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  updated_at            timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT security_tool_scans_completion_chk
+    CHECK (completion IN ('complete', 'aborted', 'incomplete')),
+  CONSTRAINT security_tool_scans_verdict_chk
+    CHECK (verdict IS NULL OR verdict IN ('clean', 'caution', 'dangerous')),
+  -- A finished scan must carry a verdict, and an unfinished one must not. This is
+  -- the invariant that keeps "the scan died" from ever being read as "it passed".
+  CONSTRAINT security_tool_scans_verdict_completion_chk
+    CHECK ((completion = 'complete') = (verdict IS NOT NULL)),
+  CONSTRAINT security_tool_scans_tier_chk
+    CHECK (tier IN ('low', 'default', 'high', 'xhigh', 'max')),
+  CONSTRAINT security_tool_scans_artifact_kind_chk
+    CHECK (artifact_kind IN ('repo', 'plugin', 'marketplace')),
+  CONSTRAINT security_tool_scans_action_chk
+    CHECK (action_taken IS NULL OR action_taken IN
+      ('none', 'install_command_printed', 'sanitized_copy', 'rebuild_spec', 'declined')),
+  CONSTRAINT security_tool_scans_counts_chk
+    CHECK (findings_critical >= 0 AND findings_high >= 0
+       AND findings_medium >= 0 AND findings_low >= 0),
+  -- Defense in depth with the route's own cap: a hostile artifact must not be
+  -- able to push unbounded text through a summary field into every future reader.
+  CONSTRAINT security_tool_scans_summary_size_chk
+    CHECK (length(findings_summary::text) <= 65536),
+  -- The summary is a LIST of one-line claims — pinning the shape at the DB layer
+  -- means a scalar or object smuggled past the route can never land.
+  CONSTRAINT security_tool_scans_summary_shape_chk
+    CHECK (jsonb_typeof(findings_summary) = 'array'),
+  CONSTRAINT security_tool_scans_url_len_chk
+    CHECK (length(target_url) <= 2048)
+);
+
+-- "Have these exact bytes been scanned before?" — the dedupe lookup. Partial: an
+-- aborted scan never produced a content_hash, and those NULLs are dead weight.
+CREATE INDEX IF NOT EXISTS security_tool_scans_content_hash_idx
+  ON security_tool_scans (content_hash)
+  WHERE content_hash IS NOT NULL;
+
+-- "What has this builder scanned lately?" — the scanner's own history.
+CREATE INDEX IF NOT EXISTS security_tool_scans_scanner_idx
+  ON security_tool_scans (scanned_by_builder_id, created_at DESC);
+
+-- "Anything scanned from this host?" — cheap reputation lookup across builders.
+CREATE INDEX IF NOT EXISTS security_tool_scans_host_idx
+  ON security_tool_scans (target_host, created_at DESC)
+  WHERE target_host IS NOT NULL;
+
+-- Rows ARE mutated after insert (action_taken is recorded once the builder acts
+-- on the verdict), so updated_at needs a real trigger — without one it silently
+-- equals created_at forever. Idempotent: OR REPLACE + DROP IF EXISTS.
+CREATE OR REPLACE FUNCTION security_tool_scans_touch_updated_at() RETURNS trigger AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS security_tool_scans_updated_at ON security_tool_scans;
+CREATE TRIGGER security_tool_scans_updated_at
+  BEFORE UPDATE ON security_tool_scans
+  FOR EACH ROW EXECUTE FUNCTION security_tool_scans_touch_updated_at();
+
+COMMIT;

package/modules/security/module.json

@@ -1,10 +1,10 @@
 {
   "key": "security",
   "title": "Security (red-team · bounty)",
-  "description": "The red-team / vulnerability-report intake and the bounty payout system (rank-gated Metic+): the /builder-redteam skill files a report, the Archon dashboard adjudicates (confirm/dispute/fix/link-fix), and the env-aware bounty table sets the per-severity drachmae payout. A core-domain module carved out of the GDS core in BV1.R79 (ADR 0093 §1; 02-module-map §5 — security-the-FEATURE, NOT security-the-property, which stays kernel). default-on because every instance can take red-team reports. Registers the `security` kernel PORT the core /public/bounty-table resolves for the payout schedule.",
+  "description": "The red-team / vulnerability-report intake and the bounty payout system (rank-gated Metic+): the /builder-redteam skill files a report, the Archon dashboard adjudicates (confirm/dispute/fix/link-fix), and the env-aware bounty table sets the per-severity drachmae payout. A core-domain module carved out of the GDS core in BV1.R79 (ADR 0093 §1; 02-module-map §5 — security-the-FEATURE, NOT security-the-property, which stays kernel). default-on because every instance can take red-team reports. Registers the `security` kernel PORT the core /public/bounty-table resolves for the payout schedule. Also owns the scan-before-install surface (goal 1000055): the artifact-scan engine (quarantine/manifest/mirror) and the security_tool_scans record — POST Metic+, GET every rank.",
   "coreVersion": "^1.8.0",
   "default": true,
-  "contributes": { "routes": ["reports"] },
+  "contributes": { "routes": ["reports", "scans"], "migrations": true },
   "provides": ["security"],
   "consumes": []
 }

package/modules/security/routes/reports.js

@@ -62,7 +62,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports',
     api.requireBuilder,
-    api.requireRank('metic', 'archon'),
+    api.requirePermission('security.report.file'),
     async (req, res) => {
       if (validateOrRespond(req, res, {
         target:         { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
@@ -99,11 +99,15 @@ module.exports = function buildSecurityReportsRouter() {
   // lifecycle bucket (open / repro_attempted / confirmed / disputed /
   // fixed / wontfix); omitted = all.
   //
-  // rank: archon — adjudication surface; reading every builder's reports.
+  // rank: metic+archon — adjudication surface; reading every builder's reports.
+  // BV1.R105 left this on requireRank because `security.report.adjudicate` was declared
+  // over the adjudication WRITES + /security/docs CRUD, not over this read. ADR 0157
+  // extends that atom's guards to name GET /security/reports and lowers its floor
+  // archon→metic, so the mapping now exists and the audience is the working rank.
   router.get(
     '/security/reports',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       const status = req.query.status ? String(req.query.status) : null;
       if (status && !security.VULN_STATUSES.includes(status)) {
@@ -135,7 +139,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/confirm',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       // drachmae_awarded is OPTIONAL and deliberately UNTYPED here: the handler
       // accepts a number, a stringified number, '' and null alike, and the inline
@@ -174,7 +178,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/dispute',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;
@@ -199,7 +203,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/fix',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;
@@ -225,7 +229,7 @@ module.exports = function buildSecurityReportsRouter() {
   router.post(
     '/security/reports/:id/link-fix',
     api.requireBuilder,
-    api.requireRank('archon'),
+    api.requirePermission('security.report.adjudicate'),
     async (req, res) => {
       // task_id is REQUIRED but untyped: the handler accepts a number or a
       // stringified number and coerces below, so a type would narrow the live

package/modules/security/routes/scans.js

@@ -0,0 +1,115 @@
+// modules/security/routes/scans.js — the scan-record surface (task 1002547,
+// goal 1000055): POST one row per /scan-before-install run, GET the rows for a
+// content hash so one builder's scan warns the next.
+//
+// Rank shape, deliberately asymmetric:
+//   * WRITE is Metic+ — a verdict-shaped write is a trust-shaped write; a row
+//     here tells every future reader "these bytes were judged X".
+//   * READ is every rank — the builder most likely to install a shiny new tool
+//     is the newest one, and the warning must reach exactly them.
+//
+// A Xenos who runs a scan still gets a DEFINED path (below), not a dead-end:
+// the refusal names what they keep (report file + chat summary) and what to do
+// next, so the degraded experience is a documented contract, not a mystery 403.
+//
+// Same idioms as reports.js next door: doorway-only requires, validateOrRespond
+// schema, res.fail codes, factory export mounted via module.json contributes.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const scanStore = require('../scan-store');
+const { validateOrRespond } = api;
+
+// Interposed BEFORE api.requireRank so a Xenos gets the documented degraded
+// path instead of the generic rank refusal. Anyone Metic+ falls through to the
+// real gate (which fitness/route-rank-check reads as this route's rank).
+function xenosDegradedPath(req, res, next) {
+  if (api.rankMeetsThreshold(req.builder?.rank, 'metic')) return next();
+  return res.fail('scan_row_requires_metic', 403, {
+    degraded_path:
+      'Your scan itself is unaffected — keep the report file in your user directory and the chat summary. ' +
+      'What your rank cannot do is write the SHARED scan record other builders query. ' +
+      'Ask any Metic+ builder to POST this scan, or re-run the record step after promotion.',
+    kept: ['report_file', 'chat_summary'],
+    not_recorded: ['gds_scan_row'],
+  });
+}
+
+module.exports = function buildSecurityScansRouter() {
+  const router = express.Router();
+
+  // POST /api/bongos/security/scans — record one scan run.
+  //
+  // Body: structure only, never quoted target content — the deep checks
+  // (one-line claims, fence-marker rejection, scrubbing, verdict/completion
+  // coupling) live in scanStore.normalizeScanPayload; the schema here rejects
+  // unknown/typo'd top-level fields (strict default) and pins basic shapes.
+  //
+  // rank: metic+archon — a verdict-shaped write is a trust-shaped write.
+  router.post(
+    '/security/scans',
+    api.requireBuilder,
+    xenosDegradedPath,
+    api.requireRank('metic', 'archon'),
+    async (req, res) => {
+      if (validateOrRespond(req, res, {
+        target_url:        { required: true, type: 'string', maxLength: 2048, minLength: 9 },
+        artifact_kind:     { required: true, type: 'string', enum: [...scanStore.ARTIFACT_KINDS] },
+        resolved_sha:      { type: 'string', maxLength: 40 },
+        content_hash:      { type: 'string', maxLength: 64 },
+        file_count:        { type: 'integer', min: 0 },
+        total_bytes:       { type: 'integer', min: 0 },
+        tier:              { required: true, type: 'string', enum: [...scanStore.TIERS] },
+        verdict:           { type: 'string', enum: [...scanStore.VERDICTS] },
+        completion:        { required: true, type: 'string', enum: [...scanStore.COMPLETIONS] },
+        abort_code:        { type: 'string', maxLength: 64 },
+        findings_critical: { type: 'integer', min: 0 },
+        findings_high:     { type: 'integer', min: 0 },
+        findings_medium:   { type: 'integer', min: 0 },
+        findings_low:      { type: 'integer', min: 0 },
+        findings_summary:  { type: 'array' },
+        action_taken:      { type: 'string', enum: [...scanStore.ACTIONS] },
+        engine_version:    { required: true, type: 'string', maxLength: 64, minLength: 1 },
+      })) return;
+
+      const norm = scanStore.normalizeScanPayload(req.body);
+      if (!norm.ok) return res.fail(norm.code, 400, norm.detail);
+
+      try {
+        const scan = await scanStore.insertScan(norm.value, req.builder.id);
+        res.status(201).json({ ok: true, scan });
+      } catch (err) {
+        console.error('[gds] POST /security/scans', err);
+        res.fail('scan_record_failed', 500);
+      }
+    }
+  );
+
+  // GET /api/bongos/security/scans?content_hash=<64 hex>
+  //
+  // "Have these exact bytes been scanned before, and what did the scan say?"
+  // Newest first. Rows carry structure only, so reading them can never expose
+  // the reader to the scanned artifact's content.
+  //
+  // rank: any-builder — deliberately open to every rank (see header).
+  router.get(
+    '/security/scans',
+    api.requireBuilder,
+    async (req, res) => {
+      const contentHash = String(req.query.content_hash || '').toLowerCase();
+      if (!/^[0-9a-f]{64}$/.test(contentHash)) {
+        return res.fail('bad_content_hash', 400, { expected: '64 lowercase hex chars' });
+      }
+      try {
+        const scans = await scanStore.findScans({ contentHash });
+        res.set('Cache-Control', 'no-store');
+        res.json({ scans });
+      } catch (err) {
+        console.error('[gds] GET /security/scans', err);
+        res.fail('scan_list_failed', 500);
+      }
+    }
+  );
+
+  return router;
+};