Configuration

La borne lit sa configuration dans /etc/pandora-box/pandora-box.toml (un autre fichier avec --config, ou la variable d'environnement PANDORA_BOX_CONFIG). Chaque clé est facultative : une clé absente prend sa valeur par défaut. La configuration est vérifiée au démarrage, et une clé inconnue ou une valeur invalide est refusée : la borne ne démarre pas avec une configuration qu'elle ne comprend pas.

Dans l'image, le système de fichiers racine est en lecture seule : la configuration fait partie de l'image, reprise de packaging/pandora-box.toml à la construction de l'image. Pour la modifier, éditez ce fichier, construisez une nouvelle image et installez-la comme une mise à jour (voir Construction de l'image et Mises à jour du système).

Vérifier une configuration, ses signatures, ses moteurs et son thème sans démarrer la borne :

pandora-box --config pandora-box.toml --check-config

Sections

Section	Réglages
[kiosk]	Nom de la borne dans les journaux, interface (framebuffer, curses, console), mode FAKE_SCAN
[display]	Thème, langue, framebuffer, retour à l'écran d'attente : voir Interface
[device]	Point de montage, systèmes de fichiers autorisés, éjection
[scan]	Processus d'analyse en parallèle, délai par fichier, politiques suspicious et on_error, bac à sable
[limits]	Taille maximale d'un fichier, nombre de fichiers, profondeur des dossiers
[policy]	Nombre de moteurs nécessaires pour un verdict malveillant
[engines.*]	Chaque moteur de détection : voir Moteurs de détection
[signatures]	Jeux de signatures et leur vérification : voir Signatures
[updates]	Mises à jour en ligne des signatures et de l'image : voir Signatures et Mises à jour du système
[siem]	Export des journaux vers un SIEM : voir Export vers un SIEM
[report], [quarantine], [logging]	Dossiers des rapports d'analyse et de la quarantaine, fichier et niveau de journal : voir Journaux

Référence

La configuration de l'image, packaging/pandora-box.toml, avec chaque clé, sa valeur par défaut et sa signification (commentaires en anglais) :

# PandoraBox configuration
# Installed as /etc/pandora-box/pandora-box.toml. Every key is optional:
# the values below are the defaults. Unknown keys are rejected at startup.
# Check this file with: pandora-box --check-config

[kiosk]
# Kiosk name written in every log entry (default: host name)
# name = "kiosk-01"

# FAKE_SCAN mode, for development only: no real detection is performed,
# only the EICAR test file is reported as malicious.
fake_scan = false

# User interface: "framebuffer" (graphical, touch screen), "curses" (full
# screen text, administrator mode) or "console" (plain text)
interface = "framebuffer"

[display]
# Graphical interface (kiosk.interface = "framebuffer"). Theme folder: logo,
# colors, texts and images in place of the built-in ones ("" for the built-in
# theme, the default). In the image, the files of image/theme/: see
# docs/interface.md.
theme = "/usr/share/pandora-box/theme"
# Language of the texts: "en", "fr", or a language the theme adds
language = "en"
# Framebuffer device
framebuffer = "/dev/fb0"
# A result stays on the screen until the device is removed, then this long
# (seconds) before the waiting screen
return_seconds = 5.0

[device]
# Folder where the USB device is mounted (must exist)
mount_point = "/media/pandora-box"

# Mounting a block device requires root (CAP_SYS_ADMIN): adding the user to a
# group is not enough. Run the kiosk as root (systemd service), or set
# use_sudo = true to run mount/umount through "sudo -n", with a sudoers rule
# limited to these commands, for instance:
#   pandora-box ALL=(root) NOPASSWD: /usr/bin/mount, /usr/bin/umount, /usr/bin/eject
use_sudo = false

# Filesystems that may be mounted; any other device is rejected
allowed_filesystems = ["vfat", "exfat", "ntfs", "ext4"]

# Timeout of mount/umount commands, in seconds
command_timeout = 60

# Eject the device (/usr/bin/eject, Debian package "eject") when the scan and
# the cleaning are over, so that the user can remove it safely. While the
# user is asked to confirm the cleaning, the device is only unmounted.
eject = true

# DEVELOPMENT ONLY, never on a kiosk: when the desktop mounts USB devices
# itself (udisks automount), use that mount instead of mounting the device.
# The device is then scanned on the system mount (usually read-write, maybe
# without noexec) and mount_point is ignored. It is unmounted and mounted
# again with udisksctl, which the desktop user may run without root.
auto_mount = false
# Maximum time to wait for the system to mount the device, in seconds
auto_mount_wait = 15.0

