Skip to content

fix(edge,tls,docs): SEC2-07 hardening quick wins and wording sweep - #647

Open
cuioss-oliver wants to merge 12 commits into
mainfrom
feature/sec2-07-hardening-quick-wins
Open

cuioss-oliver wants to merge 12 commits into
mainfrom
feature/sec2-07-hardening-quick-wins

Conversation

@cuioss-oliver

@cuioss-oliver cuioss-oliver commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Hardening quick wins and a documentation sweep from the security-hardening-tier-2 epic (PLAN-SEC2-07): the passthrough audit record now carries the matched SNI key, the management listener has a 32 KiB request-body bound, a new boot warning covers two configuration combinations behind the SNI front, and every restated statement in documents and Javadoc that disagreed with the code was corrected in one commit.

Intent

Problem. A re-review of the epic's open observations found a handful of small, low-risk gaps on main: the passthrough relay logged the raw client-supplied server name although the route had matched on the normalized key; the management listener buffered request bodies up to the 10 MiB default although no management route takes a body; two configuration combinations behind the SNI front change what source detection and the trusted-proxy judgement see, with no warning at boot; and a number of statements in documents, ADRs and Javadoc no longer matched the code.

Approach. Each behaviour change is the smallest fix, test-first, with a matched control: the normalized key is passed to the relay; the management body bound is a fixed 32K with its reason stated beside the key; the boot rule only warns and adds no configuration key. The wording corrections were listed first, read against the code, and applied together in one commit so a statement restated in several documents changed everywhere at once.

Non-goals. No change to the front's connection cap or the existing per-source shares, no new refusal reason, and no behaviour change beyond the three named above. The optional per-source bound on a passthrough target's dial budget was dropped at outline because it needs more than a constant and a map.

Changes

  • Passthrough audit record (SniFrontListener, PassthroughRelay, SniFrontListenerTest): the route passes the normalized matched key to the relay, so the INFO record names the configured host and not the raw client-supplied name.
  • Management listener body bound (application.properties, EdgeHardeningOptions, ManagementListenerTransportTest, ShippedApplicationPropertiesTest, ManagementBodyBoundIT, LocalStackTls): quarkus.management.limits.max-body-size=32K, shown on a live listener (413 one byte past the bound, 200 at the bound, every probe route still answers) and on the native image.
  • Boot warning ApiSheriff-152 (EdgeRules, ConfigValidator, ConfigLogMessages, EdgeRulesTest, doc/LogMessages.adoc, doc/configuration/security-and-edge-hardening.adoc, doc/development/boot-validation-rules.adoc): a warning when tls.passthrough_sni is combined with an acting enumeration_detection.action or a loopback forwarded.trusted_proxies entry; silent otherwise, no new configuration key.
  • One wording sweep (documents, ADR-0003, ADR-0043, ADR-0076, ADR-0078, threat model, SealedSessionCookieCodec, CsrfDefence, ConnectionCapAudit, ApiSheriffLogMessages, the compose sample idp.yaml): each statement was read against the code it describes and corrected where they disagreed; the sweep is a single commit.

Test Plan

  • verify -Ppre-commit (quality gate) and the whole-tree test run green on the final tree
  • verify -Pintegration-tests -Dit.test=ManagementBodyBoundIT,TlsPassthroughIT green on the native image (4 and 6 tests)
  • Each behaviour change started with a test that failed against the unfixed code (padded SNI names, body above the bound, the boot warning rule with matched controls)

Related Issues

None.

Summary by CodeRabbit

  • New Features
    • Startup now warns when TLS passthrough is combined with detection actions or trusted-proxy settings that can cause clients to share a source identity.
  • Bug Fixes
    • Passthrough routing and audit labels now consistently use the normalized hostname.
    • Refusal logs now identify whether a connection was refused at acceptance or during route selection.
    • The management interface now limits request bodies to 32 KiB.
  • Documentation
    • Clarified connection limits, source attribution, management-interface limits, and TLS trust-root replacement guidance.
    • Added guidance on securing access to the internal HTTPS listener and clarified trusted-navigation checks for logout.

cuioss-oliver and others added 6 commits November 20, 2026 18:16
…llo value

SniFrontListener now normalizes the ClientHello server name once and hands
that key - the passthrough_sni host as configured, lower-cased - to the relay
as its audit label, so a client can no longer write its own whitespace or
line breaks into the INFO PASSTHROUGH_RELAY_ESTABLISHED record. The
PassthroughRelay Javadoc states the label contract.

