THREAT_MODEL.md

Actix Threat Model

This is a first-pass threat model for the Actix organization, adapted from the "Threat Modeling Template for Libraries" gist. It is intended to guide review and triage; it is not a complete audit.

1. Library Overview

Actix maintains Rust crates for building asynchronous web applications and network services. The main target repositories for this model are:

• actix/actix-web: the web framework and HTTP stack, including actix-web, actix-http, actix-router, actix-files, actix-multipart, WebSocket support, macros, test helpers, and the awc HTTP/WebSocket client.
• actix/actix-net: lower-level networking crates, including actix-server, actix-tls, actix-codec, actix-rt, actix-service, actix-utils, bytestring, and local async primitives.
• actix/actix-extras: middleware and integration crates, including CORS, sessions, identity, HTTP auth, rate limiting, protobuf extraction, settings, WebSockets, and tracing middleware.

Key public APIs include:

• App, HttpServer, Scope, Resource, Route, guards, middleware, and extractors such as Json, Form, Path, Query, Bytes, Payload, and multipart forms.
• Protocol and transport APIs in actix-http, actix-server, actix-tls, actix-codec, and awc.
• Security-relevant middleware in actix-session, actix-identity, actix-web-httpauth, actix-cors, and actix-limitation.
• Proc macros in actix-macros, actix-web-codegen, and actix-multipart-derive.

2. Scope

In scope:

• Library behavior reachable through public APIs in actix-web, actix-net, and actix-extras.
• Security properties of generated routing/runtime code.
• Parsing, routing, static file serving, body streaming, compression, decompression, TLS, WebSockets, client requests, session/auth middleware, rate limiting, and structured logging.
• Supply chain and release integrity for Actix-owned crates, source, tags, GitHub Actions workflows, advisories, and crates.io publication.

Out of scope for this pass:

• Vulnerabilities that exist only in applications using Actix incorrectly.
• Community crates listed by Actix but not maintained in the Actix organization.
• The standalone actix/actix actor crate, including actor mailboxes, supervision, actor lifecycle, and actor runtime semantics. It should receive a separate threat model if it is treated as a main target.
• Actix website hosting and documentation infrastructure except where docs can materially create insecure defaults or misleading security guidance.
• Unsupported crate versions except as advisory range context.

3. Conceptual System Diagram

flowchart LR
    attacker[Remote client or peer] --> app[Application using Actix]
    developer[Developer / maintainer] --> repo[GitHub repositories]
    repo --> ci[GitHub Actions]
    ci --> crates[crates.io releases]
    crates --> app

    app --> web[actix-web APIs]
    web --> router[Routing, guards, middleware]
    web --> extractors[Extractors and body streams]
    web --> files[actix-files]
    web --> http[actix-http]
    http --> net[actix-net server, TLS, runtime]
    app --> extras[actix-extras middleware]
    extras --> redis[Redis / backing stores]
    app --> awc[awc outbound client]
    awc --> upstream[External upstream services]

    web --> deps[Third-party crates]
    net --> deps
    extras --> deps

    classDef boundary fill:#fff,stroke:#333,stroke-width:2px;
    class attacker,developer,upstream,redis,crates,deps boundary;

Loading

Primary trust boundaries:

• Network peers to actix-net/actix-http protocol parsing.
• Request data to application handlers through extractors and middleware.
• Application configuration to security behavior such as TLS, CORS, sessions, body limits, host handling, and file roots.
• Local filesystem access through actix-files and Unix socket support.
• Redis or other session/rate-limit stores to actix-extras.
• Application-controlled URLs to awc outbound connections.
• Maintainers, CI, dependencies, and crates.io publication.

4. Assets

• Integrity of Actix APIs and security-relevant defaults.
• Confidentiality and integrity of request bodies, response bodies, cookies, session state, authorization headers, client TLS configuration, and logs.
• Availability of applications that process hostile traffic through Actix.
• Filesystem boundaries for static file serving and Unix sockets.
• Correct routing and middleware ordering so authorization, CORS, and session state are applied where developers expect.
• Memory safety and async task correctness in unsafe or low-level primitives.
• Integrity of published crates, tags, changelogs, advisories, CI workflows, maintainer accounts, and crates.io credentials.
• Supported MSRV, build reproducibility, reviewed dependency sets, and the ability to ship Critical fixes without stranding supported users.
• Reputation and developer trust in Actix as a foundational dependency.

5. Threats

