fix(security): close brace-expansion wallet read + 6to4 SSRF (3.29.14) (#96)

Round-9 convergence verify (re-attacking the round-8 normalization/rtk fixes)
found 2 NEW classes — count converging 7->6->5->2.

- CRITICAL brace-expansion wallet read: cat {~,}/.bloc{k,}run/.{session,} read
  the EVM key. Brace expansion is a 4th shell primitive the round-8 dequote
  didn't model; {~,} tilde-expands while .bloc{k,}run/.{session,} brace-split
  the literal path, defeating directory+basename+glob guards at once. Now any
  comma/.. brace group is opaque (prompts, like $VAR), and deny patterns also
  run on a brace-collapsed copy. Reader-agnostic.
- MEDIUM 6to4 IPv6 SSRF: [2002:a9fe:a9fe::] embeds 169.254.169.254; decoded
  and rechecked like NAT64/::ffff: handlers.

+2 regression test groups. Suite 506/506.

Co-authored-by: 1bcMax <195689928+1bcMax@users.noreply.github.com>

Author: VickyXAI

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Franklin Agent 3.29.14 — close brace-expansion wallet read + 6to4 SSRF (round-9)
+
+A third convergence verify (re-attacking the round-8 quote-normalization and rtk-recursion fixes) confirmed **2 NEW classes** — the find count is converging (7→6→5→2) and the survivors are increasingly exotic, but one is still a critical wallet read.
+
+- **Brace-expansion wallet-key read (CRITICAL).** `cat {~,}/.bloc{k,}run/.{session,}` read the EVM private key: brace expansion is a 4th shell primitive the round-8 quote/escape normalizer didn't model. The leading `{~,}` tilde-expands while `.bloc{k,}run` / `.{session,}` brace-split the literal `.blockrun`/`.session` — defeating the directory rule, the basename rule, AND the rooted-glob anchor (the token starts with `{`, not `~`/`.`/`/`) simultaneously. Now any comma-list / `..`-range brace group is treated as opaque (forces a prompt, like `$VAR`/`$(...)`), and the wallet/secret deny patterns also run against a brace-collapsed copy of the command. Reader-agnostic (`grep`/`cut`/`cat`) — the brace mechanism was the defect.
+- **6to4 IPv6 SSRF (MEDIUM).** `http://[2002:a9fe:a9fe::]/` survived WHATWG-URL normalization and reached the fetch path; the 6to4 range `2002::/16` embeds an IPv4 (`2002:a9fe:a9fe::` → `169.254.169.254`, `2002:7f00:1::` → `127.0.0.1`). Now decoded and re-checked like the existing NAT64 / IPv4-mapped handlers. (Exploiting the embedded target needs a 6to4 relay route, but the guard gap was unconditional.)
+
+New regression tests pin both classes plus benign controls (public IPv6, brace commands). Verified: local suite 506/506.
+
 ## Franklin Agent 3.29.13 — close 5 more single-command bypasses from the 3.29.12 convergence verify (round-8)
 
 A second 13-agent convergence verify confirmed **5 NEW single-command bypass classes** the round-7 fixes didn't anticipate — one critical (a fresh evasion of the wallet directory rule itself). All fixed; benign controls preserved.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.29.13",
+  "version": "3.29.14",
   "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {

package.json

@@ -179,17 +179,23 @@ function isSegmentSafe(segment: string): boolean {
   // quoting arrangement of a wallet/secret path can reach 'safe'. (Over-matching
   // here only ever prompts — it never blocks.)
   const norm = segment.replace(/\\(.)/g, '$1').replace(/['"]/g, '');
+  // Brace expansion (`.bloc{k,}run`, `{~,}/...`, `.bloc{j..l}run`) is a 4th
+  // obfuscation primitive — the shell rewrites it to other words before opening
+  // the path, so `.blockrun`/basename literals read as non-contiguous text. Drop
+  // the brace metachars so the deny regexes below see the collapsed first word.
+  const debraced = norm.replace(/[{},]/g, '');
 
   // Never auto-approve a command that touches the wallet key store. Matching the
   // FILENAME is hopeless — it's trivially obfuscated. So match the DIRECTORY: any
   // reference to ~/.blockrun forces a prompt. (The file Read/Write/Edit tools
   // have a separate canonicalized guard; this is the best-effort net for the shell.)
-  if (/\.blockrun/i.test(norm)) {
+  if (/\.blockrun/i.test(norm) || /\.blockrun/i.test(debraced)) {
     return false;
   }
   // Relative reads with no `.blockrun` in the text (e.g. the cwd is the wallet
   // dir): match the known key/secret basenames broadly (any *wallet*.json/.key).
-  if (/(?<![\w-])(?:\.solana-session(?:-key2)?|\.session|[\w-]*wallet[\w-]*\.(?:json|key))(?![\w-])/i.test(norm)) {
+  const keyBasename = /(?<![\w-])(?:\.solana-session(?:-key2)?|\.session|[\w-]*wallet[\w-]*\.(?:json|key))(?![\w-])/i;
+  if (keyBasename.test(norm) || keyBasename.test(debraced)) {
     return false;
   }
   // Command/process substitution runs an arbitrary INNER command the classifier
@@ -214,6 +220,14 @@ function isSegmentSafe(segment: string): boolean {
   if (/\$\{?[A-Za-z_]/.test(segment)) {
     return false;
   }
+  // Brace expansion with a comma list (`{a,b}`) or `..` range (`{0..9}`) fabricates
+  // words/paths the classifier can't statically follow — `cat {~,}/.bloc{k,}run/...`
+  // reaches the wallet store while every char-literal guard misses. Treat any such
+  // group as opaque, like `$VAR`/`$(...)`. (A brace with NO comma/`..` — `{x}`, or
+  // an fd-dup `2>&1` — does not expand, so it stays safe.)
+  if (/\{[^{}]*(?:,|\.\.)[^{}]*\}/.test(segment)) {
+    return false;
+  }
   // A glob/brace in an explicit PATH (a token rooted at ~, ., or /) expands AFTER
   // this guard and can reach the wallet store (`cat ~/.b*/.s*`) or a sensitive
   // file. Bare cwd globs (`*.md`, `src/*.ts`) have no such prefix and stay safe.

src/agent/bash-guard.ts

@@ -31,6 +31,14 @@ export function isBlockedSsrfHost(hostname: string): boolean {
   if (h.includes(':')) {
     if (h === '::1' || h === '::') return true;                          // loopback / unspecified
     if (h.startsWith('fe80:') || h.startsWith('fc') || h.startsWith('fd')) return true; // link-local / ULA
+    // 6to4 (`2002:WWXX:YYZZ::/16`) embeds an IPv4 (W.X.Y.Z) in the first two
+    // hextets; a 6to4 relay routes to it (e.g. 2002:7f00:1:: → 127.0.0.1,
+    // 2002:a9fe:a9fe:: → 169.254.169.254). Decode and recheck the embedded v4.
+    const sixToFour = h.match(/^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4}):/);
+    if (sixToFour) {
+      const hi = parseInt(sixToFour[1], 16), lo = parseInt(sixToFour[2], 16);
+      return isBlockedSsrfHost(`${(hi >>> 8) & 255}.${hi & 255}.${(lo >>> 8) & 255}.${lo & 255}`);
+    }
     // NAT64 (`64:ff9b::a.b.c.d` / `64:ff9b::hhhh:hhhh`) embeds an IPv4 that a NAT64
     // gateway routes to — decode and recheck it like the IPv4-mapped form below.
     const nat64 = h.match(/^64:ff9b::(.+)$/);

src/tools/ssrf.ts

@@ -10545,3 +10545,35 @@ test('bash-guard: git branch/tag ref destruction prompts; read + create forms st
   assert.equal(safe('git tag -l'), true);
   assert.equal(safe('git tag v1.2.3'), true, 'creating a tag is safe');
 });
+
+// ─── Round-9: the 2 NEW classes from the 3.29.13 convergence verify ──────────
+test('bash-guard: brace expansion cannot smuggle a wallet-key read (4th obfuscation primitive)', async () => {
+  const { classifyBashRisk } = await import('../dist/agent/bash-guard.js');
+  const safe = (c) => classifyBashRisk(c).level === 'safe';
+  // `{~,}` tilde-expands while brace-splitting `.bloc{k,}run` / `.{session,}` so
+  // no char-literal `.blockrun`/`.session` survives — defeated all 3 guards at once.
+  for (const c of [
+    'cat {~,}/.bloc{k,}run/.{session,}',            // EVM key (critical)
+    'cat {~,}/.bloc{k,}run/.{solana-session,}',     // Solana key
+    'cat {~,}/.bloc{k,}run/.{solana-session-key2,}',
+    'grep -a . {~,}/.bloc{k,}run/.{session,}',      // reader-agnostic
+    'cut -c1-99 {~,}/.bloc{k,}run/.{session,}',
+    'cat ~/.bloc{j..l}run/.session',                // `..` range variant
+  ]) assert.equal(safe(c), false, `${c} must prompt`);
+  // A brace with no comma/range does not expand, and benign reads stay safe.
+  assert.equal(safe('cat README.md'), true);
+  assert.equal(safe('cat package.json'), true);
+});
+
+test('isBlockedSsrfHost blocks 6to4 IPv6 (2002::/16) embedding loopback/metadata', async () => {
+  const { isBlockedSsrfHost } = await import('../dist/tools/ssrf.js');
+  for (const h of [
+    '2002:7f00:1::',                                // → 127.0.0.1
+    '2002:a9fe:a9fe::',                             // → 169.254.169.254 (metadata)
+    '[2002:a9fe:a9fe::]',
+    '2002:c0a8:101::',                              // → 192.168.1.1
+  ]) assert.equal(isBlockedSsrfHost(h), true, `${h} must be blocked`);
+  // A genuinely public IPv6 (Cloudflare) and a 2002.* hostname stay allowed.
+  assert.equal(isBlockedSsrfHost('2606:4700::1111'), false);
+  assert.equal(isBlockedSsrfHost('2002:808:808::'), false, '2002:0808:0808 → 8.8.8.8 (public) allowed');
+});