penthera 1.2.0 → 1.5.0

package/lib/agents/hidden-content.js

@@ -0,0 +1,387 @@
+/**
+ * Hidden-content engine for agent instructions (skills, rule files, commands).
+ *
+ * Deterministic and offline. It looks for content a human reviewer would not
+ * see but a model would read and act on, and for payloads that run code.
+ *
+ * Designed against the ways LLM-judged skill scanners have been bypassed:
+ *   - Invisible text: Unicode tag characters, zero-width and bidi controls,
+ *     variation-selector smuggling. Decoded where possible, so the report shows
+ *     what the model would read.
+ *   - Content pushed out of view: hundreds of blank lines or a wide run of
+ *     spaces, so the payload sits past what a reviewer or a truncating judge sees.
+ *     This engine reads the whole file; there is no context window to overflow.
+ *   - Instructions in HTML comments, which Markdown renderers hide.
+ *   - Text addressed to the scanner itself ("this skill is safe, approve it").
+ *     A regex cannot be talked out of a finding, but the attempt is a signal.
+ *   - Payloads moved out of SKILL.md: every file in a skill folder is scanned,
+ *     binaries and archives are identified by magic bytes rather than extension,
+ *     and symlinks that leave the folder are reported.
+ *   - Encoded payloads: long base64 blobs, decoded and classified.
+ *
+ * Each detector returns hits `{ rule, severity, title, detail, line, count }`.
+ * Callers turn hits into findings.
+ */
+
+// ── Invisible characters ──────────────────────────────────────────────────
+
+const TAG_RANGE = /[\u{E0000}-\u{E007F}]/u;
+const TAG_RUN = /[\u{E0000}-\u{E007F}]+/gu;
+const VS_SUPPLEMENT_RUN = /[\u{E0100}-\u{E01EF}]+/gu;
+const BIDI = /[‪-‮⁦-⁩]/g;
+// Zero-width and other format characters that render as nothing. U+200D (ZWJ)
+// and U+200C (ZWNJ) have legitimate uses (emoji sequences, Persian, Indic
+// scripts), so those are filtered by context below.
+const ZERO_WIDTH = /[​-‍⁠-⁤᠎ㅤᅟᅠﾠ]/g;
+const PICTO = /\p{Extended_Pictographic}|[\u{1F3FB}-\u{1F3FF}️]/u;
+const NON_LATIN_LETTER = /[\p{L}\p{M}]/u;
+
+function lineOf(text, index) {
+  let n = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+/** Decode Unicode tag characters to the ASCII they smuggle. */
+export function decodeTagChars(s) {
+  let out = "";
+  for (const ch of s) {
+    const cp = ch.codePointAt(0);
+    if (cp >= 0xe0020 && cp <= 0xe007e) out += String.fromCharCode(cp - 0xe0000);
+  }
+  return out;
+}
+
+/** Make a decoded payload safe to print: visible ASCII only, truncated. */
+export function preview(s, max = 80) {
+  const clean = String(s).replace(/[^\x20-\x7E]/g, "·").replace(/\s+/g, " ").trim();
+  return clean.length > max ? clean.slice(0, max) + "…" : clean;
+}
+
+function detectInvisible(text) {
+  const hits = [];
+
+  const tagRuns = [...text.matchAll(TAG_RUN)];
+  if (tagRuns.length) {
+    const decoded = tagRuns.map((m) => decodeTagChars(m[0])).join(" ").trim();
+    const count = tagRuns.reduce((n, m) => n + [...m[0]].length, 0);
+    hits.push({
+      rule: "unicode-tags",
+      severity: "critical",
+      title: "Hidden text in Unicode tag characters",
+      detail: `${count} invisible tag character(s) (U+E0000–E007F). A model reads them as text; a reviewer sees nothing.` +
+        (decoded ? ` Decoded: "${preview(decoded)}"` : ""),
+      line: lineOf(text, tagRuns[0].index),
+      count,
+    });
+  }
+
+  const vsRuns = [...text.matchAll(VS_SUPPLEMENT_RUN)];
+  if (vsRuns.length) {
+    const count = vsRuns.reduce((n, m) => n + [...m[0]].length, 0);
+    hits.push({
+      rule: "variation-selectors",
+      severity: "high",
+      title: "Data hidden in variation selectors",
+      detail: `${count} supplementary variation selector(s) (U+E0100–E01EF). These are invisible and can encode arbitrary bytes ("emoji smuggling").`,
+      line: lineOf(text, vsRuns[0].index),
+      count,
+    });
+  }
+
+  const bidi = [...text.matchAll(BIDI)];
+  if (bidi.length) {
+    hits.push({
+      rule: "bidi-controls",
+      severity: "high",
+      title: "Bidirectional control characters",
+      detail: `${bidi.length} bidi override/isolate character(s) (U+202A–202E, U+2066–2069). They reorder how text displays, so what a reviewer reads differs from what the model reads (Trojan Source).`,
+      line: lineOf(text, bidi[0].index),
+      count: bidi.length,
+    });
+  }
+
+  const zw = [];
+  for (const m of text.matchAll(ZERO_WIDTH)) {
+    const ch = m[0];
+    const i = m.index;
+    if (ch === "" && i === 0) continue; // byte-order mark
+    // A zero-width space at the start of a line before ``` or ~~~ is the usual
+    // trick for showing a code fence inside a fenced block.
+    if (ch === "​" && (i === 0 || text[i - 1] === "\n") && /^(?:```|~~~)/.test(text.slice(i + 1, i + 4))) continue;
+    const prev = text.slice(Math.max(0, i - 2), i);
+    const next = text.slice(i + 1, i + 3);
+    if (ch === "‍" && PICTO.test(prev) && PICTO.test(next)) continue; // emoji ZWJ sequence
+    if (ch === "‌" || ch === "‍") {
+      const p = [...prev].pop() || "";
+      const n = [...next][0] || "";
+      // ZWNJ/ZWJ between letters of a non-Latin script is ordinary orthography.
+      if (NON_LATIN_LETTER.test(p) && NON_LATIN_LETTER.test(n) && /[^\x00-ɏ]/.test(p + n)) continue;
+    }
+    zw.push(i);
+  }
+  if (zw.length) {
+    hits.push({
+      rule: "zero-width",
+      severity: zw.length >= 3 ? "high" : "medium",
+      title: "Zero-width or invisible characters",
+      detail: `${zw.length} zero-width/invisible character(s). They can split keywords to dodge filters or carry a hidden binary encoding.`,
+      line: lineOf(text, zw[0]),
+      count: zw.length,
+    });
+  }
+
+  return hits;
+}
+
+// ── Whitespace inflation ──────────────────────────────────────────────────
+
+export const DEFAULTS = {
+  blankLines: 40,       // consecutive blank lines before more content
+  horizontalRun: 200,   // consecutive spaces/tabs on one line before more content
+  base64MinLength: 200, // characters in one base64 run
+};
+
+// Linear scans, not regexes: a nested whitespace quantifier backtracks
+// quadratically on exactly the input an attacker would write here.
+function detectWhitespaceInflation(text, opts) {
+  const hits = [];
+  const lines = text.split("\n");
+  let run = 0;
+  let longestV = 0;
+  let firstV = null;
+  let countV = 0;
+  let longestH = 0;
+  let firstH = null;
+  let countH = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+    if (/^[ \t\r]*$/.test(ln)) { run++; continue; }
+    if (run >= opts.blankLines) {
+      countV++;
+      longestV = Math.max(longestV, run);
+      if (firstV === null) firstV = i + 1;
+    }
+    run = 0;
+    let ws = 0;
+    for (let j = 0; j < ln.length; j++) {
+      const ch = ln.charCodeAt(j);
+      if (ch === 32 || ch === 9 || ch === 0xa0) { ws++; continue; }
+      if (ws >= opts.horizontalRun && ch !== 13) {
+        countH++;
+        longestH = Math.max(longestH, ws);
+        if (firstH === null) firstH = i + 1;
+      }
+      ws = 0;
+    }
+  }
+  if (countV) {
+    hits.push({
+      rule: "whitespace-vertical",
+      severity: "high",
+      title: "Content hidden below a wall of blank lines",
+      detail: `${longestV} consecutive blank lines, then more content. This pushes text past where a reviewer stops scrolling, and past what a truncating scanner reads.`,
+      line: firstV,
+      count: countV,
+    });
+  }
+  if (countH) {
+    hits.push({
+      rule: "whitespace-horizontal",
+      severity: "high",
+      title: "Content hidden off-screen to the right",
+      detail: `A run of ${longestH} spaces, then more text on the same line. Editors and diff views without wrapping never show it.`,
+      line: firstH,
+      count: countH,
+    });
+  }
+  return hits;
+}
+
+// ── Instructions in hidden places ─────────────────────────────────────────
+
+const INSTRUCTION_PATTERNS = [
+  /\b(?:ignore|disregard|forget|override)\b[^.\n]{0,40}\b(?:previous|prior|above|earlier|all|any|other)\b[^.\n]{0,20}\b(?:instructions?|rules?|prompts?|guidelines?|directions?)\b/i,
+  /\b(?:you|assistant|claude|agent|model|ai|llm)\b[^.\n]{0,30}\b(?:must|should|shall|will|are to|need to|have to)\b/i,
+  /\bdo(?:n'?t| not) (?:tell|inform|mention|reveal|show|alert|ask|notify)\b/i,
+  /\bwithout (?:asking|telling|informing|confirm\w*|permission|the user)/i,
+  /\b(?:system prompt|developer message|new instructions?)\b/i,
+  /\b(?:run|execute|exec|invoke)\b[^.\n]{0,40}\b(?:command|script|bash|shell|curl|wget|powershell)\b/i,
+  /\b(?:send|upload|post|exfiltrat\w*|transmit|forward|copy)\b[^\n]{0,60}(?:https?:\/\/|\btokens?\b|\bsecrets?\b|\bapi keys?\b|\bcredentials?\b|\.env\b|\bssh\b|\bpasswords?\b)/i,
+  /(?:~\/\.ssh|\bid_rsa\b|\bid_ed25519\b|\.aws\/credentials|\.npmrc|\.netrc|\bkeychain\b)/i,
+];
+
+// Text addressed to an automated reviewer. Legitimate skills have no reason to
+// talk to a security scanner.
+const SCANNER_DIRECTED = /\b(?:security |safety |skill |code )?(?:scanners?|reviewers?|auditors?|judges?|classifiers?|analy[sz]ers?|moderators?)\b[^.\n]{0,60}\b(?:is|as|are|mark|classify|report|treat|consider|rate|label)\b[^.\n]{0,30}\b(?:safe|benign|harmless|clean|trusted|approved?|pass(?:ed)?|low[- ]risk|false positive)\b/i;
+
+export function looksLikeInstruction(s) {
+  return INSTRUCTION_PATTERNS.some((re) => re.test(s));
+}
+
+function detectHiddenInstructions(text) {
+  const hits = [];
+  const comments = [...text.matchAll(/<!--([\s\S]*?)-->/g)];
+  const bad = comments.filter((m) => looksLikeInstruction(m[1]));
+  if (bad.length) {
+    hits.push({
+      rule: "html-comment-instructions",
+      severity: "high",
+      title: "Instructions hidden in an HTML comment",
+      detail: `${bad.length} HTML comment(s) contain instructions. Markdown renderers hide comments, the model still reads them. First: "${preview(bad[0][1])}"`,
+      line: lineOf(text, bad[0].index),
+      count: bad.length,
+    });
+  }
+  const scanner = text.match(SCANNER_DIRECTED);
+  if (scanner) {
+    hits.push({
+      rule: "scanner-directed",
+      severity: "high",
+      title: "Text addressed to a security scanner",
+      detail: `Tries to talk an automated reviewer into a verdict: "${preview(scanner[0])}". This is how LLM-judged scanners get bypassed.`,
+      line: lineOf(text, scanner.index),
+      count: 1,
+    });
+  }
+  return hits;
+}
+
+// ── Code execution patterns ───────────────────────────────────────────────
+
+const SHELL = String.raw`(?:sudo\s+)?(?:env\s+\S*\s*)?(?:ba|z|da|k|fi|c|tc)?sh\b`;
+export const EXEC_PATTERNS = [
+  { rule: "curl-pipe-shell", label: "download piped to a shell", re: new RegExp(String.raw`\b(?:curl|wget|fetch|iwr)\b[^\n|]*\|\s*${SHELL}`, "i") },
+  { rule: "curl-pipe-interpreter", label: "download piped to an interpreter", re: /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:python[0-9.]*|node|perl|ruby|php|deno|bun)\b/i },
+  { rule: "shell-process-substitution", label: "shell runs a download via process substitution", re: /\b(?:(?:ba|z)?sh|source|\.)\s+<\(\s*(?:curl|wget)\b/i },
+  { rule: "shell-command-substitution", label: "shell -c runs a download", re: /\b(?:ba|z)?sh\s+-c\s+["']?\$\(\s*(?:curl|wget)\b/i },
+  { rule: "base64-pipe-shell", label: "decoded base64 piped to a shell", re: new RegExp(String.raw`base64\s+(?:-d|--decode|-D)\b[^\n]*\|\s*${SHELL}`, "i") },
+  { rule: "shell-eval", label: "eval of command output", re: /\beval\s+["']?\$\(/ },
+  { rule: "js-eval-remote", label: "eval of fetched or decoded content", re: /\b(?:eval|Function)\s*\(\s*(?:await\s+)?(?:atob|Buffer\.from|fetch|require\(\s*["']child_process|\(await fetch)/ },
+  { rule: "py-exec-remote", label: "exec of fetched or decoded content", re: /\bexec\s*\(\s*(?:base64\.b64decode|__import__|compile|urllib|requests\.get|zlib\.decompress|marshal\.loads|bytes\.fromhex)/ },
+  { rule: "powershell-iex", label: "PowerShell Invoke-Expression of a download", re: /\b(?:iex|Invoke-Expression)\b[^\n]*\b(?:iwr|irm|Invoke-WebRequest|Invoke-RestMethod|DownloadString)\b|\b(?:iwr|irm|Invoke-WebRequest|Invoke-RestMethod|DownloadString)\b[^\n]*\|\s*(?:iex|Invoke-Expression)\b/i },
+];
+
+/** Find remote-code-execution patterns in a string (a file, a hook command). */
+export function findExecPatterns(text) {
+  const out = [];
+  for (const p of EXEC_PATTERNS) {
+    const m = text.match(p.re);
+    if (m) out.push({ rule: p.rule, label: p.label, match: m[0], index: m.index });
+  }
+  return out;
+}
+
+function detectExec(text) {
+  return findExecPatterns(text).map((m) => ({
+    rule: m.rule,
+    severity: "high",
+    title: `Remote code execution pattern: ${m.label}`,
+    detail: `\`${preview(m.match, 120)}\`. An agent following this runs code nobody reviewed, fetched at run time.`,
+    line: lineOf(text, m.index),
+    count: 1,
+  }));
+}
+
+// ── Base64 blobs ──────────────────────────────────────────────────────────
+
+const MAGIC = [
+  { name: "ELF executable", test: (b) => b[0] === 0x7f && b[1] === 0x45 && b[2] === 0x4c && b[3] === 0x46 },
+  { name: "Windows executable", test: (b) => b[0] === 0x4d && b[1] === 0x5a },
+  { name: "Mach-O executable", test: (b) => {
+    const m = b.readUInt32BE?.(0);
+    return [0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe].includes(m);
+  } },
+  { name: "zip archive", test: (b) => b[0] === 0x50 && b[1] === 0x4b && (b[2] === 0x03 || b[2] === 0x05 || b[2] === 0x07) },
+  { name: "gzip archive", test: (b) => b[0] === 0x1f && b[1] === 0x8b },
+  { name: "bzip2 archive", test: (b) => b[0] === 0x42 && b[1] === 0x5a && b[2] === 0x68 },
+  { name: "xz archive", test: (b) => b[0] === 0xfd && b[1] === 0x37 && b[2] === 0x7a && b[3] === 0x58 },
+  { name: "7z archive", test: (b) => b[0] === 0x37 && b[1] === 0x7a && b[2] === 0xbc && b[3] === 0xaf },
+  { name: "rar archive", test: (b) => b[0] === 0x52 && b[1] === 0x61 && b[2] === 0x72 && b[3] === 0x21 },
+  { name: "WebAssembly module", test: (b) => b[0] === 0x00 && b[1] === 0x61 && b[2] === 0x73 && b[3] === 0x6d },
+  // CPython bytecode: a 2-byte version magic followed by \r\n.
+  { name: "Python bytecode (.pyc)", test: (b) => b.length >= 16 && b[2] === 0x0d && b[3] === 0x0a && b[1] < 0x10 },
+  { name: "tar archive", test: (b) => b.length > 262 && b.toString("latin1", 257, 262) === "ustar" },
+];
+
+/** Name the executable/archive format of a buffer, or null. */
+export function sniffBinary(buf) {
+  if (!buf || buf.length < 4) return null;
+  const hit = MAGIC.find((m) => m.test(buf));
+  return hit ? hit.name : null;
+}
+
+function isPrintable(buf) {
+  if (!buf.length) return false;
+  let ok = 0;
+  for (const b of buf) if (b === 9 || b === 10 || b === 13 || (b >= 32 && b < 127)) ok++;
+  return ok / buf.length > 0.95;
+}
+
+function detectBase64(text, opts) {
+  const re = new RegExp(`[A-Za-z0-9+/_-]{${opts.base64MinLength},}={0,2}`, "g");
+  const blobs = [];
+  for (const m of text.matchAll(re)) {
+    const s = m[0];
+    // Real base64 mixes cases and digits; hex digests, identifiers and long
+    // words do not.
+    if (!/[A-Z]/.test(s) || !/[a-z]/.test(s) || !/[0-9]/.test(s)) continue;
+    if (/^[0-9a-f]+$/i.test(s)) continue;
+    const before = text.slice(Math.max(0, m.index - 40), m.index);
+    const image = /data:image\/[a-z+.-]+;base64,$/i.test(before);
+    const buf = Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+    const binary = sniffBinary(buf);
+    let decodedText = null;
+    if (!binary && isPrintable(buf)) decodedText = buf.toString("utf-8");
+    const execInside = decodedText ? findExecPatterns(decodedText) : [];
+    const instructionInside = decodedText ? looksLikeInstruction(decodedText) : false;
+    blobs.push({ index: m.index, length: s.length, image, binary, decodedText, execInside, instructionInside });
+  }
+  if (!blobs.length) return [];
+
+  const worst = blobs.find((b) => b.binary) || blobs.find((b) => b.execInside.length) ||
+    blobs.find((b) => b.instructionInside) || blobs.find((b) => !b.image) || blobs[0];
+  let severity = "medium";
+  let what = "an opaque encoded payload a reviewer cannot read";
+  if (worst.binary) { severity = "high"; what = `a ${worst.binary}`; }
+  else if (worst.execInside.length) { severity = "high"; what = `a ${worst.execInside[0].label} (\`${preview(worst.execInside[0].match)}\`)`; }
+  else if (worst.instructionInside) { severity = "high"; what = `hidden instructions ("${preview(worst.decodedText)}")`; }
+  else if (worst.image) { severity = "low"; what = "an inline image"; }
+  else if (worst.decodedText) what = `encoded text ("${preview(worst.decodedText, 60)}")`;
+
+  return [{
+    rule: "base64-blob",
+    severity,
+    title: "Large base64 blob",
+    detail: `${blobs.length} base64 run(s) of ${opts.base64MinLength}+ characters; the largest is ${Math.max(...blobs.map((b) => b.length))}. It decodes to ${what}.`,
+    line: lineOf(text, worst.index),
+    count: blobs.length,
+  }];
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Scan one text file for hidden content.
+ * @param {string} text
+ * @param {object} [opts] { blankLines, horizontalRun, base64MinLength, markdown }
+ */
+export function scanHiddenContent(text, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  return [
+    ...detectInvisible(text),
+    ...detectWhitespaceInflation(text, o),
+    ...detectHiddenInstructions(text),
+    ...detectExec(text),
+    ...detectBase64(text, o),
+  ];
+}
+
+export function hasTagChars(text) {
+  return TAG_RANGE.test(text);
+}
+
+// Extensions that are binary or archives no matter what the bytes say.
+export const BINARY_EXTENSIONS = /\.(?:pyc|pyo|pyd|so|dylib|dll|exe|bin|jar|class|whl|egg|zip|tar|tgz|gz|bz2|xz|7z|rar|wasm|node|deb|rpm|dmg|pkg|msi|apk)$/i;
+// Media that ships in skills legitimately.
+export const MEDIA_EXTENSIONS = /\.(?:png|jpe?g|gif|webp|ico|bmp|avif|woff2?|ttf|otf|eot|mp3|mp4|wav|ogg|webm|mov|pdf)$/i;

package/lib/agents/index.js

@@ -0,0 +1,286 @@
+/**
+ * Penthera, agents mode: an offline, deterministic audit of the AI developer
+ * tooling configured in a repo and (with --home) on this machine.
+ *
+ * No network, no LLM judge, no registry lookups. Every verdict is a rule you
+ * can read, so a skill cannot argue its way past it.
+ */
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { relative, sep, extname } from "node:path";
+import { discoverAgentConfig, walk, parseFrontmatter, MAX_FILE_BYTES } from "./discover.js";
+import { scanHiddenContent, sniffBinary, BINARY_EXTENSIONS, MEDIA_EXTENSIONS } from "./hidden-content.js";
+import { checkMcpServer, checkHook, checkPermissions, checkAllowedTools, checkMarketplaces } from "./rules.js";
+import { computeLockEntries, diffLock, readLock, writeLock, lockPath, LOCK_FILENAME } from "./lock.js";
+import { owaspFor, owaspLabel } from "./owasp.js";
+
+export { scanHiddenContent } from "./hidden-content.js";
+export { discoverAgentConfig } from "./discover.js";
+
+const SOURCE = "agents-scan";
+const CATEGORY = "agent-config";
+
+/** Turn a rule hit into a finding in Penthera's standard shape. */
+export function toFinding(hit) {
+  const ids = owaspFor(hit.rule);
+  const mapping = ids.length ? ` [${owaspLabel(ids)}]` : "";
+  return {
+    severity: hit.severity,
+    title: hit.title,
+    description: `${hit.detail}${hit.line ? ` (line ${hit.line})` : ""}${mapping}`,
+    url: hit.url,
+    category: CATEGORY,
+    source: SOURCE,
+    templateId: `agents/${hit.rule}`,
+    owasp: ids,
+    confidence: hit.confidence || (hit.severity === "info" ? "confirmed" : "likely"),
+  };
+}
+
+// ── Content scanning ──────────────────────────────────────────────────────
+
+function scanTextFile(path, display, hits) {
+  let buf;
+  try {
+    const st = statSync(path);
+    if (st.size > MAX_FILE_BYTES) {
+      hits.push({
+        rule: "file-too-large",
+        severity: "medium",
+        title: "File too large to scan",
+        detail: `${(st.size / 1024 / 1024).toFixed(1)} MB, over the ${MAX_FILE_BYTES / 1024 / 1024} MB limit. Padding a file past a scanner's size limit is a known way to hide a payload; review it by hand.`,
+        url: display,
+      });
+      return;
+    }
+    buf = readFileSync(path);
+  } catch {
+    return;
+  }
+  const binary = sniffBinary(buf);
+  if (binary) {
+    hits.push({
+      rule: "embedded-binary",
+      severity: "high",
+      title: `Embedded ${binary}`,
+      detail: `A ${binary} inside agent instructions cannot be reviewed as text, and agents can be told to unpack or run it.`,
+      url: display,
+    });
+    return;
+  }
+  if (buf.subarray(0, 8192).includes(0)) {
+    hits.push({
+      rule: "unknown-binary",
+      severity: "medium",
+      title: "Unrecognised binary file",
+      detail: "A binary file of unknown type sits next to agent instructions. Check what it is and why it is there.",
+      url: display,
+    });
+    return;
+  }
+  for (const h of scanHiddenContent(buf.toString("utf-8"))) hits.push({ ...h, url: display });
+}
+
+function scanSkillFolder(skill, inv, hits) {
+  const { files, symlinks, truncated } = walk(skill.dir);
+  let realDir = skill.dir;
+  try { realDir = realpathSync(skill.dir); } catch { /* keep */ }
+  for (const l of symlinks) {
+    let target = null;
+    try { target = realpathSync(l); } catch { /* broken */ }
+    if (!target || (target !== realDir && !target.startsWith(realDir + sep))) {
+      hits.push({
+        rule: "symlink-escape",
+        severity: "high",
+        title: "Symlink points outside the skill folder",
+        detail: `\`${relative(skill.dir, l)}\` resolves to ${target ? `\`${inv.display(target)}\`` : "a missing target"}. Scanners that stay inside the folder never see what the agent reads through it.`,
+        url: inv.display(l),
+      });
+    }
+  }
+  if (truncated) {
+    hits.push({
+      rule: "file-too-large",
+      severity: "medium",
+      title: "Skill folder too large to scan fully",
+      detail: "More files than the scanner's limit; the rest were not checked. Review the folder by hand.",
+      url: skill.display,
+    });
+  }
+  for (const f of files) {
+    const display = inv.display(f);
+    if (BINARY_EXTENSIONS.test(f)) {
+      let head = Buffer.alloc(0);
+      try { head = readFileSync(f).subarray(0, 512); } catch { /* unreadable */ }
+      const kind = sniffBinary(head) || `${extname(f)} file`;
+      hits.push({
+        rule: "embedded-binary",
+        severity: "high",
+        title: `Embedded ${kind} in skill`,
+        detail: `Compiled code and archives in a skill cannot be reviewed as text. A skill can tell the agent to run or unpack them.`,
+        url: display,
+      });
+      continue;
+    }
+    if (MEDIA_EXTENSIONS.test(f)) {
+      // Check that "media" really is media; a renamed archive is a classic dodge.
+      let head = Buffer.alloc(0);
+      try { head = readFileSync(f).subarray(0, 512); } catch { /* unreadable */ }
+      const kind = sniffBinary(head);
+      if (kind) {
+        hits.push({
+          rule: "embedded-binary",
+          severity: "high",
+          title: `${kind} disguised as ${extname(f)}`,
+          detail: `The file extension says media; the bytes say ${kind}.`,
+          url: display,
+        });
+      }
+      continue;
+    }
+    scanTextFile(f, display, hits);
+  }
+}
+
+// ── Grade ─────────────────────────────────────────────────────────────────
+
+const WEIGHT = { critical: 30, high: 15, medium: 5, low: 1, info: 0 };
+
+/** A–F grade. Any critical finding is an F; otherwise score bands. */
+export function gradeFindings(findings) {
+  let score = 100;
+  for (const f of findings) score -= WEIGHT[f.severity] ?? 0;
+  score = Math.max(0, score);
+  const critical = findings.some((f) => f.severity === "critical");
+  const grade = critical ? "F" : score >= 90 ? "A" : score >= 75 ? "B" : score >= 60 ? "C" : score >= 40 ? "D" : "F";
+  return { grade, score };
+}
+
+// ── Scan ──────────────────────────────────────────────────────────────────
+
+/**
+ * Audit agent configuration.
+ * @param {string} root
+ * @param {object} [opts] { home, homeDir, pin, onPhase }
+ */
+export async function scanAgents(root, opts = {}) {
+  const progress = opts.onPhase || (() => {});
+  const start = Date.now();
+
+  progress("Discovering agent configuration...");
+  const inv = discoverAgentConfig(root, { home: opts.home, homeDir: opts.homeDir });
+  const hits = [];
+
+  progress(`Scanning ${inv.skills.length} skill(s) for hidden content...`);
+  for (const s of inv.skills) {
+    scanSkillFolder(s, inv, hits);
+    hits.push(...checkAllowedTools(inv.display(s.skillFile), s.frontmatter, `Skill "${s.name}"`));
+  }
+
+  progress("Scanning instruction and rule files...");
+  for (const f of inv.instructionFiles) {
+    scanTextFile(f.path, f.display, hits);
+    if (/\.mdc?$/i.test(f.path)) {
+      let text = "";
+      try { text = readFileSync(f.path, "utf-8"); } catch { /* unreadable */ }
+      hits.push(...checkAllowedTools(f.display, parseFrontmatter(text), "Command"));
+    }
+  }
+
+  progress(`Checking ${inv.mcpServers.length} MCP server(s), ${inv.hooks.length} hook(s), permissions and plugins...`);
+  for (const m of inv.mcpServers) hits.push(...checkMcpServer(m));
+  for (const h of inv.hooks) hits.push(...checkHook(h));
+  hits.push(...checkPermissions(inv));
+  hits.push(...checkMarketplaces(inv));
+  for (const e of inv.errors) {
+    hits.push({ rule: "config-unparsed", severity: "info", title: "Config file could not be parsed", detail: e.message, url: e.file });
+  }
+
+  // Rug-pull pins
+  progress("Comparing against penthera.lock...");
+  const entries = computeLockEntries(inv);
+  const lpath = opts.lockPath || lockPath(inv.root);
+  const lockInfo = { path: lpath, status: "missing", changed: 0, added: 0, removed: 0, entries: Object.keys(entries).length };
+  if (opts.pin) {
+    writeLock(lpath, entries);
+    lockInfo.status = "pinned";
+  } else {
+    let lock = null;
+    try {
+      lock = readLock(lpath);
+    } catch (e) {
+      hits.push({ rule: "config-unparsed", severity: "medium", title: `${LOCK_FILENAME} is corrupt`, detail: `${e.message}. Rug-pull detection is off until it is re-pinned.`, url: LOCK_FILENAME });
+      lockInfo.status = "corrupt";
+    }
+    if (lock) {
+      const scopes = opts.home ? ["repo", "home"] : ["repo"];
+      const d = diffLock(lock, entries, { scopes });
+      Object.assign(lockInfo, { status: "checked", changed: d.changed.length, added: d.added.length, removed: d.removed.length });
+      for (const c of d.changed) {
+        hits.push({
+          rule: "lock-changed",
+          severity: "high",
+          title: `Pinned ${c.kind} changed since ${LOCK_FILENAME}: ${c.key.replace(/^\w+:/, "")}`,
+          detail: `Hash was ${c.previous.slice(0, 12)}…, now ${c.sha256.slice(0, 12)}…. A ${c.kind} that changes after review is how a rug pull works. Diff it, then re-pin with \`penthera agents --pin\` if the change is expected.`,
+          url: LOCK_FILENAME,
+        });
+      }
+      for (const a of d.added) {
+        hits.push({
+          rule: "lock-new",
+          severity: "medium",
+          title: `New ${a.kind} not in ${LOCK_FILENAME}: ${a.key.replace(/^\w+:/, "")}`,
+          detail: `Added since the last pin. Review it, then run \`penthera agents --pin\`.`,
+          url: LOCK_FILENAME,
+        });
+      }
+      for (const r of d.removed) {
+        hits.push({
+          rule: "lock-removed",
+          severity: "info",
+          title: `Pinned ${r.kind} no longer present: ${r.key.replace(/^\w+:/, "")}`,
+          detail: "Removed since the last pin.",
+          url: LOCK_FILENAME,
+        });
+      }
+    } else if (lockInfo.status === "missing" && Object.keys(entries).length) {
+      hits.push({
+        rule: "lock-missing",
+        severity: "info",
+        title: `No ${LOCK_FILENAME}: skills, MCP servers and hooks are not pinned`,
+        detail: `Run \`penthera agents --pin\` after reviewing them. Later runs then report anything that changed (rug pulls) or appeared.`,
+        url: LOCK_FILENAME,
+      });
+    }
+  }
+
+  const findings = hits.map(toFinding);
+  const { grade, score } = gradeFindings(findings);
+
+  return {
+    target: inv.root,
+    mode: "agents",
+    local: true,
+    reachable: true,
+    timestamp: new Date().toISOString(),
+    duration: Date.now() - start,
+    agents: {
+      grade,
+      score,
+      home: !!opts.home,
+      inventory: {
+        skills: inv.skills.length,
+        mcpServers: inv.mcpServers.length,
+        hooks: inv.hooks.length,
+        permissions: inv.permissions.length,
+        plugins: inv.plugins.length,
+        marketplaces: inv.marketplaces.length,
+        instructionFiles: inv.instructionFiles.length,
+        configFiles: inv.configFiles.map((f) => f.display),
+      },
+      lock: { ...lockInfo, path: inv.display(lpath) },
+    },
+    executedProbes: ["agent-config-discovery", "hidden-content", "agent-config-rules", "agent-lock"],
+    findings,
+  };
+}
+