Repository navigation
fix(core): close 7 SSRF blind spots and align IP parsing across all layers - #13
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/RedirectValidatorchain. 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.cidr::is_ip_literalIpAddr::parse()parse_ip_strict+ newis_ambiguous_ipcompanionuri_validator::parse_host_as_ipIpAddr::parse()cidr::parse_ipPolicy::validate_all_hostsIpAddr::parse()cidr::parse_ip+ ambiguous-IP rejectionSafeConnector::connectIpAddr::parse()cidr::parse_ip+ ambiguous-IP rejectionBlind-spot fixes (BS-1..BS-7)
All in
crates/ressrf-core/src/uri_validator.rsunless noted. Two newDenyReasonvariants:AmbiguousIpEncoding,SchemeRequired.is_ambiguous_ip->DenyReason::AmbiguousIpEncodingjavascript:alert(1),data:...,http:host/path, bare hostnames)DenyReason::SchemeRequired%00/%0d/%0a) parser-differential header injectionhas_prohibited_control_chars+host_has_prohibited_charsmetadata.google.internal.) bypasses suffix denydomain_matches_suffixstrips trailing dot from both host and suffixhttp://127.0.0.1\@trusted.com/)\normalized to/before authority extraction\\host\shareURLsRedirectValidatordoes not re-resolve DNS on hostname redirectsVerification: 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)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)tests/vectors/redirect_chains.jsonis now wired intocrates/ressrf-http/tests/redirect_chains.rs(12/12 passing)Tier 2 -- testcontainers (network stack, Docker required):
tests/containers/coredns/(Corefile + zone file) andtests/containers/wiremock/mappings/(14 stubs)crates/ressrf-tcp/tests/ssrf_e2e.rsspins up CoreDNS + WireMock viatestcontainers-rs0.27 behind a newe2eCargo featuree2e-testsjob in.github/workflows/ci.yml(Linux only, off by default so the multi-OS matrix stays hermetic; zizmor--pedanticclean)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 ~30scargo clippy --workspace --all-targets -- -D warnings-- cleancargo fmt --all -- --check-- cleanbash go/ressrf/build_wasm.shthengo 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 --releasethenpytest-- 42 pass / 6 skipped / 0 failcd node && nvm use 22.22.1 && npm test-- 189/189 pass; newConformance: SSRF Technique Vectorsblock is greenzizmor --pedantic .github/workflows/ci.yml-- 0 findingsCI plan after merge:
test-rust,test-go,test-python,test-nodematrices remain hermetic and unaffected (no new dependencies in the default feature set).e2e-testsjob runs on Ubuntu only, pullscoredns/coredns:1.11.3andwiremock/wiremock:3.9.1, and runscargo 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, newe2eCargo feature gate onressrf-tcp, rebuiltcore.wasmso the Go and Node bindings pick up the new error variants and validator behavior.