Component / API / Interaction	S - Spoofing	T - Tampering	R - Repudiation	I - Information Disclosure	D - DoS	E - Elevation of Privilege
HTTP parser, routing, guards, ConnectionInfo, host/scheme handling	Spoofed Host, forwarded headers, or peer identity if apps treat them as trusted	Malformed paths or headers alter route selection	Ambiguous logs if peer data is proxy-derived	Host, route, or error details leak through generated URLs or errors	Header storms, slow clients, route explosion	Bypassing virtual-host or method guards can reach unintended handlers
HTTP/1 request framing and proxy interop	Frontend/backend disagreement can spoof request boundaries	CL/TE ambiguity, duplicate Content-Length, chunked extensions, trailers, or Transfer-Encoding casing can tamper with message framing	Smuggled requests are difficult to attribute to the visible request	Smuggling can expose another user's response or internal endpoint behavior	Malformed chunked bodies and trailer abuse can tie up parsers	Request smuggling can bypass routing, auth, or proxy-layer controls
HTTP/2 framing and stream lifecycle	Stream state confusion can spoof request ownership	CONTINUATION, HPACK, pseudo-header, or reset sequencing bugs can alter request interpretation	Rapid stream churn weakens request attribution	Header compression or stream errors can leak state across streams if mishandled	CONTINUATION floods, Rapid Reset-style churn, excessive stream counts, and flow-control abuse	H2-to-H1 downgrade or h2c confusion can bypass controls applied to another protocol
Extractors: Json, Form, Query, Path, Payload, Bytes, protobuf	Caller-provided content type or path params spoof valid input	Deserialization quirks produce unexpected app state	Validation failures may not be logged by apps	Error bodies can reveal schema or internal parser detail	Large bodies, deeply nested payloads, slow streams, decompression bombs	Extractor order or fallback behavior can skip app-level auth/validation
Multipart and file upload support	User-controlled field names and filenames masquerade as trusted metadata	Filename/header metadata reused by apps can tamper with filesystem paths	Upload actions hard to attribute without app logging	Temporary file names, parser errors, or content metadata leak	Many parts, long boundaries, large fields, slow upload streams	Unsafe app handling of filename metadata can write outside intended roots
actix-files static serving	Request paths spoof legitimate asset paths	Symlinks, changing directories, Windows separators, alternate data streams, reserved names, or case-insensitive paths can alter served content	File access often not app-audited	Directory listings, hidden files, source maps, config files	Range requests, blocking file IO pressure, large directory listings	Misconfigured roots or guards expose protected files
Compression and decompression	Encodings can be spoofed through headers	Compressed variants can serve stale or unintended content	Limited attribution for compression negotiation	Size/timing differences may reveal content characteristics	Compression bombs or high CPU codecs	Content negotiation bugs can bypass middleware expectations
TLS acceptors/connectors and certificate roots	Wrong SNI/hostname/root store can spoof peers	Misconfigured TLS options alter transport guarantees	Failed handshakes may be weakly logged	Certificate or handshake errors can expose internal config	Handshake floods, expensive crypto, resolver stalls	Weak certificate validation in callers can enable MITM
awc outbound client	User-controlled URLs can spoof internal targets; root-store feature choice affects peer identity	Redirects, DNS, headers, cross-scheme redirects, or custom TLS connectors can alter outbound request meaning	Outbound requests may lack audit context	SSRF can expose metadata services or internal APIs	Slow upstreams, redirect loops, large responses	SSRF, disabled certificate verification in custom connectors, or dangerous-h2c misuse can reach privileged network locations
WebSockets in actix-http, actix-web-actors, actix-ws	Upgrade requests and subprotocols spoof expected clients	Frame fragmentation/control frames can alter message flow	Long-lived connections complicate audit trails	Cross-origin WebSocket use can leak app data	Unbounded sessions, frame buffering, ping/pong abuse	Missing origin/auth checks in apps can expose privileged channels
Sessions and identity (actix-session, actix-identity)	Forged or replayed cookie-backed state or Redis session keys	Weak keys, signed-only cookie-backed state, Redis store tampering, or stale TTL updates can alter identity	Logout/renewal actions may be hard to prove	Signed cookie-backed stores are readable by clients; Redis-backed stores can leak through logs or errors	Cookie size limits, Redis outages, large session state, and TTL refresh load	Session fixation, stale identity, or fail-open store handling can become auth bypass
HTTP auth, CORS, and rate limiting extras	Spoofed origins, auth schemes, IP keys, or proxy headers	Misconfigured CORS or limiter keys alter policy	Rejected auth/limit events may not be recorded	CORS or auth errors reveal policy	Redis-backed limiting can fail open/closed or overload stores	CORS/auth middleware ordering errors can expose protected routes
Tracing/logging middleware	Request IDs or trace headers can spoof correlation	Log injection through headers or paths	Missing canonical request IDs reduce non-repudiation	Authorization headers, cookies, query strings, or PII in logs	High-cardinality fields or large logs exhaust storage	Leaked tokens from logs enable later privilege use
Low-level runtime, codecs, unsafe blocks, local channels/wakers	N/A	Broken invariants in unsafe APIs can corrupt state	N/A	Memory safety issues can disclose memory	Panics, wakeup bugs, queue growth, worker limits	Memory corruption can become arbitrary code execution
Proc macros and generated code	Macro input can spoof handler visibility or route metadata	Generated route/runtime code can differ from developer expectations	Generated code is harder to audit after expansion	Compiler diagnostics can leak local paths	Pathological macro input can slow builds	Codegen bugs can expose handlers or weaken guards
Dependencies and feature flags	Malicious dependency or typosquat spoofs trusted crate	Compromised dependency tampers with build/runtime behavior; feature drift can silently widen attack surface	Hard to prove which dependency version was used without lock context	Dependency logs/errors leak data	Vulnerable parsers/codecs/TLS crates cause runtime DoS	Build scripts/proc macros execute with developer/CI privileges; advisory tooling MSRV drift can block fixes
GitHub Actions, releases, crates.io publication	Compromised maintainer, token, or workflow identity	Tags, release artifacts, advisories, or crates can be modified	Ambiguous release provenance	CI logs can expose secrets	CI abuse blocks releases or drains maintainer time	Compromised publish credentials affect all downstream users

