@codyswann/lisa 4.74.9 → 4.75.1

package/plugins/lisa-devin/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -0,0 +1,550 @@
+#!/usr/bin/env node
+/**
+ * Validate the `secrets`, `remoteEnv`, and `automations` blocks.
+ *
+ * These blocks are read by shell, by Node, and by generated workflows, so a
+ * malformed one surfaces late and somewhere unhelpful — a container that fails
+ * mid-setup, a scheduled loop that never fires, a dispatch that names a surface
+ * nobody provisioned. Checking the shape up front turns all of those into one
+ * message at `doctor` time.
+ *
+ * Structure only. Whether a credential resolves is `doctor-secrets.mjs`; this
+ * asks whether the declaration could ever be correct.
+ *
+ * Usage:
+ *   validate-config.mjs
+ * @module validate-config
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+
+import { SURFACES as SURFACE_CAPABILITIES } from "./surfaces.mjs";
+
+/** Providers with a read implementation today. */
+const IMPLEMENTED_PROVIDERS = new Set(["bitwarden", "doppler", "env"]);
+
+/** Providers named in the dispatch table but not yet implemented. */
+const DECLARED_PROVIDERS = new Set(["1password", "aws", "vault"]);
+
+/**
+ * Surfaces the resolver knows.
+ *
+ * Derived from the resolver's own table rather than restated here. The two
+ * lists previously drifted apart by construction: adding a surface meant
+ * remembering to edit a second file, and forgetting produced a config that
+ * resolved correctly at runtime while `doctor` called it unknown.
+ */
+const SURFACES = new Set(Object.keys(SURFACE_CAPABILITIES));
+
+/**
+ * What a provisioned surface must record before anything dispatches to it.
+ *
+ * Deliberately not uniform, because these surfaces do not bind the same way. A
+ * Codex Cloud environment is bound to one repository, so naming the repository
+ * is part of proving the environment is the right one. A Claude cloud
+ * environment has no repository at all — it is account-scoped configuration
+ * (network policy, variables, setup script) and the repository arrives per
+ * session — so its durable handle is the routine that dispatch fires.
+ *
+ * Requiring `repository` of every surface, as this file used to, would demand
+ * a field that cannot be true of `claude-web` in any meaningful sense.
+ *
+ * `repository` stays the default so every existing surface keeps its current
+ * contract. This file checks structure only — whether a declaration *could* be
+ * correct — so it deliberately does not restate the fuller preconditions that
+ * `lisa-remote-dispatch` enforces at the moment it actually dispatches.
+ */
+const SURFACE_BINDINGS = {
+  "claude-web": ["routineId", "fireUrl"],
+};
+
+/**
+ * The fields a surface must record, with the default applied.
+ *
+ * Read through one helper rather than at each call site, because the two
+ * callers answer different questions — "could this declaration be correct" and
+ * "may an automation dispatch to it" — and a fallback that drifted between them
+ * would let those answers disagree about the very same config.
+ * @param {string} surface Surface name.
+ * @returns {string[]} Field names that must be present.
+ */
+function bindingsFor(surface) {
+  return SURFACE_BINDINGS[surface] ?? ["repository"];
+}
+
+/**
+ * Install methods the toolchain runner supports.
+ *
+ * This is a deliberate copy of `INSTALL_METHODS` in `toolchain.mjs`, which is
+ * the list that actually decides. Skills are distributed as self-contained
+ * directories and nothing imports across a skill boundary, so importing the
+ * authority here would couple two skills' distribution for one array.
+ *
+ * The copy has drifted twice. First `release-tar` was missing while the runner
+ * had supported it for as long as gh has been pinned. Then `release-tree` and
+ * `release-binary` were both missing, which rejected a valid `jq` pin. Each
+ * time the only safeguard was a comment asking the next author to remember.
+ * A conformance test now compares the two sets directly, so adding a kind on
+ * either side fails until both know it.
+ */
+const INSTALL_METHODS = new Set([
+  "release-zip",
+  "release-tar",
+  "release-tree",
+  "release-binary",
+  "npm-global",
+]);
+
+/**
+ * Download kinds — every method that fetches a URL, so every one that needs a
+ * checksum. Spelled as "not npm-global" rather than as a list, because the next
+ * download kind should inherit the obligation by default; the drift above came
+ * from lists that had to be remembered.
+ * @param {string} method An install method.
+ * @returns {boolean} Whether the method fetches a pinned artifact.
+ */
+function isDownloadKind(method) {
+  return INSTALL_METHODS.has(method) && method !== "npm-global";
+}
+
+/**
+ * Validate `secrets.propagating`, which carries two shapes on purpose.
+ *
+ * A bare string mirrors `secrets.rotating`: it pins which *credential* may be
+ * copied into a foreign store, and any target may receive it. An object adds
+ * `targets`, pinning *where it may go* as well — the stronger statement, and the
+ * one worth making for anything not intended fleet-wide.
+ *
+ * Checked here rather than folded into the `require`/`rotating` loop because
+ * that loop assumes every entry is a string, and quietly rejecting the object
+ * form would leave the stronger declaration unusable.
+ * @param {unknown} propagating The declaration, if present.
+ * @returns {string[]} Problems found.
+ */
+function validatePropagating(propagating) {
+  if (propagating === undefined || propagating === null) return [];
+  if (!Array.isArray(propagating)) {
+    return [
+      `secrets.propagating must be an array of exact key names, or of ` +
+        `{ name, targets } objects`,
+    ];
+  }
+  const problems = [];
+  for (const entry of propagating) {
+    const name = typeof entry === "string" ? entry : entry?.name;
+    if (typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name)) {
+      problems.push(
+        `secrets.propagating entry ${JSON.stringify(entry)} has no exact ` +
+          `UPPER_SNAKE_CASE name. Lookup is never fuzzy.`
+      );
+      continue;
+    }
+    if (typeof entry === "string") continue;
+    const targets = entry.targets;
+    if (targets === undefined) continue;
+    if (!Array.isArray(targets) || targets.length === 0) {
+      problems.push(
+        `secrets.propagating["${name}"].targets must be a non-empty array of ` +
+          `"<org>" or "<owner>/<repo>". Omit it to allow any target.`
+      );
+      continue;
+    }
+    for (const target of targets) {
+      if (
+        typeof target !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)?$/.test(
+          target
+        )
+      ) {
+        problems.push(
+          `secrets.propagating["${name}"] target ${JSON.stringify(target)} is ` +
+            `neither an organization nor an owner/repo.`
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * Validate the `secrets` block.
+ * @param {object|undefined} secrets The block, if present.
+ * @returns {string[]} Problems found.
+ */
+export function validateSecrets(secrets) {
+  if (!secrets) return [];
+  const problems = [];
+  const provider = secrets.provider ?? "env";
+
+  if (DECLARED_PROVIDERS.has(provider)) {
+    problems.push(
+      `secrets.provider "${provider}" is documented but has no read ` +
+        `implementation yet. Add one in providers.mjs rather than configuring it.`
+    );
+  } else if (!IMPLEMENTED_PROVIDERS.has(provider)) {
+    problems.push(
+      `secrets.provider "${provider}" is unknown. ` +
+        `Known: ${[...IMPLEMENTED_PROVIDERS, ...DECLARED_PROVIDERS].join(", ")}.`
+    );
+  }
+
+  if (
+    secrets.namespace &&
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(secrets.namespace)
+  ) {
+    problems.push(
+      `secrets.namespace "${secrets.namespace}" is not one safe path segment. ` +
+        `It is joined onto a config root, so a separator could redirect writes.`
+    );
+  }
+
+  if (secrets.surface && !SURFACES.has(secrets.surface)) {
+    problems.push(
+      `secrets.surface "${secrets.surface}" is unknown. ` +
+        `Known: ${[...SURFACES].join(", ")}.`
+    );
+  }
+
+  // `rotating` is a flat list on every surface. `require` also accepts a
+  // surface-scoped object, because the required set genuinely differs by where
+  // the agent runs — see `resolveRequire` in surfaces.mjs.
+  validateKeyList("rotating", secrets.rotating, problems);
+  validateRequire(secrets.require, problems);
+
+  problems.push(...validatePropagating(secrets.propagating));
+
+  // Excluding a name from every surface and declaring it copyable to a foreign
+  // store are opposite instructions about the same credential. The propagator
+  // refuses at push time; catching it here means the contradiction surfaces in
+  // review rather than the first time someone needs the push to work.
+  const excluded = new Set(secrets.narrow?.excludeKeys ?? []);
+  for (const entry of secrets.propagating ?? []) {
+    const name = typeof entry === "string" ? entry : entry?.name;
+    if (typeof name === "string" && excluded.has(name)) {
+      problems.push(
+        `secrets.propagating["${name}"] is also in secrets.narrow.excludeKeys. ` +
+          `Those say opposite things about the same credential.`
+      );
+    }
+  }
+
+  if ((secrets.rotating ?? []).length && !secrets.bootstrap?.key) {
+    problems.push(
+      `secrets.rotating is declared but secrets.bootstrap.key is not. A ` +
+        `rotating credential whose replacement cannot be written back is ` +
+        `stranded the first time it is used.`
+    );
+  }
+
+  return problems;
+}
+
+/**
+ * Validate the artifact half of one install entry.
+ *
+ * Split out because the same obligations apply whether the fields sit directly
+ * on the entry or inside a per-platform block: a method must be one Lisa can
+ * execute, an archive must carry a checksum, and an npm install must name a
+ * package. Duplicating those three rules per shape is how one shape ends up
+ * quietly weaker than the other.
+ * @param {string} label How to name this entry in a message.
+ * @param {object} entry The entry or platform block.
+ * @param {string[]} problems Accumulator.
+ */
+/**
+ * Whether a value parses as a dotted version the comparator can order.
+ * @param {unknown} value Candidate version.
+ * @returns {boolean} True for "20", "1.2", "1.2.3" and similar.
+ */
+function isVersionish(value) {
+  return typeof value === "string" && /^\d+(\.\d+)*$/.test(value.trim());
+}
+
+/**
+ * Validate a flat list of exact environment-variable names.
+ * @param {string} field Config field name, for messages.
+ * @param {unknown} value The declared value.
+ * @param {string[]} problems Collector.
+ */
+function validateKeyList(field, value, problems) {
+  if (value === undefined || value === null) return;
+  if (!Array.isArray(value)) {
+    problems.push(`secrets.${field} must be an array of exact key names`);
+    return;
+  }
+  for (const name of value) {
+    if (typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name)) {
+      problems.push(
+        `secrets.${field} entry ${JSON.stringify(name)} is not an exact ` +
+          `UPPER_SNAKE_CASE environment-variable name. Lookup is never fuzzy.`
+      );
+    }
+  }
+}
+
+/**
+ * Validate `require` in either of its two shapes.
+ *
+ * An array means every surface. An object scopes per surface, with `all`
+ * applying everywhere. Unknown keys are rejected rather than ignored: a typo
+ * like `github_actions` for `github-actions` would otherwise resolve to an
+ * empty list and silently assert nothing on the one surface it was written
+ * for — a declaration that reads as protection and delivers none.
+ * @param {unknown} value The declared value.
+ * @param {string[]} problems Collector.
+ */
+function validateRequire(value, problems) {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    validateKeyList("require", value, problems);
+    return;
+  }
+  if (typeof value !== "object") {
+    problems.push(
+      `secrets.require must be an array of key names, or an object keyed by ` +
+        `surface with an optional "all" entry`
+    );
+    return;
+  }
+  for (const [key, names] of Object.entries(value)) {
+    if (key !== "all" && !SURFACES.has(key)) {
+      problems.push(
+        `secrets.require key "${key}" is not a known surface. ` +
+          `Known: all, ${[...SURFACES].join(", ")}.`
+      );
+      continue;
+    }
+    validateKeyList(`require.${key}`, names, problems);
+  }
+}
+
+function validateInstallArtifact(label, entry, problems) {
+  if (!INSTALL_METHODS.has(entry.install)) {
+    problems.push(
+      `remoteEnv install ${label} has method ${JSON.stringify(entry.install)}. ` +
+        `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+    );
+    return;
+  }
+  // Every download kind, not an enumerated few. A tarball pinned without a
+  // checksum trusts whatever the URL serves today exactly as much as a zip
+  // does, and checking only one of them meant the tool Lisa's guardrails shell
+  // out to — gh, which ships a tarball on Linux — was the one going unverified.
+  // A `release-binary` matters most of all: the artifact is directly
+  // executable, so a wrong one needs no unpacking step to run.
+  if (isDownloadKind(entry.install) && !(entry.url && entry.sha256)) {
+    problems.push(
+      `remoteEnv install ${label} needs both url and sha256. A pinned ` +
+        `version with no checksum still trusts whatever the URL serves today.`
+    );
+  }
+  // A tree is the one kind with no sane default entry point: the archive root
+  // is a directory, so an omitted `binary` would install a directory as a
+  // command. The runner refuses it, and a validator that accepted it would just
+  // move the failure from review to provisioning.
+  if (entry.install === "release-tree" && !entry.binary) {
+    problems.push(
+      `remoteEnv install ${label} needs "binary" — the path to the entry ` +
+        `point INSIDE the archive, such as "maestro/bin/maestro".`
+    );
+  }
+  if (entry.install === "npm-global" && !entry.package) {
+    problems.push(`remoteEnv install ${label} needs a package`);
+  }
+}
+
+/**
+ * Validate the `remoteEnv` block.
+ * @param {object|undefined} remoteEnv The block, if present.
+ * @returns {string[]} Problems found.
+ */
+export function validateRemoteEnv(remoteEnv) {
+  if (!remoteEnv) return [];
+  const problems = [];
+
+  for (const tool of remoteEnv.tools?.require ?? []) {
+    if (!tool.name) {
+      problems.push("remoteEnv.tools.require entry has no name");
+      continue;
+    }
+    // `minVersion` was accepted unvalidated while `install` entries had their
+    // shape checked in full. The asymmetry mattered: the value is fed to a
+    // version comparison, so `minVersion: "twenty"` sorted below every real
+    // version and the requirement silently passed for any installed release —
+    // a declared constraint that enforced nothing.
+    if (tool.minVersion !== undefined && !isVersionish(tool.minVersion)) {
+      problems.push(
+        `remoteEnv require "${tool.name}" has minVersion ` +
+          `${JSON.stringify(tool.minVersion)}, which is not a dotted version ` +
+          `like "20" or "1.2.3". It is compared numerically, so a value that ` +
+          `does not parse would accept every installed version.`
+      );
+    }
+  }
+  for (const tool of remoteEnv.tools?.install ?? []) {
+    if (!tool.name) {
+      problems.push("remoteEnv.tools.install entry has no name");
+      continue;
+    }
+    if (!tool.version) {
+      problems.push(`remoteEnv install "${tool.name}" has no pinned version`);
+    }
+    // A flat entry means one artifact serves every platform — true of npm-global
+    // and of nothing else. Anything downloaded is platform-specific, so those
+    // declare a block per platform and each block is validated in full: a
+    // half-filled map is the failure this shape exists to prevent, and it is
+    // invisible until someone runs setup on the platform that was left out.
+    if (tool.platforms === undefined) {
+      validateInstallArtifact(`"${tool.name}"`, tool, problems);
+      continue;
+    }
+    if (
+      typeof tool.platforms !== "object" ||
+      tool.platforms === null ||
+      Array.isArray(tool.platforms)
+    ) {
+      problems.push(
+        `remoteEnv install "${tool.name}" has a platforms field that is not an ` +
+          `object keyed by <platform>-<arch>. Omit it when one artifact serves ` +
+          `every platform.`
+      );
+      continue;
+    }
+    const platforms = Object.entries(tool.platforms);
+    if (platforms.length === 0) {
+      problems.push(
+        `remoteEnv install "${tool.name}" declares platforms but lists none, so ` +
+          `it can never be installed anywhere.`
+      );
+      continue;
+    }
+    for (const [platform, block] of platforms) {
+      validateInstallArtifact(`"${tool.name}" (${platform})`, block, problems);
+    }
+  }
+
+  for (const [surface, block] of Object.entries(remoteEnv.surfaces ?? {})) {
+    if (!SURFACES.has(surface)) {
+      problems.push(`remoteEnv.surfaces has unknown surface "${surface}"`);
+      continue;
+    }
+    for (const field of bindingsFor(surface)) {
+      if (!block[field]) {
+        problems.push(`remoteEnv.surfaces["${surface}"] has no ${field}`);
+      }
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Report whether a surface has been provisioned far enough to dispatch to.
+ * @param {object|undefined} remoteEnv The remote-environment block.
+ * @param {string} surface Surface name.
+ * @returns {boolean} Whether every binding field is recorded.
+ */
+export function isProvisioned(remoteEnv, surface) {
+  const block = remoteEnv?.surfaces?.[surface];
+  if (!block) return false;
+  return bindingsFor(surface).every(field => Boolean(block[field]));
+}
+
+/**
+ * Validate the `automations` block against declared surfaces.
+ * @param {object|undefined} automations The block, if present.
+ * @param {object|undefined} remoteEnv The remote-environment block.
+ * @returns {string[]} Problems found.
+ */
+export function validateAutomations(automations, remoteEnv) {
+  if (!automations) return [];
+  const problems = [];
+
+  for (const [name, loop] of Object.entries(automations)) {
+    if (loop.scheduler !== "github-actions") continue;
+    if (!loop.schedule) {
+      problems.push(`automations["${name}"] has no schedule`);
+    }
+    if (!loop.executionEnv) {
+      problems.push(`automations["${name}"] has no executionEnv`);
+      continue;
+    }
+    if (!SURFACES.has(loop.executionEnv)) {
+      problems.push(
+        `automations["${name}"].executionEnv "${loop.executionEnv}" is unknown`
+      );
+      continue;
+    }
+    if (!isProvisioned(remoteEnv, loop.executionEnv)) {
+      problems.push(
+        `automations["${name}"] dispatches to "${loop.executionEnv}", which is ` +
+          `not provisioned. Run /lisa:setup:remote-env ${loop.executionEnv} first.`
+      );
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Validate every block this plan introduced.
+ * @param {object} cfg Parsed `.lisa.config.json`.
+ * @returns {string[]} Problems found.
+ */
+export function validateConfig(cfg) {
+  return [
+    ...validateSecrets(cfg.secrets),
+    ...validateRemoteEnv(cfg.remoteEnv),
+    ...validateAutomations(cfg.automations, cfg.remoteEnv),
+  ];
+}
+
+function main() {
+  const path = join(process.cwd(), ".lisa.config.json");
+  if (!existsSync(path)) {
+    console.log("no .lisa.config.json — nothing to validate");
+    return;
+  }
+  const problems = validateConfig(JSON.parse(readFileSync(path, "utf8")));
+  if (!problems.length) {
+    console.log(
+      "config: secrets, remoteEnv and automations blocks are well-formed"
+    );
+    return;
+  }
+  for (const problem of problems) console.error(`  ${problem}`);
+  throw new Error(`${problems.length} configuration problem(s)`);
+}
+
+/**
+ * Whether this module is the one node was asked to run.
+ *
+ * Both sides are realpath'd: a raw URL comparison answers "no" through a
+ * symlinked checkout, a git worktree, or a /tmp path on macOS, so the module
+ * loads, runs nothing and exits 0 — a silent no-op that reads as success.
+ *
+ * A local copy rather than an import: plugin payload scripts ship standalone,
+ * with no `lib/` sibling to import from once installed.
+ * @param {string} moduleUrl - The caller's own `import.meta.url`.
+ * @param {string | undefined} [argv1] - Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the caller should run its CLI body.
+ */
+function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/plugins/lisa-devin/skills/lisa-security-review/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: lisa-security-review
+description: "Security review methodology. STRIDE threat modeling, OWASP Top 10 vulnerability checks, auth/validation/secrets handling review, and mitigation recommendations."
+---
+
+# Security Review
+
+Identify vulnerabilities, evaluate threats, and recommend mitigations for code changes.
+
+## Analysis Process
+
+1. **Read affected files** -- understand current security posture of the code being changed
+2. **STRIDE analysis** -- evaluate Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege risks
+3. **Check input validation** -- are user inputs sanitized at system boundaries?
+4. **Check secrets handling** -- are credentials, tokens, or API keys exposed in code, logs, or error messages?
+5. **Check auth/authz** -- are access controls properly enforced for new endpoints or features?
+6. **Review dependencies** -- do new dependencies introduce known vulnerabilities?
+
+## The impact-or-exploitability bar
+
+Severity is **earned, not pattern-matched**. Every security-shaped finding is classified
+mechanically, before it is written up:
+
+| Field | What it holds |
+|-------|---------------|
+| `reproducer` | an evidence ref of a kind that reaches the claim's boundary, or `none` |
+| `impact` | a bounded impact/exploitability statement (who can do what, to what data, under what preconditions), or `unproven` |
+| `reason` | one line saying why the finding landed in its bucket |
+
+**The bar:** a finding is **proven** only when it carries **both** a reproducer **and** a bounded
+impact statement. **Missing either ⇒ unproven.** No other input changes the bucket.
+
+What counts as a reaching reproducer is defined by the `claim-evidence-mapping` contract (**BCE-1**,
+#1835), not here: an injection claim at the `http-api` boundary needs an `http-transcript`; a UI
+claim needs a `screenshot` or `recording`. A passing unit `test-run-log` reaches `code-unit` only and
+never discharges either.
+
+**Each field stands on its own.** The two halves are recorded independently: a finding with a bounded
+impact but no reproducer keeps its impact statement verbatim and only `reproducer` reads `none`; a
+finding with a reproducer but no bounded impact keeps the evidence ref and only `impact` reads
+`unproven`. **Never overwrite** a field you actually have with a missing-value placeholder — the
+`reason` line names which half is missing, and the surviving half is the head start the next reviewer
+needs.
+
+## The two buckets — conservative by default
+
+Findings render in two clearly-labeled buckets: **Security (proven)** and **Security (unproven)**.
+
+A reproducer-less finding **stays in the security section**, labeled `unproven` with its reason. It
+is **never auto-demoted** to a `maintenance` bucket and it is **not removed** from the report —
+under-reporting a real vulnerability is the worse failure, so the conservative default keeps it
+visible where a security reader looks.
+
+**Single policy point.** The unproven bucket's label is the only thing an owner may change:
+`security.review.unprovenBucket` in `.lisa.config.json`, default `security-unproven`. An owner who
+prefers true demotion sets it to a maintenance label; the finding then renders under that bucket and
+**no other classification logic changes** — the bar, the fields, and the reasons are identical.
+
+Write both buckets in operator voice (`factory-model` rule 5): a person who does not code reads this
+at the gate. "Anyone who can reach the search box can read other customers' orders — reproduced with
+the request transcript below" is usable; "possible SQLi in handler" is not.
+
+This bar governs *code-review* security findings. Dependency CVE remediation keeps its own decision
+ladder in the `security-audit-handling` rule — cite it, do not restate or fork it.
+
+Bucketing is **advisory** — it shapes the report, it does not block a merge — on the same terms as
+the boundary checks, which stay reporting-only until `verification.gate.enforceBoundaries` is `true`
+in `.lisa.config.json`.
+
+## Output Format
+
+Structure findings as:
+
+```
+## Security Analysis
+
+### Threat Model (STRIDE)
+| Threat | Applies? | Description | Mitigation |
+|--------|----------|-------------|------------|
+| Spoofing | Yes/No | ... | ... |
+| Tampering | Yes/No | ... | ... |
+| Repudiation | Yes/No | ... | ... |
+| Info Disclosure | Yes/No | ... | ... |
+| Denial of Service | Yes/No | ... | ... |
+| Elevation of Privilege | Yes/No | ... | ... |
+
+### Security Checklist
+- [ ] Input validation at system boundaries
+- [ ] No secrets in code or logs
+- [ ] Auth/authz enforced on new endpoints
+- [ ] No SQL/NoSQL injection vectors
+- [ ] No XSS vectors in user-facing output
+- [ ] Dependencies free of known CVEs
+
+### Security (proven)
+- [finding] -- where in the code, how to prevent
+  - reproducer: [evidence ref, e.g. evidence/<ticket>/http-transcript-01.txt]
+  - impact: [who can do what, to what data, under what preconditions]
+  - reason: reproducer + bounded impact
+
+### Security (unproven)
+- [finding] -- where in the code, how to prevent
+  - reproducer: [evidence ref if one exists, else `none`]
+  - impact: [bounded statement if one exists, else `unproven`]
+  - reason: [which half is missing -- e.g. "impact bounded, but never reproduced"]
+    -- kept in the security section, not demoted
+
+### Recommendations
+- [recommendation] -- priority (critical/warning/suggestion)
+```
+
+Rename the unproven heading only when `security.review.unprovenBucket` is set to something other
+than `security-unproven`; everything else stays as written.
+
+## Rules
+
+- Focus on the specific changes proposed, not a full security audit of the entire codebase
+- Flag only real risks -- do not invent hypothetical threats for internal tooling with no user input
+- Classify every finding against the bar before writing it up; never leave a finding unbucketed
+- Never silently drop or downgrade a finding out of the security section -- `unproven` is the
+  conservative landing spot, and the reason line says why
+- Prioritize OWASP Top 10 vulnerabilities
+- If the changes are purely internal (config, refactoring, docs), report "No security concerns" and explain why
+- Always check `.gitleaksignore` patterns to understand what secrets scanning is already in place