**************
Administration
**************

Design
======

**Keysas** provides three different daemons running at the same time and three different configuration files to be able to configure each daemon.
The following schema explains the logic behind **Keysas**.

.. image:: img/keysas-core-architecture.png

Untrusted files are deposited (via rsync over ssh) in the entry SAS (in).

**Keysas-in**, the first daemon will take some metadata (name, date, sha256) of each file discovered and send each file descriptor (as raw) 
to the second daemon **Keysas-transit** with the associated metadata using an abstract socket. 
When done, **Keysas-in** simply unlink(at) the files.

**Keysas-transit** receives the file descriptor through the abstract socket and metadata. It automatically verifies the sha256 digest, scans the file descriptors using **Clamav** and **Yara**.
It also performs a size and magic number verification.
Each test and verification is added to metadata and sent to **Keysas-out**.

**Keysas-out** receives the raw file descriptors and metadata through a dedicated abstract socket.
It immediately verifies the sha256 digest. If a file is considered unhealthy (reading metadata), the file descriptor is definitly closed. 
If not the file descriptor is copied into the outgoing SAS with a report containing the metadata associated.
If enrolled using **Keysas-admin**, it also performs an hybrid post-quantum signature using Ed25519/Dilithium5 on each file and linked report containing the file metadata and the station analysis.

System configuration
====================

Recommendations
---------------

Here are some recommendations and best practices to use **Keysas** in good conditions.

.. admonition:: System hardening recommendations.

 The GNU/Linux system used should be hardened according to the best practices such as *ANSSI*, *CIS*, *STIG* etc.

 You can take a look at the following: https://www.ssi.gouv.fr/en/guide/configuration-recommendations-of-a-gnulinux-system/ 

.. admonition:: Network Cards (Only for network gateway)
 :class: tip

 We recommend to set up at least four network cards:
  * One dedicated card and IP address for the untrusted network;
  * One dedicated card and IP address for the trusted network;
  * One dedicated card and IP address for the administration tasks;
  * One dedicated card and IP address for Syslog.

.. admonition:: OpenSSH configuration (Only for network gateway)
 :class: tip

 You can set up three separate OpenSSH daemons:
  * One for the *administration* network;
  * One for the *untrusted* network;
  * One for the *trusted* network.

 Alternatively, you can choose to set up only two separate OpenSSH daemons:
  * One for the *administration* network;
  * One for the *untrusted* network and the *trusted* network.
  
A third solution would be to reserve an SSH access using a dedicated daemon and a dedicated network.

 **In any cases, you should configure allowed users and networks in your sshd configuration:**

 .. code-block:: bash

   # OpenSSH daemon listening on the *untrusted_network*:
   AllowUsers untrusted_user@untrusted_network untrusted_user2@untrusted_network

 .. code-block:: bash

   # OpenSSH daemon listening on the *trusted_network*:
   AllowUsers trusted_user@trusted_network trusted_user2@trusted_network

 .. code-block:: bash

   # OpenSSH daemon listening on the *administration_network*:
   AllowUsers admin_user@administration_network admin_user2@administration_network

 Explanations about creating *untrusted_users* and *trusted_users* can be found in the :ref:`Usage` section.

keysas-in
--------------

**keysas-in** daemon is responsible for sending file descriptors in the entry point directory.
The ELF binary is installed under:

.. code-block:: shell-session

  /usr/bin/keysas-in

The configuration file for this daemon is:

.. code-block:: shell-session

  /etc/keysas/keysas-in.conf

The corresponding logs:

.. code-block:: shell-session

  journalctl -fu keysas-in.service

Let's take a look at the configuration:

.. code-block:: shell-session

 $ view /etc/keysas/keysas-in.conf

It should look like this:

.. code-block:: bash

 # Keysas-in configuration file
 # This file is part of keysas

 # Socket_in path
 # You should not touch this parameter.
 SOCKET_IN=socket_in

 # Path where incoming files will be deposited
 # You should not touch this parameter.
 # Pay attention to add a slash at the end.
 SAS_IN=/var/local/in/

.. warning::
 Do not modify this parameters unless you really know what to do.

