Skip to content

feat: add native Go port (go-native/) alongside wazero binding - #29

Merged
gonzaloserrano merged 17 commits into
mainfrom
gsr/add-native-go-port
May 27, 2026
Merged

gonzaloserrano merged 17 commits into
mainfrom
gsr/add-native-go-port

Conversation

@gonzaloserrano

@gonzaloserrano gonzaloserrano commented May 25, 2026 •

Copy link
Copy Markdown
Contributor

A downstream Go-only service needed in-app SSRF validation, so it adopted the WASM-backed binding shipped here at go/ressrf/. After a couple of production iterations the consuming team raised real friction: Rust↔WASM↔Go boundaries hide from pprof/delve, every fix needs the Rust toolchain in the PR pipeline, and 24/7 on-call wants the parser readable in Go. A native Go port was developed against the same 220+ JSON conformance vectors plus differential fuzz against the Rust WASM, then brought in-tree as a sibling to the wazero binding so both options live under one repo and one release cadence.

The integration itself is additive: the existing wazero binding at go/ressrf/ is unchanged at the API level (same import path, same core.wasm). The native port lives at the new go-native/ressrf/ slot with subpackages httpx/tcpx/sshx (only sshx pulls golang.org/x/crypto). Two small commits ride along to keep the new matrixed CI green: golang.org/x/crypto v0.51.0 → v0.52.0 in the wazero binding (5 pre-existing SSH CVEs that the per-PR govulncheck now surfaces) and astral-tokio-tar 0.6.1 → 0.6.2 in Cargo.lock (RUSTSEC-2026-0145, transitive via testcontainers in the e2e-feature suite).

Non-obvious context the diff doesn't show:

  • The doubled go-native/ressrf/ path is forced, not aesthetic. golangci-lint's goimports rejected a flat go-native/ package because its hyphenated tail doesn't match package ressrf — every self-import would have needed an explicit alias. Deepening the path so the tail matches the package name fixes that and parallels the wazero binding's go/ressrf/ layout.
  • The native port is wired to tests/vectors/ and crates/ressrf-core/config/ from the start, not vendored copies. The per-PR drift check the standalone repo carried is gone — one source of truth for both bindings.
  • The differential-fuzz harness in go-native/ressrf/internal/diff/ loads the WASM oracle directly from the wazero binding's go/ressrf/core.wasm. Any Rust-core change that breaks parser parity will fail the diffuzz job in the same PR that ships the change.
  • CI is matrixed where it makes sense (govulncheck across both modules) and split where the jobs do different things (test/lint/drift/fuzz are per-binding). Dependabot groups updates separately for each module so wazero and native dep bumps stay reviewable independently.

Verified locally: go test ./... green on both modules (207 + 418 tests), make fuzz-rust-regress replays the 4 persisted divergence fixtures cleanly, actionlint + zizmor pass on all four touched workflow files.

@gonzaloserrano
gonzaloserrano force-pushed the gsr/add-native-go-port branch from 99483ac to 7e76d03 Compare May 25, 2026 16:03
@CLAassistant

CLAassistant commented May 25, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@gonzaloserrano
gonzaloserrano force-pushed the gsr/add-native-go-port branch from 7e76d03 to cb202bf Compare May 25, 2026 16:05
@gonzaloserrano
gonzaloserrano force-pushed the gsr/add-native-go-port branch from 24c0805 to 36a1ace Compare May 26, 2026 10:19
mostafa

This comment was marked as outdated.

@mostafa
mostafa dismissed their stale review May 27, 2026 07:40

Need to check one more thing.

@mostafa mostafa left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome work! I left some comments, mostly minor.

There is one more thing that might need some attention, probably a design choice, but would be happy to know your thought on it.

Internal engine identifiers violate Go acronym casing
internal/engine/deny_reasons.go and error.go use UrlParseError, DnsEmptyResponse, UrlRuleDenied, PlaintextHttpDenied, DenyUrlRuleDenied, DenyDnsEmptyResponse, DenyAmbiguousIpEncoding, DenyInDenyCidr, etc. Go's convention is URL, DNS, HTTP, IP, CIDR, that are all caps. The public re-exports in deny_reasons.go (URLParseError = engine.UrlParseError, etc.) get this right and hide the internal naming from consumers, but the engine itself is consistently non-idiomatic. The current .golangci.yaml doesn't enable stylecheck or revive's var-naming rule so it doesn't fail CI. A pure rename (no behavior change) would tighten the Go-style claim in the README and stop the aliasing-with-renaming dance in the public package.