6. Mitigations and Risk Ranking

Risk labels in this first pass are prioritization shorthand, not a full likelihood-by-impact score. A later pass should split likelihood, impact, and confidence for each row.

Risk	Threat Area	Countermeasures
High	HTTP/1 request smuggling and framing ambiguity	Add regression tests for CL/TE disagreement, duplicate Content-Length, chunked trailers, casing variants, invalid chunk extensions, proxy-style keep-alive reuse, and historical smuggling-adjacent advisories.
High	HTTP/2 frame and stream exhaustion	Test CONTINUATION limits, Rapid Reset-style churn, max concurrent streams, HPACK limits, flow-control stalls, h2c upgrade behavior, and H2-to-H1 downgrade paths.
High	Parser, extractor, multipart, WebSocket, and compression DoS	Keep default body and buffer limits explicit; add regression tests for maximum header counts, large paths, multipart boundary edge cases, decompression ratios, frame fragmentation, and slow-stream behavior.
High	Static file boundary escapes or unintended disclosure	Preserve canonicalization and traversal tests; keep directory listings disabled by default; test symlink, hidden file, percent-encoding, Unicode path, Windows path semantics, range, and pre-compressed variant behavior.
High	Session/auth integrity bugs	Keep encrypted session cookies as the default; document key management; test signed/private cookies, rotation expectations, TTL renewal, logout purge behavior, Redis failure modes, and session fixation cases.
High	Release integrity	Require 2FA for maintainers, least-privilege GitHub Actions permissions, protected release branches/tags, minimal publish credentials, private advisory handling, build reproducibility checks where practical, and coordinated RustSec/GHSA publication for real vulnerabilities.
High	Unsafe and low-level async invariants	Require comments or tests that capture invariants for unsafe blocks in actix-net, bytestring, actix-files, HTTP/2 header construction, and WebSocket pinning; fuzz parsers/codecs where practical.
Medium	Host, scheme, proxy, and origin spoofing	Document that forwarded headers and Host are untrusted unless normalized by trusted proxy middleware; test Host guards, generated URLs, CORS origins, WebSocket origins, and rate-limit key extraction.
Medium	SSRF and TLS misuse through awc	Make examples avoid passing user URLs directly; document allow-listing, DNS/IP filtering, redirect policy including cross-scheme redirects, response limits, timeouts, metadata-service blocking, root-store feature selection, and the risk of custom connectors that disable verification.
Medium	TLS configuration mistakes	Prefer current Rustls versions in examples; keep older TLS features only when needed; test hostname validation, SNI, root store choices, ALPN, h2/h2c behavior including dangerous-h2c, and handshake timeout/load behavior.
Medium	Middleware ordering surprises	Add docs and examples for security middleware ordering; test common compositions: auth before handlers, session before identity, CORS preflight with auth, rate limiting before expensive extractors.
Medium	Logging and tracing leaks	Redact or avoid logging cookies, authorization headers, query secrets, and session data in examples; provide guidance for safe request IDs and bounded-cardinality fields.
Medium	Dependency compromise or vulnerable transitive crates	Keep deny.toml, lockfiles, and existing cargo-deny CI checks under review; consider cargo-audit, cargo-vet, or cargo-crev if maintainer capacity allows; minimize default features; review build scripts and proc-macro dependencies as executable code; track advisory tooling MSRV so security checks keep running.
Low	Repudiation inside library internals	Actix middleware should not be marketed as audit logging, but examples and middleware should make it easy for applications to attach stable request IDs without trusting attacker-controlled values.

7. Review Triggers

Revisit this model when:

• A parser, extractor, router, file-serving, TLS, WebSocket, compression, or session storage implementation changes.
• A new default feature is added or an existing default is removed.
• A proc macro starts generating security-relevant routing, guard, or middleware code.
• A new dependency adds native code, build scripts, proc macros, TLS, DNS, compression, parsing, or storage behavior.
• Release automation, maintainer permissions, advisory process, or crates.io publishing changes.
• A Critical or High incident is handled under INCIDENT_RESPONSE.md.