keysas-transit
------------------

**keysas-transit** is mainly responsible for perfoming **Clamav** and **Yara** scans and verifying size limit and forbidden file formats based on their **magic numbers**.


The ELF binary is installed under:

.. code-block:: shell-session

  /usr/bin/keysas-transit

The configuration file for this daemon is:

.. code-block:: shell-session

  /etc/keysas/keysas-transit.conf

The corresponding logs:

.. code-block:: shell-session

  journactl -fu keysas-transit.service

Let's now take a look at the configuration of the second daemon called *keysas-transit*:

.. code-block:: shell-session

 $ view /etc/keysas/keysas-transit.conf

It should look like this:

.. code-block:: bash

 # Keysas-transit configuration file
 # This file is part of keysas.
 #
 # Socket_in path
 # You should not touch this parameter.
 # Pay attention to add a slash at the end
 SOCKET_IN=socket_in

 # Socket_out path
 # You should not touch this parameter.
 # Pay attention to add a slash at the end
 SOCKET_OUT=socket_out

 # Max file size to be transfered
 # You should not touch this parameter.
 MAX_SIZE=500000000

 # Path to Yara rules (don't forget to add index.yar)
 RULES=/usr/share/keysas/rules/index.yar

 # Yara max file size to scan
 # The bigger it is, the longer it takes to scan a file !
 # Default is 50Mo (50000000 bytes)
 YARA_MAXFILESIZE=50000000

 # Yara timeout when scannning files
 YARA_TIMEOUT=1000

 # Tells if keysas should remove the file if Yara matched at least one rule
 YARA_CLEAN=true

 # Clamd server IP 
 # Note that if you modify this address, you also
 # have to edit the following file 
 # /etc/systemd/system/keysas-in.service.d/keysas-in.conf
 # to allow sockets via systemd.
 # See https://keysas.fr/configuration.html#systemd
 # for more information.
 CLAMAV_IP=127.0.0.1

 # Clamd server port
 CLAMAV_PORT=3310

 # Set here a whitelist (comma separated) of allowed file types
 # For example:
 # ALLOWED_TYPES="deb,rpm"
 # See https://keysas.fr/administration.html#keysas-transit for more information.
 ALLOWED_TYPES="jpg,png,bmp,mp4,m4v,avi,wmv,mpg,flv,mp3,wav,ogg,epub,mobi,doc,docx,xls,xlsx,ppt,pptx"


.. warning::
 Do not modify **SOCKET_IN**, **SOCKET_OUT** parameters unless you really know what to do.

You might want to ajust **MAX_SIZE**, **YARA_MAXFILESIZE**, **YARA_TIMEOUT**, **YARA_CLEAN** and **ALLOWED_TYPES** according to your needs.

YARA_MAXFILESIZE
~~~~~~~~~~~~~~~~

This parameter sets the maximum file size (in bytes) to be scanned. The bigger it is, the longer it can take to scan a file !
You should set this option to the same value as MAX_SIZE to be consistant.
If a file is bigger than YARA_MAXFILESIZE, it is deleted.

YARA_TIMEOUT
~~~~~~~~~~~~

This parameter sets a timeout (in seconds) to scan a file.
If a file scan takes too long because of a big file, you can adjust the timeout here.

YARA_CLEAN
~~~~~~~~~~

This parameter tells if **Keysas** should remove the file if Yara matched at least one rule.

ALLOWED_TYPES
~~~~~~~~~~~~~~~

This parameter creates a whitelist of allowed file types. Types not explicitly listed here simply won't by transfered. For now the following types are supported:

https://github.com/bojand/infer#supported-types

keysas-out
--------------

The last daemon called **keysas-out** is only responsible for writing the file descriptors and the reports on the directory outgoing directory.

The ELF binary is installed under:

.. code-block:: shell-session

  /usr/bin/keysas-out

The configuration file for this daemon is:

.. code-block:: shell-session

  /etc/keysas/keysas-out.conf

The corresponding logs:

.. code-block:: shell-session

  journalctl -fu keysas-out.service

Finally, here is the configuration of the last daemon called *keysas-out*:

