Skip to content

fix(core): close 7 SSRF blind spots and align IP parsing across all layers - #13

Merged
mostafa merged 16 commits into
mainfrom
feat/ssrf-blind-spot-fixes
May 11, 2026
Merged

mostafa merged 16 commits into
mainfrom
feat/ssrf-blind-spot-fixes

Conversation

@mostafa

@mostafa mostafa commented May 11, 2026 •

Copy link
Copy Markdown
Member

Summary

Deep code analysis (cross-referenced against the OWASP SSRF Prevention Cheat Sheet, PortSwigger's SSRF guide, and 21+ research articles) identified 4 IP parsing inconsistencies and 7 concrete blind spots in the UriValidator / Policy / SafeConnector / RedirectValidator chain. This PR fixes every one and adds a two-tier verification suite that covers all known bypass techniques across all four supported language bindings.

Inconsistency fixes (IC-1..IC-4)

Every IP parsing site now goes through cidr::parse_ip (strict). Ambiguous forms (0177.0.0.1, 0x7f000001, 2130706433, 127.1) are no longer silently treated as DNS hostnames at the boundary.

ID Layer Before After
IC-1 cidr::is_ip_literal IpAddr::parse() parse_ip_strict + new is_ambiguous_ip companion
IC-2 uri_validator::parse_host_as_ip IpAddr::parse() cidr::parse_ip
IC-3 Policy::validate_all_hosts IpAddr::parse() cidr::parse_ip + ambiguous-IP rejection
IC-4 SafeConnector::connect IpAddr::parse() cidr::parse_ip + ambiguous-IP rejection

Blind-spot fixes (BS-1..BS-7)

All in crates/ressrf-core/src/uri_validator.rs unless noted. Two new DenyReason variants: AmbiguousIpEncoding, SchemeRequired.

ID Severity Bypass Fix
BS-1 HIGH Octal/hex/decimal/shorthand IPv4 hosts is_ambiguous_ip -> DenyReason::AmbiguousIpEncoding
BS-2 HIGH Scheme-less URLs (javascript:alert(1), data:..., http:host/path, bare hostnames) Pseudo-scheme detector + new DenyReason::SchemeRequired
BS-3 MEDIUM NUL/CRLF (raw and %00/%0d/%0a) parser-differential header injection has_prohibited_control_chars + host_has_prohibited_chars
BS-4 MEDIUM Trailing dot (metadata.google.internal.) bypasses suffix deny domain_matches_suffix strips trailing dot from both host and suffix
BS-5 MEDIUM Backslash confusion (http://127.0.0.1\@trusted.com/) \ normalized to / before authority extraction
BS-6 LOW UNC \\host\share URLs Explicit prefix rejection
BS-7 DESIGN RedirectValidator does not re-resolve DNS on hostname redirects Documented as a defense-in-depth design (TCP layer catches it)

Verification: Tier 1 + Tier 2

Tier 1 -- Shared JSON vectors (URL-level, no network):

  • tests/vectors/ssrf_techniques.json -- ~92 cases across 10 categories (IP representation, IPv6 notation, parser confusion, protocol smuggling, cloud metadata, Unicode/IDN, headers, plus controls)
  • Consumed by Rust (crates/ressrf-core/tests/ssrf_techniques.rs), Go (go/ressrf/ssrf_techniques_test.go), Python (python/tests/test_conformance.py::TestSsrfTechniques), Node (node/tests/conformance.test.ts)
  • The previously orphaned tests/vectors/redirect_chains.json is now wired into crates/ressrf-http/tests/redirect_chains.rs (12/12 passing)

Tier 2 -- testcontainers (network stack, Docker required):

  • tests/containers/coredns/ (Corefile + zone file) and tests/containers/wiremock/mappings/ (14 stubs)
  • crates/ressrf-tcp/tests/ssrf_e2e.rs spins up CoreDNS + WireMock via testcontainers-rs 0.27 behind a new e2e Cargo feature
  • 11 e2e tests cover: DNS-based attacks (wildcard-to-loopback, metadata alias, mixed public/private answers), DNS-rebinding TOCTOU pinning, redirect chains (private IP, IMDS, decimal-IMDS, IPv4-mapped IPv6 IMDS, gopher, file), and a combined redirect+DNS chain
  • New e2e-tests job in .github/workflows/ci.yml (Linux only, off by default so the multi-OS matrix stays hermetic; zizmor --pedantic clean)

Test plan

Local verification (Docker 29.4.2, macOS arm64):

  • cargo test --workspace -- 174+ tests, all green (122 lib + 5 url-validation + 92 ssrf_techniques + 12 redirect_chains + others)
  • cargo test --features e2e -p ressrf-tcp --test ssrf_e2e -- 11/11 in ~30s
  • cargo clippy --workspace --all-targets -- -D warnings -- clean
  • cargo fmt --all -- --check -- clean
  • bash go/ressrf/build_wasm.sh then go test ./... -- all green; 85/92 ssrf_techniques cases run (7 skipped because Go binding does not expose denied/trusted suffix knobs)
  • cd python && uv run --no-sync maturin develop --release then pytest -- 42 pass / 6 skipped / 0 fail
  • cd node && nvm use 22.22.1 && npm test -- 189/189 pass; new Conformance: SSRF Technique Vectors block is green
  • zizmor --pedantic .github/workflows/ci.yml -- 0 findings

CI plan after merge:

  • Existing multi-OS test-rust, test-go, test-python, test-node matrices remain hermetic and unaffected (no new dependencies in the default feature set).
  • New e2e-tests job runs on Ubuntu only, pulls coredns/coredns:1.11.3 and wiremock/wiremock:3.9.1, and runs cargo test --features e2e -p ressrf-tcp --test ssrf_e2e --locked.

Files

39 files, +4126 / -75. New shared assets under tests/, new test runners per language, new e2e Cargo feature gate on ressrf-tcp, rebuilt core.wasm so the Go and Node bindings pick up the new error variants and validator behavior.

mostafa and others added 16 commits May 11, 2026 18:24
Fixes 4 IP parsing inconsistencies and 7 SSRF bypass blind spots
identified by deep code analysis against the OWASP SSRF Prevention
Cheat Sheet, PortSwigger guide, and 21+ SSRF research articles.

Inconsistencies (IC-1..IC-4): every IP parsing site now uses
`cidr::parse_ip` (strict) instead of `IpAddr::parse()` (permissive),
so ambiguous forms like `0177.0.0.1`, `0x7f000001`, `2130706433`,
and `127.1` are detected at the boundary instead of silently
becoming DNS lookups.

Blind spots fixed in `UriValidator::validate_url` and
`parse_url_parts`:

- BS-1: ambiguous IPv4 encodings (octal/hex/decimal/shorthand)
  rejected with the new `DenyReason::AmbiguousIpEncoding`
- BS-2: scheme-less URLs (`javascript:alert(1)`, `data:...`,
  `http:host/path`, bare hostnames) rejected via
  `SchemeNotAllowed` or new `DenyReason::SchemeRequired`
- BS-3: NUL/CRLF (raw and percent-encoded `%00`/`%0d`/`%0a`)
  rejected to prevent parser-differential header injection
- BS-4: trailing dot stripped from host before suffix matching,
  so `metadata.google.internal.` cannot bypass a denied suffix
- BS-5: backslash normalized to `/` before authority extraction,
  so `http://127.0.0.1\@trusted.com/` resolves to `127.0.0.1` and
  is blocked by the bare-IP check
- BS-6: UNC-style `\\host\share` URLs explicitly rejected
- BS-7: documented that `RedirectValidator::validate_hop` does
  not re-resolve DNS by design and relies on the TCP-layer
  `SafeConnector` for the IP check

Also adds `cidr::is_ambiguous_ip()` companion to `is_ip_literal`
so callers can distinguish "this is a hostname" from "this looks
like an IP but in a non-canonical form".

All 122 unit tests + 5 integration tests pass; clippy clean
under `-D warnings` with workspace pedantic lints.
Comprehensive shared test vectors covering all 10 SSRF bypass
categories from the blind-spot plan. Each case feeds a crafted URL
through UriValidator + Policy and asserts blocked or allowed.

Categories covered:
- ip_representation: decimal, octal, hex, mixed, shorthand IPv4
- ipv6_notation: loopback variants, IPv4-mapped, IPv4-compatible,
  6to4, Teredo, NAT64, AWS IMDSv6 (fd00:ec2::254), link-local, ULA
- url_parser_confusion: userinfo @ bypass, backslash, no `//`, NUL,
  CRLF/LF, protocol-relative `//host` and `\\\\host`, case-varied
  schemes, fragments, trailing dots, bare hostnames
- protocol_smuggling: file, gopher, dict, sftp, tftp, ldap, jar,
  data, javascript, phar, smb, ftp, netdoc
- cloud_metadata: AWS IMDSv1/IPv6, GCP, K8s svc.cluster.local,
  Azure IMDS/Wireserver, AWS ECS, DigitalOcean, Oracle, Docker
  daemon, IMDS via mapped IPv6, plus RFC1918 and CGNAT
- unicode_idn: punycode allowed, non-punycode `--` rejected,
  documented fullwidth-Latin gap
- redirect_chains: placeholder for tier-2 e2e coverage
- control: canonical public URLs, ports, userinfo, suffix
  allowlist matches and boundary cases

Vectors are language-neutral and will be consumed by the upcoming
Rust integration runner plus the Go/Python/Node conformance tests.
New integration test `crates/ressrf-core/tests/ssrf_techniques.rs`
loads the shared vectors and runs each case through
`UriValidator::validate_url` with an `ExternalOnly` policy. Verifies
both the allowed/blocked decision and the optional `reason_type`
tag against the snake_case `DenyReason` discriminant.

Vector tweaks for runner correctness:
- `ipv4_compatible_loopback`: the deprecated `[::127.0.0.1]` form
  parses to `::7f00:1`, a public IPv6, not loopback. Marked as a
  documented gap (expected: allowed). Defense relies on the
  canonical IPv4-mapped form `[::ffff:127.0.0.1]`.
- `url_userinfo_percent_at_imds` / `url_userinfo_double_at`:
  with an `ExternalOnly` policy attached, the bare-IP IMDS check
  fires before the `%40` userinfo bypass detector. Reason updated
  to `bare_ip_denied_before_scheme`. Added a separate
  `url_userinfo_no_policy_imds`-style case targeting a public
  hostname so the userinfo-bypass path is still verified.

All 92 vectors pass; full workspace test suite (180+ tests) green;
clippy clean.
Sets up Tier 2 e2e infrastructure shared by all language bindings.

`tests/containers/coredns/`:
- `Corefile`: minimal CoreDNS config that authoritatively serves
  the synthetic `ssrf.test` zone.
- `ssrf.zone`: A records covering wildcard-to-internal, IMDS aliases,
  multi-answer mixed public/private, trailing-dot FQDN, and rebind
  helpers.

`tests/containers/wiremock/mappings/`: 14 stub-mapping JSON files
covering one redirect scenario each (302 to private IP, IMDS,
IPv6 loopback, IPv4-mapped-IPv6 IMDS, decimal-encoded IP, gopher,
file, scheme downgrade, 3-hop progressive, redirect to DNS alias,
allowed redirect, plus a baseline `/` 200 OK).

`tests/containers/README.md` documents the per-name resolution
table, per-endpoint redirect targets, and how each language's
runner mounts and consumes them.

`crates/ressrf-tcp/Cargo.toml`:
- New `e2e` feature pulling in `testcontainers` 0.27 and `reqwest`
  0.12 (rustls-tls only), plus the existing `hickory` feature so
  the e2e tests can point a custom resolver at the CoreDNS
  container.
- Default workspace build is unchanged; no testcontainers, reqwest,
  or hickory pulled into normal CI.

Verified `cargo check -p ressrf-tcp --features e2e` succeeds and
default `cargo build --workspace` is unaffected.
New `crates/ressrf-tcp/tests/ssrf_e2e.rs` (gated behind the `e2e`
feature) plus `tests/common/mod.rs` shared helpers. Spins up the
shared `CoreDNS` and `WireMock` containers and exercises bypass
techniques through the full network stack.

`ContainerDns`: hickory-resolver-based `DnsBackend` that points
at a custom `SocketAddr` (the mapped CoreDNS UDP port), built
with a single `NameServerConfig` whose `ConnectionConfig::port`
matches the container-mapped host port.

`coredns::start` / `wiremock::start`: container helpers that
mount `tests/containers/{coredns,wiremock}/` into the standard
container paths and wait for ready banners on stdout
(`CoreDNS-` and `port:` respectively).

Tests covered (all passing locally against Docker 29.4.2):
- DNS-based: wildcard-loopback, metadata-alias, multi-answer
  mixed public/private (verifies the all-resolved-IPs filter
  drops the private IP)
- DNS rebinding (TOCTOU): custom `DnsBackend` returns different
  IPs per call; asserts `SafeResolver` calls `resolve()` exactly
  once
- WireMock redirect chains: 302 to private IP, IMDS, decimal-IMDS,
  IPv4-mapped IPv6 IMDS, gopher, file scheme
- Combined: redirect target uses CoreDNS hostname that maps to
  loopback

`crates/ressrf-tcp/Cargo.toml`: adds `e2e` feature pulling in
`testcontainers = 0.27`, `reqwest = 0.12` (rustls-tls only),
plus the existing `hickory` feature; adds `ressrf-http` as a
dev-dep so the redirect-chain tests can use `RedirectValidator`
in-process. Default builds and CI matrix unaffected.

Verified: `cargo test --features e2e -p ressrf-tcp` -> 11/11
passing in 30s; default `cargo test --workspace` -> 160 tests
passing; clippy clean with workspace pedantic lints.
The shared `tests/vectors/redirect_chains.json` had 12 hand-curated
vectors but no automated consumer. New
`crates/ressrf-http/tests/redirect_chains.rs` walks each chain
through `RedirectValidator::validate_hop` (the same path real HTTP
clients hit on every 3xx response) and asserts the expected
allowed/blocked outcome and the hop index where blocking happens.

Vector schema preserved + extended:
- `chain[0]` is the origin URL; `chain[1..]` are redirect targets.
- `policy_preset`: `external_only` | `internal_only` | `none`.
- `allow_cidrs`: optional allow-list overrides (e.g. permit a
  specific RFC1918 range).
- `allow_plaintext_http` (new optional flag): when `true`, switches
  the policy to `ProtocolRules { allow_plaintext_http: true,
  require_https: false }`. Required for the
  `redirect_to_allowed_private_range` case which redirects to
  `http://10.42.x.x` after explicitly allowing that range.
- `max_redirects` semantics clarified: counts total URLs in the
  chain including the origin. The runner subtracts one before
  passing to `RedirectPolicy::follow` so a chain of N URLs with
  vector `max_redirects = N` is exactly at the limit.

12/12 redirect-chain vectors pass; full workspace test suite
(174 tests including the new one) green; clippy clean.

The same `redirect_chains.json` is also exercised end-to-end via
WireMock in `crates/ressrf-tcp/tests/ssrf_e2e.rs`, where the
validator's decision is verified against actual HTTP 302
responses.
`go/ressrf/ssrf_techniques_test.go` walks every URL in the shared
`tests/vectors/ssrf_techniques.json` through the WASM-backed
`Policy.IsAllowed` and asserts the expected allow/block decision.

Cases that require domain-suffix configuration (`denied_suffixes` /
`trusted_suffixes`) are skipped because the Go binding does not
currently expose those knobs. 85 of 92 vectors execute; 7 skipped
(suffix-config cases mirroring the existing TestURLValidation
pattern).

`go/ressrf/core.wasm` and `node/core.wasm` rebuilt via
`go/ressrf/build_wasm.sh` (1.19 MB after wasm-opt -Oz + strip)
so the new `DenyReason::SchemeRequired` and
`DenyReason::AmbiguousIpEncoding` variants surface through the
WASM ABI as their `Display` strings, and the BS-1..BS-6 fixes in
`UriValidator` are exercised end-to-end from Go.

Verified: `go test ./...` passes; new vector runner shows
`--- PASS:` for all 85 unskipped cases.
`tests/conftest.py` exposes a new `ssrf_techniques_vectors` fixture
loading the shared JSON file.

`tests/test_conformance.py` adds `TestSsrfTechniques` mirroring the
existing `TestUrlValidation` pattern: walks every vector through
the PyO3-backed `Policy.validate_url` and asserts the expected
allow/block decision. Cases requiring `denied_suffixes` /
`trusted_suffixes` are skipped because those configuration knobs
are not exposed on the Python `PolicyBuilder` surface.

Verified after rebuilding the PyO3 extension with
`maturin develop --release`: full suite 42 passed, 6 skipped, 0
failed (the new vector class accounts for 1 passing test
covering all 85 unskipped URL-level cases).
`node/tests/conformance.test.ts` gains a `Conformance: SSRF
Technique Vectors` describe block that walks every URL in the
shared `tests/vectors/ssrf_techniques.json` through the
WASM-backed `Policy.isAllowed` and asserts the expected
allow/block decision.

Each test name is `[<category>] <case-name>` so the per-category
breakdown surfaces in the node:test output. Cases that need
denied/trusted domain suffix configuration are skipped (mirroring
the existing `Conformance: URL Validation` block) since those
knobs are not exposed on the Node `PolicyBuilder` surface.

Verified: full Node test suite is 189 pass / 0 fail under Node
22.22.1; the new describe block reports `ok 7 - Conformance:
SSRF Technique Vectors`.
New `e2e-tests` job in `.github/workflows/ci.yml` runs the
testcontainers-based Tier 2 SSRF e2e suite added in
`crates/ressrf-tcp/tests/ssrf_e2e.rs`.

The job:
- runs on `ubuntu-latest` only because the GitHub-hosted macOS
  and Windows runners do not ship a Docker daemon
- pre-pulls `coredns/coredns:1.11.3` and `wiremock/wiremock:3.9.1`
  in a dedicated step to surface registry/network failures
  cleanly and avoid per-test pull races
- invokes `cargo test --features e2e -p ressrf-tcp --test ssrf_e2e
  --locked`; the `e2e` Cargo feature is off by default, so the
  existing multi-OS `test-rust` matrix stays hermetic and unaffected
- uses a separate `Swatinem/rust-cache` key (`e2e`) so the
  testcontainers + reqwest + hickory dependency tree does not
  pollute or invalidate the default-feature cache

Conventions:
- top-level `permissions: {}` already in place; per-job
  `contents: read` for checkout
- all actions pinned by full commit SHA with version comment
- `persist-credentials: false` on checkout

Verified: zizmor --pedantic clean (1 suppressed); YAML parses.
Previously, running the e2e suite on a workstation without a Docker
daemon (typical macOS / Windows dev machine) crashed every container-
backed test with `Client(Init(SocketNotFoundError("/var/run/docker.sock")))`.

`tests/common/mod.rs` now exposes:
- `can_run_linux_containers()` -- shells out to `docker info --format '{{.OSType}}'`
  and returns `true` only when the daemon is reachable AND serving
  Linux containers (Windows-container daemons cannot run our images)
- `skip_without_docker!()` macro (#[macro_export]) -- early-returns
  with an `eprintln!` notice when Docker is unavailable

Every test in `tests/ssrf_e2e.rs` that touches `coredns::start` or
`wiremock::start` now invokes `skip_without_docker!()` at the top.
The DNS-rebinding TOCTOU test is unaffected because it uses an
in-process `DnsBackend` and never opens a container.

Verified:
- with Docker running: 11/11 pass in ~32s (unchanged)
- with Docker daemon hidden (`PATH=/usr/bin:/bin cargo test ...`):
  11/11 pass; nine "Skipping: Docker with Linux container support
  is not available" notices print; only the two pure-Rust tests
  actually exercise the validator
- the CI `e2e-tests` job (Ubuntu with Docker installed) still runs
  every case as before; nothing in the workflow needed to change

Pattern follows the convention used in @RSigma's
`crates/rsigma-runtime/tests/nats_integration.rs`.
Three READMEs now describe the new test machinery added in this branch:

- `README.md` (root): the Testing section calls out the 92-case
  `ssrf_techniques.json` shared vector and the Tier 2 testcontainers
  suite (`cargo test --features e2e -p ressrf-tcp --test ssrf_e2e`).
  The CI/CD list gains a dedicated SSRF e2e bullet so contributors
  see the new Linux-only job at a glance.

- `HACKING.md`: shared-vector table gets a new `ssrf_techniques.json`
  row enumerating the bypass categories. A new "Tier 2 e2e tests
  (Docker required)" subsection points at `tests/containers/` and
  the `skip_without_docker!` macro pattern, so future contributors
  know exactly where to plug in new attack scenarios.

- `crates/ressrf-tcp/README.md`: feature-flag table documents the
  new `e2e` Cargo feature as internal (testcontainers + reqwest +
  hickory), explicitly noting it is not intended for downstream
  consumers.

No public-API surface changes -- only docs.
@mostafa
mostafa merged commit e268151 into main May 11, 2026
23 checks passed
@mostafa
mostafa deleted the feat/ssrf-blind-spot-fixes branch May 11, 2026 17:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant