Status: Reviewed by a Pekko maintainer. Every question put to the maintainers (§14) is answered and is settled model; §5b records the project's standing position on configuration defaults. Every claim is either cited to Pekko HTTP's own source and configuration, or stated by a maintainer. One item is referred rather than settled (§14 Q10).
| Project | Apache Pekko HTTP |
| Written against | commit b1de40b, main |
| Date | 2026-10-02 |
| Authors | ASF Security team, at the request of the Pekko PMC |
| Version binding | Versioned alongside the project. A report against version N is triaged against the model as it stood at N, not at main. |
| Reporting | Findings that violate a §8 property should be reported per SECURITY.md. Findings under §3 or §9 will be closed citing this document. |
| Companion model | Pekko HTTP is built on Pekko Streams and Actors. The actor, remoting and cluster layers are modeled in apache/pekko's THREAT_MODEL.md; this document does not restate them. |
Provenance legend. (documented) — stated in Pekko HTTP's own docs or reference.conf, cited. (maintainer) — stated by a Pekko maintainer in review. Nothing in this document is inferred: every claim first drafted from code or configuration was either confirmed by a maintainer or corrected against the source, and several were corrected — the review history is in the pull requests this document links to.
Apache Pekko HTTP is a Scala/Java toolkit for building HTTP-based services and clients on top of Pekko Streams. It provides a full HTTP/1.1 and HTTP/2 implementation — parsing, connection management, marshalling, and a routing DSL of composable "directives" — as an embeddable library, not a standalone server. The application supplies the routes, the authentication, and the deployment.
Pekko HTTP is a library the application embeds. There is no Pekko HTTP daemon to secure independently of the service built on it.
Caller roles:
- The embedding application — fully trusted. Defines routes, supplies handlers, chooses configuration.
- The operator/deployer — trusted for the instance. Chooses what sits in front of the service (§4), TLS termination, and limits.
- The HTTP client — untrusted. This is the adversary the model is mostly about.
| Family | Modules | Entry point | In model |
|---|---|---|---|
| Core protocol | http-core, parsing |
Wire bytes → HttpRequest / HttpResponse |
yes — primary surface |
| HTTP/2 | http-core (impl/engine/http2) |
HTTP/2 framing, HPACK, streams | yes |
| Routing DSL | http |
Route, directives, rejection/exception handling |
yes |
| Marshalling | http-marshallers-scala, http-marshallers-java |
JSON/XML entity conversion | yes |
| CORS | http-cors |
cors() directive |
yes — see §5a |
| Caching | http-caching |
response cache directives | yes |
| Test kits | http-testkit, http-testkit-munit, http-tests, http-compatibility-tests, http2-tests |
— | no — §3 |
| Benchmarks | http-bench-jmh |
— | no — §3 |
| Lint / build / docs | http-scalafix, docs, project, scripts, legal |
— | no — §3 |
(maintainer — §14 Q6)
- Test kits, benchmarks, scalafix rules, build tooling and documentation sources. A finding in
http-bench-jmhor any*-testsmodule isOUT-OF-MODEL: unsupported-component. (maintainer — §14 Q6) - Pekko HTTP is not a WAF, and not an edge-hardened server. Applications "should not be exposed to the public internet directly"; an "enterprise grade routing solution" or a load balancer such as Apache HTTP Server or Nginx "would be safer" (documented —
security.md). See §4. - Pekko HTTP is not an authentication or authorization system.
authenticateBasic,authenticateOAuth2andauthorizeare plumbing: the credential check is a function the application supplies. There is no user store, session model or policy engine. (maintainer — §14 Q7) - The actor, stream, remoting and cluster layers are covered by
apache/pekko's threat model. - Attackers who already control the embedding process. (maintainer — §14 Q7)
The trust boundary is the inbound HTTP request. Everything derived from wire bytes — request line, headers, cookies, entity, HTTP/2 frames — is attacker-controlled until the application validates it.
Pekko HTTP's documented posture:
"Pekko HTTP-based applications should not be exposed to the public internet directly. We believe Pekko HTTP behaves pretty well under most known Denial of Service attacks, but if you want the best security, you should use an enterprise grade routing solution. Even using a load balancing solution like an up-to-date version of Apache HTTP Server or Nginx would be safer than exposing Pekko HTTP-based applications directly to the public internet." — (documented —
security.md, "Security model")
This is a graded claim, not a disclaimer of DoS as a class. §14 Q1 resolves it into the content-vs-volume line that triage applies.
- Core protocol / HTTP/2 — reachable from raw wire bytes. A parser defect here needs no application cooperation.
- Routing DSL — reachable from a request the application's own routes expose. A finding must name the directive and show a route shape a reasonable application would write.
- Marshalling — reachable from an entity body only where the application has bound that marshaller to a route. Findings in the underlying JSON/XML library belong to that library.
- CORS — reachable only where the application has installed
cors(). Opt-in, not on by default. - Caching — reachable only where the application has installed a caching directive; cache-key correctness is the sharp edge.
- Runtime. A conformant JVM. Pekko HTTP does not defend against a hostile JVM or in-process attacker. (maintainer — §14 Q7)
- Fronting infrastructure. Something sits in front in production (documented —
security.md). Per §14 Q1 this is load-bearing for volume only: the proxy is relied on for flood and slow-loris defence, not for bounding a single request, which is P1's job. - TLS. Pekko HTTP can terminate TLS itself (
HttpsConnectionContext); in a fronted deployment termination is commonly the proxy's job. Cipher and protocol selection come from the JSSE context the application supplies — Pekko HTTP pins nothing and overrides no JDK default. (maintainer — §14 Q8) - Client IP.
remote-address-attributeshipsoff(documented —reference.conf). When on, the attribute holds the address of whoever opened the TCP connection to Pekko HTTP. With a load balancer or reverse proxy in front, that is the proxy's address.extractClientIPreadsX-Forwarded-For/X-Real-Ipand is client-controllable;extractDirectClientIPreads the attribute alone and is not (§14 Q4). (documented —MiscDirectives.scala)
Verified by scanning the main sources of http-core, http, parsing, http-caching and http-cors (documented — source scan, §14 Q9):
- Binds no port until the application asks for one. Binding is reachable only through
Http().newServerAt(...)and theServerBuilderit returns; nothing binds at class or extension initialization. - Installs no signal handlers and spawns no child processes. No
sun.misc.Signal,ProcessBuilderorRuntime.execin the main sources. - Registers no JVM shutdown hook. No
addShutdownHookin the main sources. TheActorSystemit runs on does register hooks —CoordinatedShutdown's, and Artery's when remoting is enabled — so an integrator will observe hooks in the process; they belong toapache/pekko's model. "Pekko HTTP registers no shutdown hook" is the claim; "a Pekko HTTP process has no shutdown hook" is false. (maintainer — §14 Q9) - Touches the file system only through directives the application installs.
getFromFile/getFromDirectoryread.storeUploadedFile(s)writes to a destination the application chooses;fileUploadAllbuffers parts into temp files in one directory per actor system, removed by aCoordinatedShutdowntask (#1217). Nothing writes at initialization or outside an installed directive; beyondFileUploadDirectivesthe main sources contain noFileOutputStream,Files.write,FileWriterorcreateTempFile. - Does not mutate process-global state at initialization — no
System.setProperty,Security.setProperty,Security.addProviderorsetDefault(...).
Pekko HTTP's resistance to malformed and abusive input is a function of pekko.http.server.parsing.*, plus two pekko.http.routing.* entries bounding what the parsing limits cannot see — an entity's size after decompression. These are the documented, shipped limits (all documented — http-core and http reference.conf):
| Setting | Default | What it bounds |
|---|---|---|
max-uri-length |
2k |
Request-line URI |
max-method-length |
16 |
Method token |
max-header-name-length |
64 |
Single header name |
max-header-value-length |
8k |
Single header value |
max-header-count |
64 |
Headers per message |
max-content-length |
8m (server) |
Entity size |
max-chunk-size |
1m |
Single chunk |
max-chunk-count |
100000 |
Chunks per message |
max-chunk-ext-length |
256 |
Chunk extension |
max-part-count |
10000 |
Parts in one multipart entity — the amplification max-content-length does not bound |
max-comment-parsing-depth |
5 |
Nested comment recursion |
max-to-strict-bytes |
8m |
toStrict materialization |
max-concurrent-streams |
256 |
HTTP/2 concurrent streams |
max-header-list-size |
64 KiB |
HTTP/2 decompressed header list, and the accumulated HEADERS + CONTINUATION fragments for one header block |
max-frame-size |
512kB |
HTTP/2 single incoming frame, checked on its frame header before the payload is buffered; a limit on what is accepted, not advertised as SETTINGS_MAX_FRAME_SIZE |
incoming-connection-level-buffer-size |
10 MB |
HTTP/2 incoming data buffered across one connection |
incoming-stream-level-buffer-size |
512kB |
HTTP/2 incoming data buffered for one stream |
outgoing-control-frame-buffer-size |
1024 |
HTTP/2 outgoing control frames queued before the connection fails |
frame-type-throttle |
frame-types = ["reset", "empty-data-no-end-stream"], cost = 100, burst = 100, interval = 1 s |
HTTP/2 frames rate-limited — RST_STREAM by default, against Rapid Reset (CVE-2023-44487), and empty DATA frames that do not end their stream, against Empty Frames Flood (CVE-2019-9518) — secure default |
max-connections |
1024 |
Server connections |
pipelining-limit |
1 |
In-flight pipelined requests |
idle-timeout |
60 s |
Connection inactivity, in either direction (§9) |
request-timeout |
20 s |
Per-request handling |
uri-parsing-mode |
strict |
URI leniency |
cookie-parsing-mode |
rfc6265 |
Cookie leniency |
verbose-error-messages |
off |
Whether parse errors leak detail to the client — secure default |
error-logging-verbosity |
full |
How much of a rejected request reaches the server log — with full, the raw request target (§9) |
illegal-response-header-name-processing-mode |
error |
Blocks response-splitting via header names — secure default |
illegal-response-header-value-processing-mode |
error |
Blocks response-splitting via header values — secure default |
server-header |
pekko-http/${version} |
Advertises product and version |
remote-address-attribute |
off |
Exposes socket peer address to routes |
transparent-head-requests |
off |
HEAD handled as GET |
routing.decode-max-bytes-per-chunk |
1m |
Single ByteString a decoding directive emits |
routing.decode-max-size |
8m |
Entity size after decoding (§9) |
These limits are the model's quantitative spine. A request within every documented limit that causes disproportionate resource use is VALID; one that simply exceeds a limit is P1 working; one that needs a limit raised is OUT-OF-MODEL: non-default-build (§14 Q1).
http-cors ships:
| Setting | Default |
|---|---|
allowed-origins |
"*" |
allow-credentials |
yes |
allowed-headers |
"*" |
allowed-methods |
["GET", "POST", "HEAD", "OPTIONS"] |
allow-generic-http-requests |
yes |
"If parameter is * and credentials are not allowed, a * is set in Access-Control-Allow-Origin. Otherwise, the origins given in the Origin request header are echoed." (documented — http-cors/reference.conf) With both defaults in force the directive echoes the requesting Origin and allows credentials — the most permissive default in the project, bounded by cors() being opt-in and the default being deliberate. Its disposition follows §5b: a request to change it is not a vulnerability report. (maintainer — §14 Q2)
That ruling covers the default, never the enforcement. Where an operator has restricted allowed-origins, the directive must honour it: a request pairing an allowed origin with a disallowed one used to pass while every origin was echoed back (#1262) — VALID under §5b.4. (maintainer)
Pekko HTTP's deployment base is inherited from Akka HTTP, and http-cors's defaults arrived with the code donated by Lomig Mégard (legal/CorsNotice.txt). Defaults are chosen for compatibility with those deployments, whose operators already front the service (§4, §10.1) and choose limits for their traffic; tightening a default breaks them on upgrade, often as requests that used to work failing with a 4xx.
Pekko HTTP therefore takes the following position (maintainer):
- Defaults are compatibility choices, not security claims. §5a lists every setting whose default affects the security envelope; §10 lists what the operator must do as a result. Together they are the contract.
- A report that a default should be more restrictive is not a vulnerability report. It is a change request, closed as
BY-DESIGN: default-configuration(§13). This covers the CORS pair,server-header, and every limit someone considers too generous. - Proposals to change a default are welcome, and belong on the development list. The PMC weighs compatibility cost, migration path, and whether a major version is in flight. Defaults change through project discussion, not as the remediation of a security report.
- If an implementation is wrong, Pekko HTTP fixes it. A control that does not do what it is documented to do once enabled is a defect, in scope, at the severity §8 assigns. This is the sharp end of the model: a
max-header-list-sizethat fails to bound CONTINUATION accumulation, anillegal-response-header-value-processing-mode = errorthat lets a CRLF through, asafeDirectoryChildPaththat can be walked out of — those are the findings this project wants, and the second and third were real and fixed during this review (#1256, #1218). This posture governs which value ships as the default, never whether the mechanism works.
Users are free to strengthen any §5a setting, and §10 says which ones matter most. What the project will not do is change the shipped value on their behalf.
| Surface | Input | Attacker-controllable? | Who must enforce what |
|---|---|---|---|
| Any bound route | Request line (method, URI, version) | Yes | Pekko HTTP: §5a length limits |
| Any bound route | Headers, incl. Host, Cookie |
Yes | Pekko HTTP: count/length limits. App: semantic trust |
| Any bound route | X-Forwarded-*, X-Real-Ip |
Yes — trivially spoofable | App — surfaced by extractClientIP, never validated; use extractDirectClientIP for access control or rate limiting (§14 Q4) |
| Any bound route | Entity body (fixed, chunked, streamed) | Yes | Pekko HTTP: size/chunk limits. App: content validation |
| Route with a multipart unmarshaller | Body parts — boundaries, per-part headers, part count | Yes | Pekko HTTP: max-part-count, header limits per part, each part carrying only its own headers (#1279). App: per-part validation |
Custom ParsingErrorHandler |
IllegalRequestContext.rawRequestTarget |
Yes — the client's request-target bytes, as received; present whenever the target was read, so the failure may lie elsewhere (a header, the entity) | App — escape before logging or echoing; documented at the class |
| HTTP/2 | Frames, HPACK table, stream IDs | Yes | Pekko HTTP: max-frame-size, max-concurrent-streams, frame-type-throttle, P9 |
| Route with marshaller | Entity parsed to a domain type | Yes | Underlying JSON/XML library + app |
cors() |
Origin, Access-Control-Request-* |
Yes | Operator: §5a CORS config |
| File-serving directives | Path segments | Yes | Pekko HTTP + app — see §9, §14 Q3 |
| Client API | Response from an upstream server | Yes if the upstream is untrusted | App: treat responses as untrusted. Which request a response answers follows the origin's HTTP/1.1 framing, which the pool trusts (§14 Q12) |
| Config | application.conf |
No — trusted deployment input | Operator |
In scope:
- The remote HTTP client. Arbitrary bytes, malformed framing, oversized or deeply-nested input, many concurrent connections, abusive HTTP/2 frame sequences. The primary adversary — though what it achieves through sheer volume is the proxy's problem (§14 Q1). (maintainer — §14 Q7)
- A malicious upstream server, where the application uses the client API against an untrusted endpoint. (maintainer — §14 Q7) What it controls is its own responses: a host connection pool talks to that one origin and trusts its HTTP/1.1 framing to send one response per request, so an origin that answers a request it was never sent is answering its own client, not crossing a boundary (§14 Q12). (maintainer)
- A cross-origin web attacker, where the application enables CORS. (maintainer — §14 Q2)
Explicitly out of scope:
- Attackers with code execution in the embedding JVM.
- The embedding application itself. A route that deliberately leaks data is an application bug.
- Side-channel observers. No general timing guarantees are made about routing or parsing. Credential comparison is the exception (P8): a timing finding against
Credentials.verifyis in scope; one against an application-suppliedprovideVerifyis not. (documented —SecurityDirectives.scala,EnhancedByteArray.scala)
| # | Property & conditions | Violation symptom | Severity | Provenance |
|---|---|---|---|---|
| P1 | Inbound messages are bounded by the §5a limits: reaching a limit stops the parse, every header a message carries counts towards the count limits, and buffered bytes are released from the accounting when the buffer is discarded | OOM or unbounded buffering from input within documented limits; a limit reached without the parse stopping | Critical | (documented — reference.conf, HttpMessageParser.scala, Http2FrameParsing.scala, Http2StreamHandling.scala) |
| P2 | Response splitting is blocked: illegal response header names and values are error by default, and the renderers drop any header whose rendered bytes contain CR, LF or NUL — on the HTTP/1.1 header block, chunked-response trailers and the HTTP/2 HPACK path alike — and any chunk extension containing CR or LF |
CR or LF in an application-supplied header, trailer or chunk extension, or NUL in a header or trailer, reaching the wire | Critical | (documented — reference.conf, Rendering.isIllegalHeaderChar, RenderSupport.renderChunk) |
| P3 | Parse errors do not leak detail to the client — verbose-error-messages = off |
Internal parse state or stack detail in a 400 response under defaults | High | (documented — reference.conf) |
| P4 | Strict URI and RFC6265 cookie parsing by default, rather than lenient normalization that invites smuggling | Two components disagreeing on a URI or cookie under strict |
High | (documented — reference.conf) |
| P5 | Connection and request lifetimes are bounded — idle-timeout 60s closes a connection with no traffic in either direction for that long; request-timeout 20s bounds handling once a request's entity has been fully received (a body still arriving is not covered; §9); max-connections 1024; pipelining-limit 1. idle-timeout is an inactivity timeout, not a receive deadline (§9) |
A connection with no traffic outliving idle-timeout; a fully received request outliving request-timeout with no response; resources held past either bound after the connection is gone |
High | (documented — reference.conf, timeouts.md) |
| P6 | HTTP/2 concurrency and stream churn are bounded — max-concurrent-streams = 256 caps open streams, and frame-type-throttle rate-limits RST_STREAM (100/s, burst 100) so a peer cannot cycle through that cap for free (Rapid Reset, CVE-2023-44487); the same budget covers empty DATA frames that do not end their stream, which no flow-control window bounds (Empty Frames Flood, CVE-2019-9518) |
Unbounded stream/state growth on one connection, or unbounded churn through a bounded concurrency limit | High | (documented — reference.conf) |
| P7 | HTTP/2 header blocks are bounded — max-header-list-size = 64 KiB caps the decompressed header list and the accumulated HEADERS + CONTINUATION fragments; over-limit blocks get GOAWAY(ENHANCE_YOUR_CALM) rather than being buffered |
Unbounded buffering from a CONTINUATION flood or an oversized header list | Critical | (documented — reference.conf) |
| P8 | Credential comparison is constant-time where the verifier calls Credentials.verify — secure_== XOR-accumulates over the full length after a length check. The length check returns early, so whether the presented secret has the stored secret's length is not hidden; verify(secret, hasher) comparing fixed-length digests removes even that |
Secret recoverable byte-by-byte from response timing against a verify-based verifier |
High | (documented — SecurityDirectives.scala, EnhancedByteArray.scala) |
| P9 | HTTP/2 streams are isolated from each other's malformed request fields: a request whose method, target, authority or a header field fails to parse into the model is answered with a 400 on its own stream, and the connection — its HPACK state and every other stream — carries on. A connection a proxy multiplexes for many clients is what this protects. Not covered: HTTP/2 framing violations — a missing, duplicate, misplaced or unknown pseudo-header, or a connection-specific header (Connection, Transfer-Encoding, TE other than trailers) — which RequestParsing.protocolError raises as Http2ProtocolException, closing the connection with GOAWAY (§14 Q11) |
One stream's malformed request field failing, stalling or desynchronising the connection for the other streams | High | (documented — RequestErrorFlow.scala, RequestParsing.scala, Http2Blueprint.errorHandling) |
P1–P7 and P9 are default-on. P8 holds only for a verifier that calls Credentials.verify (§10.4). The DoS boundary is the §14 Q1 content-vs-volume line.
How §8 was verified. P1, P2 and P9 were first asserted from configuration and design, then checked against the code; each had defects, all fixed at or before the pinned commit. P1: max-chunk-count reported the limit without stopping the parse (#1220); repeated Connection headers escaped max-header-count (#1255); HTTP/2 connection-level buffer accounting leaked on discarded streams until the connection window drained and every stream stalled (#1259, #1281); nothing bounded multipart part count (#1266); the HTTP/2 frame parser buffered a frame of any declared length, up to 16 MiB − 1, before any other bound applied (#1264). P2: the CR/LF guard missed chunked trailers and extensions (#1256), NUL (#1260) and the HTTP/2 header path (#1258). P9: a header that failed to parse desynchronised the HPACK dynamic table for every later frame (#1252), and a field the HTTP/1.1 parser rejected failed the connection instead of the stream (#1297). The properties as stated are claims about the merged code, not about the settings. (maintainer)
- No claim of complete DoS resistance. "Behaves pretty well under most known Denial of Service attacks" (documented —
security.md) is scoped to volume (§14 Q1): Pekko HTTP does not claim to withstand floods, but does claim that one in-limits request cannot provoke disproportionate work — that is P1, and a violation isVALID. - No edge hardening. Rate limiting, IP reputation, request scrubbing, connection throttling beyond
max-connections, slow-loris mitigation beyondidle-timeout— none provided, none planned. (maintainer — §14 Q1) - No authentication or authorization. The security directives are plumbing. (maintainer — §14 Q7)
- No CSRF protection. (maintainer — §14 Q7)
- No output encoding / XSS defence. Pekko HTTP renders what the application marshals. (maintainer — §14 Q7)
- No trusted client-IP derivation from headers.
extractClientIPsurfacesX-Forwarded-For/X-Real-Ipunvalidated; there is no trusted-proxy chain configuration.extractDirectClientIPis trustworthy but yields the last proxy, not the client (§14 Q4). - No defence against an origin that misframes its own responses. A host connection pool pairs responses with requests in the order they were sent and trusts the origin's HTTP/1.1 framing. An origin that sends a response with no request outstanding can have it delivered to a later request on the same connection (§14 Q12).
- The security directives are not a security system.
authenticateBasicandauthenticateOAuth2route credentials to an application-supplied verifier; no password policy, rate limiting or lockout. They supply a constant-time comparison (P8) only to a verifier that callsCredentials.verify. allowed-origins = "*"does not mean "no credentials are exposed". With the shippedallow-credentials = yesit echoes the caller'sOrigin(§5a).remote-address-attributeis not the client IP behind a proxy. It is the socket peer.max-content-lengthis not a global memory bound. It bounds one entity; concurrent connections multiply it.verbose-error-messages = offis not a log-hygiene setting. It governs what reaches the client. What reaches the server log iserror-logging-verbosity, which shipsfull: a request whose target fails to parse has that target written to the log at warning level (UriParser.failcopies the failing input line into theErrorInfodetail;DefaultParsingErrorHandlerpasses it tologParsingError, which logsformatPrettyat warning underfull). Attacker-chosen bytes in the log at an alerting level are a log-injection and log-flooding consideration the operator owns (§10.9). (documented —reference.conf,UriParser.fail,ParsingErrorHandler.scala,parsing/package.scala)- A rejection is not a failure. The routing DSL's rejection mechanism is control flow, not a security control — an unhandled rejection can fall through to a different route.
- Request smuggling / desync between a fronting proxy and Pekko HTTP is inherently two-party; strict parsing (P4) helps but cannot settle it alone. What Pekko HTTP does own is its own framing decision: framing a message by a different rule than a conformant upstream would is a defect here, not a stalemate. An unparseable
Transfer-Encodingframed byContent-Length(#1267) and whitespace tolerated inside a chunk size (#1257) were both such cases; both are now rejected. - Slow-loris and connection exhaustion.
idle-timeoutbounds inactivity in either direction: a client sending a byte inside every window keeps the connection alive by design, and a hard receive deadline needs a reverse proxy or an application-level entity timeout (documented —reference.conf,timeouts.md). A trickling client isBY-DESIGN: property-disclaimed; exhausting the bounds by volume is disclaimed (§14 Q1). In scope: a connection holding resources with no traffic that outlives the timeout, or a bound whose own cleanup leaks — as the request-timeout path did, keeping one scheduled task per open request alive after the connection was gone (#1284). - Decompression bombs are bounded where decoding goes through
decodeRequest/decodeRequestWith: per-chunk output bydecode-max-bytes-per-chunk, decoded size bydecode-max-size(§5a,CodingDirectives.scala). Left to the caller: decoding outside those directives —Coders.Gzip.decodeMessage, or client-side response decoding — and raisingdecode-max-size, which may be set toinfinite. - SSRF via the client API, where the application takes a URL from a request.
- Path traversal — three tiers (§14 Q3).
getFromDirectory,listDirectoryContentsand thegetFromBrowseableDirector*pair run the unmatched path throughsafeDirectoryChildPath: segment filter plus canonical containment against the served root. Containment is claimed there, so an escape isVALID— one was found and fixed, a symlink into a sibling directory whose name shared the root as a string prefix (#1218).getFromResourceDirectoryapplies the segment filter only, since a class-loader resource name has no canonical form.getFromFileandgetFromResourcefilter nothing; handing either request input is a §11 misuse. Residual: on WindowsFile.getCanonicalPathdoes not resolve NTFS symlinks or junctions, so a link out of the root is not detected there — serving a link-free tree is the operator's. - XXE in XML marshallers — a property of the underlying parser.
- Put an enterprise-grade proxy or load balancer in front of an internet-facing service (documented —
security.md). - Do not raise the §5a limits without understanding the memory cost — each is multiplied by concurrent connections.
- If CORS is enabled, set
allowed-originsexplicitly. Do not ship"*"+allow-credentials = yesto a credentialed API (§5a). - Compare credentials with
Credentials.verify(P8) — not==on the secret, and notprovideVerifyunless the supplied verifier is itself constant-time. - Use
extractDirectClientIP, notextractClientIP, for access control, rate limiting or audit logging. Derive identity fromX-Forwarded-Foronly where a trusted proxy sets it and you validate the chain yourself. - Validate and canonicalize any request-derived path before passing it to a file-serving directive.
- Treat client-API responses from untrusted upstreams as untrusted input.
- Consider
server-header = ""if product/version disclosure matters to your threat model. - Consider
error-logging-verbosity = simplewhere logs are shipped or alerted on (§9).
- Exposing a Pekko HTTP service directly to the internet with no fronting proxy.
- Enabling
cors()and leavingallowed-origins = "*"on an API that uses cookies or bearer tokens. - Reaching for
extractClientIPfor rate limiting, audit logging or access control, whereextractDirectClientIPis the one the caller cannot choose. - Raising
max-content-lengthtoinfiniteto accept large uploads, without a concurrency bound. - Comparing credentials with
==inside anauthenticateBasicverifier, orprovideVerifywith a non-constant-time verifier. - Passing a request path segment straight to
getFromFileorgetFromResource. Neither filters what it is handed.getFromResourcelooks like the sibling ofgetFromResourceDirectorybut skips the segment filter that directive applies, sogetFromResource(s"public/$name")against a directory-backed class loader can be walked intoapplication.conforlogback.xml. - Turning
verbose-error-messages = onin production. - Building a
Raw-Request-URIheader from request input. It renders the request target verbatim — into the HTTP/1.1 request line, and since #1280 as the HTTP/2:path. Since #1296 the header, and a customHttpMethod, reject at construction anything that could corrupt the request line — the target must be visible ASCII, the method a token — so the misuse no longer reaches injection; what remains is that the client bytes choose the target the upstream sees, unnormalized. A value that passes construction and still corrupts the request line isVALIDunder §5b.4. (documented —headers.scala,HttpMethod.scala,http-model.md) - Echoing
IllegalRequestContext.rawRequestTargetfrom a customParsingErrorHandlerinto the response or log without escaping it. The class documents it as attacker-controlled; the default handler never reads it.
- "
Serverheader discloses the product and version." Documented default, configurable viaserver-header.BY-DESIGN: default-configurationper §5b. - "No authentication on routes." Authentication is the application's responsibility (§9). A scan of this library cannot conclude a route is unauthenticated.
- "Request exceeding
max-uri-length/max-header-countis rejected." That is P1 working. - "N concurrent connections / requests exhaust CPU, memory or sockets." Volume-based exhaustion is
BY-DESIGN: property-disclaimedper §14 Q1 — defence belongs to the fronting proxy (§10.1). A report must show one in-limits request doing disproportionate work. A load-generator result is not a finding. - "
extractClientIPtrusts a client-supplied header." By design and documented at the directive, withextractDirectClientIPas the trustworthy alternative (§14 Q4).BY-DESIGN: property-disclaimed. A report thatextractDirectClientIPcan be influenced by a header is in scope. - "CORS allows any origin." The shipped default, reachable only where the application opted into
cors().BY-DESIGN: default-configurationper §5b; a misconfigured deployment is a finding against the application. - "
allow-credentials = yeswithallowed-origins = "*"sendsAccess-Control-Allow-Origin: *with credentials." It does not — the literal*is sent only when credentials are not allowed; otherwise the requestOriginis echoed (CorsSettingsImpl.scala, covered byCorsDirectivesSpec). Factually wrong. - "Credential comparison is vulnerable to a timing attack." Wrong against
Credentials.verify(P8); against an application's ownprovideVerifycomparator it is a finding in that application. - "A malformed HTTP/2 pseudo-header closes the whole connection." A framing violation from the peer closing that peer's own connection with
GOAWAYrather thanRST_STREAM.BY-DESIGN: property-disclaimedper §14 Q11. - "The client pool delivers a stray response to the next request." Requires the origin to send more responses than it was sent requests — for example by framing a conformant request body by a different rule and answering part of it as a further request, or by writing a response onto an idle keep-alive connection. The pool only talks to that origin and trusts its framing. An early response no longer leaves the connection open for reuse (§14 Q12).
BY-DESIGN: property-disclaimedper §14 Q12. - Findings in
*-tests,http-testkit*,http-bench-jmh,http-scalafix,docs—OUT-OF-MODEL: unsupported-componentper §3. - "The process registers JVM shutdown hooks." Pekko HTTP registers none (§5). The hooks are
CoordinatedShutdown's and, with remoting, Artery's —apache/pekko's model.OUT-OF-MODEL: unsupported-component. - Findings in the actor or stream layer —
apache/pekko's model, not this one.
- A change to any §5a default, especially a parsing limit, a timeout, or a CORS setting.
- A new protocol version or transport (HTTP/3).
- Taking on any authentication, authorization, or rate-limiting responsibility currently disclaimed in §9.
- A change to the documented "do not expose directly" posture in
security.md. - Promotion of a §3 module into the supported surface.
- A change to the §5 process-behaviour claims. One near-miss is on record: #1217 originally registered a JVM shutdown hook from Pekko HTTP itself and was reworked to a
CoordinatedShutdowntask before merging, so the claims stand. - A report that cannot be routed to exactly one §13 disposition — evidence of a model gap; revise the model rather than making an ad-hoc call.
| Disposition | Meaning | Licensed by |
|---|---|---|
VALID |
Violates a §8 property via an in-scope adversary and input. For resource exhaustion: a single request within all §5a limits causing super-linear CPU or memory | §6, §7, §8, §14 Q1 |
VALID-HARDENING |
No §8 property violated, but the API makes a §11 misuse easy enough to warrant hardening. Typically no CVE | §11 |
OUT-OF-MODEL: trusted-input |
Requires control of an input §6 marks trusted (configuration, application-supplied handlers) | §6 |
OUT-OF-MODEL: adversary-not-in-scope |
Requires in-JVM code execution, or a malicious embedding application | §7 |
OUT-OF-MODEL: unsupported-component |
Lands in a §3 module, or in the actor/stream layer | §3 |
OUT-OF-MODEL: non-default-build |
Only manifests under a non-default §5a setting — including any resource-exhaustion report that needs a limit raised from its default. A real defect reachable only off-default; contrast default-configuration, which is no defect at all |
§5a, §14 Q1 |
BY-DESIGN: default-configuration |
Asks that a §5a default be changed to a more restrictive value. Not a vulnerability; §5b.3 invites the proposal on the development list | §5b |
BY-DESIGN: property-disclaimed |
Concerns a §9 property — authentication, CSRF, XSS, edge hardening — or depends on request volume rather than request content | §9, §14 Q1 |
KNOWN-NON-FINDING |
Matches a §11a pattern | §11a |
MODEL-GAP |
Routable to none of the above — triggers §12 | §12 |
Questions the draft put to the maintainers, with the ruling each received. All are settled model (maintainer).
Q1 — Where is the DoS line? Content vs. volume:
A single request within every §5a documented limit that provokes super-linear CPU or memory is
VALID— the P1 violation symptom. A finding that requires a §5a limit to be raised from its shipped default isOUT-OF-MODEL: non-default-build. A finding that depends on request volume rather than request content — connection floods, slow-loris at scale, aggregate bandwidth — isBY-DESIGN: property-disclaimed. Volume defence is the fronting proxy's job (§10.1).
Q2 — The CORS defaults. A compatibility default under §5b: the values arrived with the donated code and existing users depend on them; cors() is opt-in and an application that enables it is expected to configure it (§10.3). Changing the default is BY-DESIGN: default-configuration. The implementation is in scope: cors() admitting an origin its configuration should have rejected, or emitting credentials for one it should not, is a defect under §5b.4.
Q3 — File-serving directives. Containment is claimed by safeDirectoryChildPath — segment filter (.., /, \) plus canonical containment of the resolved file under the served root — for getFromDirectory, listDirectoryContents and the getFromBrowseableDirector* pair. A genuine escape is VALID under §5b.4; review found one (string-prefix comparison of canonical paths, #1218). getFromResourceDirectory gets the segment filter only. getFromFile and getFromResource get neither and passing them request input is a §11 misuse. Residual: on Windows File.getCanonicalPath does not resolve NTFS symlinks or junctions; serving a link-free tree there is the operator's. (documented — FileAndResourceDirectives.scala)
Q4 — X-Forwarded-For and client identity. extractClientIP resolves X-Forwarded-For (first address) → X-Real-Ip → the remoteAddress attribute, and its scaladoc says the headers are under the client's control unless a trusted proxy overwrites them. extractDirectClientIP reads the attribute alone. "extractClientIP trusts a spoofable header" is BY-DESIGN: property-disclaimed; anything client-controlled reaching extractDirectClientIP is VALID. (documented — MiscDirectives.scala)
Q5 — Constant-time credential comparison. Credentials.Provided.verify compares via constant-time secure_== — recorded as P8. A timing finding against verify is VALID; one against an application's own provideVerify comparator is BY-DESIGN: property-disclaimed — handing the raw secret to application code waives the guarantee (§10.4). A report that verify reveals the secret's length describes documented behaviour of secure_==, not a P8 violation: P8 protects the content. (documented — EnhancedByteArray.scala)
Q6 — Module in/out split. The §2 table is the maintainers' own. http-caching is in — cache-key confusion is a real class. http-scalafix, the test kits, http-bench-jmh, docs, project, scripts and legal are out: OUT-OF-MODEL: unsupported-component.
Q7 — Non-goals. Confirmed as stated in §3, §7 and §9: no authentication system, authorization policy, CSRF protection or XSS/output encoding (BY-DESIGN: property-disclaimed). Out of the adversary model: in-JVM code execution, and a malicious embedding application. In: the remote client, a malicious upstream server behind the client API, a cross-origin attacker where cors() is enabled.
Q8 — TLS. Where Pekko HTTP terminates TLS via HttpsConnectionContext, protocol and cipher selection come from the JSSE context the application supplies; nothing is pinned or overridden. "Weak cipher accepted" is OUT-OF-MODEL: trusted-input. A defect in how Pekko HTTP drives the context — failing to apply a supplied restriction, continuing after a handshake failure — is VALID. In-process termination is supported; fronting is what the docs recommend.
Q9 — The §5 negative claims. Verified by source scan, with one correction: the draft said Pekko HTTP writes no files, and the upload directives do — §5 states the accurate boundary. Pekko HTTP registers no shutdown hook of its own; the ActorSystem's hooks belong to apache/pekko's model. A report that Pekko HTTP installs a hook is factually wrong (§11a).
Q10 — Coexistence of the security documents. Following apache/pekko#3478:
| Document | Canonical for | Reached by |
|---|---|---|
SECURITY.md |
The reporting policy | Anyone arriving via the repository, and every other document |
THREAT_MODEL.md (this document) |
Scope — what is and is not a vulnerability, and how a report is triaged | Reporters, triagers, scanning tools |
docs/src/main/paradox/security.md |
Security announcements, and the documentation-site index of security material | Readers of the documentation site |
Each links to the others rather than restating them. security.md's "Security model" section stays as the documented source §4 quotes. One statement is referred: security.md's upstream-coordination sentence ("any issues affecting Apache Pekko and Akka should be reported to Apache team first…") is a reporting statement outside SECURITY.md; it is left in place pending a maintainer decision to promote it verbatim or drop it.
Q11 — HTTP/2 framing violations close the connection. A missing, duplicate, misplaced or unknown pseudo-header, or a connection-specific header, is raised by RequestParsing.protocolError as Http2ProtocolException and answered with GOAWAY, not the stream error RFC 9113 §8.1.1 asks for. Only the violating peer's connection is lost; a proxy multiplexing many clients onto one connection owns generating conformant pseudo-headers and stripping connection-specific ones. A report of this is BY-DESIGN: property-disclaimed — it falls outside P9. Answering with RST_STREAM instead is a compliance improvement for an ordinary issue, not a security report. (maintainer)
Q12 — The HTTP client trusts the origin's HTTP/1.1 response framing. A host connection pool talks to exactly one origin, and on each connection it pairs responses with requests in the order the requests were sent. It trusts the origin to send exactly one response per request. An origin that sends a response for which no request is outstanding — for example after framing a conformant request body by a different rule and answering the rest of it as a further request, or by writing a response onto an idle keep-alive connection — can have that response delivered to a later request on the same connection: the client parses data on a connection only against the next request sent on it (ResponseParsingMerge), so bytes that arrive with no request outstanding are held and parsed as the response to the next request. Every response involved still comes from the origin the application pointed the pool at, which it already trusts to answer those requests; no trust boundary is crossed, and nothing reaches a different pool or origin. An origin that desynchronises this way has a request-smuggling defect of its own, and a gateway that fans many users' requests onto it inherits that defect from the origin, not from Pekko HTTP. A report of this is BY-DESIGN: property-disclaimed. The pool already never reuses a connection after an early response — one that completes before the request entity is fully sent — and stops sending the request entity when that response is an error or carries Connection: close (#1350), so the leftover request body cannot be answered on a later request. Making the pool more defensive still against non-conforming origins — such as discarding a connection that receives data with no request outstanding — is hardening for an ordinary issue or PR, not a security report. Still in scope: a response crossing between pools or origins, or the client framing a conformant origin's response by a different rule than RFC 9112 — Pekko HTTP's own framing decision, as in §9. (maintainer)
| Existing statement | Source | Lands in |
|---|---|---|
| Applications should not be exposed to the public internet directly | security.md |
§3, §4, §10.1 |
| Behaves "pretty well" under most known DoS attacks — scoped to volume by §14 Q1 | security.md + maintainer ruling |
§4, §9, §11a, §13, §14 Q1 |
| An enterprise-grade routing solution or LB (httpd, Nginx) is safer | security.md |
§5, §10.1 |
| Report privately per ASF guidelines; subscribe to announce@ | security.md |
SECURITY.md, §1 |
Parsing limits (max-uri-length, max-header-*, max-chunk-*, max-part-count, …) |
http-core/reference.conf |
§5a, §8 P1 |
idle-timeout is a bidirectional inactivity timeout, not a request-receive deadline |
http-core/reference.conf, timeouts.md |
§8 P5, §9 |
error-logging-verbosity = full logs the failing request target at warning level |
http-core/reference.conf, UriParser.fail, DefaultParsingErrorHandler, logParsingError |
§5a, §9, §10.9 |
IllegalRequestContext.rawRequestTarget is unvalidated, attacker-controlled input |
ParsingErrorHandler.scala |
§6, §11 |
verbose-error-messages = off |
http-core/reference.conf |
§5a, §8 P3 |
Illegal response header name/value processing = error |
http-core/reference.conf |
§5a, §8 P2 |
uri-parsing-mode = strict, cookie-parsing-mode = rfc6265 |
http-core/reference.conf |
§5a, §8 P4 |
| Timeouts and connection caps | http-core/reference.conf |
§5a, §8 P5 |
max-concurrent-streams = 256 |
http-core/reference.conf |
§5a, §8 P6 |
max-header-list-size = 64 KiB, bounding HEADERS + CONTINUATION accumulation |
http-core/reference.conf |
§5a, §8 P7 |
frame-type-throttle charging RST_STREAM and empty DATA frames without END_STREAM by default, against Rapid Reset (CVE-2023-44487) and Empty Frames Flood (CVE-2019-9518) |
http-core/reference.conf |
§5a, §8 P6 |
HTTP/2 max-frame-size, incoming buffer bounds and outgoing-control-frame-buffer-size |
http-core/reference.conf |
§5a, §8 P1 |
Raw-Request-URI must be visible ASCII and a custom method a token; neither should be built from request input |
http-model.md, headers.scala, HttpMethod.scala |
§11 |
Decoding limits (decode-max-bytes-per-chunk, decode-max-size), applied by the decodeRequest* directives |
http/reference.conf, CodingDirectives.scala |
§5a, §9 |
Credentials.verify compares via constant-time secure_== |
SecurityDirectives.scala, EnhancedByteArray.scala |
§7, §8 P8, §9, §10.4, §14 Q5 |
A request field that fails to parse into the model is answered with a 400 on its own HTTP/2 stream; pseudo-header and connection-specific-header violations close the connection with GOAWAY |
RequestErrorFlow.scala, RequestParsing.protocolError, Http2Blueprint.errorHandling |
§8 P9 |
safeDirectoryChildPath rejects ../separator segments and enforces canonical containment |
FileAndResourceDirectives.scala |
§9, §14 Q3 |
remote-address-attribute = off |
http-core/reference.conf |
§5, §9, §14 Q4 |
extractClientIP reads X-Forwarded-For/X-Real-Ip; extractDirectClientIP reads the attribute alone |
MiscDirectives.scala |
§5, §6, §9, §10.5, §11a, §14 Q4 |
CORS: * + credentials echoes the request Origin |
http-cors/reference.conf |
§5a, §9, §11a, §14 Q2 |
http-cors code donated by Lomig Mégard, defaults inherited with it |
legal/CorsNotice.txt, NOTICE |
§5b, §14 Q2 |