Agent security

Connection security

The agent opens the connection to Pierrr itself, over outbound HTTPS: there is no administration port to open on your server. The connection is encrypted with the most recent version of the protocol, and the agent refuses any older one.

Since Pierrr version 0.0.49-beta, a new server connects to an address dedicated to servers, agents.pierrr.com. The connection then goes straight from your server to Pierrr, with no intermediary, and it is encrypted end to end. A server connected before that version keeps going through api.pierrr.com. To move it to the new address, use "Move to the new address" on the server's page in the console: the agent first checks the new address, and goes back to the old one by itself if it cannot reconnect through it. Pierrr never does it without you.

Pierrr only sends the agent commands defined in advance: deploy an app, read logs, run a backup, for example. This channel cannot run an arbitrary command on the machine.

Signed commands

Since version 0.62.0-beta, every command Pierrr sends to the agent is signed. The agent keeps Pierrr's key from the moment it is installed, or from its first connection after the update. From then on it refuses:

• a command that is not signed, or is signed by another key;
• a command it has already received, sent a second time;
• a command whose time is more than ten minutes away from your server's clock.

Someone who managed to sit between Pierrr and your server could therefore neither run a command there nor replay one already sent. If Pierrr ever changes its key, the agent only accepts the new one when the old one signed it: there is nothing for you to do.

The server's clock matters

If your server's clock drifts by more than ten minutes, commands are refused with a message that says so, shown in the Journal tab of the server's page. Check that time synchronisation is on:

timedatectl status

The output should say that the clock is synchronised. Once the time is right again, the next commands go through normally.

Verified updates

The agent never updates itself, and it only installs a new version signed by one of the keys it knows. These keys only sign agent versions and are renewed regularly: the agent knows the key in service and the one that will succeed it, so a renewal asks nothing of you. It also refuses any version older than the one in place.

Since version 0.73.0-beta, this command shows the fingerprints of the keys your agent accepts:

pierrr-agent version

The installation script checks the same signature before installing the agent, against the same fingerprints written into the script itself.

Limit what Pierrr can do on your server

You can decide yourself what Pierrr may do on your server, in a policy.yaml file next to the agent's configuration: /etc/pierrr-agent/policy.yaml. The file is yours: Pierrr never writes it.

The agent reads the file again on every command: a change applies at once, without restarting the agent. With no file, nothing is restricted.

The settings

• mode: full (the default) lets Pierrr do everything, read-only only lets it read.
• allow (optional): when the list is there, only the commands it names are allowed.
• deny (optional): these commands are always refused, even when allow names them.
• isolateBuilds (optional, false by default): true isolates the builds of your applications, see below.
• scanSummaryOnly (optional, false by default): true reduces every security scan on this server to a summary, see below.

In read-only mode, allow can only narrow the list of reads further: it never adds a command that changes the server.

Examples

Pierrr can only look at the server:

mode: read-only

Pierrr can do everything except delete a project or uninstall the agent from the console:

mode: full
deny:
  - destroy-project
  - self-destruct

An allow list blocks everything it does not name, including the operations Pierrr chains for you: a deployment, for example, goes through several commands. Once you have set one, run the operation concerned and check the command log.

Isolate builds

A build runs the steps written in your application's repository. With isolateBuilds: true, the tool that builds your applications can no longer reach the server itself nor the private networks it is connected to: local network, internal addresses of your hosting provider, instance information service of a cloud provider, applications already running on the server. It keeps the internet to download dependencies, name resolution, and the server's public ports 80 and 443, so a build that reads your own site keeps working. This is how Pierrr's own servers run.

mode: full
isolateBuilds: true

The agent applies these rules before every build and removes them as soon as the setting goes back to false. It has to run as the server's administrator, which the standard installation does. If it cannot apply them, the build is refused rather than run without them, with the reason in the command log.

A build that needs a machine of your private network (an internal package registry, for example) will fail with this setting: leave it at false in that case.

Summary-only scans

By default, a security scan reports for each finding its identifier, its severity, the file or package concerned and a short message, never an excerpt of your code. With summary only, just the identifier and the severity of each finding leave the server: no file path, no package, no line, no message. The console counts findings by severity and lists their identifiers; the details stay on your server.

mode: full
scanSummaryOnly: true

Change the setting from the Settings tab of the server page in the console, or enforce it from this file with scanSummaryOnly: true: it then holds whatever the console asks. An agent too old to produce the summary runs no scan at all until it is updated.

What read-only mode allows

In read-only mode, Pierrr can still read the state of the server and its containers, their logs, the space the volumes take, and download an existing backup. Everything else is refused, including what Pierrr starts on its own: no deployment, no new backup, scheduled ones included, and no agent update from Pierrr. To update the agent, switch back to full for the time of the update.

A file that cannot be read or is badly written (an unknown mode, for example) counts as read-only: a mistake in the file never gives Pierrr more rights.

See a refused command

A command refused by your policy shows up in the command log, in the Journal tab of the server's page: it is marked as failed, with the reason for the refusal under its label.

Command names

The command log shows each command under a label. In the file, write its name, as given in the tables below.

Read commands, allowed in read-only mode

Commands that change the server

The other commands are Pierrr's upkeep of the server: routing, domains, networks. Refusing them can stop your applications from being reachable, so they are best left allowed.