Comment thread go-native/ressrf/docs/how-it-works.html Resolved
Comment thread go-native/ressrf/README.md Resolved
Comment thread Cargo.lock Resolved
Comment thread go-native/ressrf/errors.go Resolved
Comment thread go-native/ressrf/policy.go Resolved
Comment thread .github/workflows/diffuzz.yml Resolved
Comment thread go-native/ressrf/go.mod Resolved
Comment thread README.md Resolved
Comment thread README.md Resolved
gonzaloserrano added a commit that referenced this pull request May 27, 2026
Mostafa's review batch. Eight items addressed; two deferred pending
his reply on the trade-off.

Quick fixes:
  - Reflow manually-wrapped paragraphs in README.md and
    go-native/ressrf/README.md so GitHub renders to viewport width.
  - Bump go-native's wazero v1.10.1 -> v1.11.0 to match the wazero
    binding's pin (one workspace, one version floor).
  - Drop continue-on-error from diffuzz.yml. The default is false,
    so the explicit value was noise; the comment block at the top
    of the workflow already documents that divergence findings
    fail the job.

Bug-shaped:
  - go-native/ressrf/policy.go: toBlockedError now resolves DenyReason
    via errors.As instead of a bare type assertion. A wrapped engine
    rejection (fmt.Errorf("...%w...")) used to fall through to Detail,
    silently dropping the typed Reason that downstream switch-on-Kind
    consumers depend on (e.g. tiger-connect's "blocked_by_policy"
    structured-log gate). errors.As preserves the chain.
  - go-native/ressrf/errors.go: removed the testing import. The package
    no longer pulls flag parsing + benchmark scaffolding into every
    consumer's production binary. DisableForTests moved to a new
    public ressrftest/ subpackage; the atomic bypass flag moved to
    internal/testbypass/ so both ressrf (Bypassed reader) and
    ressrftest (DisableForTests writer) share it without ressrf
    transitively importing testing. Three internal test call sites
    updated.

Internal-engine acronym rename (the "aliasing-with-renaming" cleanup
Mostafa flagged in the top-level review):
  - internal/engine/ identifiers renamed to Go-idiomatic acronym
    casing: UrlParseError -> URLParseError, DnsEmptyResponse ->
    DNSEmptyResponse, plus the Deny* and Tier* parallel families
    (DenyBareIpDeniedBeforeScheme -> DenyBareIPDeniedBeforeScheme,
    DenyInDenyCidr -> DenyInDenyCIDR, TierIana -> TierIANA,
    TierCloudAws -> TierCloudAWS, etc). 16 identifiers total across
    9 internal files plus the two _generated.go files.
  - DataTier.String() returns also updated to match the new casing
    ("IANA", "CSPMetadata", "CloudAWS", "CloudGCP"). These are
    diagnostic output only; not part of any wire format or
    cross-language conformance vector (verified).
  - Public deny_reasons.go aliases collapse from translation-mode
    (DenyURLParseError = engine.DenyUrlParseError) to pass-through
    (DenyURLParseError = engine.DenyURLParseError). Public API
    surface is byte-identical; the rename is purely internal.

Docs:
  - go-native/ressrf/docs/how-it-works.html ported to
    docs/how-it-works.md. README link updated. The original styled
    HTML lost its CSS-positioned pipeline diagrams in the conversion;
    they became simple arrow-text sentences, which read fine in any
    markdown renderer and are grep-able where the HTML wasn't.