[scan]
# Number of files scanned in parallel: "auto" (one per CPU, as many as the
# memory allows: 1.5 GB for clamd and the system, then 256 MB each, for the
# YARA rules mostly), or a number
workers = "auto"

# Maximum time to scan one file with all the engines, in seconds. A worker
# that exceeds it is killed and the file is reported as an error.
file_timeout = 300.0

# Files reported as suspicious by an engine:
#   "block": quarantined and removed from the device, like malicious files
#   "warn":  kept on the device, the user is warned
suspicious = "block"

# Files that could not be fully scanned (engine error or timeout, file over a
# limit, too many files or folders too deep):
#   "block": the device is reported as NOT VERIFIED and must not be used
#            (unscanned files are listed but never removed)
#   "warn":  the user is warned and the unscanned files are listed
on_error = "block"

# FAKE_SCAN mode only: simulated scan time per file, in seconds
fake_delay = 0.0

# Run each scan worker in a sandbox: bubblewrap (no network, a minimal file
# system without the device), as sandbox_user without privileges, with a
# system call filter. The kiosk opens the files and passes them to the
# workers. Needs root, bwrap and setpriv: set it to false for development.
sandbox = true
sandbox_user = "pandora-box-scan"

[limits]
# Files bigger than this size (in bytes) are not scanned (default: 1 GiB)
max_file_size = 1073741824
# Maximum number of files on a device; the scan stops beyond it
max_files = 100000
# Maximum folder depth; deeper folders are not scanned
max_depth = 64

[policy]
# Number of engines that must report a file as malicious; with fewer
# positive engines, the file is only suspicious
min_malicious_engines = 1

# Detection engines. Every engine is enabled unless explicitly disabled:
# if an enabled engine cannot load its signatures, the kiosk refuses to start.
# At least one content engine (clamav or yara) is required.
# Signature updates come with phase 2: see docs/engines.md.

[engines.malwarebazaar]
# Offline list of malicious SHA-256 hashes (abuse.ch MalwareBazaar),
# converted with: python -m pandora_box.hashdb build <export> <database>
enabled = true
database = "/var/lib/pandora-box-signatures/current/malwarebazaar/malwarebazaar.sha256.bin"

[engines.hashlookup]
# CIRCL hashlookup Bloom filter of known files (SHA-1, DCSO bloom format).
# "Known" does not mean "benign", and a Bloom filter has false positives
# (about 1 in 10,000): see docs/engines.md.
enabled = true
bloom = "/var/lib/pandora-box-signatures/current/hashlookup/hashlookup-full.bloom"
# Do not run ClamAV and YARA on known files (malicious hashes are always
# checked). Off: known is not benign, the CIRCL filter also lists the EICAR
# test file, tools and malware; on only saves time on software devices
skip_content_engines = false
# The filter is published monthly
max_age_days = 45.0

[engines.clamav]
# clamd Unix socket. clamd.conf must set "AlertExceedsMax yes": otherwise
# clamd reports content beyond its limits as clean without scanning it.
enabled = true
socket = "/run/clamav/clamd.ctl"
# "fildes": pass the open file to clamd, "instream": send its content,
# "auto": fildes, then instream if clamd cannot use the descriptor
mode = "auto"
# Socket timeout for one file, in seconds
timeout = 120.0
# Must not exceed MaxFileSize, MaxScanSize and StreamMaxLength of clamd.conf:
# bigger files are reported as errors without being sent (default: 100 MiB)
max_file_size = 104857600
# Detection names reported as suspicious instead of malicious (documents
# with macros: Heuristics.OLE2.ContainsMacros, clamd.conf AlertOLE2Macros)
suspicious_names = ["PUA.*", "Heuristics.*"]
# Detection names meaning that the file was not fully scanned: beyond the
# limits of clamd (archives too, decompression bombs), encrypted archives and
# documents (clamd.conf AlertEncrypted)
error_names = ["Heuristics.Limits.Exceeded.*", "Heuristics.Encrypted.*"]

