penthera 1.4.0 → 1.6.0

package/src/cli/ui.js

@@ -0,0 +1,89 @@
+/**
+ * `penthera ui [--port 0] [--open] [--project <dir>]... [--reports <dir>] [--demo]`
+ *
+ * Starts the local dashboard on 127.0.0.1 and prints a one-time URL. See
+ * docs/dashboard.md for the security model.
+ */
+import { parseArgs } from "node:util";
+import { spawn } from "node:child_process";
+import { bold, dim, red, green } from "./ansi.js";
+
+const HELP = `
+  ${bold("penthera ui")}: the local dashboard, on 127.0.0.1 only
+
+  ${dim("Usage")}
+    $ penthera ui [--open] [--port <n>] [--project <dir>]... [--reports <dir>]
+    $ penthera ui --demo          Realistic fake data, for a first look or screenshots
+
+  ${dim("Options")}
+        --port <n>          Port to listen on (default: 0, a random free port)
+        --open              Open the one-time URL in your browser
+        --project <dir>     Folder the dashboard may read and run the agent loop in
+                            (repeatable; default: the current folder)
+        --reports <dir>     Report JSON folder (default: <first project>/reports)
+        --demo              Seed fake data; nothing is read from disk
+    -h, --help              Show this help
+
+  The URL holds a one-time token. Opening it sets a session cookie; the token
+  then stops working. Nothing outside the project folders and ~/.penthera is
+  read, and the server never contacts the network. Ctrl-C stops it.
+`;
+
+function openBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+      : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch { /* the URL is printed anyway */ }
+}
+
+export async function runUi(argv, { version }) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: false,
+      options: {
+        port: { type: "string", default: "0" },
+        open: { type: "boolean", default: false },
+        project: { type: "string", multiple: true },
+        reports: { type: "string" },
+        demo: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    process.stderr.write(`  ${red("Error")} ${e.message}\n${HELP}`);
+    return 2;
+  }
+  const opts = parsed.values;
+  if (opts.help) { console.log(HELP); return 0; }
+  const port = Number(opts.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    process.stderr.write(`  ${red("Error")} --port must be 0-65535\n`);
+    return 2;
+  }
+
+  const { startUiServer } = await import("../ui/server.js");
+  let ui;
+  try {
+    ui = await startUiServer({ port, projects: opts.project, reportsDir: opts.reports, demo: opts.demo, version });
+  } catch (e) {
+    process.stderr.write(`  ${red("Not started")} ${e.message}\n`);
+    return 2;
+  }
+
+  process.stdout.write(`\n  ${bold("penthera ui")}${opts.demo ? dim("  (demo data)") : ""}\n`);
+  process.stdout.write(`  ${green(ui.url)}\n`);
+  process.stdout.write(dim(`  one-time link: it signs this browser in once, then stops working\n`));
+  process.stdout.write(dim(`  listening on 127.0.0.1:${ui.port} only. Ctrl-C to stop\n\n`));
+  if (opts.open) openBrowser(ui.url);
+
+  await new Promise((resolve) => {
+    const stop = () => { process.stdout.write("\n  Stopped.\n"); ui.close().then(resolve); };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  return 0;
+}

package/src/cli.js

@@ -24,7 +24,9 @@ import { blankAssessment } from "../lib/compliance/self-assessment.js";
 import { buildPolicyPack, policyPackIndex } from "../lib/compliance/policy-pack.js";
 import { parseQuestionnaire, answerQuestionnaire, formatQuestionnaireMarkdown } from "../lib/compliance/questionnaire.js";
 import { buildIncidentReports, formatIncidentMarkdown, incidentTemplate } from "../lib/compliance/incident.js";
-import { buildSbom } from "../lib/whitebox/sbom.js";
+import { buildSbom, buildAiBom } from "../lib/whitebox/sbom.js";
+import { aiBomSummary } from "../lib/whitebox/aibom.js";
+import { buildCraReports, craTemplate, formatCraMarkdown, readCraInput } from "../lib/compliance/cra.js";
 import { emptyHistory, updateHistory, buildAuditLoop } from "../lib/audit-loop.js";
 import { rateSuppliers, parseSupplierList, formatSuppliersMarkdown } from "../lib/supply-chain.js";
 
@@ -57,12 +59,14 @@ const HELP = `
     $ penthera --repo <path>         Scan a local repo (white-box)
     $ penthera <url> --repo <path>   Full scan (both)
     $ penthera agents [path]         Audit AI agent config: skills, MCP, hooks (offline)
-    $ penthera deps [path]           What your npm dependencies can do (offline)
+    $ penthera deps [path]           What your npm and Python dependencies can do (offline)
     $ penthera install <pkg...>      Check what an npm install adds before anything runs
+    $ penthera hook install          Pre-commit hook: staged secrets, agent config, lockfiles
     $ penthera memory show|verify|forget  Local learning store (never leaves the machine)
     $ penthera fix --plan            Plan local fix recipes (penthera fix --help)
     $ penthera evidence verify <dir> Check an evidence bundle's hashes and signature
     $ penthera agent --loop          Scan, fix, verify, learn; local commits only (--help)
+    $ penthera ui [--open] [--demo]  Local dashboard on 127.0.0.1 (penthera ui --help)
 
   ${dim("Scan modes")}
         --profile <name>        quick | standard | deep (default: standard)
@@ -77,22 +81,28 @@ const HELP = `
         --all                   Enable all modes (recon + deep + fuzz)
         --machine               macOS machine audit (keyloggers, trojans, rootkits)
         --offline               Contact only the scan target: no recon sources, no
-                               Retire.js download (uses the vendored snapshot)
+                               Retire.js download (uses the vendored snapshot),
+                               no DNS lookups for SPF/DMARC
 
   ${dim("Agents mode")}  ${dim("(penthera agents [path], offline, read-only)")}
         --home                  Also audit ~/.claude, ~/.cursor and Claude Desktop config
         --pin                   Write penthera.lock (SHA-256 of skills, MCP servers, hooks)
 
-  ${dim("Deps mode")}  ${dim("(penthera deps [path], reads package-lock.json + node_modules, offline)")}
+  ${dim("Deps mode")}  ${dim("(penthera deps [path], reads package-lock.json, Python lockfiles or a .venv, offline)")}
         --diff <lock|dir>       Capability diff against an old lockfile or installed tree
         --base <git-ref>        Capability diff against the lockfile at a git ref
         --online                Also check npm registry metadata (the only network use)
-        --prod                  Skip devDependencies
+        --prod                  Skip dev dependencies
+        --venv <path>           Python virtualenv to read (default: .venv or venv)
         --pr-comment <file>     Write a short Markdown capability diff for a PR comment
+        --license-policy <p>    permissive | weak-copyleft-ok | no-agpl, or a policy file
 
   ${dim("Install mode")}  ${dim("(penthera install [pkg...]; penthera install --help for all options)")}
         --yes / --dry-run       Install only if nothing breaches the policy / report only
 
+  ${dim("Hook mode")}  ${dim("(penthera hook install|uninstall|run; penthera hook --help)")}
+                                Pre-commit: staged secrets, agent config, lockfile diff
+
   ${dim("Options")}
     -r, --repo <path>       Path to repo for source analysis
         --api-root <path>   API routes directory (default: auto-detect)
@@ -102,6 +112,7 @@ const HELP = `
         --audience <who>    developer | owner | auditor report (for --markdown or stdout)
         --report-template <file.md>  Your own Markdown template ({{summary.critical}}, {{#each findings}})
         --evidence <dir>    Evidence bundle: all reports + manifest.json with SHA-256s
+        --no-footer         Leave the one-line "Checked by Penthera" footer off Markdown output
         --sign-key <key>    Sign the bundle's manifest with an SSH key (ssh-keygen -Y sign)
         --baseline <file>   Compare against previous JSON report
         --framework <name>  Add a compliance mapping to reports (nis2)
@@ -114,6 +125,9 @@ const HELP = `
         --incident <file>   Generate NIS2 incident-report drafts + timeline
         --incident-init <file>  Write a blank incident template and exit
         --sbom <file>       Write a CycloneDX software bill of materials (from --repo)
+        --aibom <file>      Write a CycloneDX 1.6 AI-BOM: AI SDKs, models, MCP servers, skills, prompts
+        --cra <file>        Generate CRA Article 14 report drafts + timeline (writes cra-reports.md)
+        --cra-init <file>   Write a blank CRA reporting template and exit
         --history <file>    Track findings over time (time-to-fix, ageing, drift)
         --memory            Learn from this scan locally; apply suppressions + ranking
         --suppliers <file>  Passively rate suppliers' public domains (RAG, measure d)
@@ -166,6 +180,12 @@ export async function run() {
     return;
   }
 
+  if (process.argv[2] === "hook") {
+    const { runHookCommand } = await import("./cli/hook.js");
+    process.exitCode = await runHookCommand(process.argv.slice(3));
+    return;
+  }
+
   if (process.argv[2] === "evidence") {
     const { runEvidence } = await import("./cli/evidence.js");
     process.exit(runEvidence(process.argv.slice(3)));
@@ -176,6 +196,11 @@ export async function run() {
     return runFix(process.argv.slice(3));
   }
 
+  if (process.argv[2] === "ui") {
+    const { runUi } = await import("./cli/ui.js");
+    process.exit(await runUi(process.argv.slice(3), { version: pkg.version }));
+  }
+
   if (process.argv[2] === "agent") {
     const { runAgent } = await import("./cli/agent.js");
     process.exit(await runAgent(process.argv.slice(3)));
@@ -192,6 +217,7 @@ export async function run() {
         markdown:    { type: "string" },
         sarif:       { type: "string" },
         audience:    { type: "string" },
+        "no-footer": { type: "boolean", default: false },
         "report-template": { type: "string" },
         evidence:    { type: "string" },
         "sign-key":  { type: "string" },
@@ -206,6 +232,9 @@ export async function run() {
         incident:    { type: "string" },
         "incident-init": { type: "string" },
         sbom:        { type: "string" },
+        aibom:       { type: "string" },
+        cra:         { type: "string" },
+        "cra-init":  { type: "string" },
         history:     { type: "string" },
         memory:      { type: "boolean", default: false },
         suppliers:   { type: "string" },
@@ -214,6 +243,8 @@ export async function run() {
         online:      { type: "boolean", default: false },
         "pr-comment": { type: "string" },
         prod:        { type: "boolean", default: false },
+        "license-policy": { type: "string" },
+        venv:        { type: "string" },
         profile:     { type: "string" },
         "auth-cookie": { type: "string" },
         "auth-bearer": { type: "string" },
@@ -292,6 +323,32 @@ export async function run() {
     process.exit(0);
   }
 
+  if (opts["cra-init"]) {
+    const path = resolve(opts["cra-init"]);
+    writeFileSync(path, JSON.stringify(craTemplate(), null, 2) + "\n");
+    console.log(`Wrote a blank CRA reporting template to ${path}`);
+    console.log(`Set type and aware_at (ISO 8601), then run:  penthera --cra ${opts["cra-init"]}`);
+    process.exit(0);
+  }
+
+  if (opts.cra) {
+    let input;
+    try {
+      input = readCraInput(resolve(opts.cra));
+    } catch (e) {
+      printError(`Could not read --cra file: ${e.message}`);
+      process.exit(2);
+    }
+    for (const err of input.errors) printError(err);
+    const result = buildCraReports(input.cra, loadJurisdiction(), { now: new Date().toISOString(), prefilled: input.prefilled });
+    const outPath = resolve("cra-reports.md");
+    writeFileSync(outPath, formatCraMarkdown(result));
+    console.log(`CRA Article 14 report drafts written to ${outPath}`);
+    for (const t of result.timeline) console.log(`  ${t.title} (${t.within}): ${t.dueBy ? `due ${t.dueBy}` : t.basis || "n/a"}, ${t.status}`);
+    for (const w of result.warnings) console.log(`  ⚠️ ${w}`);
+    process.exit(0);
+  }
+
   if (opts.suppliers && opts.offline) {
     printError("--suppliers rates third-party domains, which --offline forbids.");
     process.exit(2);
@@ -326,8 +383,8 @@ export async function run() {
     await runDeps(positionals.slice(1), opts, { version: pkg.version });
     return;
   }
-  if (opts.diff || opts.base || opts.online || opts["pr-comment"] || opts.prod) {
-    printError("--diff, --base, --online, --prod and --pr-comment only apply to `penthera deps`.");
+  if (opts.diff || opts.base || opts.online || opts["pr-comment"] || opts.prod || opts["license-policy"] || opts.venv) {
+    printError("--diff, --base, --online, --prod, --pr-comment, --license-policy and --venv only apply to `penthera deps`.");
     process.exit(2);
   }
 
@@ -352,8 +409,8 @@ export async function run() {
   const url = positionals[0] && !agentsMode ? normalizeBaseUrl(positionals[0]) : null;
   const repo = opts.repo || null;
 
-  if (!agentsMode && !url && !repo && !opts.machine && !opts.readiness && !opts["policy-pack"] && !opts.sbom && !opts.questionnaire) {
-    printError("No target specified. Provide a URL, --repo, --machine, --readiness, --policy-pack, --sbom, --questionnaire, or combine them.");
+  if (!agentsMode && !url && !repo && !opts.machine && !opts.readiness && !opts["policy-pack"] && !opts.sbom && !opts.aibom && !opts.questionnaire) {
+    printError("No target specified. Provide a URL, --repo, --machine, --readiness, --policy-pack, --sbom, --aibom, --questionnaire, or combine them.");
     console.log(HELP);
     process.exit(2);
   }
@@ -537,7 +594,7 @@ export async function run() {
     }
   }
 
-  const mdOpts = { version: pkg.version, baseline: baselineStats };
+  const mdOpts = { version: pkg.version, baseline: baselineStats, footer: !opts["no-footer"] };
   const custom = customReport(merged, opts, { version: pkg.version, template: reportCtx.template });
 
   // Output
@@ -609,6 +666,19 @@ export async function run() {
     }
   }
 
+  if (opts.aibom) {
+    const aibom = buildAiBom(resolve(opts.repo || "."), {
+      serialNumber: `urn:uuid:${randomUUID()}`,
+      timestamp: new Date().toISOString(),
+      toolVersion: pkg.version,
+    });
+    writeFileSync(resolve(opts.aibom), JSON.stringify(aibom, null, 2) + "\n");
+    if (!opts.quiet && !opts.json) {
+      const n = aiBomSummary(aibom);
+      process.stderr.write(`  AI-BOM (CycloneDX 1.6) ${n.sdks} SDKs, ${n.models} models, ${n.mcpServers} MCP servers, ${n.skills} skills, ${n.prompts} prompts → ${opts.aibom}\n`);
+    }
+  }
+
   if (opts["policy-pack"]) {
     const dir = resolve(opts["policy-pack"]);
     mkdirSync(dir, { recursive: true });
@@ -668,7 +738,7 @@ export async function run() {
     );
   }
 
-  if ((opts.output || opts.markdown || opts.sarif || opts.evidence || opts.readiness || opts["policy-pack"] || opts.sbom || opts.history || opts.questionnaire) && !opts.quiet && !opts.json) {
+  if ((opts.output || opts.markdown || opts.sarif || opts.evidence || opts.readiness || opts["policy-pack"] || opts.sbom || opts.aibom || opts.history || opts.questionnaire) && !opts.quiet && !opts.json) {
     process.stderr.write("\n");
   }
 

package/src/report/audience.js

@@ -8,6 +8,8 @@
  *              probes, suppressions (who and why), loop timeline, NIS2 and OWASP
  */
 import { buildReportModel, CONFIDENCE_LABELS } from "./model.js";
+import { mdInline } from "./md-escape.js";
+import { footerLines } from "./footer.js";
 
 export const AUDIENCES = ["developer", "owner", "auditor"];
 
@@ -24,10 +26,7 @@ const NIS2_STATUS = {
 };
 
 /** Inline text: one line, no table breaks, no raw HTML. */
-function md(s) {
-  return String(s ?? "").replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").replace(/\r?\n|\r/g, " ")
-    .replace(/\\/g, "\\\\").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\|/g, "\\|");
-}
+const md = mdInline;
 /** Penthera's own remediation text (lib/remediation): may hold code spans, so only fold lines. */
 function prose(s) {
   return String(s ?? "").replace(/\r?\n|\r/g, " ");
@@ -51,8 +50,9 @@ function header(L, title, m) {
   L.push(`> ${md(m.target)} · scanned ${when(m.timestamp)} · Penthera v${m.tool.version}`, "");
 }
 
-function footer(L) {
+function footer(L, m) {
   L.push("---", "", "*Authorized security testing only. See the Penthera README for ethical use guidelines.*", "");
+  L.push(...footerLines(m));
 }
 
 function timelineSection(L, t, { heading = "## Fix timeline" } = {}) {
@@ -111,7 +111,7 @@ export function formatDeveloperReport(m) {
     for (const x of m.suppressed) L.push(`- ${md(x.title)} (${code(x.fid)}): ${md(x.reason)} (${md(x.actor)}, ${x.by})`);
     L.push("");
   }
-  footer(L);
+  footer(L, m);
   return L.join("\n");
 }
 
@@ -167,7 +167,7 @@ export function formatOwnerReport(m) {
     L.push("## Fixes", "");
     L.push(`${t.verified} ${t.verified === 1 ? "fix" : "fixes"} verified by a re-scan, ${t.failed} failed, ${t.open} still open. Typical time to fix: ${t.medianTimeToFix}.`, "");
   }
-  footer(L);
+  footer(L, m);
   return L.join("\n");
 }
 
@@ -256,15 +256,15 @@ export function formatAuditorReport(m) {
 
   L.push("## Verifying this report", "");
   L.push(`If this report came in an evidence bundle, check that nothing in it changed since it was produced: ${code("penthera evidence verify <dir> --allowed-signers <file>")}. See [docs/evidence.md](${EVIDENCE_URL}).`, "");
-  footer(L);
+  footer(L, m);
   return L.join("\n");
 }
 
 const FORMATTERS = { developer: formatDeveloperReport, owner: formatOwnerReport, auditor: formatAuditorReport };
 
 /** Render the report for one audience. Throws on an unknown audience. */
-export function formatAudienceReport(result, audience, { version } = {}) {
+export function formatAudienceReport(result, audience, { version, footer = true } = {}) {
   const fmt = FORMATTERS[audience];
   if (!fmt) throw new Error(`Unknown --audience "${audience}". Use one of: ${AUDIENCES.join(", ")}.`);
-  return fmt(buildReportModel(result, { version }));
+  return fmt({ ...buildReportModel(result, { version }), footer });
 }

package/src/report/evidence.js

@@ -9,11 +9,12 @@
  * See docs/evidence.md.
  */
 import { createHash } from "node:crypto";
-import { execFileSync, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import {
   readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, lstatSync,
 } from "node:fs";
 import { join, resolve, relative, sep } from "node:path";
+import { createGit } from "../agent/git.js";
 
 export const SCHEMA = "penthera-evidence/1";
 export const NAMESPACE = "penthera-evidence";
@@ -75,8 +76,10 @@ function quote(a) {
 export function gitInfo(dir) {
   if (!dir) return null;
   try {
-    const commit = execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-    const status = execFileSync("git", ["-C", dir, "status", "--porcelain"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    // The scanned repo is untrusted: no fsmonitor, no hooks, no transports.
+    const git = createGit(dir);
+    const commit = git.run("rev-parse", "HEAD").trim();
+    const status = git.run("status", "--porcelain");
     return /^[0-9a-f]{40,64}$/.test(commit) ? { commit, dirty: status.trim().length > 0 } : null;
   } catch {
     return null;
@@ -174,19 +177,28 @@ function sshVerify(args, manifestBuf) {
   return { ok: r.status === 0, out: `${r.stdout || ""}${r.stderr || ""}`.trim() };
 }
 
-function checkSignature(root, manifestBuf, allowedSigners) {
+/**
+ * Signature status. A bundle that says it is signed (manifest.signature, or a
+ * .sig file) only passes when the signature verifies against --allowed-signers:
+ * anyone can re-sign a rewritten manifest with their own key, so a signature
+ * whose signer was not checked proves nothing and must not read as "verified".
+ */
+function checkSignature(root, manifestBuf, manifest, allowedSigners) {
   const sigPath = join(root, SIGNATURE);
+  const declared = manifest.signature != null;
   if (!existsSync(sigPath)) {
+    if (declared) return { status: "missing", ok: false, detail: `the manifest declares a signature but ${SIGNATURE} is missing` };
     return allowedSigners
       ? { status: "missing", ok: false, detail: `--allowed-signers was given but there is no ${SIGNATURE}` }
-      : { status: "unsigned", ok: true, detail: "bundle is not signed; hashes only prove it is internally consistent" };
+      : { status: "unsigned", ok: true, detail: "UNSIGNED: hashes only prove the bundle is internally consistent, not who wrote it" };
+  }
+  if (lstatSync(sigPath).isSymbolicLink() || !lstatSync(sigPath).isFile()) {
+    return { status: "invalid", ok: false, detail: `${SIGNATURE} is not a regular file` };
   }
   if (!allowedSigners) {
     const r = sshVerify(["check-novalidate", "-n", NAMESPACE, "-s", sigPath], manifestBuf);
-    if (r.missing) return { status: "unchecked", ok: true, detail: "ssh-keygen not found; signature not checked" };
-    return r.ok
-      ? { status: "valid-unknown-signer", ok: true, detail: "signature is valid, but the signer was not checked: pass --allowed-signers" }
-      : { status: "invalid", ok: false, detail: r.out };
+    if (!r.missing && !r.ok) return { status: "invalid", ok: false, detail: r.out };
+    return { status: "unverified", ok: false, detail: "the bundle is signed, but the signer was not checked: pass --allowed-signers <file> listing the keys you trust" };
   }
   const allowed = resolve(allowedSigners);
   if (!existsSync(allowed)) return { status: "invalid", ok: false, detail: `allowed signers file ${allowedSigners} not found` };
@@ -203,14 +215,16 @@ function checkSignature(root, manifestBuf, allowedSigners) {
 
 /**
  * Verify a bundle. Never throws on a bad bundle; returns { ok, ... }.
+ * `warnings` carries the UNSIGNED notice for a bundle that passes without a
+ * signature; `requireSignature` turns that into a failure.
  * @param {string} dir
- * @param {{ allowedSigners?: string }} opts
+ * @param {{ allowedSigners?: string, requireSignature?: boolean }} opts
  */
-export function verifyEvidence(dir, { allowedSigners = null } = {}) {
+export function verifyEvidence(dir, { allowedSigners = null, requireSignature = false } = {}) {
   const root = resolve(dir);
   const problems = [];
   const files = [];
-  const fail = (msg) => ({ ok: false, problems: [msg], files, unlisted: [], signature: null, manifest: null });
+  const fail = (msg) => ({ ok: false, problems: [msg], warnings: [], files, unlisted: [], signature: null, manifest: null });
 
   const manifestPath = join(root, MANIFEST);
   if (!existsSync(manifestPath)) return fail(`${MANIFEST} not found in ${dir}`);
@@ -246,8 +260,13 @@ export function verifyEvidence(dir, { allowedSigners = null } = {}) {
   for (const p of unlisted) problems.push(`${p} is in the bundle but not in the manifest`);
   for (const f of files) if (!f.ok) problems.push(`${f.path}: ${f.reason}`);
 
-  const signature = checkSignature(root, manifestBuf, allowedSigners);
+  const signature = checkSignature(root, manifestBuf, manifest, allowedSigners);
   if (!signature.ok) problems.push(`signature: ${signature.detail}`);
+  const warnings = [];
+  if (signature.status === "unsigned") {
+    if (requireSignature) problems.push("signature: --require-signature was given but the bundle is not signed");
+    else warnings.push("UNSIGNED bundle: anyone could have written it. Ask for a signed bundle and verify with --allowed-signers --require-signature.");
+  }
 
-  return { ok: problems.length === 0, problems, files, unlisted, signature, manifest };
+  return { ok: problems.length === 0, problems, warnings, files, unlisted, signature, manifest };
 }

package/src/report/footer.js

@@ -0,0 +1,11 @@
+/**
+ * One-line footer at the end of human-readable Markdown output: the default
+ * report, audience reports, the PR comment and the evidence bundle README.
+ * Never added to SARIF or JSON. `--no-footer` turns it off.
+ */
+export const FOOTER = "Checked by Penthera, open-source security for the apps and AI systems you ship · https://github.com/danoszz/penthera";
+
+/** Lines to push at the very end of a Markdown document, or none when opted out. */
+export function footerLines({ footer = true } = {}) {
+  return footer === false ? [] : [FOOTER, ""];
+}

package/src/report/markdown.js

@@ -9,6 +9,8 @@ import { buildActionPlan, formatActionPlanMarkdown } from "../../lib/remediation
 import { formatAuditLoopMarkdown } from "../../lib/audit-loop.js";
 import { referencesFor, formatSourcesMarkdown } from "../../lib/references.js";
 import { formatDepsMarkdown } from "../../lib/deps/report.js";
+import { mdInline } from "./md-escape.js";
+import { footerLines } from "./footer.js";
 
 const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 const SEV_TAG = {
@@ -33,9 +35,7 @@ function countBySeverity(findings) {
   return counts;
 }
 
-function mdEscape(s) {
-  return String(s || "").replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
+const mdEscape = mdInline;
 
 /**
  * Generate Markdown report content from scan result.
@@ -43,6 +43,7 @@ function mdEscape(s) {
 export function formatMarkdownReport(result, opts = {}) {
   const findings = sortFindings(result.findings);
   const counts = countBySeverity(findings);
+  // TODO(good-first-issue): the "0.2.0" fallback is stale; read the version from package.json instead.
   const version = opts.version || "0.2.0";
   const lines = [];
 
@@ -57,6 +58,7 @@ export function formatMarkdownReport(result, opts = {}) {
   lines.push(`|---|---|`);
   lines.push(`| **Target** | \`${result.target || "unknown"}\` |`);
   lines.push(`| **Scan time** | ${result.timestamp?.replace("T", " ").slice(0, 19) || "-"} UTC |`);
+  // TODO(good-first-issue): a missing duration prints ", "; print "-" like the other empty cells and add a test.
   lines.push(`| **Duration** | ${result.duration ? `${(result.duration / 1000).toFixed(1)}s` : ", "} |`);
   lines.push(`| **Mode** | ${result.modes?.join(", ") || result.mode || "-"} |`);
   lines.push(`| **Reachable** | ${result.reachable ? "Yes" : "No"} |`);
@@ -231,6 +233,7 @@ export function formatMarkdownReport(result, opts = {}) {
   lines.push("");
   lines.push("*Authorized security testing only. See Penthera README for ethical use guidelines.*");
   lines.push("");
+  lines.push(...footerLines(opts));
 
   return lines.join("\n");
 }

package/src/report/md-escape.js

@@ -0,0 +1,16 @@
+/**
+ * One escape for untrusted text placed inline in Markdown (table cells, list
+ * items). Finding titles, evidence and questionnaire text come from scanned
+ * targets or pasted files, so they must not break the table, inject HTML, or
+ * smuggle a backslash that un-escapes our own `\|`. Backslash goes first so the
+ * escapes added after it are not themselves doubled.
+ */
+export function mdInline(s) {
+  return String(s ?? "")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "")
+    .replace(/\r?\n|\r/g, " ")
+    .replace(/\\/g, "\\\\")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\|/g, "\\|");
+}

package/src/reporter.js

@@ -15,6 +15,7 @@ const PKG_VERSION = JSON.parse(
 
 // ── ANSI helpers ─────────────────────────────────────────────────────────
 
+// TODO(good-first-issue): also drop colors when stdout is not a TTY (piped output gets escape codes); let FORCE_COLOR=1 override.
 const NO_COLOR = !!process.env.NO_COLOR;
 
 const ansi = (code) => (s) => NO_COLOR ? s : `\x1b[${code}m${s}\x1b[0m`;

package/src/scan-url.js

@@ -386,7 +386,11 @@ async function scanUrlInContext(target, opts) {
   } catch { /* non-critical */ }
 
   // ── Phase 9b: Email authentication posture (SPF/DMARC via DNS) ─────────
-  if (!local && !isIpHost) {
+  // DNS TXT/MX queries go to resolvers, not the target, so --offline skips them.
+  if (!local && !isIpHost && opts.offline) {
+    progress("Skipping email authentication (--offline: no DNS lookups for SPF, DMARC, MX)...");
+  }
+  if (!local && !isIpHost && !opts.offline) {
     progress("Checking email authentication (SPF, DMARC)...");
     try {
       const emailResult = await probeEmailDns(extractDomain(target));