Skip to content

docs(examples): add regex-allowlist credential-leak example + index-page link#23

Merged
chad-loder merged 1 commit into
mainfrom
docs/avoid-regex-vuln-example
May 13, 2026
Merged

docs(examples): add regex-allowlist credential-leak example + index-page link#23
chad-loder merged 1 commit into
mainfrom
docs/avoid-regex-vuln-example

Conversation

@chad-loder
Copy link
Copy Markdown
Owner

Summary

  • Adds a new worked example, Avoid regex hostname-allowlist credential leaks (docs/examples/avoid-regex-hostname-allowlist-vulns.md), explaining the textbook URL-allowlist regex bug and the URLPattern fix.
  • Adds a sly hyperlink on the docs home page (docs/index.md) pointing security-curious readers at the seed invoke-ai/InvokeAI#7518.
  • Wires the new page into the Examples index (docs/examples/index.md — new "Security" section) and the site nav (properdocs.yml).

Why this example matters

invoke-ai/InvokeAI#7518 is an open issue on a ~26k★ Python AI project that surfaces a concrete credential-leak scenario:

remote_api_tokens:
  - url_regex: 'private.example'
    token: 'secret'

The intent reads cleanly — "attach secret when calling private.example." But re.search finds the regex source anywhere in the URL string, and a URL is not a flat character sequence, so two attacker-controlled URL shapes also match:

  1. https://malicious.example/private.example/theft.safetensors  ·  path-segment fallthrough
  2. https://private.example.malicious.example/theft.safetensors  ·  subdomain shadowing

The example walks through both attack shapes, the component-aware URLPattern fix, and the "host or any subdomain" variant via {:subdomain.}*private.example.

What this PR changes

File Change
docs/examples/avoid-regex-hostname-allowlist-vulns.md new — full worked example
docs/examples/index.md adds Security section pointing at the new page
properdocs.yml nav entry under Examples (alongside the webhook-shape validator)
docs/index.md one extra clause closing the "differentiator" paragraph: [hand-rolled regexes for URL allowlists are routinely error-prone](...) linking to the InvokeAI issue

Test plan

  • just docs — strict-mode build green (no broken links, nav consistent)
  • just lint — all tools green (ruff, mypy, pyright, ty, semgrep, shellcheck, rumdl, codespell, interrogate, validate-pyproject)
  • Signed commit (ED25519)

No code changes; docs only.

…age link

Adds a new worked example explaining why hand-rolled regexes are the wrong
tool for hostname allowlists, why URLPattern is the textbook fix, and how
to spell the common "host or any subdomain" policy as a component-aware
pattern rather than a regex tweak.

The canonical case is invoke-ai/InvokeAI#7518: a configuration field
where each trusted upstream gets a regex paired with a credential. The
naive entry ``url_regex: 'private.example'`` leaks the secret when the
client visits either of two attacker-controlled URL shapes:

  - https://malicious.example/private.example/theft.safetensors
    (path-segment fallthrough; re.search finds the literal anywhere)
  - https://private.example.malicious.example/theft.safetensors
    (subdomain shadowing; the legitimate label sits inside the attacker's host)

A component-aware URLPattern matches the hostname *as the hostname*; it
cannot be tricked into accepting a path segment or a label-of-attacker's-host
that happens to spell the same text.

Wires the new page into:

  - docs/examples/index.md under a new "Security" section
  - properdocs.yml nav (alongside the webhook-shape validator)
  - docs/index.md home page — a sly inline note that hand-rolled regex
    URL allowlists are routinely error-prone, linking to the seed
    InvokeAI issue. The differentiator paragraph now closes with one
    extra clause that points security-curious readers at the example.

No code changes; docs only. ``just docs`` builds clean in strict mode.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 13, 2026
@chad-loder chad-loder enabled auto-merge (squash) May 13, 2026 03:59
@chad-loder chad-loder merged commit cc35b06 into main May 13, 2026
11 checks passed
@chad-loder chad-loder deleted the docs/avoid-regex-vuln-example branch May 13, 2026 04:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant