Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Work in progress
  • Loading branch information
amousset committed Oct 19, 2022
1 parent 64e14b1 commit 447f95e
Showing 1 changed file with 113 additions and 108 deletions.
221 changes: 113 additions & 108 deletions src/reference/modules/administration/pages/security.adoc
@@ -1,140 +1,64 @@
= Network security
= Security

Communication between servers and nodes uses two channels:
== Hardening configuration

* 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.
Rudder provides secure defaults whenever possible, but depending on your use case you can
add additional configurations to make your Rudder installation more secure.

Both enforce using TLS 1.2+.
=== Server

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.
* By default, all HTTPS traffic is handled by the same virtual host in Apache httpd. To allow hardening the connection security, a first step is to split public Web/API from internal node-server communication. You can do so by commenting the default virtual host in `/etc/apache2/sites-enabled/rudder.conf` or `/etc/httpd/conf.d/rudder.conf` (depending on the distribution), and uncommenting the two separate configurations. You only need a way to make a difference in the configuration, in general with a different port or a specific domain for Web/API.

== Authentication mechanisms
* Once your virtual hosts are split, set up a valid certificate for the Web/API. This allows validating the server identity from Web browsers and API clients. You can use an internal PKI or a publicly trusted certificate, like with _Let's Encrypt_. The certificate configuration is done in `/etc/apache2/sites-enabled/rudder.conf` or `/etc/httpd/conf.d/rudder.conf` depending on your distribution, in the Web/API virtual host. To configure the TLS settings of the Web/API virtual hosts depending on your requirements and platform, we recommend using https://ssl-config.mozilla.org/[Mozilla SSL configurator generator].

=== Credentials
* _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:

On all agents and relays, and servers:
[source,ini]
----
rudder.server.hsts=true
----

* `/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.
* 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:

Only on servers and relays:
[source,ini]
----
rudder.auth.idle-timeout=15 minutes
----

* `/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.
* It is recommended to use an external authentication backend exposing an OpenID connect or OAUTH2 interface with a second authentication factor (TOTP, WebAuthn, etc.).

=== Policy update and remote run (tcp/443)
* 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`.

This protocol is used for:
* 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).

* Policy download on Linux and AIX nodes
* Remote run from policy servers to nodes
* Give minimal privileges to users using roles

It uses the key pairs in `/var/rudder/cfengine-community/ppkeys/` to authenticate the node and server during
communication.
* Give minimal privileges to you API tokens and use a different token for each application.

==== Server authentication
=== Agent

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).
* If you don't use the remote-run feature (using the _Trigger agent_ button in node details or the `nodes/apply` HTTP API), you can totally disable the service listening on the network. This way, your Rudder agents will not expose anything on the network. To do so, you need to disable the `rudder-cf-serverd` sub-service, with a Rudder technique or the `systemctl disable --now rudder-cf-serverd` command.

==== Agent authentication
** **Note**: On Rudder servers and relays this service is necessary and cannot be disabled.

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.
=== Network

=== HTTPS
==== Generalities

HTTPS is used for:
* Even if all communications are encrypted, we recommend avoiding Rudder communications across public networks, and putting them inside a VPN in case you need access outside your private network.

* 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
* Add firewall rules to limit access to Rudder ports to relevant systems.

==== 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.

== 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

Replace the default self-signed certificate by a valid one (i.e. recognized by the nodes) certificate in place in:

* `/opt/rudder/etc/ssl/rudder.key`
* `/opt/rudder/etc/ssl/rudder.crt`

CAUTION: You need to make sure all nodes use a hostname that matches this certificate
as their configured policy server.

You can for example use Let's Encrypt to get free certificates if your server
has an access to the Internet.

In this case you should copy `fullchain.pem` into `rudder.crt` and `privkey.pem` into
`rudder.key`, and automate this copy to allow automatic renewal.

Then enable *Enforce validation of policy server certificate for inventory and reporting* in *Settings -> General -> Certificate validation*. This will make nodes require a valid certificate to send
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

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.

CAUTION: Currently initial policies are not configurable, so this change needs to be done after each upgrade.

On the root server, in `/var/rudder/cfengine-community/masterfiles/promises.cf`:

----
"rudder_verify_certs" expression => strcmp("", "true");
# should be replaced by
"rudder_verify_certs" expression => "true";
----

and in `/var/rudder/cfengine-community/masterfiles/rudder.json`:

----
# add
"RUDDER_VERIFY_CERTIFICATES":"true",
----

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
Expand Down Expand Up @@ -176,3 +100,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
* On Unix systems, a custom protocol wrapped in TLS on tcp/5309

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.

0 comments on commit 447f95e

Please sign in to comment.