github.com/outbrain/consul@v1.4.5/website/source/docs/internals/security.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Security Model"
     4  sidebar_current: "docs-internals-security"
     5  description: |-
     6    Consul relies on both a lightweight gossip mechanism and an RPC system to provide various features. Both of the systems have different security mechanisms that stem from their designs. However, the security mechanisms of Consul have a common goal: to provide confidentiality, integrity, and authentication.
     7  ---
     8  
     9  # Security Model
    10  
    11  Consul relies on both a lightweight gossip mechanism and an RPC system
    12  to provide various features. Both of the systems have different security
    13  mechanisms that stem from their designs. However, the security mechanisms
    14  of Consul have a common goal: to provide
    15  [confidentiality, integrity, and authentication](https://en.wikipedia.org/wiki/Information_security).
    16  
    17  The [gossip protocol](/docs/internals/gossip.html) is powered by [Serf](https://www.serf.io/),
    18  which uses a symmetric key, or shared secret, cryptosystem. There are more
    19  details on the security of [Serf here](https://www.serf.io/docs/internals/security.html).
    20  For details on how to enable Serf's gossip encryption in Consul, see the
    21  [encryption doc here](/docs/agent/encryption.html).
    22  
    23  The RPC system supports using end-to-end TLS with optional client authentication.
    24  [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) is a widely deployed asymmetric
    25  cryptosystem and is the foundation of security on the Web.
    26  
    27  This means Consul communication is protected against eavesdropping, tampering,
    28  and spoofing. This makes it possible to run Consul over untrusted networks such
    29  as EC2 and other shared hosting providers.
    30  
    31  ~> **Advanced Topic!** This page covers the technical details of
    32  the security model of Consul. You don't need to know these details to
    33  operate and use Consul. These details are documented here for those who wish
    34  to learn about them without having to go spelunking through the source code.
    35  
    36  ## Secure Configuration
    37  
    38  The Consul threat model is only applicable if Consul is running in a secure
    39  configuration. Consul does not operate in a secure-by-default configuration. If
    40  any of the settings below are not enabled, then parts of this threat model are
    41  going to be invalid. Additional security precautions must also be taken for
    42  items outside of Consul's threat model as noted in sections below.
    43  
    44  * **ACLs enabled with default deny.** Consul must be configured to use ACLs with
    45    a whitelist (default deny) approach. This forces all requests to have explicit
    46    anonymous access or provide an ACL token.
    47  
    48  * **Encryption enabled.** TCP and UDP encryption must be enabled and configured
    49    to prevent plaintext communication between Consul agents. At a minimum,
    50    `verify_outgoing` should be enabled to verify server authenticity with each
    51    server having a unique TLS certificate. `verify_server_hostname` is also
    52    required to prevent a compromised agent restarting as a server and being given
    53    access to all secrets.
    54  
    55      `verify_incoming` provides additional agent verification via mutual
    56    authentication, but isn't _strictly_ necessary to enforce the threat model
    57    since requests must also contain a valid ACL token. The subtlety is that
    58    currently `verify_incoming = false` will allow servers to still accept
    59    un-encrypted connections from clients (to allow for gradual TLS rollout). That
    60    alone doesn't violate the threat model, but any misconfigured client that
    61    chooses not to use TLS will violate the model. We recommend setting this to
    62    true. If it is left as false care must be taken to ensure all consul clients
    63    use `verify_outgoing = true` as noted above, but also all external API/UI
    64    access must be via HTTPS with HTTP listeners disabled.
    65  
    66  ### Known Insecure Configurations
    67  
    68  In addition to configuring the non-default settings above, Consul has several
    69  non-default options that potentially present additional security risks.
    70  
    71  * **Script checks enabled with network-exposed API.** If a Consul agent (client
    72    or server) exposes its HTTP API to the network beyond localhost,
    73    [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) must
    74    be `false` otherwise, even with ACLs configured, script checks present a
    75    remote code execution threat.
    76    [`enable_local_script_checks`](/docs/agent/options.html#_enable_local_script_checks)
    77    provides a secure alterative if the HTTP API must be exposed and is available
    78    from 1.3.0 on. This feature was also back-ported to patch releases 0.9.4,
    79    1.1.1, and 1.2.4 [as described here](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations).
    80  
    81  * **Remote exec enabled.** Consul includes a [`consul exec`
    82    feature](/docs/commands/exec.html) allowing execution of arbitrary commands
    83    across the cluster. This is disabled by default since 0.8.0. We recommend
    84    leaving it disabled. If enabled, extreme care must be taken to ensure correct
    85    ACLs restrict access, for example any management token grants access to
    86    execute arbitrary code on the cluster.
    87  
    88  * **Verify Server Hostname Used Alone.** From version 0.5.1 to 1.4.0 we documented that
    89    `verify_server_hostname` being `true` _implied_ `verify_outgoing` however due
    90    to a bug this was not the case so setting _only_ `verify_server_hostname`
    91    results in plaintext communciation between client and server. See
    92    [CVE-2018-19653](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19653)
    93    for more details. This is fixed in 1.4.1.
    94  
    95  ## Threat Model
    96  
    97  The following are parts of the Consul threat model:
    98  
    99  * **Consul agent-to-agent communication.** Communication between Consul agents should be secure from eavesdropping. This requires transport encryption to be enabled on the cluster and covers both TCP and UDP traffic.
   100  
   101  * **Consul agent-to-CA communication.** Communication between the Consul server and the configured certificate authority provider for Connect is always encrypted.
   102  
   103  * **Tampering of data in transit.** Any tampering should be detectable and cause Consul to avoid processing the request.
   104  
   105  * **Access to data without authentication or authorization.** All requests must be authenticated and authorized. This requires that ACLs are enabled on the cluster with a default deny mode.
   106  
   107  * **State modification or corruption due to malicious messages.** Ill-formatted messages are discarded and well-formatted messages require authentication and authorization.
   108  
   109  * **Non-server members accessing raw data.**  All servers must join the cluster (with proper authentication and authorization) to begin participating in Raft. Raft data is transmitted over TLS.
   110  
   111  * **Denial of Service against a node.** DoS attacks against a node should not compromise the security stance of the software.
   112  
   113  * **Connect-based Service-to-Service communication.** Communications between two Connect-enabled services (natively or by proxy) should be secure from eavesdropping and provide authentication. This is achieved via mutual TLS.
   114  
   115  The following are _not_ part of the Consul threat model for Consul server agents:
   116  
   117  * **Access (read or write) to the Consul data directory.** All Consul servers, including non-leaders, persist the full set of Consul state to this directory. The data includes all KV, service registrations, ACL tokens, Connect CA configuration, and more. Any read or write to this directory allows an attacker to access and tamper with that data.
   118  
   119  * **Access (read or write) to the Consul configuration directory.** Consul configuration can enable or disable the ACL system, modify data directory paths, and more. Any read or write of this directory allows an attacker to reconfigure many aspects of Consul. By disabling the ACL system, this may give an attacker access to all Consul data.
   120  
   121  * **Memory access to a running Consul server agent.** If an attacker is able to inspect the memory state of a running Consul server agent the confidentiality of almost all Consul data may be compromised. If you're using an external Connect CA, the root private key material is never available to the Consul process and can be considered safe. Service Connect TLS certificates should be considered compromised; they are never persisted by server agents but do exist in-memory during at least the duration of a Sign request.
   122  
   123  The following are _not_ part of the Consul threat model for Consul client agents:
   124  
   125  * **Access (read or write) to the Consul data directory.** Consul clients will use the data directory to cache local state. This includes local services, associated ACL tokens, Connect TLS certificates, and more. Read or write access to this directory will allow an attacker to access this data. This data is typically a smaller subset of the full data of the cluster.
   126  
   127  * **Access (read or write) to the Consul configuration directory.** Consul client configuration files contain the address and port information of services, default ACL tokens for the agent, and more. Access to Consul configuration could enable an attacker to change the port of a service to a malicious port, register new services, and more. Further, some service definitions have ACL tokens attached that could be used cluster-wide to impersonate that service. An attacker cannot change cluster-wide configurations such as disabling the ACL system.
   128  
   129  * **Memory access to a running Consul client agent.** The blast radius of this is much smaller than a server agent but the confidentiality of a subset of data can still be compromised. Particularly, any data requested against the agent's API including services, KV, and Connect information may be compromised. If a particular set of data on the server was never requested by the agent, it never enters the agent's memory since replication only exists between servers. An attacker could also potentially extract ACL tokens used for service registration on this agent, since the tokens must be stored in-memory alongside the registered service.
   130  
   131  * **Network access to a local Connect proxy or service.** Communications between a service and a Connect-aware proxy are generally unencrypted and must happen over a trusted network. This is typically a loopback device. This requires that other processes on the same machine are trusted, or more complex isolation mechanisms are used such as network namespaces. This also requires that external processes cannot communicate to the Connect service or proxy (except on the inbound port). Therefore, non-native Connect applications should only bind to non-public addresses.
   132  
   133  * **Improperly Implemented Connect proxy or service.** A Connect proxy or natively integrated service must correctly serve a valid leaf certificate, verify the inbound TLS client certificate, and call the Consul agent-local authorize endpoint. If any of this isn't performed correctly, the proxy or service may allow unauthenticated or unauthorized connections.
   134  
   135  ## External Threat Overview
   136  
   137  There are four components that affect the Consul threat model: the server agent, the client agent, the Connect CA, and Consul API clients (including proxies for Connect).
   138  
   139  The server agent participates in leader election and data replication via Raft. All communications with other agents is encrypted. Data is stored at rest unencrypted in the configured data directory. The stored data includes ACL tokens and TLS certificates. If the built-in CA is used with Connect, root certificate private keys are also stored on disk. External CA providers do not store data in this directory. This data directory must be carefully protected to prevent an attacker from impersonating a server or specific ACL user. We plan to introduce further mitigations (including at least partial data encryption) to the data directory over time, but the data directory should always be considered secret.
   140  
   141  For a client agent to join a cluster, it must provide a valid ACL token with node:write capabilities. The join request and all other API requests between the client and server agents communicate via TLS. Clients serve the Consul API and forward all requests to a server over a shared TLS connection. Each request contains an ACL token which is used for both authentication and authorization. Requests that do not provide an ACL token inherit the agent-configurable default ACL token.
   142  
   143  The Connect CA provider is responsible for storing the private key of the root (or intermediate) certificate used to sign and verify connections established via Connect. Consul server agents communicate with the CA provider via an encrypted method. This method is dependent on the CA provider in use. Consul provides a built-in CA which performs all operations locally on the server agent. Consul itself does not store any private key material except for the built-in CA.
   144  
   145  Consul API clients (the agent itself, the built-in UI, external software) must communicate to a Consul agent over TLS and must provide an ACL token per request for authentication and authorization.
   146  
   147  ## Network Ports
   148  
   149  For configuring network rules to support Consul, please see [Ports Used](/docs/agent/options.html#ports)
   150  for a listing of network ports used by Consul and details about which features
   151  they are used for.