Maltrail is a malicious traffic detection system that monitors network traffic against known threat indicators – malicious domains, IPs, URLs, and HTTP User-Agent strings. It pulls from dozens of public threat intelligence feeds and combines them with built-in heuristic analysis to catch both known and unknown threats crossing your network.
This guide covers installing and configuring Maltrail v1.2 on Linux (Ubuntu/Debian and RHEL-based distributions). We will set up both the sensor and server components, configure systemd services for production use, set up firewall rules, and integrate with external SIEM platforms.
Prerequisites
Before starting, make sure you have the following in place:
- A Linux server running Ubuntu 24.04/22.04, Debian 13/12, Rocky Linux 10/9, AlmaLinux 10/9, or RHEL 10/9
- Root or sudo access
- At least 1 GB of RAM (more for multiprocessing mode)
- Python 3.x installed
- Network interface connected to a SPAN/mirror port or inline bridge for traffic monitoring
- Ports 8337/UDP (sensor logging) and 8338/TCP (web dashboard) available
Step 1: Install Dependencies for Maltrail
Maltrail requires Python 3, the pcapy-ng packet capture library, and a few build tools. The exact packages differ by distribution.
On Ubuntu/Debian:
sudo apt update
sudo apt install -y git python3 python3-dev python3-pip python-is-python3 libpcap-dev build-essential procps schedtoolOn Rocky Linux/AlmaLinux/RHEL:
sudo dnf install -y git python3 python3-devel python3-pip libpcap-devel gcc gcc-c++ procps-ng schedtoolNext, install the pcapy-ng Python library. This is the packet capture binding Maltrail uses to sniff network traffic:
sudo pip3 install pcapy-ngIf your distribution restricts system-wide pip installs (PEP 668), use the --break-system-packages flag or install inside a virtual environment. For a dedicated monitoring server, system-wide install is fine:
sudo pip3 install pcapy-ng --break-system-packagesStep 2: Clone the Maltrail Repository
Clone the latest Maltrail release from GitHub into /opt/maltrail. Using /opt keeps third-party software separate from system packages:
sudo git clone --depth 1 https://github.com/stamparm/maltrail.git /opt/maltrailVerify the clone completed successfully:
ls /opt/maltrail/sensor.py /opt/maltrail/server.py /opt/maltrail/maltrail.confAll three files should be listed – sensor.py (traffic sensor), server.py (web dashboard backend), and maltrail.conf (shared configuration).
Step 3: Configure Maltrail Sensor and Server
Maltrail uses a single configuration file for both sensor and server components. The defaults work for a basic deployment where both run on the same machine, but you should review a few key settings.
Open the configuration file:
sudo vi /opt/maltrail/maltrail.confReview and adjust these important sections:
Server Settings
The server section controls the web dashboard and log collection:
# [Server]
# Listen address for web dashboard (0.0.0.0 = all interfaces)
HTTP_ADDRESS 0.0.0.0
# Web dashboard port
HTTP_PORT 8338
# Enable SSL/TLS for production use
USE_SSL false
# Default admin credentials - CHANGE THE PASSWORD
# Generate hash: echo -n 'YourNewPassword' | sha256sum | cut -d " " -f 1
USERS
admin:9ab3cd9d67bf49d01f6a2e33d0bd9bc804ddbe6ce1ff5d219c42624851db5dbc:0:The default password is changeme!. Generate a new password hash immediately:
echo -n 'YourSecurePassword' | sha256sum | cut -d " " -f 1Replace the hash in the USERS line with the output from that command.
Sensor Settings
The sensor section controls how traffic is captured and analyzed:
# [Sensor]
# Number of capture processes (increase for high-traffic networks)
PROCESS_COUNT 1
# Monitor all network interfaces
MONITOR_INTERFACE any
# Capture buffer size (percentage of RAM or fixed size like 512MB)
CAPTURE_BUFFER 10%
# Enable heuristic analysis for unknown threats
USE_HEURISTICS true
# Trail update interval in seconds (86400 = daily)
UPDATE_PERIOD 86400
# Feeds to disable (noisy or outdated)
DISABLED_FEEDS turris, ciarmy, policeman, myip, alienvault
# Minimum number of feeds an IP must appear on to be flagged
IP_MINIMUM_FEEDS 3For production deployments, consider setting MONITOR_INTERFACE to a specific interface (like eth0) rather than any, and increase PROCESS_COUNT if you are monitoring high-bandwidth links.
Remote Sensor Configuration
If the sensor runs on a different machine than the server, configure the sensor to forward logs via UDP. Uncomment and set the LOG_SERVER directive in the sensor section:
# Remote server to send log entries
LOG_SERVER 192.168.1.10:8337On the server side, uncomment the UDP listener:
# UDP log collection address and port
UDP_ADDRESS 0.0.0.0
UDP_PORT 8337Step 4: Start the Maltrail Sensor
The sensor requires root privileges because it captures raw network packets. Start it manually first to confirm everything works:
sudo python3 /opt/maltrail/sensor.pyOn first launch, the sensor downloads threat intelligence feeds. You should see output similar to this:
Maltrail (sensor) v1.2
[i] loading static trails (32604)...
[i] loading trails from feed 'abuseipdb'...
[i] loading trails from feed 'blocklist'...
...
[i] loaded 125847 trails (43 feeds)
[i] monitoring interface 'any'...The initial feed download can take a few minutes depending on your internet connection. Once you see the “monitoring interface” message, the sensor is actively inspecting traffic. Press Ctrl+C to stop it – we will configure it as a systemd service in a later step.
Step 5: Start the Maltrail Server (Web Dashboard)
The server component provides the web-based reporting dashboard and stores event logs. It does not require root privileges. Start it to verify the web interface works:
python3 /opt/maltrail/server.py &You should see the server start and begin listening:
Maltrail (server) v1.2
[i] using storage directory '/var/log/maltrail'...
[i] starting HTTP server at 'http://0.0.0.0:8338/'...If the log directory does not exist, create it and set proper permissions:
sudo mkdir -p /var/log/maltrail
sudo chown -R root:root /var/log/maltrailStep 6: Access the Maltrail Web Dashboard
Open a web browser and navigate to http://your-server-ip:8338. You will see the Maltrail login page. Use the credentials configured in maltrail.conf – the default username is admin and the default password is changeme! (which you should have already changed in Step 3).
After logging in, the dashboard displays detected threats grouped by time. Each entry shows the source IP, destination, trail type (domain, IP, URL), and the threat category. The dashboard updates in real-time as the sensor detects new malicious traffic.
Key dashboard features include:
- Timeline view – 24-hour sliding window of detected events
- Threat classification – events tagged by type (malware, scanner, attacker, reputation)
- Source tracking – which feed or heuristic flagged each trail
- Search and filtering – filter by IP, domain, time range, or severity
Step 7: Configure Maltrail as a Systemd Service
Running Maltrail manually is fine for testing, but production deployments need systemd units for automatic startup, restart on failure, and proper logging. We will create two separate services – one for the sensor and one for the server.
Sensor Service
Create the sensor systemd unit file:
sudo vi /etc/systemd/system/maltrail-sensor.serviceAdd the following configuration:
[Unit]
Description=Maltrail Malicious Traffic Detection Sensor
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/python3 /opt/maltrail/sensor.py
WorkingDirectory=/opt/maltrail
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.targetServer Service
Create the server systemd unit file:
sudo vi /etc/systemd/system/maltrail-server.serviceAdd the following configuration:
[Unit]
Description=Maltrail Malicious Traffic Detection Server
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
ExecStart=/usr/bin/python3 /opt/maltrail/server.py
WorkingDirectory=/opt/maltrail
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.targetReload systemd, enable both services to start at boot, and start them:
sudo systemctl daemon-reload
sudo systemctl enable --now maltrail-sensor.service
sudo systemctl enable --now maltrail-server.serviceVerify both services are running:
sudo systemctl status maltrail-sensor.service maltrail-server.serviceBoth services should show active (running). If either fails, check the journal for errors:
sudo journalctl -u maltrail-sensor.service -n 50 --no-pager
sudo journalctl -u maltrail-server.service -n 50 --no-pagerStep 8: Configure Firewall for Maltrail
Maltrail needs two ports open – TCP 8338 for the web dashboard and UDP 8337 for remote sensor log collection. If you are running both components on the same server and only need local dashboard access, you can skip the UDP port.
Using firewalld (RHEL/Rocky/AlmaLinux)
Open the required ports and reload the firewall. If you need a refresher on firewalld management, check our dedicated guide:
sudo firewall-cmd --permanent --add-port=8338/tcp
sudo firewall-cmd --permanent --add-port=8337/udp
sudo firewall-cmd --reloadVerify the ports are open:
sudo firewall-cmd --list-portsYou should see 8338/tcp and 8337/udp in the output.
Using UFW (Ubuntu/Debian)
Allow the Maltrail ports through UFW:
sudo ufw allow 8338/tcp comment "Maltrail Web Dashboard"
sudo ufw allow 8337/udp comment "Maltrail Sensor Logging"
sudo ufw reloadConfirm the rules are active:
sudo ufw status numberedBoth Maltrail rules should appear in the list. For production environments, restrict access to specific source IPs rather than opening the ports to everyone.
Step 9: Integrate Maltrail with a SIEM Platform
Maltrail supports forwarding detected events to external SIEM platforms through Syslog and Logstash integrations. This is valuable when Maltrail is one of several security tools feeding into a central platform like Wazuh or Elastic SIEM.
Syslog Integration
To forward events to a Syslog server, edit maltrail.conf and uncomment the SYSLOG_SERVER directive in the sensor section:
sudo vi /opt/maltrail/maltrail.confSet your Syslog server address and port:
# Remote address to send Syslog events
SYSLOG_SERVER 192.168.1.20:514Logstash/JSON Integration
For Elastic Stack or similar platforms, Maltrail can send events in JSON format to a Logstash listener. Uncomment and configure the LOGSTASH_SERVER directive:
# Remote address to send JSON events to Logstash
LOGSTASH_SERVER 192.168.1.20:5000Maltrail uses a severity regex to classify events when forwarding. The default configuration categorizes events into high, medium, and low severity:
REMOTE_SEVERITY_REGEX (?P(remote )?custom\)|malwaredomainlist|iot-malware|malware(?! (distribution|site))|adversary|ransomware)|(?Ppotential malware site|malware distribution)|(?Pmass scanner|reputation|attacker|spammer|compromised|crawler|scanning) Adjust the regex patterns to match your organization’s severity classifications.
Fail2ban Integration
Maltrail exposes a /fail2ban endpoint that returns attacker IPs in a format fail2ban can consume. This lets you automatically block source IPs that Maltrail flags as malicious. The endpoint is restricted to local and private networks by default through the FAIL2BAN_ALLOWLIST setting.
After making any SIEM configuration changes, restart the sensor to apply them:
sudo systemctl restart maltrail-sensor.serviceKeeping Maltrail Updated
Maltrail’s effectiveness depends on current threat feeds. The sensor updates feeds automatically based on the UPDATE_PERIOD setting (daily by default). To update the Maltrail application itself, pull the latest changes from Git:
cd /opt/maltrail && sudo git pullThen restart both services:
sudo systemctl restart maltrail-sensor.service maltrail-server.serviceCheck the Maltrail releases page periodically for new versions and significant changes.
Conclusion
Maltrail is now running as a production-ready malicious traffic detection system on your Linux server. The sensor monitors network traffic against threat intelligence feeds while the web dashboard gives you visibility into detected threats. For production hardening, enable SSL on the web dashboard, restrict firewall rules to trusted management IPs, and forward events to your central SIEM for correlation with other security data sources. Tools like Suricata IDS complement Maltrail well by providing deep packet inspection alongside Maltrail’s threat intelligence matching.
