Work in progress

src/reference/modules/administration/pages/security.adoc

@@ -1,90 +1,54 @@
-= Network security
+= Security
 
-Communication between servers and nodes uses two channels:
-
-* HTTPS from nodes to servers
-* Custom protocol wrapped in TLS on tcp/5309, from nodes to server to
-download policies and (optionally) from server to nodes to trigger runs.
-
-Both enforce using TLS 1.2+.
-
-We recommend using a VPN for all communications between node and server
-if on a public network. If it's not the case, it's necessary to follow the following
-guide to improve security level.
+== Hardening configuration
 
-== Authentication mechanisms
+Rudder provides secure defaults whenever possible, but depending on your use case you can
+add additional configurations to make your Rudder installation more secure.
 
-=== Credentials
+=== Server
 
-On all agents and relays, and servers:
+==== Web application
 
-* `/var/rudder/cfengine-community/ppkeys/localhost.priv`, the node's private key, that allows the node to download its policies. It is a 4096-bit RSA key.
-* `/var/rudder/cfengine-community/ppkeys/localhost.pub`, the node's public key
-* `/opt/rudder/etc/agent.cert`, the node's certificate. It is embedded in inventories and signs inventories and compliance reports.
-
-Only on servers and relays:
-
-* `/opt/rudder/etc/rudder.key`, the HTTP server's private key. It is a 2048-bit RSA key by default.
-* `/opt/rudder/etc/rudder.crt`, the HTTP server's certificate chain. It is generated as a self-signed certificate at server installation. See procedure below to replace it by a valid one.
-
-=== Policy update and remote run (tcp/443)
-
-This protocol is used for:
-
-* Policy download on Linux and AIX nodes
-* Remote run from policy servers to nodes
-
-It uses the key pairs in `/var/rudder/cfengine-community/ppkeys/` to authenticate the node and server during
-communication.
-
-==== Server authentication
-
-The server is trusted by the node at first connection ("Trust On First Use") by default, but you can provide a public
-key to pre-establish trust (see guide below).
+* _HTTP Strict Transport Security_ (HSTS) allows ensuring the user's browser will always use HTTPS to connect to your server. It is not enabled by default as it may conflict with other services served from the same domain (e.g. package repositories). If you only use HTTPS with your Rudder's server domain, you can enable the HSTS header in `/opt/rudder/etc/rudder-web.properties` by modifying or adding the following property:
 
-==== Agent authentication
+[source,ini]
+----
+rudder.server.hsts=true
+----
 
-The first inventory sent by the node contains it's public key (apart of its certificates). Once accepted,
-it's policies are only available to a node having the matching private key.
+* Session expiration is configured by default to 30 minutes of user inactivity. You may want to shorten this value in `/opt/rudder/etc/rudder-web.properties` by modifying or adding the following property:
 
-=== HTTPS
+[source,ini]
+----
+rudder.auth.idle-timeout=15 minutes
+----
 
-HTTPS is used for:
+* It is recommended to use an external authentication backend exposing an OpenID connect or OAUTH2 interface with a second authentication factor (TOTP, WebAuthn, etc.).
 
-* Sending inventories and reports from nodes to policy servers
-* Remote-run trigger between root server and relays
-* File sharing between nodes and policy server
-* Policies and shared-files downloads on Windows nodes
+* In case you use local Rudder users, your passwords should be hashed with `bcrypt`. It may not be the case of you upgraded your server from pre-6.0 versions. You can see this value either in the user management page or `/opt/rudder/etc/rudder-users.xml`.
 
-==== Server authentication
+* You may want to hide the Apache httpd version from the headers. It cannot be done inside Rudder's configuration as it is a global parameter. To do so, you need to set the `ServerTokens` parameter to the `Prod` value (in `/etc/httpd` or `/etc/apache` depending on your distribution).
 
-Our HTTPS setup uses standard certificates, that are self-signed by default, and nodes
-do not verify their policy server's certificate when sending an inventory or a report.
+=== Agent
 
-Follow the guide below to replace them by valid certificates and enable certificate validation.
+Disable cf-serverd
 
-==== Agent authentication
+=== Network
 
-Inventories and reports are sent without client authentication at HTTP level, but they are signed the node's certificate,
-and checked on central server before being processed.
+==== Generalities
 
-For Windows policy and file download, HTTPS client authentication is done using the `agent.cert` node's certificate
-for allow allow access to the node with the matching private key.
+VPN for Rudder communications
 