[engines.yara]
enabled = true
# Rule sets: a .yar file or a folder of .yar/.yara files, each in its own
# namespace. YARA Forge already includes the signature-base rules; to add the
# full signature-base set anyway, append:
#   { name = "signature-base", path = "/var/lib/pandora-box-signatures/current/yara/signature-base/yara" }
rules = [
    { name = "yara-forge", path = "/var/lib/pandora-box-signatures/current/yara/yara-forge/yara-rules-core.yar" },
]
# Compiled rules cache ("" disables it)
cache_dir = "/var/cache/pandora-box/yara"
# Scan timeout for one file, in seconds
timeout = 60.0
# Rules that do not compile:
#   "fail":      refuse to start
#   "skip_rule": ignore them; they are listed in the logs and every scan report
on_compile_error = "fail"
# Rule files to ignore (glob patterns matched against the file path)
exclude = []
# Rule "score" metadata (0-100): from malicious_score the file is malicious,
# from suspicious_score it is suspicious, below it the match is informational.
# default_score applies to rules without a score.
malicious_score = 75
suspicious_score = 40
default_score = 60


[engines.heuristics]
# Structure of the files, without signatures: PDF with JavaScript or a
# Launch action, programs disguised as documents (facture.pdf, facture.pdf.exe).
# Findings are suspicious.
enabled = true
[signatures]
# Warn at startup when a signature database is older than this (in days);
# each engine can override it with its own max_age_days. A database without
# a date (ClamAV custom signatures only) is logged, not shown.
max_age_days = 7.0

# Signed signature sets (docs/signatures.md). The engines read the files of
# the installed set, folder/current. A set is only installed when it is
# signed by a public key of the keys folder (*.pem) and newer than the
# installed one.
folder = "/var/lib/pandora-box-signatures"
keys = "/usr/share/pandora-box/keys"
# Verify the installed set at startup (signature and every file), and refuse
# engine files outside of it. Without a valid set, the kiosk does not scan:
# it only accepts a signature update device. Set it to false for development.
verify = true
# Install the signed set of a device that holds a pandora-box-signatures
# folder at its root (such a device is not scanned)
update_from_devices = true

[updates]
# Online signature updates (docs/signatures.md): off by default, a kiosk works
# offline. They also need the image profile "online" (network, firewall, and
# the pandora-box-update timer, every 6 hours).
enabled = false
# Either the kiosk downloads the signatures from their sources and signs
# the set with its own key (MalwareBazaar needs an abuse.ch Auth-Key, a
# credential of the image: docs/signatures.md)...
sources = []
# e.g. sources = ["clamav", "yara-forge", "malwarebazaar", "hashlookup"]
# ...or it downloads a published signed set: the folder of the set
# (manifest.json, its signature and the files). HTTPS is recommended, HTTP is
# accepted.
url = ""
# URLs in place of the default ones of the sources, e.g. a company mirror:
# mirrors = { clamav = "https://clamav.example.org", hashlookup = "https://..." }
# Folder of a published image update (A/B updates, docs/update.md); "" for
# no online image updates
image_url = ""
# HTTP(S) proxy, e.g. "http://proxy.example.org:3128" ("": direct)
proxy = ""
# Timeout of each request, in seconds
timeout = 300.0
# Install the signed image update of a device that holds a pandora-box-image
# folder at its root, then restart (A/B updates, docs/update.md)
image_from_devices = true

[siem]
# Export of the logs to a SIEM (docs/siem.md): off by default, a kiosk works
# offline. It also needs the image profile "online" (network, firewall, and
# the pandora-box-siem service). Every entry of the log file is sent, also
# those logged while the SIEM could not be reached.
enabled = false
# Host name or IP address of the SIEM
host = ""
# "tls" (certificate verified), "tcp" or "udp"
transport = "tls"
# Port of the SIEM; 0: 6514 for tls, 514 for tcp and udp
port = 0
# Certificate authorities of the SIEM certificate (PEM file), for tls; ""
# for those of the system. In the image: image/siem-ca.pem, installed as
# /usr/share/pandora-box/siem-ca.pem
ca = ""
# "syslog": RFC 5424 message, the JSON entry as message (octet counting over
# tcp and tls); "json": the JSON entry alone (one per line over tcp and tls)
format = "syslog"
# Syslog facility: "user" or "local0" to "local7"
facility = "local0"
# Timeout of the connection and of each send, in seconds
timeout = 10.0

[report]
# JSON scan reports, one per scanned device
folder = "/var/lib/pandora-box/reports"

[quarantine]
# Copy infected files to the kiosk before removing them from the device
enabled = true
folder = "/var/lib/pandora-box/quarantine"

[logging]
# JSON lines log file ("" disables logging)
file = "/var/log/pandora-box/pandora-box.log"
# DEBUG, INFO, WARNING or ERROR
level = "INFO"