Deferred (pending Mostafa's reply on the trade-off):
  - Cargo.lock revert of astral-tokio-tar 0.6.1 -> 0.6.2 (would
    re-red the cargo audit job here; RUSTSEC-2026-0145 is in
    testcontainers' transitive deps).
  - Differential-fuzz coverage extension to URL rules, audit, and
    WithBypassIPCheck. Mostafa marked it a "perfectly reasonable
    starting point", so this lands as a follow-up issue rather than
    in this PR.

Verified: 418 tests pass across 10 packages (the new internal/testbypass
and ressrftest packages are now counted in the test sweep); diff-fuzz
regression replay clean; actionlint + zizmor pass on the workflow
edit; regenerating internal/engine/*_generated.go from the workspace
config is idempotent under the renamed identifier set.
gonzaloserrano added a commit that referenced this pull request May 27, 2026
The previous diagram listed only the wazero binding under "Go" and
relied on a paragraph below to describe the native port. Mostafa
asked for the diagram itself to show the parallel pathway.

The native port now lives in a side panel attached to the main
pipeline. The panel makes three things visible at a glance:

  - Connected to ressrf-core at the *spec* level (shared JSON config
    and tests/vectors), not the *code* level — there is no Rust
    dependency or transitive WASM in the build path.
  - Sits outside the ressrf-wasm/ressrf-http/ressrf-ssh column
    because it does not pass through any of those crates.
  - Stays pinned to ressrf-core via the differential-fuzz harness,
    not by source-level inheritance.

The previous paragraph below the diagram collapsed to a one-liner
pointing at go-native/ressrf/ — the side panel now carries the
"what" and the one-liner carries the "why use it" (pprof/delve,
no Rust toolchain in PR pipeline).

Addresses #29 review comment r3309874897.
…nding

Imports the timescale/ressrf-go native Go port into the workspace so
Go-team consumers can pick up SSRF protection without a WASM runtime
or Rust toolchain in the build path. The wazero binding at go/ressrf/
keeps working unchanged for callers that prefer the shared Rust
engine.

Layout mirrors the wazero binding: module path is
github.com/timescale/ressrf/go-native/ressrf so the import-path tail
matches the package name (package ressrf), letting consumers write
ressrf.NewPolicy(...) without an explicit alias. The go-native/
parent answers "what kind of binding?"; ressrf/ answers "what does
it export?" — same shape as go/ressrf/ for the wazero variant.

Source: github.com/timescale/ressrf-go at the current HEAD, wired to
the workspace's canonical files from the start — no vendored copies
of the conformance vectors or the Rust-crate config. Excluded from
the import: .git/, .github/ (CI wiring is a follow-up), LICENSE
(parent repo's MIT covers it, matching go/ressrf, python, node),
go.sum (regenerated under the new module path).

Subpackages httpx, tcpx, sshx kept as separate packages so only sshx
callers pull golang.org/x/crypto. All 19 in-tree imports were
rewritten from github.com/timescale/ressrf-go to
github.com/timescale/ressrf/go-native/ressrf.

In-tree wiring (vs the standalone-repo arrangement):
  - internal/testvectors/ loads vectors from <repo-root>/tests/vectors/
    instead of carrying a copy
  - internal/cmd/gen-data + the go:generate directive in
    internal/engine/ip_ranges.go read from
    <repo-root>/crates/ressrf-core/config/ instead of a vendored copy
  - the standalone port's per-PR drift check disappears — there's only
    one source of truth for both vectors and config, shared with every
    other binding

golang.org/x/crypto pinned to v0.52.0 from the start (the standalone
repo was on v0.42.0 with 5 unpatched SSH CVEs flagged by govulncheck:
GO-2026-5013/5017/5018/5019/5020). v0.52.0 requires Go 1.25+, so the
module's go directive is 1.25.0; the wazero binding stays at 1.26.3.

Verified: go build, go vet, and 418 tests pass across 8 packages;
the diffuzz-tagged build also compiles; regenerating
ip_ranges_generated.go + cloud_generated.go from
crates/ressrf-core/config produces a byte-identical output (no drift).
The existing wazero binding under go/ressrf/ is untouched.

Follow-ups (separate commits):
  - rewire internal/diff/ to load the WASM oracle from the sibling
    wazero binding's go/ressrf/core.wasm
  - top-level README + HACKING entries documenting both bindings
  - CI jobs for the native port (test, lint, drift, fuzz, diffuzz)
The standalone port had to git-clone /tmp/ressrf and cargo-build the
WASM oracle on every `make fuzz-rust` (~30s first run, ~2-3s cached).
In-tree, the wazero binding at go/ressrf/ already ships the same
artifact, so the harness just opens that file directly via
runtime.Caller — no clone, no cargo, no actions/cache footprint.

  - internal/diff/oracle.go: default wasmPath resolves to
    <repo-root>/go/ressrf/core.wasm via runtime.Caller, making the
    harness CWD-independent (RESSRF_WASM_PATH still overrides).
    Imports also regrouped to satisfy goimports (stdlib above
    third-party with blank-line separator).
  - Makefile: dropped the _oracle target, RESSRF_RUST_REPO,
    RESSRF_RUST_DIR, and RESSRF_WASM_TARGET. fuzz-rust and
    fuzz-rust-regress no longer depend on a synchronisation step.
  - README: rewrote the "Differential fuzz vs the Rust oracle"
    section to describe the in-tree oracle (post-processed via
    wasm-opt + wasm-tools strip — the production artifact, not a
    raw cargo output).

Verified: make fuzz-rust-regress (deterministic replay of 4
persisted divergence fixtures) passes in 0.6s; a 5s live fuzz did
177k execs at ~30k/sec across 14 workers with zero divergences.
Now that the workspace ships two Go bindings, the docs need to make
both visible and explain when to pick which.

Top-level README:
  - packages table: add the go-native/ressrf/ row below the wazero row
  - architecture diagram: keep the existing ASCII intact, append a
    note describing the parallel native port
  - Quick Start: split the Go example into "Go (wazero, shared Rust
    engine)" + "Go (native)"
  - install table: two Go rows, distinct version requirements
  - Allow Lists / URL Rules: show wazero and native snippets
  - CI/CD bullet: both bindings + the differential-fuzz job
  - test commands: include both modules

HACKING.md:
  - Requirements: Go 1.25+ (native) / 1.26+ (wazero)
  - Building / linting / testing / benchmarking sections cover both
  - "Adding a new cloud provider" + "Adding a new language binding":
    the native port is now an explicit reference path; cloud-provider
    work in Go now also means regenerating
    go-native/ressrf/internal/engine/
  - Test-vector recipe: also add a Go test in go-native/ressrf/

go/ressrf/README.md (wazero binding): header note pointing at the
sibling native port for callers that don't want a WASM runtime.

Verified: both bindings still build and test clean.
Brings the standalone-repo CI coverage from timescale/ressrf-go in
tree alongside the wazero binding's existing jobs. Both Go modules
get equal protection without doubling the workflow file count.

ci.yml: three new jobs alongside the existing test-go / lint-go
(which keep covering go/ressrf):
  - test-go-native: multi-OS race-detected go test for go-native/ressrf/
  - lint-go-native: golangci-lint against the native module
  - generated-up-to-date: re-runs `go generate` and fails on diff,
    catching the case where someone edits crates/ressrf-core/config/
    without refreshing go-native/ressrf/internal/engine/*_generated.go

audit.yml: matrixed govulncheck across [go/ressrf, go-native/ressrf]
so a vulnerable transitive in either module fails the audit. Added
go-native/ressrf/go.mod + go.sum to the path triggers.

fuzz.yml: new fuzz-go-native matrix job (8 Go targets — ParseCIDR,
ParseCIDRLoose, IsAmbiguousIP, ValidateURL, Policy, URLRulesEvaluate,
GlobMatchHost, GlobMatchPath), shares the existing weekly Monday
03:00 trigger with the Rust cargo-fuzz job.

diffuzz.yml (new): native Go vs the in-tree WASM oracle. Materially
simpler than the standalone-repo version — no /tmp/ressrf clone, no
Rust toolchain install, no cargo cache, because the oracle is just
go/ressrf/core.wasm. Triggers on the union of paths that could
affect either side of the parser comparison, plus weekly Monday
04:00 (one hour after cargo-fuzz). continue-on-error: divergence
findings are informational, not blocking.

dependabot.yml: added /go-native/ressrf gomod entry alongside
/go/ressrf, with distinct group names (go-native-deps, go-wasm-deps)
so dependency PRs land separately and stay reviewable.

ressrf-go's update-data.yml is intentionally not ported — upstream's
existing IP-range refresh (update-ip-ranges.yml) is canonical and
the in-tree drift check (generated-up-to-date) makes a second monthly
refresh redundant.

Verified: actionlint and zizmor pass on all four workflow files.
govulncheck flagged 5 pre-existing SSH CVEs in the wazero binding's
golang.org/x/crypto/ssh dependency (pinned at v0.51.0 since before
this PR): GO-2026-5013 (byte arithmetic underflow / panic),
GO-2026-5017 (server deadlock on unexpected client response),
GO-2026-5018 (pathological RSA/DSA DoS), GO-2026-5019 (FIDO/U2F
security key bypass), GO-2026-5020 (infinite loop on large channel
writes).

These were already failing the daily govulncheck schedule on main,
but the matrixed audit job added in this PR makes them visible per-PR.
Fixing now to keep PR CI green; v0.52.0 patches all five and keeps
the wazero binding on the same x/crypto floor as the new go-native
sibling.

Verified: go test ./... on go/ressrf still passes (207 tests).
cargo audit (newly visible per-PR via the matrixed Security Audit
workflow this PR adds) flags RUSTSEC-2026-0145 "PAX Header
Desynchronization in astral-tokio-tar" — advisory dated 2026-05-18,
fixed in >=0.6.2. Pulled transitively via testcontainers 0.27.3
(used by the SSRF e2e tests under ressrf-tcp's `e2e` Cargo feature).

`cargo update -p astral-tokio-tar` lifts the lock to 0.6.2 within
the existing testcontainers constraint — no workspace-wide bump, no
direct dependency edits.

Verified: cargo check --workspace --all-features clean.
Mostafa's review batch. Eight items addressed; two deferred pending
his reply on the trade-off.

Quick fixes:
  - Reflow manually-wrapped paragraphs in README.md and
    go-native/ressrf/README.md so GitHub renders to viewport width.
  - Bump go-native's wazero v1.10.1 -> v1.11.0 to match the wazero
    binding's pin (one workspace, one version floor).
  - Drop continue-on-error from diffuzz.yml. The default is false,
    so the explicit value was noise; the comment block at the top
    of the workflow already documents that divergence findings
    fail the job.

Bug-shaped:
  - go-native/ressrf/policy.go: toBlockedError now resolves DenyReason
    via errors.As instead of a bare type assertion. A wrapped engine
    rejection (fmt.Errorf("...%w...")) used to fall through to Detail,
    silently dropping the typed Reason that downstream switch-on-Kind
    consumers depend on (e.g. tiger-connect's "blocked_by_policy"
    structured-log gate). errors.As preserves the chain.
  - go-native/ressrf/errors.go: removed the testing import. The package
    no longer pulls flag parsing + benchmark scaffolding into every
    consumer's production binary. DisableForTests moved to a new
    public ressrftest/ subpackage; the atomic bypass flag moved to
    internal/testbypass/ so both ressrf (Bypassed reader) and
    ressrftest (DisableForTests writer) share it without ressrf
    transitively importing testing. Three internal test call sites
    updated.

Internal-engine acronym rename (the "aliasing-with-renaming" cleanup
Mostafa flagged in the top-level review):
  - internal/engine/ identifiers renamed to Go-idiomatic acronym
    casing: UrlParseError -> URLParseError, DnsEmptyResponse ->
    DNSEmptyResponse, plus the Deny* and Tier* parallel families
    (DenyBareIpDeniedBeforeScheme -> DenyBareIPDeniedBeforeScheme,
    DenyInDenyCidr -> DenyInDenyCIDR, TierIana -> TierIANA,
    TierCloudAws -> TierCloudAWS, etc). 16 identifiers total across
    9 internal files plus the two _generated.go files.
  - DataTier.String() returns also updated to match the new casing
    ("IANA", "CSPMetadata", "CloudAWS", "CloudGCP"). These are
    diagnostic output only; not part of any wire format or
    cross-language conformance vector (verified).
  - Public deny_reasons.go aliases collapse from translation-mode
    (DenyURLParseError = engine.DenyUrlParseError) to pass-through
    (DenyURLParseError = engine.DenyURLParseError). Public API
    surface is byte-identical; the rename is purely internal.

Docs:
  - go-native/ressrf/docs/how-it-works.html ported to
    docs/how-it-works.md. README link updated. The original styled
    HTML lost its CSS-positioned pipeline diagrams in the conversion;
    they became simple arrow-text sentences, which read fine in any
    markdown renderer and are grep-able where the HTML wasn't.

Deferred (pending Mostafa's reply on the trade-off):
  - Cargo.lock revert of astral-tokio-tar 0.6.1 -> 0.6.2 (would
    re-red the cargo audit job here; RUSTSEC-2026-0145 is in
    testcontainers' transitive deps).
  - Differential-fuzz coverage extension to URL rules, audit, and
    WithBypassIPCheck. Mostafa marked it a "perfectly reasonable
    starting point", so this lands as a follow-up issue rather than
    in this PR.

Verified: 418 tests pass across 10 packages (the new internal/testbypass
and ressrftest packages are now counted in the test sweep); diff-fuzz
regression replay clean; actionlint + zizmor pass on the workflow
edit; regenerating internal/engine/*_generated.go from the workspace
config is idempotent under the renamed identifier set.
The previous diagram listed only the wazero binding under "Go" and
relied on a paragraph below to describe the native port. Mostafa
asked for the diagram itself to show the parallel pathway.

The native port now lives in a side panel attached to the main
pipeline. The panel makes three things visible at a glance:

  - Connected to ressrf-core at the *spec* level (shared JSON config
    and tests/vectors), not the *code* level — there is no Rust
    dependency or transitive WASM in the build path.
  - Sits outside the ressrf-wasm/ressrf-http/ressrf-ssh column
    because it does not pass through any of those crates.
  - Stays pinned to ressrf-core via the differential-fuzz harness,
    not by source-level inheritance.

The previous paragraph below the diagram collapsed to a one-liner
pointing at go-native/ressrf/ — the side panel now carries the
"what" and the one-liner carries the "why use it" (pprof/delve,
no Rust toolchain in PR pipeline).

Addresses #29 review comment r3309874897.
Mirrors the go-native fix (review comment r3309874897) on the
wazero binding. Mostafa explicitly noted: "I believe this should be
fixed in the WASM port as well."

go/ressrf/errors.go used to import the testing package directly to
host DisableForTests, which pulled flag parsing + benchmark
scaffolding into every production binary that imports the wazero
binding. The same shape as the go-native split now applies here:

  - go/ressrf/internal/testbypass/flag.go: holds the atomic.Bool
    that ressrf.Disabled() reads. No testing dependency.
  - go/ressrf/ressrftest/disable.go: holds DisableForTests(t).
    Imports testing; production code never reaches it.
  - go/ressrf/errors.go: drops the testing import; Disabled() now
    reads testbypass.Flag.

Three internal test files (policy_test.go, protocol_http_test.go,
protocol_tcp_test.go) updated to import ressrftest and call
ressrftest.DisableForTests(t). All package-ressrf-internal callers;
no external consumer changes needed (tiger-connect uses the native
binding, not the wazero one).

Verified: 207 tests pass across 3 packages (ressrf + the two new
sub-packages); go vet clean; testing import confirmed absent from
go/ressrf/errors.go.
The subpackage refactor (commits 82b4d98 + 9f09e4b) moved
DisableForTests out of the root package into ressrftest/, but the
READMEs in both bindings still showed the old `ressrf.DisableForTests(t)`
call. Consumers copy-pasting either snippet would hit
`undefined: ressrf.DisableForTests`.

Updates both READMEs to:
  - call `ressrftest.DisableForTests(t)`
  - include the import line
  - explain why the helper lives in a subpackage (so `testing` stays
    out of production binaries)

Wazero binding also gets a function-table update so the qualified
names match the rest of the doc.

Addresses td-code-review finding #4.
…enied

Commit 82b4d98 renamed 16 identifiers from non-idiomatic acronym
casing (Url→URL, Dns→DNS, Cidr→CIDR, etc.) but missed the type
PlaintextHttpDenied. The const DenyPlaintextHTTPDenied was renamed
correctly; the corresponding struct was not, leaving the kind ↔
reason pair inconsistent.

Also enable revive's var-naming rule in .golangci.yaml so a future
missed entry fails CI rather than slipping past manual sweep. This
was Mostafa's specific anti-regression suggestion in the top-level
review.

Verified: go build, go vet, 418 tests pass; grep for PlaintextHttp
returns zero; grep for other potentially non-idiomatic acronym
identifiers returns only a comment citing the Rust-side UrlRule
serde name (intentional, accurate).

Addresses td-code-review finding #5.
audit.go opened with `// Package ressrf provides SSRF protection
backed by a WASM policy engine`, copy-pasted from the wazero binding
when the native port was first imported. It was the only file in
go-native/ressrf/ carrying a package-level comment, so godoc and
pkg.go.dev would publish a description that directly contradicts the
README's "no WASM, no CGO" headline.

Move the canonical package doc to a dedicated doc.go so future
refactors of audit.go can't lose it, and describe what the native
port actually is: pure Go, validated against the shared JSON
conformance vectors, pinned to the Rust core via differential fuzz
rather than via Rust code.

Verified: `go doc github.com/timescale/ressrf/go-native/ressrf` now
shows the native engine description.

Addresses td-code-review finding #1.
net.SplitHostPort returns an error on a bracketed IPv6 literal that
is missing the port (e.g. "[::1]"). The fallback path used to set
host = addr literally, then net.JoinHostPort(host, "22") produced
"[[::1]]:22" — doubly-bracketed and unparseable by the network stack.

SSH dials to bracketed-IPv6 hosts without an explicit port silently
failed at the TCP layer with confusing address-format errors that
looked unrelated to user input. The policy gate never even ran
because the error fired before reaching it.

Strip enclosing brackets in the SplitHostPort fallback so the bare
IP reaches both the policy check and JoinHostPort cleanly.

Added TestSSHDialBracketedIPv6WithoutPort that dials "[::1]" and
asserts errors.Is(err, ressrf.ErrBlocked) — meaning the policy gate
fired (not a parser malformed-address error).

Verified: 5 sshx tests pass (4 prior + 1 new regression).

Addresses td-code-review finding #3.
setupPair was unconditionally skipping every fuzz subtest when
go/ressrf/core.wasm was absent. Reproduced locally: removing the
artifact and running `make fuzz-rust-regress` exited 0 with 116
SKIP lines including the 4 persisted divergence fixtures. The
diffuzz workflow's stated contract ("Divergence findings fail the
job: a fresh parser divergence blocks the merge that introduced
it") silently degraded to "absence of an oracle blocks nothing."

Add a CI-mode gate via RESSRF_REQUIRE_WASM=1 env var. The test
file reads the var and promotes the skip to a Fatal when set; the
diffuzz workflow exports it for the job. Developers running
`go test -tags diffuzz` locally without the env var still get the
skip with the build instruction.

Verified by reproducing the bug locally:
  - Without WASM + with env var: FAIL (the desired CI behavior)
  - Without WASM + without env var: still SKIPs (developer flow)

Addresses td-code-review finding #2.
Both bindings' DisableForTests register a t.Cleanup that flips the
testbypass.Flag back to false on test exit. No test verified the
re-enable actually fired — the single existing TestDisableForTests
in each binding only asserts bypass is active during a test.

A future refactor that drops the t.Cleanup line or swaps its order
with Store(true) would let bypass leak into every subsequent test
in the same package. Every "should be blocked" test in adjacent
tests would then silently pass regardless of the policy: an
order-dependent Heisenbug invisible until somebody reorders.

The nested-subtest shape is load-bearing — without it, the parent
test's Cleanup runs after the assertion and the test is meaningless.
Reproduced by removing the t.Cleanup line: the test FAILs at
"bypass leaked past subtest cleanup".

Both new tests live in ressrftest_test (black-box) so they exercise
the consumer-facing surface. The packages don't exist yet, so this
also creates them.

Addresses td-code-review finding #10.
A 601-line hand-styled HTML comparison page that lived in
go-native/ressrf/docs/ as porting-decision rationale during the
native-port standalone repo's life. It was imported as-is when the
port moved into this monorepo.

Two problems with keeping it:
  - It's in the package's docs/ directory, so pkg.go.dev and any
    repo browser sees a 601-line page about an unrelated upstream
    PR alongside the legitimate how-it-works walkthrough.
  - "PR #25" will close or merge; after that the comparison becomes
    orphan-context nobody will know is safe to delete.

The comparison's purpose was to justify the port. The port has
happened (merged into timescale/ressrf as the go-native binding);
future readers wanting "why a native port?" can read the
integration PR's description rather than a 601-line HTML page in
docs/. git history preserves the file for anyone who needs it.

No inbound references confirmed via grep across *.md / *.go / *.html
/ *.yml.

Addresses td-code-review finding #8.
The -out default `internal/engine` is relative to the current
working directory, not "relative to repo root" as the help string
claimed. A contributor running gen-data from the actual repo root
following the help text would write to <repo-root>/internal/engine/
which doesn't exist; if their shell auto-creates the dir, generated
files land in the wrong place while the engine package keeps stale
tables.

The doc comment at the top of main.go already says to run from
go-native/ressrf/, so the default does land in the right place when
the documented workflow is followed. The flag help just disagreed.

Addresses td-code-review finding #12.
@gonzaloserrano
gonzaloserrano force-pushed the gsr/add-native-go-port branch from 811e522 to 77ec1c4 Compare May 27, 2026 13:05
@gonzaloserrano
gonzaloserrano merged commit 47383bd into main May 27, 2026
31 checks passed
@gonzaloserrano
gonzaloserrano deleted the gsr/add-native-go-port branch May 27, 2026 13:27
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.

4 participants