bmad-plus 0.19.0 → 0.21.0

package/src/bmad-plus/packs/pack-seo/scripts/seo_fetch.py

@@ -3,7 +3,8 @@
 SEO Fetch — Secure HTTP page fetcher for SEO analysis.
 
 Features:
-- SSRF protection (blocks private/loopback/reserved IPs)
+- SSRF protection (blocks private/loopback/reserved IPs, re-checked on every
+  redirect hop, connection pinned to the validated address)
 - Multi-UA support (standard, Googlebot, GPTBot, ClaudeBot)
 - Redirect chain tracking
 - Cookie handling
@@ -16,12 +17,16 @@ License: MIT
 import argparse
 import ipaddress
 import json
+import os
 import socket
 import sys
+import time
 from urllib.parse import urljoin, urlparse
 
 try:
     import requests
+    from requests.adapters import DEFAULT_POOLBLOCK, HTTPAdapter
+    from urllib3 import PoolManager
 except ImportError:
     print("Error: requests library required. Install: pip install requests", file=sys.stderr)
     sys.exit(1)
@@ -61,10 +66,37 @@ DEFAULT_HEADERS = {
 
 # ── Security: SSRF Prevention ──────────────────────────────────────
 
+ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+# RFC 6052 well-known NAT64 prefix: the last 32 bits are the IPv4 host the
+# translator will reach, so the address is only as safe as that IPv4 host.
+_NAT64_PREFIX = ipaddress.ip_network("64:ff9b::/96")
+
+
+class UnsafeURLError(requests.exceptions.InvalidURL):
+    """A URL, or the address it resolves to, must never be fetched."""
+
+
 def _ip_is_blocked(ip: "ipaddress._BaseAddress") -> bool:
-    """Return True if an IP falls in any range that must never be reached."""
+    """Return True if an IP falls in any range that must never be reached.
+
+    Anything that is not globally routable is refused: private, loopback,
+    link-local (cloud metadata at 169.254.169.254), carrier-grade NAT
+    (100.64.0.0/10, e.g. Alibaba metadata at 100.100.100.200), documentation
+    and benchmarking ranges, multicast and reserved space. IPv6 forms that
+    embed an IPv4 destination are judged by that destination.
+    """
+    if ip.version == 6:
+        embedded = ip.ipv4_mapped
+        if embedded is None and ip in _NAT64_PREFIX:
+            embedded = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
+        if embedded is not None:
+            return _ip_is_blocked(embedded)
+        if ip.is_site_local:
+            return True
     return bool(
-        ip.is_private
+        not ip.is_global
+        or ip.is_private
         or ip.is_loopback
         or ip.is_reserved
         or ip.is_link_local
@@ -73,47 +105,152 @@ def _ip_is_blocked(ip: "ipaddress._BaseAddress") -> bool:
     )
 
 
-def is_safe_url(url: str) -> bool:
-    """Block requests to private, loopback, and reserved IP addresses.
+def check_url(url: str) -> str:
+    """Apply the URL-level rules and return the hostname, without resolving it.
 
-    Fails CLOSED: a missing host, a non-HTTP(S) scheme, a DNS resolution
-    error, or an unparseable/blocked address all cause the URL to be
-    rejected. Every resolved address (IPv4 and IPv6) must be public.
+    Fails CLOSED with UnsafeURLError: a scheme outside http/https, embedded
+    credentials, a missing host or an invalid port rejects the URL.
     """
     parsed = urlparse(url)
+    if parsed.scheme not in ALLOWED_SCHEMES:
+        raise UnsafeURLError(f"scheme not allowed: {parsed.scheme or '(none)'}")
+    # "user:pass@" would be sent as an Authorization header and makes
+    # "https://trusted.example@evil.example/" style URLs misleading.
+    if parsed.username is not None or parsed.password is not None:
+        raise UnsafeURLError("credentials in URL are not allowed")
     hostname = parsed.hostname
-
     if not hostname:
-        return False
+        raise UnsafeURLError("URL has no host")
+    try:
+        parsed.port
+    except ValueError:
+        raise UnsafeURLError("URL has an invalid port") from None
+    return hostname
 
-    if parsed.scheme not in ("http", "https"):
-        return False
 
+def resolve_public_address(hostname: str) -> str:
+    """Resolve a hostname and return the public address to connect to.
+
+    Fails CLOSED with UnsafeURLError on a DNS error or when any resolved
+    address (IPv4 or IPv6) is not public: every address the name resolves to
+    must be public, so the returned one is safe whichever the resolver would
+    have preferred.
+    """
     try:
-        # Resolve ALL IP addresses (IPv4 and IPv6) via getaddrinfo
         addrinfo = socket.getaddrinfo(hostname, None)
-    except socket.gaierror:
-        return False  # Fail closed: unresolvable host is treated as unsafe
-
-    if not addrinfo:
-        return False  # Fail closed: no addresses resolved
+    except (socket.gaierror, UnicodeError):
+        raise UnsafeURLError(f"cannot resolve host {hostname}") from None
 
+    addresses = []
     for entry in addrinfo:
-        ip_str = entry[4][0]  # sockaddr[0] contains the IP string
         try:
-            ip = ipaddress.ip_address(ip_str)
+            ip = ipaddress.ip_address(entry[4][0])
         except ValueError:
-            return False  # Fail closed: unparseable address
-        # IPv4-mapped IPv6 (::ffff:a.b.c.d) must be checked as its IPv4 form
-        mapped = getattr(ip, "ipv4_mapped", None)
-        if mapped is not None and _ip_is_blocked(mapped):
-            return False
+            raise UnsafeURLError(f"{hostname} resolved to an unparseable address") from None
         if _ip_is_blocked(ip):
-            return False
+            raise UnsafeURLError(f"{hostname} resolves to a private/internal address ({ip})")
+        addresses.append(ip)
+    if not addresses:
+        raise UnsafeURLError(f"cannot resolve host {hostname}")
+
+    # A pinned connection cannot fall back to another address, and IPv6 routes
+    # are often missing in containers and CI: prefer IPv4 on dual-stack hosts.
+    preferred = next((ip for ip in addresses if ip.version == 4), addresses[0])
+    return str(preferred)
+
 
+def resolve_target(url: str) -> "tuple[str, str]":
+    """Validate a URL and return ``(hostname, address)`` to connect to.
+
+    Combines check_url() and resolve_public_address(); see their rules.
+    """
+    hostname = check_url(url)
+    return hostname, resolve_public_address(hostname)
+
+
+def is_safe_url(url: str) -> bool:
+    """Return True when resolve_target() accepts the URL (see its rules)."""
+    try:
+        resolve_target(url)
+    except UnsafeURLError:
+        return False
     return True
 
 
+class _PinnedPoolManager(PoolManager):
+    """urllib3 pool manager that only opens pools on validated IP literals.
+
+    Every requests version reaches the network through
+    PoolManager.connection_from_host (directly, or via connection_from_url),
+    whatever adapter hook it calls first. Validating here, instead of in a
+    requests hook that has been renamed across releases, keeps the guard
+    closed on old and future requests versions alike.
+    """
+
+    def connection_from_host(self, host, port=None, scheme="http", pool_kwargs=None):
+        hostname = (host or "").strip("[]")
+        if not hostname:
+            raise UnsafeURLError("URL has no host")
+        address = resolve_public_address(hostname)
+        if scheme == "https":
+            pool_kwargs = dict(pool_kwargs or {})
+            pool_kwargs["server_hostname"] = hostname
+            pool_kwargs["assert_hostname"] = hostname
+        return super().connection_from_host(
+            address, port=port, scheme=scheme, pool_kwargs=pool_kwargs
+        )
+
+
+class PinnedAddressAdapter(HTTPAdapter):
+    """Transport adapter that connects to the exact address it validated.
+
+    A plain requests call resolves the host again when urllib3 opens the
+    socket, so a hostile DNS server can answer a public address to the SSRF
+    check and a private one to the connection (DNS rebinding). This adapter's
+    pool manager resolves and validates each host itself, then opens the
+    connection pool on that IP literal. The Host header, TLS SNI and the
+    certificate hostname check still use the original name, so HTTPS
+    verification is unchanged. Proxies are refused: a proxy would resolve the
+    name itself and bypass the pinned address.
+    """
+
+    def init_poolmanager(self, connections, maxsize, block=DEFAULT_POOLBLOCK, **pool_kwargs):
+        super().init_poolmanager(connections, maxsize, block, **pool_kwargs)
+        # Rebuild with the exact settings requests chose for this version.
+        self.poolmanager = _PinnedPoolManager(
+            num_pools=connections, **self.poolmanager.connection_pool_kw
+        )
+
+    def proxy_manager_for(self, proxy, **proxy_kwargs):
+        raise UnsafeURLError("proxies are not supported by the pinned transport")
+
+    def send(self, request, **kwargs):
+        check_url(request.url)
+        # urllib3 would derive Host from the pool's IP literal; keep the name.
+        if "Host" not in request.headers:
+            request.headers["Host"] = urlparse(request.url).netloc.rpartition("@")[2]
+        return super().send(request, **kwargs)
+
+
+def create_session() -> requests.Session:
+    """Build a requests session whose every connection is SSRF-checked and pinned.
+
+    Environment proxies and ~/.netrc credentials are ignored: a proxy defeats
+    address pinning and netrc would attach credentials to attacker-chosen hosts.
+    A custom CA bundle named by REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE (corporate
+    TLS inspection) is still honoured, since it does not weaken pinning.
+    """
+    session = requests.Session()
+    session.trust_env = False
+    ca_bundle = os.environ.get("REQUESTS_CA_BUNDLE") or os.environ.get("CURL_CA_BUNDLE")
+    if ca_bundle:
+        session.verify = ca_bundle
+    adapter = PinnedAddressAdapter()
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+    return session
+
+
 # ── Core Fetcher ───────────────────────────────────────────────────
 
 def fetch_page(
@@ -147,37 +284,24 @@ def fetch_page(
         url = f"https://{url}"
         parsed = urlparse(url)
 
-    if parsed.scheme not in ("http", "https"):
+    if parsed.scheme not in ALLOWED_SCHEMES:
         result["error"] = f"Invalid URL scheme: {parsed.scheme}"
         return result
 
-    # SSRF check
-    if not is_safe_url(url):
-        resolved = "unknown"
-        try:
-            # Use getaddrinfo for consistent multi-address resolution
-            addrinfo = socket.getaddrinfo(parsed.hostname, None)
-            resolved = ", ".join(set(entry[4][0] for entry in addrinfo))
-        except Exception:
-            pass
-        result["error"] = f"Blocked: URL resolves to private/internal IP ({resolved})"
-        return result
-
+    current_url = url
     try:
-        session = requests.Session()
+        session = create_session()
 
         headers = dict(DEFAULT_HEADERS)
         ua_string = USER_AGENTS.get(user_agent, user_agent)
         headers["User-Agent"] = ua_string
 
-        import time
         start = time.monotonic()
 
-        # Follow redirects manually so is_safe_url() runs on EVERY hop.
-        # Letting requests follow redirects internally would allow a
-        # public URL to redirect (302) to an internal/metadata endpoint
-        # (redirect-based SSRF), bypassing the initial check.
-        current_url = url
+        # Follow redirects manually so every hop goes back through the pinned
+        # adapter, which validates the target before connecting. Letting
+        # requests follow redirects internally would hide the hop count and
+        # the chain; the adapter still guards each connection either way.
         redirect_chain = []
         hops = 0
         response = None
@@ -198,19 +322,9 @@ def fetch_page(
                 break
 
             next_url = urljoin(current_url, location)
-            next_parsed = urlparse(next_url)
-
-            if next_parsed.scheme not in ("http", "https"):
-                result["error"] = (
-                    f"Blocked redirect to non-HTTP(S) scheme: {next_parsed.scheme}"
-                )
-                return result
-
-            # Re-validate the redirect target (blocks redirect-based SSRF)
-            if not is_safe_url(next_url):
-                result["error"] = (
-                    f"Blocked: redirect to private/internal URL ({next_url})"
-                )
+            next_scheme = urlparse(next_url).scheme
+            if next_scheme not in ALLOWED_SCHEMES:
+                result["error"] = f"Blocked redirect to non-HTTP(S) scheme: {next_scheme}"
                 return result
 
             hops += 1
@@ -221,6 +335,7 @@ def fetch_page(
             redirect_chain.append(
                 {"url": current_url, "status": response.status_code}
             )
+            response.close()
             current_url = next_url
 
         elapsed_ms = round((time.monotonic() - start) * 1000)
@@ -233,6 +348,11 @@ def fetch_page(
         result["response_time_ms"] = elapsed_ms
         result["redirect_chain"] = redirect_chain
 
+    except UnsafeURLError as e:
+        if current_url == url:
+            result["error"] = f"Blocked: {e}"
+        else:
+            result["error"] = f"Blocked: redirect to private/internal URL ({current_url}): {e}"
     except requests.exceptions.Timeout:
         result["error"] = f"Request timed out after {timeout}s"
     except requests.exceptions.TooManyRedirects:

package/src/bmad-plus/skills/bmad-plus-uat/ref/uat-results.schema.json

@@ -20,6 +20,7 @@
     "updatedAt": { "type": "string", "format": "date-time" },
     "finishedAt": { "type": ["string", "null"], "format": "date-time" },
     "overallNote": { "type": "string" },
+    "redactions": { "type": "integer", "minimum": 1, "description": "Credential-like values replaced by [REDACTED] in the notes before the run was written. Absent when nothing was replaced." },
     "carriedFrom": {
       "type": "object",
       "description": "Present when the page continued a run that answered another revision of the recipe. The rule is fixed: an answer travelled only when its line was identical (same step, same letter, same text); every other line was asked again. The earlier run is left untouched.",

package/tools/cli/bmad-plus-cli.js

@@ -128,8 +128,20 @@ for (const modulePath of [
   configured.action(command.action);
 }
 
+// Stdin is resumed above so prompts work on Windows. Once the command has settled
+// nothing reads it, and a resumed terminal would keep the process alive: the shell
+// never got its prompt back until Ctrl+C (0.20.0 acceptance run).
+function releaseStdin() {
+  if (!process.stdin.isTTY) return;
+  process.stdin.pause();
+  process.stdin.unref();
+}
+
 // Await asynchronous registry checks and updates before completing the CLI.
-program.parseAsync(process.argv).catch((error) => {
-  console.error(`BMAD+: ${error.message}`);
-  process.exitCode = 1;
-});
+program
+  .parseAsync(process.argv)
+  .catch((error) => {
+    console.error(`BMAD+: ${error.message}`);
+    process.exitCode = 1;
+  })
+  .finally(releaseStdin);