SniFrontListenerTest proves it: a server name padded with whitespace
including CR and LF still routes to the passthrough backend and is audited
under the configured host, with an exact host as the matched control.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
No management route reads a request body, yet the body handler on every
management route buffered up to the 10 MiB Quarkus default. The shipped
application.properties now sets quarkus.management.limits.max-body-size=32K:
the smallest power of two above every body the form limits (2 KiB attribute,
1 KiB buffered bytes) and the 8 KiB chunk bound (observed with a 16 KiB
chunk) must see to answer on their own terms, so it pre-empts none of their
400s. The bound is fixed, not configurable.

ManagementListenerTransportTest refuses a declared body one byte past 32 KiB
with 413, serves exactly 32 KiB, and serves a body-less GET on every probe
route; ShippedApplicationPropertiesTest pins the key. The EdgeHardeningOptions
Javadoc, the threat model and the TLS architecture document state the
shipped bound.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
…t onto the relay leg

Behind the SNI front every terminated connection reaches the edge from the
loopback relay leg, so source detection and the trusted-proxy judgement see
every terminated client as one loopback peer. The new boot rule
EdgeRules.validatePassthroughSourceCollapse, registered in
ConfigValidator.DEFAULT_RULES, emits WARN ApiSheriff-152 once per present
combination under a non-empty tls.passthrough_sni: enumeration_detection
enabled with block or delay (the action then acts on every terminated client
at once), and a forwarded.trusted_proxies range overlapping 127.0.0.0/8 or
containing ::1 (every client's forwarded headers are then trusted). The record
names the combination by a fixed token, never a range or address; it never
refuses the boot.

EdgeRulesTest proves each combination warns and all six matched controls stay
silent. LogMessages.adoc, the edge-hardening configuration reference and the
boot-validation concern map describe the rule.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
…their restatements

Correct every listed statement the code contradicts, with its restatements,
in one sweep:

- connection cap: counted only once a connection is established (after its
  TLS handshake on the HTTPS listener), one counter for the redirect and
  HTTPS listeners, no per-source share, not bounded by the SNI front
- internal HTTPS port: binds 0.0.0.0 per Dockerfile.native, with the
  container-network consequence
- unresolvable forwarded chain: one unresolved-via source per proxy, shared
  by every client behind it (ADR-0003, ADR-0076, threat model, ADR-0078)
- BFF-02: the pending-authorization record is server-held and single-use in
  both session modes
- ApiSheriff-146: the template places a dial_budget refusal at the route
  decision, not at accept
- ADR-0043 / SealedSessionCookieCodec: only the access token is always
  fresh, the ID token can repeat, the active scope set is replaced, and the
  scope names are those the identity provider returns
- mTLS revocation removes every certificate of the chain; idp.yaml routes
  are segment-prefix routes; the logout proof's Sec-Fetch-Site: none
  statement carries the no-Origin qualifier; BFF-09 lists every
  speculative-load marker

Co-Authored-By: plan-marshall <noreply@cuioss.de>
ManagementBodyBoundIT exchanges raw HTTP/1.1 over TLS with the compose
stack's management port: a declared body one byte past 32 KiB to the
liveness probe is refused 413, a body of exactly 32 KiB is served, and
every probe route answers a body-less GET with 200. LocalStackTls now
exposes its trust-all context so the raw-socket IT reuses it.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
…r-free and gate-formatted

The quality gate flagged the string concatenation inside the ApiSheriff-152 warn call; build the token in a local first. Also accept the formatter's indentation of two continuation lines in files this branch authored.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
@sourcery-ai

sourcery-ai Bot commented Nov 20, 2026

Copy link
Copy Markdown

Sorry @cuioss-oliver, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 19 hours and 9 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

The changes add boot warnings for passthrough source-collapse configurations, set the management request-body limit to 32 KiB, and use normalized SNI values for passthrough routing labels. They also update refusal logging and document connection-cap, session, TLS, and endpoint behavior.

Changes: Passthrough source-collapse validation

Layer / File(s) Summary
Source-collapse warning
api-sheriff/src/main/java/de/cuioss/sheriff/gateway/config/..., api-sheriff/src/test/java/de/cuioss/sheriff/gateway/config/..., doc/LogMessages.adoc, doc/configuration/security-and-edge-hardening.adoc, doc/development/boot-validation-rules.adoc
Boot validation warns when passthrough SNI is combined with an acting detection action or a trusted-proxy range that overlaps loopback. Tests cover qualifying and control cases.
Forwarded-source attribution
doc/adr/0003-forwarded-headers.adoc, doc/adr/0076-One_per-source_detection_substrate_counts_pre-trust_rejections_and_answers_a_tripped_source.adoc, doc/adr/0078-Per-source_threat_classification_raises_one_ECS_alert_per_episode_from_its_own_ledger.adoc, doc/security-threat-model.adoc
The documentation describes canonical proxy source keys, IPv4 and IPv6 keying, and enforcement by source and folded host.

Management listener body limit

Layer / File(s) Summary
Configure and verify the body limit
api-sheriff/src/main/java/de/cuioss/sheriff/gateway/edge/admission/EdgeHardeningOptions.java, api-sheriff/src/main/resources/application.properties, api-sheriff/src/test/java/de/cuioss/sheriff/gateway/quarkus/*, doc/architecture/tls-and-inbound-security.adoc, doc/security-threat-model.adoc, integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/*
The management listener uses a 32 KiB body limit. Tests check the configured property, the size boundary, body-less probe routes, and listener responses.

Connection-cap behavior

Layer / File(s) Summary
Connection-cap accounting
api-sheriff/src/main/java/de/cuioss/sheriff/gateway/config/ConfigLogMessages.java, api-sheriff/src/main/java/de/cuioss/sheriff/gateway/edge/admission/ConnectionCapAudit.java, api-sheriff/src/main/resources/application.properties, doc/architecture/tls-and-inbound-security.adoc, doc/configuration/security-and-edge-hardening.adoc, doc/security-threat-model.adoc, doc/user/edge-security.adoc
Comments and documentation state that HTTPS connections count after the TLS handshake and hold a slot until closure. They describe the shared cap and the passthrough front’s separate scope.

SNI routing and refusal logs

Layer / File(s) Summary
Refusal stages and warning records
api-sheriff/src/main/java/de/cuioss/sheriff/gateway/ApiSheriffLogMessages.java, api-sheriff/src/main/java/de/cuioss/sheriff/gateway/tls/SniFrontListener.java, api-sheriff/src/test/java/de/cuioss/sheriff/gateway/tls/SniFrontListenerTest.java, doc/LogMessages.adoc, doc/development/tls-edge.adoc
Refusal records include a stage. Tests and documentation distinguish accept-time cap and source-share refusals from route-decision dial-budget refusals.
Normalized passthrough routing
api-sheriff/src/main/java/de/cuioss/sheriff/gateway/tls/PassthroughRelay.java, api-sheriff/src/main/java/de/cuioss/sheriff/gateway/tls/SniFrontListener.java, api-sheriff/src/test/java/de/cuioss/sheriff/gateway/tls/SniFrontListenerTest.java
Passthrough lookup and relay labeling use the normalized SNI key. Tests check audit labels for padded and exact SNI values.

Security and session documentation

Layer / File(s) Summary
Session and navigation behavior
api-sheriff/src/main/java/de/cuioss/sheriff/gateway/bff/cookie/SealedSessionCookieCodec.java, api-sheriff/src/main/java/de/cuioss/sheriff/gateway/bff/csrf/CsrfDefence.java, doc/adr/0043-Compress-then-encrypt_in_the_sealed_session_cookie_and_the_CRIME_BREACH_discriminator.adoc, doc/security-threat-model.adoc, doc/variants/03-bff-cookie.adoc, doc/LogMessages.adoc
The documentation describes refresh scope replacement, possible repeated ID tokens, navigation and prefetch signals, pending authorization storage, and logout revocation behavior.
Security and TLS documentation
doc/development/tls-edge.adoc, doc/user/tls-edge.adoc, doc/user/environment-variable-overrides.adoc, doc/LogMessages.adoc
The documentation describes internal listener reachability, certificate trust-bundle guidance, and additional warning and error records.

Identity-provider endpoint comments

Layer / File(s) Summary
Endpoint prefix matching
deployment/compose-sample/docker/sheriff-config-auth-fronted/endpoints/idp.yaml
The comments distinguish subpaths beneath a listed prefix from paths with an extra character after the prefix.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Merge Risk: Low · up to b4519

The code changes look sound, but several documents misstate port configuration, delay enforcement and forwarded-chain behavior, and a few earlier minor concerns remain open. Fix the documentation before merging; there is no runtime risk from these items.

Pre-merge checks: Passed 2

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the three areas the PR touches (edge, tls, docs) and the SEC2-07 tag, but it does not name the main behavior changes. Those are the passthrough audit key now using the normalized confi…
Full details: Title check

Explanation

The title names the three areas the PR touches (edge, tls, docs) and the SEC2-07 tag, but it does not name the main behavior changes. Those are the passthrough audit key now using the normalized configured SNI host, the management body limit lowered to 32K, and the new ApiSheriff-152 boot warning. The title is broad and partly generic. It is related to the changeset, so it is not a fail.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 9

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Central YAML; Path: .coderabbit.yaml
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 2e328ef2-8829-4c8c-b079-a77280b401b5
Commits

Reviewing files that changed from the base of the PR and between 79c415e and 6015b5c.

Files selected for processing: 31

  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/ApiSheriffLogMessages.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/bff/cookie/SealedSessionCookieCodec.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/bff/csrf/CsrfDefence.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/config/ConfigLogMessages.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/config/validation/ConfigValidator.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/config/validation/rule/EdgeRules.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/edge/admission/ConnectionCapAudit.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/edge/admission/EdgeHardeningOptions.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/tls/PassthroughRelay.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/tls/SniFrontListener.java
  • api-sheriff/src/main/resources/application.properties
  • api-sheriff/src/test/java/de/cuioss/sheriff/gateway/config/validation/rule/EdgeRulesTest.java
  • api-sheriff/src/test/java/de/cuioss/sheriff/gateway/quarkus/ManagementListenerTransportTest.java
  • api-sheriff/src/test/java/de/cuioss/sheriff/gateway/quarkus/ShippedApplicationPropertiesTest.java
  • api-sheriff/src/test/java/de/cuioss/sheriff/gateway/tls/SniFrontListenerTest.java
  • deployment/compose-sample/docker/sheriff-config-auth-fronted/endpoints/idp.yaml
  • doc/LogMessages.adoc
  • doc/adr/0003-forwarded-headers.adoc
  • doc/adr/0043-Compress-then-encrypt_in_the_sealed_session_cookie_and_the_CRIME_BREACH_discriminator.adoc
  • doc/adr/0076-One_per-source_detection_substrate_counts_pre-trust_rejections_and_answers_a_tripped_source.adoc
  • doc/adr/0078-Per-source_threat_classification_raises_one_ECS_alert_per_episode_from_its_own_ledger.adoc
  • doc/architecture/tls-and-inbound-security.adoc
  • doc/configuration/security-and-edge-hardening.adoc
  • doc/development/boot-validation-rules.adoc
  • doc/development/tls-edge.adoc
  • doc/security-threat-model.adoc
  • doc/user/edge-security.adoc
  • doc/user/tls-edge.adoc
  • doc/variants/03-bff-cookie.adoc
  • integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/LocalStackTls.java
  • integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/ManagementBodyBoundIT.java

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

}

@ParameterizedTest(name = "GET {0}")
@ValueSource(strings = {"health", "health/live", "health/ready", "health/started", "metrics"})

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Functional Correctness · Quick win

Derive the probe cases from the registered routes.

This list already omits health/group and health/well, which SmallRyeHealthProcessor.defineHealthRoutes registers from SmallRyeHealthBuildTimeConfig. The native test repeats the same incomplete list at Line 88. Both tests can therefore pass without checking every probe route. (raw.githubusercontent.com)

Derive the concrete probe inventory from the route registrations at build or test runtime. Use that inventory in both tests instead of extending two manual lists.

As per path instructions, “Treat a hardcoded list that must mirror a set defined elsewhere … as a defect unless it is derived from that source at build or run time.”

Source: Path instructions

Comment thread doc/adr/0003-forwarded-headers.adoc Resolved
Comment thread doc/adr/0003-forwarded-headers.adoc Resolved
Comment thread doc/user/tls-edge.adoc Outdated
because every certificate in the bundle is an anchor. A cross-certificate is another: if a remaining
root has cross-signed the removed root or one of its intermediates, a client that presents that
cross-certificate can still complete the handshake. Before relying on the cut-off, make sure no
certificate left in the file certifies the removed one or belongs to its chain, and confirm the

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Security & Privacy · Quick win

The emergency cut-off text does not say how to handle a cross-certificate that a remaining root issues for the removed root's intermediate.

The bundle is a trust-anchor set, and each anchor is trusted directly. The text at doc/user/tls-edge.adoc:386-395 explains that a remaining intermediate or cross-certificate can keep a path to the removed root. It tells operators to check the file, and then to test with a certificate issued under the removed root. The check covers certificates present in the file. It does not cover a cross-certificate that a client presents and that is not in the file.

Add a step to the cut-off procedure. Operators must identify every certificate from a remaining root that cross-signs the removed root or one of its intermediates. They must then confirm that a client presenting such a certificate is rejected. Test with a leaf issued by each affected intermediate, not only with a leaf issued directly by the removed root.

Comment thread doc/variants/03-bff-cookie.adoc Resolved
cuioss-oliver and others added 6 commits November 21, 2026 10:11
…nd state review conditions exactly

PR #647 review fixes.

- SniFrontListener.Refusal carries its stage beside its token, and
  WARN.FRONT_CONNECTION_REFUSED logs that stage as its own parameter
  instead of enumerating every reason in the template. SniFrontListenerTest
  asserts each reason's stage and that the template names no reason or
  stage of its own.
- LogMessages.adoc, the developer and operator TLS-edge topics describe the
  new parameter.
- ADR-0003 and ADR-0076 state the unresolved-via- source per IPv4 proxy
  and per IPv6 /64, and that detection acts on the source and folded host.
- security-and-edge-hardening.adoc qualifies the passthrough single-source
  statement by the loopback trusted-proxy case.
- tls-edge.adoc aligns the emergency trust-root cut-off check with
  cross-certificates a client presents.
- 03-bff-cookie.adoc states the logout proof as refusing a request that
  identifies itself through Fetch Metadata or a speculative-load marker.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
…lth/well

PR #647 review fixes.

- ManagementBodyBoundIT creates its SSLSocket unconnected and connects it
  with EXCHANGE_TIMEOUT_MILLIS, so a management port that drops the connect
  attempt fails the exchange in time; SO_TIMEOUT, the HTTP/1.1 ALPN pin and
  the explicit handshake are unchanged.
- ManagementListenerTransportTest and ManagementBodyBoundIT add health/group
  and health/well to their body-less GET probe-route lists, and their
  DisplayNames and Javadoc name the listed default SmallRye Health and
  metrics routes instead of claiming every probe route.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
The pre-commit quality gate re-indented the two @valuesource arrays that
gained health/group and health/well.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
The environment-variable reference still called the internal HTTPS port a
loopback port, restating the sentence the wording sweep corrected in
doc/development/tls-edge.adoc. State the actual bind there and drop
"loopback" from the two sibling restatements.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
Drop "loopback" from the remaining restatements of the terminated
listener's internal port (shipped properties comments, TlsEdgeProducer
Javadoc, a test comment), correct the management body comment that
called the body the only bound below its default, and qualify the
ApiSheriff-152 cause row with the loopback trusted proxy case.
Comment and documentation text only.

Co-Authored-By: plan-marshall <noreply@cuioss.de>
…listener loopback

The dial-budget row in the user guide and the matching bullet in the threat
model said the dial goes to the gateway's own loopback port/listener. The
front dials the internal listener through localhost; the listener itself
binds every interface of the container. Say what the dial does and nothing
about how the listener is bound.

Co-Authored-By: plan-marshall <noreply@cuioss.de>

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Sourcery assessment

Approved.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 4

Review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Central YAML; Path: .coderabbit.yaml
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 03dda131-a377-4432-a9ae-18f29cb4f04d
Commits

Reviewing files that changed from the base of the PR and between 6015b5c and b45193c.

Files selected for processing: 18

  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/ApiSheriffLogMessages.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/tls/SniFrontListener.java
  • api-sheriff/src/main/java/de/cuioss/sheriff/gateway/tls/TlsEdgeProducer.java
  • api-sheriff/src/main/resources/application.properties
  • api-sheriff/src/test/java/de/cuioss/sheriff/gateway/config/SingleSourceTlsContractTest.java
  • api-sheriff/src/test/java/de/cuioss/sheriff/gateway/quarkus/ManagementListenerTransportTest.java
  • api-sheriff/src/test/java/de/cuioss/sheriff/gateway/tls/SniFrontListenerTest.java
  • doc/LogMessages.adoc
  • doc/adr/0003-forwarded-headers.adoc
  • doc/adr/0076-One_per-source_detection_substrate_counts_pre-trust_rejections_and_answers_a_tripped_source.adoc
  • doc/configuration/security-and-edge-hardening.adoc
  • doc/configuration/tls-and-egress.adoc
  • doc/development/tls-edge.adoc
  • doc/security-threat-model.adoc
  • doc/user/environment-variable-overrides.adoc
  • doc/user/tls-edge.adoc
  • doc/variants/03-bff-cookie.adoc
  • integration-tests/src/test/java/de/cuioss/sheriff/gateway/integration/ManagementBodyBoundIT.java
Files skipped from review as they are similar to previous changes: 5

  • api-sheriff/src/main/resources/application.properties
  • doc/LogMessages.adoc
  • doc/configuration/security-and-edge-hardening.adoc
  • doc/development/tls-edge.adoc
  • doc/security-threat-model.adoc

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Comment on lines +101 to +103
request's folded host, like on any source, because a client can always produce such a header: a
block or a delay the pair earns acts on every request keyed on both that unresolved source and that
folded host. Only a request carrying no such

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Functional Correctness · Quick win

Limit the stated effect of delay on keyed requests.

A block that the source and folded host earn applies to every request keyed on both. delay does not. While the tripped source's held-answer share has room, delay holds only that source's rejection answers. Other requests from the source proceed without delay. When the share is used up, delay refuses that source's requests with 429 until a held answer is released.

Correct the sentence at lines 101-103, and the equivalent sentence in ADR-0076, so that they state this difference.

Suggested fix

-block or a delay the pair earns acts on every request keyed on both that unresolved source and that
-folded host. Only a request carrying no such
+block the pair earns acts on every request keyed on both that unresolved source and that
+folded host. A delay the pair earns holds rejection answers while the share of held answers has room, and refuses requests with 429 once that share is used up. Only a request carrying no such
Committable suggestion

IMPORTANT
Review the replacement and indentation, then test before committing.

Suggested change
request's folded host, like on any source, because a client can always produce such a header: a
block or a delay the pair earns acts on every request keyed on both that unresolved source and that
folded host. Only a request carrying no such
request's folded host, like on any source, because a client can always produce such a header: a
block the pair earns acts on every request keyed on both that unresolved source and that
folded host. A delay the pair earns holds rejection answers while the share of held answers has room, and refuses requests with 429 once that share is used up. Only a request carrying no such

=== Accepted costs

* A trusted proxy that does not manage `X-Forwarded-*` is unsupported, and no setting covers that deployment. Passing a client's `X-Forwarded-For` through unchanged hands the spoofed chain the win. Appending only to `Forwarded` makes a client-sent `X-Forwarded-For` contest the chain: no client resolves, and every such request through that proxy shares the proxy's unresolved source.
* A trusted proxy that does not manage `X-Forwarded-*` is unsupported, and no setting covers that deployment. Passing a client's `X-Forwarded-For` through unchanged hands the spoofed chain the win. Appending only to `Forwarded` makes a client-sent `X-Forwarded-For` contest the chain: no client resolves, and every such request shares the proxy's unresolved source -- its own for an IPv4 proxy, the one of its /64 for an IPv6 proxy, shared with every trusted proxy in that /64.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Functional Correctness · Quick win

Limit the unresolved-chain claim to disagreeing chains.

The sentence states that any client-sent X-Forwarded-For produces no client and a shared unresolved source. That is true only when the client-sent value disagrees with the proxy-added Forwarded for= value. When the two values agree, the client resolves. ForwardedClientResolutionTest asserts this for the agreeing pair, with X-Forwarded-For and Forwarded: for= both set to 203.0.113.7.

Rewrite the sentence so that it names the disagreement as the condition.

Suggested ADR wording

--- "a/doc/adr/0003-forwarded-headers.adoc"
+++ "b/doc/adr/0003-forwarded-headers.adoc"
@@ -162,7 +162,7 @@
 
 === Accepted costs
 
-* A trusted proxy that does not manage `X-Forwarded-*` is unsupported, and no setting covers that deployment. Passing a client's `X-Forwarded-For` through unchanged hands the spoofed chain the win. Appending only to `Forwarded` makes a client-sent `X-Forwarded-For` contest the chain: no client resolves, and every such request shares the proxy's unresolved source -- its own for an IPv4 proxy, the one of its /64 for an IPv6 proxy, shared with every trusted proxy in that /64.
+* A trusted proxy that does not manage `X-Forwarded-*` is unsupported, and no setting covers that deployment. Passing a client's `X-Forwarded-For` through unchanged hands the spoofed chain the win. Appending only to `Forwarded` makes a client-sent `X-Forwarded-For` contest the chain only when it disagrees with the proxy-added `Forwarded` `for=` value. A disagreeing pair resolves no client, and every such request shares the proxy's unresolved source -- its own for an IPv4 proxy, the one of its /64 for an IPv6 proxy, shared with every trusted proxy in that /64. An agreeing pair resolves its client.
 
 == Links
 
Committable suggestion

IMPORTANT
Review the replacement and indentation, then test before committing.

Suggested change
* A trusted proxy that does not manage `X-Forwarded-*` is unsupported, and no setting covers that deployment. Passing a client's `X-Forwarded-For` through unchanged hands the spoofed chain the win. Appending only to `Forwarded` makes a client-sent `X-Forwarded-For` contest the chain: no client resolves, and every such request shares the proxy's unresolved source -- its own for an IPv4 proxy, the one of its /64 for an IPv6 proxy, shared with every trusted proxy in that /64.
* A trusted proxy that does not manage `X-Forwarded-*` is unsupported, and no setting covers that deployment. Passing a client's `X-Forwarded-For` through unchanged hands the spoofed chain the win. Appending only to `Forwarded` makes a client-sent `X-Forwarded-For` contest the chain only when it disagrees with the proxy-added `Forwarded` `for=` value. A disagreeing pair resolves no client, and every such request shares the proxy's unresolved source -- its own for an IPv4 proxy, the one of its /64 for an IPv6 proxy, shared with every trusted proxy in that /64. An agreeing pair resolves its client.

| `SHERIFF_TLS_INTERNAL_HTTPS_PORT`
| `8444`
| The internal loopback port the terminated listener moves to under the passthrough topology.
| The internal port the terminated listener moves to under the passthrough topology. The listener

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Functional Correctness · Quick win

State that the two port settings must match under passthrough.

SHERIFF_TLS_INTERNAL_HTTPS_PORT sets only the port the SNI front listener dials. It does not move the terminated listener. QUARKUS_HTTP_SSL_PORT sets the port the terminated listener binds. Nothing in the code derives one value from the other. If the two values differ, the front dials a port where no listener runs, and passthrough connections fail.

Suggested documentation fix

--- "a/doc/user/environment-variable-overrides.adoc"
+++ "b/doc/user/environment-variable-overrides.adoc"
@@ -110,9 +110,10 @@
 
 | `SHERIFF_TLS_INTERNAL_HTTPS_PORT`
 | `8444`
-| The internal port the terminated listener moves to under the passthrough topology. The listener
-  binds `quarkus.http.host`, which the image sets to `0.0.0.0`, so it listens on every interface of
-  the container, not on loopback alone; keep this port unpublished.
+| The port the SNI front listener dials to reach the terminated listener. It must equal the
+  `QUARKUS_HTTP_SSL_PORT` value (`8444`) in a passthrough deployment. The front does not move the
+  terminated listener. The terminated listener binds `quarkus.http.host`, which the image sets to
+  `0.0.0.0`, so it listens on every interface of the container; keep this port unpublished.
 |===
 
 === Certificate, key and trust material

| The internal loopback port the terminated listener moves to under the passthrough topology.
| The internal port the terminated listener moves to under the passthrough topology. The listener
binds `quarkus.http.host`, which the image sets to `0.0.0.0`, so it listens on every interface of
the container, not on loopback alone; keep this port unpublished.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Security & Privacy · Quick win

Add the container-network restriction to the internal port row.

Keeping 8444 unpublished does not block peers on the container network. Any container on the same Compose or pod network can connect to the listener directly and skip the front listener's SNI split, ClientHello deadline, and per-source limits. Add a sentence to this row that tells operators to restrict the container network to the peers that must reach the gateway. Refer to the TLS edge documentation for the full bypass description.

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