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.

Untrusted files are deposited (via rsync over ssh) in the entry window (in) and automatically scanned by an antivirus server. If a file is considered unhealthy, it is logged/hashed and immediately deleted.
Files considered as healthy are also logged and hashed (sha256) but sent (with associated hashes) to the transit window through several (one per file) unidirectional software diode (named pipe). A static analysis is performed on each file using libyara and a report is generated if one or more rules matched.
Finally, files in transit and any reports generated are transfered to the output window through another software diode subsystem.
System configuration
Recommendations
Here are some recommendations and best practices to use Keysas in good conditions.
System hardening recommendations.
To be safe enough, 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/
Network Cards
- 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.
It is also highly recommended to preserve an SSH access using a dedicated daemon and a dedicated network.
OpenSSH configuration
- 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.
In any cases, you should configure allowed users and networks in your sshd configuration:
# OpenSSH daemon listening on the *untrusted_network*:
AllowUsers untrusted_user@untrusted_network untrusted_user2@untrusted_network
# OpenSSH daemon listening on the *trusted_network*:
AllowUsers trusted_user@trusted_network trusted_user2@trusted_network
# 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 Usage section.
keysas-in
keysas-in daemon is responsible for scanning files in the entry point directory, using an antivirus signature database and producing a sha256 digest for each file. The ELF binary is installed under:
/usr/bin/keysas-in
The configuration file for this daemon is:
/etc/keysas/keysas-in.conf
The corresponding log directory is:
/var/log/keysas-in/
Let’s take a look at the configuration:
$ view /etc/keysas/keysas-in.conf
It should look like this:
# keysas-in configuration file
# This file is part of keysas
#
# 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
# Diode-in directory
# You should not touch this parameter.
DIODEIN=/run/diode-in/
# Path where incoming files will be deposited
# You should not touch this parameter.
KEYSASIN=/var/local/in/
# Path to log directory
# You should not touch this parameter.
LOG=/var/log/keysas-in/
# Maximum size in bytes before rotating current log
ROTATE_OVER_SIZE=3000000
# How many log file to keep under $LOG path
NB_OF_LOG_FILES=3
# Maximum file size to transfert
# Default is 500Mo
MAXFILESIZE=500000000
Warning
Do not modify DIODE-IN, KEYSASIN and LOG parameters unless you really know what to do.
You might want to ajust CLAMAV_IP, CLAMAV_PORT, ROTATE_OVER_SIZE, NB_OF_LOG_FILES and MAXFILESIZE according to your needs.
CLAMAV_IP
As commented in the configuration file, this is the IP address where the Clamav daemon will be listening to. If Clamav is installed locally, you have no need to modify this parameter. Port 3310 is the default port for both Clamav and keysas. If the Clamav daemon is running somewhere else, change the address here:
CLAMAV_IP=192.168.1.43
Note
In order, the make this change efficient, you also need to edit the corresponding Systemd unit to allow tcp sockets for the new address. See the Systemd unit files section for more details.
ROTATE_OVER_SIZE
This parameter represents the maximum log size in bytes before automatically rotating the current log in path /var/log/keysas-in/.
NB_OF_LOG_FILES
This parameter represents the number of log files to keep in path /var/log/keysas-in/.
MAXFILESIZE
This parameter represents the maximum file size (in bytes) allowed to be transfered. If a file is bigger than MAXFILESIZE, it is deleted.
Note
Files bigger than MAXFILESIZE will be automatically removed.
keysas-transit
keysas-transit is mainly responsible for removing forbidden file format based on their magic numbers and scanning incoming files with libyara.
The ELF binary is installed under:
/usr/bin/keysas-transit
The configuration file for this daemon is:
/etc/keysas/keysas-transit.conf
The corresponding log directory is:
/var/log/keysas-transit/
Let’s now take a look at the configuration of the seconf daemon called keysas-transit:
$ view /etc/keysas/keysas-transit.conf
It should look like this:
# Keysas-transit configuration file
# This file is part of keysas.
#
# Diode-in directory
# You should not touch this parameter.
DIODEIN=/run/diode-in/
# Diode-out directory
# You should not touch this parameter.
DIODEOUT=/run/diode-out/
# Path where for files in transit
# You should not touch this parameter.
TRANSIT=/var/local/transit/
# Path to log directory
# You should not touch this parameter.
# Pay attention to add a slash at the end
LOG=/var/log/keysas-transit/
# 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
# Maximum size in bytes before rotating current log
ROTATE_OVER_SIZE=3000000
# How many log file to keep under $LOG path
NB_OF_LOG_FILES=3
# Set here a whitelist (comma separated) of allowed file formats
# For example:
# ALLOWED_FORMATS="deb,rpm"
# See https://keysas.fr/administration.html#keysas-transit for more information.
ALLOWED_FORMATS="jpg,png,bmp,mp4,m4v,avi,wmv,mpg,flv,mp3,wav,ogg,epub,mobi,doc,docx,xls,xlsx,ppt,pptx"
Warning
Do not modify DIODEIN, DIODEOUT, TRANSIT and LOG parameters unless you really know what to do.
You might want to ajust YARA_MAXFILESIZE, YARA_TIMEOUT, YARA_CLEAN, ROTATE_OVER_SIZE and NB_OF_LOG_FILES 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 takes to scan a file ! You should set this option to the same value as MAXFILESIZE (keysas-in) 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.
ROTATE_OVER_SIZE
This parameter represents the the maximum log size in bytes before automatically rotating the current log in path /var/log/keysas-in/.
NB_OF_LOG_FILES
This parameter represents the number of log files to keep in path /var/log/keysas-in/.
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:
Supported types
Image
jpg - image/jpeg
png - image/png
gif - image/gif
webp - image/webp
cr2 - image/x-canon-cr2
tif - image/tiff
bmp - image/bmp
heif - image/heif
avif - image/avif
jxr - image/vnd.ms-photo
psd - image/vnd.adobe.photoshop
ico - image/vnd.microsoft.icon
Video
mp4 - video/mp4
m4v - video/x-m4v
mkv - video/x-matroska
webm - video/webm
mov - video/quicktime
avi - video/x-msvideo
wmv - video/x-ms-wmv
mpg - video/mpeg
flv - video/x-flv
Audio
mid - audio/midi
mp3 - audio/mpeg
dsf - audio/x-dsf
m4a - audio/m4a
ogg - audio/ogg
flac - audio/x-flac
wav - audio/x-wav
amr - audio/amr
aac - audio/aac
aiff- audio/aiff
Archive
epub - application/epub+zip
zip - application/zip
tar - application/x-tar
rar - application/vnd.rar
gz - application/gzip
bz2 - application/x-bzip2
7z - application/x-7z-compressed
xz - application/x-xz
pdf - application/pdf
swf - application/x-shockwave-flash
rtf - application/rtf
eot - application/octet-stream
ps - application/postscript
sqlite - application/vnd.sqlite3
nes - application/x-nintendo-nes-rom
crx - application/x-google-chrome-extension
cab - application/vnd.ms-cab-compressed
deb - application/vnd.debian.binary-package
ar - application/x-unix-archive
Z - application/x-compress
lz - application/x-lzip
rpm - application/x-rpm
dcm - application/dicom
zst - application/zstd
msi - application/x-ole-storage
Book
epub - application/epub+zip
mobi - application/x-mobipocket-ebook
Documents
doc - application/msword
docx - application/vnd.openxmlformats-officedocument.wordprocessingml.document
xls - application/vnd.ms-excel
xlsx - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
ppt - application/vnd.ms-powerpoint
pptx - application/vnd.openxmlformats-officedocument.presentationml.presentation
odt - application/vnd.oasis.opendocument.text
ods - application/vnd.oasis.opendocument.spreadsheet
odp - application/vnd.oasis.opendocument.presentation
Font
woff - application/font-woff
woff2 - application/font-woff
ttf - application/font-sfnt
otf - application/font-sfnt
Application
wasm - application/wasm
exe - application/vnd.microsoft.portable-executable
dll - application/vnd.microsoft.portable-executable
elf - application/x-executable
bc - application/llvm
mach - application/x-mach-binary
class - application/java
dex - application/vnd.android.dex
dey - application/vnd.android.dey
der - application/x-x509-ca-cert
obj - application/x-executable
Text
sh - text/x-shellscript
xml - text/xml
html - text/html
Known Issues
exe and dll have the same magic number so it’s not possible to tell which one just based on the binary data. exe is returned for all.
keysas-out
The last daemon called keysas-out is only responsible for retreiving incoming files from the software data diodes and writing them on the directory KEYSASOUT.
The ELF binary is installed under:
/usr/bin/keysas-out
The configuration file for this daemon is:
/etc/keysas/keysas-out.conf
The corresponding log directory is:
/var/log/keysas-out/
Finally, here is the configuration of the last daemon called keysas-out:
/etc/keysas/keysas-out.conf
It should look like this:
# Keysas-out configuration file
# This file is part of Keysas
#
# Diode directory
# You should not touch this parameter.
# Pay attention to add a slash at the end
DIODEOUT=/run/diode-out/
# Path where incoming files will be deposited
# You should not touch this parameter.
# Pay attention to add a slash at the end
KEYSASOUT=/var/local/out/
# Path to log directory
# You should not touch this parameter.
# Pay attention to add a slash at the end
LOG=/var/log/keysas-out/
# Maximum size in bytes before rotating current log
ROTATE_OVER_SIZE=3000000
# How many log file to keep under $LOG
NB_OF_LOG_FILES=3
Warning
You should not modify DIODEOUT, KEYSASOUT and LOG parameters.
You can ajust ROTATE_OVER_SIZE and NB_OF_LOG_FILES like previously discussed.
ROTATE_OVER_SIZE
This parameter represents the the maximum log size in bytes before automatically rotating the current log in path /var/log/keysas-out/.
NB_OF_LOG_FILES
This parameter represents the number of log files to keep in path /var/log/keysas-out/.
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:
/etc/systemd/system/keysas-in.service
This fragment contains the basic configuration of the unit. You do not need to modify this one.
And :
/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:
$ systemctl cat keysas-in
If you want to allow keysas-in to communicate with a Clamav server listening on IP 192.168.1.43:
Edit the Systemd unit
#/etc/systemd/system/keysas-in.service.d/security.conf
IPAddressAllow=127.0.0.1/8
Change the above parameter with:
#/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:
$ sudo systemctl daemon-reload
and restart keysas:
$ 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:

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:
$ sudo apparmor_parser -r /etc/apparmor.d/usr.bin.keysas-in
Then, verify that the profile is still in enforce mode:
$ 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)
...
Static analysis
keysas-transit daemon is able to perform a Yara scan on transfered files according to the rules defined in path:
/usr/share/keysas/rules/index.yar
This file can be a simple rule like provided in the default installation or it can act as an index listing a subset of rules.
The default rule is just an exemple matching on Dirtyc0w source code, but you can easily create your own rules or reuse already existing rule packages. Include your custom rules into /usr/share/keysas/rules/index.yar, like that :
include "./custom/custom_rule.yar"
Help
Take a look at https://github.com/Yara-Rules/rules for more details but keep in mind that some rules are not well maintained and may not fit the version of libyara installed via apt. You should test every new rules before adding them in production.