-== Secure setup
+=== Pre-establish trust
 
 The following steps allows configuring Rudder to enforce certificate validation and
 establishing trust with pre-shared information during agent provisioning.
 
-=== Setup root server
+==== Setup root server
 
 To enforce secure communications with the nodes, follow these steps on the root server.
 
-==== Reporting
-
-Check that the reporting protocol is set to *HTTPS only*, as it enforces only accepting signed reports.
-
-==== Certificate
+===== Certificate
 
 Replace the default self-signed certificate by a valid one (i.e. recognized by the nodes) certificate in place in:
 
@@ -106,7 +70,7 @@ reports and inventories.
 Once enabled, all nodes will check the server's certificate before sending reports or inventories (after the first successful policy update). Next step will do the same
 for the first agent run, with initial policies.
 
-==== Initial policies
+===== Initial policies
 
 To enforce certificate verification from agent install (and not only after first generation and policy update), we need to modify initial policies served by the root server.
 
@@ -134,7 +98,7 @@ and in `/var/rudder/cfengine-community/masterfiles/rudder.json`:
 
 After these changes all new nodes will validate certificates from first run.
 
-=== Provisioning an agent with pre-established trust
+==== Provisioning an agent with pre-established trust
 
 This section expects that the server-side setup has been done. At allows going a bit further by providing a hash of the server key at installation
 to validate the server identity from the first connection, and avoid trusting the
@@ -176,3 +140,84 @@ C9o5xHCOTDecATXMg0gGQHbjm0x0a1nt+X1gyyjNfHLX13n5as9JXf0CAwEAAQ==
 
 Now you can set your policy server with `rudder agent policy-server mypolicyserver`
 and the agent will only accept the connection if it matches the provided key hash.
+
+
+
+
+
+
+
+
+
+== Security model
+
+Communication between servers and nodes uses two channels:
+
+* HTTPS from nodes to servers
+* On Unix only, custom protocol wrapped in TLS on tcp/5309, from nodes to server to
+download policies and (optionally) from server to nodes to trigger runs.
+
+Both enforce using TLS 1.2+.
+
+We recommend using a VPN for all communications between node and server
+if on a public network. If it's not the case, it's necessary to follow the following
+guide to improve security level.
+
+== Authentication mechanisms
+
+=== Credentials
+
+On all agents and relays, and servers:
+
+* `/var/rudder/cfengine-community/ppkeys/localhost.priv`, the node's private key, that allows the node to download its policies. It is a 4096-bit RSA key.
+* `/var/rudder/cfengine-community/ppkeys/localhost.pub`, the node's public key
+* `/opt/rudder/etc/agent.cert`, the node's certificate. It is embedded in inventories and signs inventories and compliance reports.
+
+Only on servers and relays:
+
+* `/opt/rudder/etc/rudder.key`, the HTTP server's private key. It is a 2048-bit RSA key by default.
+* `/opt/rudder/etc/rudder.crt`, the HTTP server's certificate chain. It is generated as a self-signed certificate at server installation. See procedure below to replace it by a valid one.
+
+=== Policy update and remote run (tcp/443)
+
+This protocol is used for:
+
+* Policy download on Linux and AIX nodes
+* Remote run from policy servers to nodes
+
+It uses the key pairs in `/var/rudder/cfengine-community/ppkeys/` to authenticate the node and server during
+communication.
+
+==== Server authentication
+
+The server is trusted by the node at first connection ("Trust On First Use") by default, but you can provide a public
+key to pre-establish trust (see guide below).
+
+==== Agent authentication
+
+The first inventory sent by the node contains it's public key (apart of its certificates). Once accepted,
+it's policies are only available to a node having the matching private key.
+
+=== HTTPS
+
+HTTPS is used for:
+
+* Sending inventories and reports from nodes to policy servers
+* Remote-run trigger between root server and relays
+* File sharing between nodes and policy server
+* Policies and shared-files downloads on Windows nodes
+
+==== Server authentication
+
+Our HTTPS setup uses standard certificates, that are self-signed by default, and nodes
+do not verify their policy server's certificate when sending an inventory or a report.
+
+Follow the guide below to replace them by valid certificates and enable certificate validation.
+
+==== Agent authentication
+
+Inventories and reports are sent without client authentication at HTTP level, but they are signed the node's certificate,
+and checked on central server before being processed.
+
+For Windows policy and file download, HTTPS client authentication is done using the `agent.cert` node's certificate
+for allow allow access to the node with the matching private key.