.. code-block:: shell-session

 /etc/keysas/keysas-out.conf

It should look like this:

.. code-block:: bash

 # Keysas-out configuration file
 # This file is part of keysas
 #
 # Socket_out path
 # You should not touch this parameter.
 # Pay attention to add a slash at the end
 SOCKET_OUT=socket_out

 # Path where incoming files will be deposited
 # You should not touch this parameter.
 # Pay attention to add a slash at the end
 SAS_OUT=/var/local/out/


.. warning::
  You should not modify **SOCKET_OUT** and **KEYSASAS_OUTSOUT** parameters. 

Systemd unit files
------------------

We won't discuss here how **Keysas**'s systemd hardening is made, as it is not much interesting. We will simply explain how to reconfigure **keysas-in**'s unit if you need to run the Clamav daemon on another server. 

*Systemd* units are splitted into two differrent files. In case of **keysas-in**:

.. code-block:: shell-session

 /etc/systemd/system/keysas-in.service

This fragment contains the basic configuration of the unit. You do not need to modify this one.

And :

.. code-block:: shell-session

 /etc/systemd/system/keysas-in.service.d/security.conf

This is where comes the hardening part of the unit. The security.conf file is a drop-in systemd file. It is automatically concatenated with the fragment part of the unit.
You can see the entire resulting unit using the following command:

.. code-block:: shell-session

 $ systemctl cat keysas-in

If you want to allow **keysas-in** to communicate with a *Clamav* server listening on IP 192.168.1.43:

.. admonition:: Edit the Systemd unit
 :class: note
  
 .. code-block:: shell-session

   #/etc/systemd/system/keysas-in.service.d/security.conf
   IPAddressAllow=127.0.0.1/8

 Change the above parameter with:

 .. code-block:: shell-session

   #/etc/systemd/system/keysas-in.service.d/security.conf
   IPAddressAllow=192.168.1.43/32


.. warning::

 Do not forget to provide a netmask, Systemd requires it !


Then, reload the daemon:

.. code-block:: shell-session

 $ sudo systemctl daemon-reload

and restart **keysas**:

.. code-block:: shell-session

 $ sudo systemctl restart keysas

And that's it, you're all done !

Here is the security result achieved by default according to the **systemd analyse-security** command:

.. image:: /img/systemd-security.png
 
Apparmor
--------

From *Wikipedia* :

"AppArmor (Application Armor) is a Linux kernel security module that allows the system administrator to restrict 
programs capabilities with per-program profiles. Profiles can allow capabilities like network access, raw socket access, 
and the permission to read, write, or execute files on matching paths."

.. note::

 Although we are working on supporting SELinux, **Keysas** is only providing Apparmor profiles at this time.  

**Apparmor** profiles are located here:

 * /etc/apparmor.d/usr.bin.keysas-in
 * /etc/apparmor.d/usr.bin.keysas-transit
 * /etc/apparmor.d/usr.bin.keysas-out

You will probably never have to modify them (it is not recommended anyway). Nevertheless, in case you need to update them, do not forget to reload the changed profile:

.. code-block:: shell-session

 $ sudo apparmor_parser -r /etc/apparmor.d/usr.bin.keysas-in

Then, verify that the profile is still in **enforce mode**:

.. code-block:: shell-session

 $ sudo aa-status
 9 processes are in enforce mode.
   /usr/bin/freshclam (1580) 
   /usr/bin/keysas-in (433022) 
   /usr/bin/keysas-out (433027) 
   /usr/bin/keysas-transit (433025) 
   /usr/sbin/clamd (966)
   ...

Libyara analysis
-----------------

**keysas-transit** daemon is able to perform a *Yara* scan on transfered files according to the rules defined in path:

.. code-block:: shell-session

  /usr/share/keysas/rules/index.yar

This file act as an index listing a subset of rules.

The default target **make install-yararules** already clones a lot of usefull rules from various repositories , but you can easily create your own rules.
Include your custom rules into /usr/share/keysas/rules/index.yar, like that :

.. code-block:: shell-session

 include "./custom/custom_rule.yar"

.. admonition:: Help
 :class: tip

 You should test every new rules before adding them in production.