From 59c741c3045a683cc0f52a03569444ab9e60b982 Mon Sep 17 00:00:00 2001 From: Justin Bertram Date: Tue, 26 May 2026 10:30:19 -0500 Subject: [PATCH] ARTEMIS-6077 document threat model --- docs/user-manual/_book.adoc | 1 + docs/user-manual/index.adoc | 1 + docs/user-manual/threat-model.adoc | 294 +++++++++++++++++++++++++++++ 3 files changed, 296 insertions(+) create mode 100644 docs/user-manual/threat-model.adoc diff --git a/docs/user-manual/_book.adoc b/docs/user-manual/_book.adoc index 57f40a88451..4f5e8160c0c 100644 --- a/docs/user-manual/_book.adoc +++ b/docs/user-manual/_book.adoc @@ -79,6 +79,7 @@ include::jms-bridge.adoc[leveloffset=1] //== Security +include::threat-model.adoc[leveloffset=1] include::security.adoc[leveloffset=1] include::masking-passwords.adoc[leveloffset=1] include::resource-limits.adoc[leveloffset=1] diff --git a/docs/user-manual/index.adoc b/docs/user-manual/index.adoc index 86d460b8429..8f4e76bc946 100644 --- a/docs/user-manual/index.adoc +++ b/docs/user-manual/index.adoc @@ -88,6 +88,7 @@ image::images/artemis_text_black_small.png[align="center"] == Security +* xref:threat-model.adoc#threat-model[Threat Model] * xref:security.adoc#authentication-authorization[Authentication & Authorization] * xref:masking-passwords.adoc#masking-passwords[Masking Passwords] * xref:resource-limits.adoc#resource-limits[Limiting Resource Utilization] diff --git a/docs/user-manual/threat-model.adoc b/docs/user-manual/threat-model.adoc new file mode 100644 index 00000000000..8800b117201 --- /dev/null +++ b/docs/user-manual/threat-model.adoc @@ -0,0 +1,294 @@ += Threat Model +:idprefix: +:idseparator: - +:docinfo: shared + +This document defines the security boundaries, assumptions, and guarantees of Apache Artemis. +It serves as the authoritative reference for triaging security reports, guiding secure deployments, and understanding which threats Artemis defends against versus which are the responsibility of operators and applications. + +Security researchers, operators deploying Artemis in production, and application developers integrating with the broker should consult this model to understand the security contract. + +Findings should be reported per link:https://artemis.apache.org/security-advisories[Artemis' security disclosure process]. +Findings that that fall under <> will be accepted. +Findings that are <> or involve security properties <> will be closed citing this document. + +== Scope and Intended Use + +=== Versioning + +This threat model is versioned alongside Artemis. +A security report against project version _N_ is triaged against the model *as it stood at _N_*. + +=== Primary intended use cases + +* Multi-protocol message broker for enterprise messaging systems +* Pub/sub and point-to-point messaging topologies +* Integration hub for heterogeneous client environments (Java, C++, Python, JavaScript, .NET) + +=== Deployment contexts + +* Standalone +* Embedded broker within another Java application + +=== Actors + +==== Client actors + +Artemis distinguishes between two main client actors (network/API callers): + +* *Messaging* — send and consume messages via supported messaging protocols +* *Management* — invoke management operations via web console, JMX, Jolokia HTTP, or management messages + +==== Operator actor + +* *Operator* — has filesystem or physical access to the broker (can edit `broker.xml`, access journal files, restart the broker process). +This is not a "client" actor because there is no network call; the operator interacts directly with the host system. + +=== Component-Family Table + +[cols="2,4,2,1"] +|=== +| Family | Representative API/Entry Point | Touches External Resources? | In Model? + +| Broker Core +| Core protocol handler, journal, paging, routing engine +| Yes — filesystem (journal, paging), network (bridges, federation) +| *Yes* + +| Protocol Adapters +| AMQP, MQTT, STOMP, OpenWire, Core protocol implementations +| Yes — network +| *Yes* + +| Management APIs +| JMX MBeans, Jolokia HTTP, Management messages +| Yes — network (JMX/HTTP), local JMX +| *Yes* + +| Client Libraries +| Core client, JMS 2.0 client, Jakarta Messaging 3.1 client +| Yes — network (to broker) +| *Partial* +|=== + +== Out of Scope + +=== Use cases Artemis does not support + +* Message broker as a cryptographic confidentiality boundary — the broker has access to plaintext message payloads; end-to-end encryption between message producers and consumers must be implemented outside the broker. +* Defense against malicious operators with filesystem or JVM access — an operator with filesystem access can read journal files, modify configuration, or attach a debugger. +* Real-time guarantees or bounded latency — the broker is designed for reliability, not hard real-time performance. +* Byzantine fault tolerance in clustered deployments beyond simple fail-stop failures — the clustering model assumes cluster nodes are honest or fail-stop, not adversarial. + +=== Threats Artemis does not attempt to defend against + +* Attacks requiring local JVM access (e.g., agent attachment, debugger, `-javaagent` instrumentation). +* Physical or hypervisor-level attacks on the host. +* Side-channel attacks (timing, speculative execution) on message metadata or routing decisions. +* Denial-of-service via resource exhaustion at OS level (e.g., file descriptor limits, kernel OOM) — operators must configure OS limits. + +=== Code that ships but is not covered by this model + +* Third-party dependencies (Netty, JGroups, etc.) — threat-modeled separately by their respective projects. + +== Trust Boundaries and Data Flow + +=== Primary trust boundary + +Data enters the broker via: + +. *Network messaging protocols* (AMQP/MQTT/STOMP/OpenWire/Core) from messaging clients. +HTTP connections can upgrade to Core protocol. +AMQP, MQTT, and STOMP support WebSocket as a transport. +Beyond these specific upgrade/transport paths, protocol switching is not allowed. +. *Management interfaces* (JMX, Jolokia HTTP, management messages) from management clients +. *Filesystem reads* (configuration files, journal replay, paged messages) by operator or broker process + +=== Trust transitions + +. *Messaging Client → Broker Core:* Messages from network clients (untrusted or authenticated) are parsed by protocol adapters and routed to the broker core. +Authentication happens at connection establishment; authorization happens per operation (send, consume, create queue, etc.). +. *Management Client → Broker Core:* Management operations from management clients are subject to RBAC. +. *Broker Core → Filesystem:* Broker writes to append-only journal and paging files; integrity of persisted data depends on filesystem and OS guarantees. + +=== Reachability preconditions per component + +* *Protocol Adapters:* A finding is in-model only if reachable from network input on the corresponding protocol port without requiring authenticated management credentials. +* *Broker Core:* A finding is in-model if reachable from messaging client-controlled payloads, headers, or addressing metadata. +* *Management APIs:* A finding is in-model if reachable from an authenticated management client's request. + +== Assumptions About the Environment + +=== Operating system and runtime + +* The broker assumes a conformant JVM (Java 17 or later). +* The broker assumes the OS provides standard filesystem semantics (atomicity of writes < page size, durability after fsync). +* The broker assumes the OS enforces process isolation (no untrusted local processes can ptrace or inject code). + +=== Concurrency + +* The broker is designed to be thread-safe for concurrent client connections. +* The broker assumes the JVM correctly implements Java's multi-threading semantics (thread synchronization, memory visibility between threads, safe publication of shared data). +A JVM with broken concurrency primitives could cause race conditions in authentication, authorization, or message routing. +* Runtime configuration reload (`broker.xml`, `security-settings`) is safe under load. +Configuration changes do not cause inconsistent state or authorization bypass during reload. + +=== Filesystem assumptions + +* The broker assumes it has exclusive write access to its data directory (journal, paging, bindings). +* The broker assumes the filesystem does not arbitrarily corrupt data (bit flips, silent data corruption). *Note:* The broker performs no integrity checks on persisted data (see <>); corruption is not detected. +Operators requiring corruption detection must use OS-level mechanisms (ZFS checksums, dm-integrity, etc.). +* The broker uses libaio on Linux for high-performance journal writes; it assumes libaio behaves correctly. + +=== Network assumptions + +* The broker does not assume confidentiality or integrity of network traffic unless TLS/SSL is configured. +* The broker assumes the network can deliver or drop packets but does not inject malicious packets from non-client sources (i.e., no on-path attacker at IP layer unless TLS mitigates). + +=== What Artemis does _not_ do to its host + +* Does not install signal handlers beyond standard JVM handlers +* Does not spawn child processes in normal operation (CLI tools may spawn broker as child, but the broker itself does not spawn processes) +* Does not mutate process-wide JVM state (locale, timezone, default charset) beyond standard JVM behavior +* Does not modify system-wide state (iptables, kernel modules, global system properties) +* Does not open listening sockets on ports other than those explicitly configured + +== Configuration Variants + +[cols="1,1,3"] +|=== +| Knob | Default | Impact + +| `security-enabled` +| `true` +| When `false`, disables all authentication and authorization + +| `sslEnabled` +| `false` +| When `true`, provides transport confidentiality and integrity + +| `needClientAuth` +| `false` +| When `true`, enforces mutual TLS at the transport layer before any protocol interaction. Completely prevents unauthenticated network attackers from establishing connections. Stronger than protocol-level authentication as it operates at the TLS handshake. + +| Management RBAC +| enabled +| Enables fine-grained permissions on management operations +|=== + +== Adversary Model + +=== Adversaries in Scope + +. *Unauthenticated network attacker:* +.. *When mutual TLS is enforced:* This threat is *completely eliminated*. +The attacker cannot establish a network connection without a TLS certificate signed by a trusted CA. +Enforcement happens at the transport layer during the TLS handshake, before any protocol interaction. +.. *When authentication is enforced*: Cannot meaningfully interact without authentication. +Unauthenticated connection attempts are rejected at the protocol level (e.g., MQTT `CONNECT` with invalid credentials) before any messaging operations are permitted. +However, the attacker can still establish network connections and send protocol frames/packets up to the authentication step; attempt authentication with guessed credentials; attempt DoS via connection exhaustion or malformed input during connection or authentication phase. +. *Authenticated messaging client (low-privilege):* Has valid credentials but limited authorization (e.g., can send to specific addresses but not manage the broker). +Can attempt privilege escalation via protocol exploits or misuse of broker features. +. *Authenticated management client (low-privilege):* Has valid credentials but limited authorization; connects via web console, JMX, Jolokia HTTP, or management messages. +Can potentially read broker state and metrics, enumerate queues, addresses, connections, and consumers, view message counts, etc.; monitor broker performance. +Can attempt to exploit management API vulnerabilities to gain elevated privileges; denial of service via management interface abuse. + +=== Adversaries Out of Scope + +. *Malicious operator with filesystem or JVM access:* An operator with filesystem write access to the data directory, ability to attach a debugger, or `kill -9` access can read/modify all data, bypass all security controls, and cause arbitrary behavior. +The broker does not defend against malicious operators. +. *Side-channel observers:* Timing attacks on message routing, cache-timing on authentication, speculative execution side channels. +. *Co-tenant attackers in shared JVM:* If multiple applications share the same JVM and classpath, the broker does not defend against malicious code in the same JVM. +. *On-path network attacker:* Physical access to network infrastructure; mitigated by TLS. +. *Clients with full admin permissions:* Such a client can perform any management operation, including reading message content. +Reports about admin capabilities (e.g., "admin can read messages") are triaged as `BY-DESIGN`. +. *When `security-enabled=false`:* Can send arbitrary protocol messages and perform messaging or management operations without authentication. +This configuration is not supported in production. +Reports against such deployments with are triaged as `OUT-OF-SCOPE`. + +== Security Properties Provided + +. *Authentication of messaging & management clients:* When just `security-enabled=true` then protocol-level authentication is enforced (e.g. via username & password, JWT, etc.). +However, when TLS client certificate authentication is also enabled then transport-layer authentication during TLS handshake is enforced. +TLS client certificates provide stronger authentication as they prevent unauthenticated clients from establishing any connection. +. *Authorization of messaging clients:* When `security-enabled=true` and `security-settings` are configured. +. *Authorization for management clients:* When `management-message-rbac=true` *or* `management.xml` is configured appropriately and `security-settings` are in place. +. *Confidentiality and integrity of messages in transit:* When `sslEnabled=true` on the relevant `acceptor`. + +== Security Properties Not Provided + +. *End-to-end confidentiality of message payloads:* The broker has access to plaintext message bodies. +If message payloads must be kept confidential from the broker operator, the application must implement application-layer encryption. +. *Authentication of message content origin:* The broker authenticates the _connection_ that sends a message, not the message itself. +A compromised client or a client authorized to send to an address can claim to be any logical sender. +Applications requiring non-repudiation must implement message signing. +. *Comprehensive per-client message rate limiting across all protocols:* Message rate limiting is available for Core and MQTT 5 clients, but *not* for AMQP, STOMP, OpenWire, or MQTT 3.x clients. +Clients using protocols without rate limiting can send messages at line rate until paging or disk space limits are enforced. +Operators must use network-level controls for protocols that lack broker-side rate limiting. +. *Memory growth within paging limits:* Memory consumption that grows with messages up to configured paging limits is expected behavior, not a DoS vulnerability. +However, super-linear CPU consumption or hangs on pathological input *are* bugs. +. *Byzantine fault tolerance in clustering:* Clustered deployments assume peer brokers are honest or fail-stop. +If a peer broker is compromised and sends adversarial messages, the cluster may enter an inconsistent state. +Byzantine fault tolerance is not provided. +. *Protection against operator-level attacks:* An operator with filesystem access can read all persisted messages, modify configuration to grant themselves any role, or inject/modify messages in the journal. +The broker does not validate journal or paging file integrity; tampering is not detected. + +== Downstream Responsibilities + +=== For operators deploying the broker + +. *Enable authentication and authorization:* Set `security-enabled=true`. +. *Configure TLS for network exposure:* If the broker is exposed to an untrusted network, enable SSL/TLS on all protocol ports. +Use strong cipher suites and disable weak protocols (SSLv3, TLS 1.0, TLS 1.1) to prevent protocol downgrade attacks. +The broker inherits TLS configuration from the JVM; insecure TLS settings expose credentials and message content. +. *Consider mutual TLS for high-security deployments:* Enable `needClientAuth=true` on acceptors to require clients to present valid certificates during the TLS handshake. +This provides transport-layer authentication that completely eliminates unauthenticated network attackers since they cannot establish connections without valid certificates. +This is stronger than protocol-level authentication because the TLS handshake is enforced before any messaging protocol interaction, preventing connection establishment attacks and protocol-level authentication bypass attempts. +Recommended for internet-facing brokers or environments with untrusted networks. +. *Restrict filesystem access:* Ensure the broker's data directory (journal, paging, etc.) is readable/writable only by the broker process user. +The broker performs no strict integrity checks on journal/paging files; filesystem permissions are the only protection against tampering and message injection via configuration manipulation. +An attacker who can write to `broker.xml` can reconfigure `security-settings` and bypass all authorization. +An attacker who can copy journal files can replay persisted messages on another broker instance. +Consider OS-level integrity mechanisms (filesystem checksums, dm-integrity, read-only snapshots for backups) if corruption detection or replay prevention is required. +. *Restrict management interface access:* JMX is *not exposed on the network by default*. +If you configure remote JMX or Jolokia HTTP access, ensure authentication and TLS are enabled; prefer localhost-only binding for management interfaces exposed to untrusted networks. +. *Review and harden JAAS configuration:* If using JAAS, ensure login modules are correctly configured and credentials are not embedded in cleartext files with world-readable permissions. +. *Set resource limits at OS level:* Configure ulimits (file descriptors, memory) to prevent resource exhaustion. +. *Implement rate limiting for protocols that lack broker-side support:* AMQP, STOMP, OpenWire, and MQTT 3.x clients do not support broker-side message rate limiting. +Use network-level rate limiting (firewall rules, load balancer limits) or connection throttling to prevent message-flooding DoS from these protocols. +Core and MQTT 5 clients support rate limiting. +. *Do not disable security in production:* Do not set `security-enabled=false` in production. +This setting is dev-only. + +=== For applications using the broker + +. *Validate message content:* Applications must validate untrusted message content. +. *Implement application-layer encryption if needed:* If message confidentiality from the broker operator is required, encrypt payloads before sending. + +== Conditions That Might Change This Model + +. A new protocol is added — new parser, new attack surface. +. A new public API surface is exposed. +. A new deployment mode is supported (e.g., multi-tenancy in a single JVM with untrusted co-tenants). +. A default configuration value changes in a way that affects security (e.g., `security-enabled` default flips to `false`, or TLS ciphers change). +. A security property in <> is changed or disclaimed. +. A vulnerability report cannot be cleanly routed to one of the <> dispositions — this indicates a model gap. + +== Triage Dispositions + +[cols="2,4"] +|=== +| Disposition | Meaning + +| `VALID` +| Violates a <> and reachable via <>. Requires fixing and CVE assignment. + +| `OUT-OF-SCOPE` +| Requires an <>, <> outside the threat model. + +| `BY-DESIGN` +| Concerns a property Artemis <>. +Intentional behavior, not a vulnerability. +|=== + +*Note:* If a report cannot be cleanly assigned to one of these dispositions, the model has a gap and <>.