Maltrail

https://github.com/stamparm/maltrail
Admin
Maltrail is a malicious traffic detection system that uses public and custom blacklists (domains,...
Tokens:18,583
Snippets:122
Trust Score:9.2
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Maltrail Server Component (Bash)

Source: https://context7.com/stamparm/maltrail/llms.txt

Starts the Maltrail server, which provides the web-based reporting interface. It includes options for custom configuration and notes the default access URL and credentials.

```bash
# Start server (reporting interface)
python server.py

# Start server with custom config
python server.py -c /etc/maltrail/maltrail.conf

# Access web interface at http://127.0.0.1:8338
# Default credentials: admin:changeme!
```

--------------------------------

### Install Maltrail Dependencies and Sensor (Bash)

Source: https://context7.com/stamparm/maltrail/llms.txt

Installs necessary packages on Ubuntu/Debian, clones the Maltrail repository, and starts the sensor component. It also demonstrates how to test detection with a known malicious IP and view logs.

```bash
# Install dependencies on Ubuntu/Debian
sudo apt-get install git python3 python3-dev python3-pip python-is-python3 libpcap-dev build-essential procps schedtool
sudo pip3 install pcapy-ng

# Clone and start sensor
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail
sudo python3 sensor.py

# Start sensor with custom config
sudo python3 sensor.py -c /etc/maltrail/maltrail.conf

# Test detection with known malicious IP
ping -c 1 136.161.101.53
cat /var/log/maltrail/$(date +"%Y-%m-%d").log
```

--------------------------------

### Systemd Service Setup

Source: https://context7.com/stamparm/maltrail/llms.txt

Instructions for setting up Maltrail as a systemd service for both sensor and server.

```APIDOC
## Systemd Service Setup

### Setup Service Files
Copy the provided service files to the systemd system directory:

```bash
sudo cp maltrail-sensor.service /etc/systemd/system/
sudo cp maltrail-server.service /etc/systemd/system/
```

After copying the files, you will need to enable and start the services using `systemctl`:

```bash
sudo systemctl enable maltrail-sensor.service
sudo systemctl start maltrail-sensor.service

sudo systemctl enable maltrail-server.service
sudo systemctl start maltrail-server.service
```
```

--------------------------------

### Maltrail Heuristic Detection Configuration Examples

Source: https://context7.com/stamparm/maltrail/llms.txt

Examples of heuristic detection rules within Maltrail, which can be enabled by setting USE_HEURISTICS to true in the configuration. These cover various detection methods like long domain names, high entropy, and direct executable downloads.

```python
# Heuristic detection examples (enabled with USE_HEURISTICS true)

# Long domain name detection
# Threshold: SUSPICIOUS_DOMAIN_LENGTH_THRESHOLD
# Example: abcdefghijklmnopqrstuvwxyz0123456789.example.com

# High domain entropy detection
# Threshold: SUSPICIOUS_DOMAIN_ENTROPY_THRESHOLD
# Example: xj8k3mq9pr4s.ru (DGA domain)

# Excessive consonants in domain
# Threshold: SUSPICIOUS_DOMAIN_CONSONANT_THRESHOLD
# Example: qwrtpsdfghjklzxcvbnm.com

# Direct executable download
# Extensions: .exe, .dll, .scr, .bin, .apk, .ps1, etc.
# Example: http://192.0.2.50/payload.exe

# Port scanning detection
# Threshold: PORT_SCANNING_THRESHOLD connections
# Example: Multiple SYN packets to different ports from same source

# DNS exhaustion detection
# Threshold: DNS_EXHAUSTION_THRESHOLD queries
# Example: Random subdomain queries (DDoS attack)

# Web application scanning
# Detection: SQL injection, XSS, directory traversal patterns
# Example: /admin.php?id=1' OR '1'='1
```

--------------------------------

### Start Maltrail Server

Source: https://github.com/stamparm/maltrail/blob/master/README.md

This snippet demonstrates how to start the Maltrail server component. It first ensures the Maltrail directory exists by cloning the repository if necessary, then navigates into the directory and executes the server script.

```shell
[[ -d maltrail ]] || git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail
python server.py
```

--------------------------------

### Logstash Integration

Source: https://context7.com/stamparm/maltrail/llms.txt

Configure Logstash to process Maltrail logs. Includes server configuration, JSON output example, and Logstash pipeline configuration.

```APIDOC
## Logstash Integration

### Configuration
Set the Logstash server in `maltrail.conf`:
```
LOGSTASH_SERVER 192.168.2.107:5000
```

### JSON Output Example
```json
{
  "timestamp": 1608818692,
  "sensor": "beast",
  "severity": "high",
  "src_ip": "192.168.5.137",
  "src_port": 48949,
  "dst_ip": "8.8.8.8",
  "dst_port": 53,
  "proto": "UDP",
  "type": "DNS",
  "trail": "morphed.ru",
  "info": "andromeda (malware)",
  "reference": "(static)"
}
```

### Logstash Configuration Example
```logstash
input {
  udp {
    port => 5000
    codec => json
  }
}
filter {
  if [sensor] == "beast" {
    mutate {
      add_tag => ["maltrail", "security"]
    }
  }
}
output {
  elasticsearch {
    hosts => ["localhost:9200"]
    index => "maltrail-%{+YYYY.MM.dd}"
  }
}
```
```

--------------------------------

### Manage Maltrail Services with systemctl

Source: https://context7.com/stamparm/maltrail/llms.txt

Commands to enable, start, and check the status of Maltrail server and sensor services using systemctl. This ensures Maltrail runs as intended and allows for quick status verification.

```bash
sudo systemctl daemon-reload
sudo systemctl enable maltrail-server.service
sudo systemctl enable maltrail-sensor.service
sudo systemctl start maltrail-server.service
sudo systemctl start maltrail-sensor.service
systemctl status maltrail-server.service
systemctl status maltrail-sensor.service
```

--------------------------------

### Set Up Maltrail as a Systemd Service

Source: https://context7.com/stamparm/maltrail/llms.txt

This snippet details the steps to set up Maltrail as a systemd service by copying the provided service files to the systemd directory. This allows Maltrail sensor and server to be managed using standard systemd commands (start, stop, enable, disable).

```bash
# Copy service files
sudo cp maltrail-sensor.service /etc/systemd/system/
sudo cp maltrail-server.service /etc/systemd/system/
```

--------------------------------

### Install Maltrail on SUSE/openSUSE

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Installs necessary packages (gcc, git, pcapy-ng, python3, etc.), clones the Maltrail repository, and moves it to /opt on SUSE/openSUSE systems.

```sh
sudo zypper install gcc gcc-c++ git libpcap-devel python3-devel python3-pip procps schedtool
sudo pip3 install pcapy-ng
cd /tmp
git clone --depth 1 https://github.com/stamparm/maltrail.git
sudo mv /tmp/maltrail /opt
sudo chown -R $USER:$USER /opt/maltrail
```

--------------------------------

### Maltrail Whitelist Configuration

Source: https://context7.com/stamparm/maltrail/llms.txt

Demonstrates how to create and configure a whitelist file for Maltrail to exclude specific domains, IPs, and URLs from being flagged. It also shows how to reference this file in the main configuration and a Python example for programmatic checks.

```bash
# Create whitelist file
cat > /etc/maltrail/whitelist.txt << 'EOF'
# Whitelisted domains
google.com
microsoft.com
*.cloudflare.com

# Whitelisted IPs
8.8.8.8
8.8.4.4
192.168.0.0/16

# Whitelisted URLs
http://updates.example.com/*
EOF

# Configure in maltrail.conf
USER_WHITELIST /etc/maltrail/whitelist.txt

# Programmatic whitelist check (in custom code)
from core.common import check_whitelisted
if check_whitelisted("example.com", "192.168.1.1"):
    print("Traffic is whitelisted")
```

--------------------------------

### Install Maltrail on Ubuntu/Debian

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Installs necessary packages (git, python3, pcapy-ng, etc.), clones the Maltrail repository, and moves it to /opt on Ubuntu/Debian systems.

```sh
sudo apt-get install git python3 python3-dev python3-pip python-is-python3 libpcap-dev build-essential procps schedtool
sudo pip3 install pcapy-ng
cd /tmp
git clone --depth 1 https://github.com/stamparm/maltrail.git
sudo mv /tmp/maltrail /opt
sudo chown -R $USER:$USER /opt/maltrail
```

--------------------------------

### Install Maltrail Sensor on SUSE/openSUSE

Source: https://github.com/stamparm/maltrail/blob/master/README.md

This snippet outlines the installation process for Maltrail's sensor on SUSE/openSUSE systems. It covers installing development tools, git, Python 3 packages, and the pcapy-ng library, followed by cloning the Maltrail repository and running the sensor.

```shell
sudo zypper install gcc gcc-c++ git libpcap-devel python3-devel python3-pip procps schedtool
sudo pip3 install pcapy-ng
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail
sudo python3 sensor.py
```

--------------------------------

### Maltrail Server Configuration (INI)

Source: https://context7.com/stamparm/maltrail/llms.txt

Example configuration for the Maltrail server component, covering HTTP address and port, SSL settings, user authentication, UDP log collection, server trail updates, IP aliases, Fail2ban regex, and blacklist generation rules.

```ini
# [Server] section configuration

# HTTP server listen address
HTTP_ADDRESS 0.0.0.0

# HTTP server listen port
HTTP_PORT 8338

# Enable SSL/TLS
USE_SSL false

# SSL certificate file
#SSL_PEM misc/server.pem

# User authentication (username:sha256(password):UID:filter_netmask)
# Generate password hash: echo -n 'password' | sha256sum | cut -d " " -f 1
USERS
    admin:9ab3cd9d67bf49d01f6a2e33d0bd9bc804ddbe6ce1ff5d219c42624851db5dbc:0:

# UDP server for log collection from remote sensors
#UDP_ADDRESS 0.0.0.0
#UDP_PORT 8337

# Server updates trails too
USE_SERVER_UPDATE_TRAILS false

# IP aliases for web interface
#IP_ALIASES
#    8.8.8.8:google
#    8.8.4.4:google

# Fail2ban regex for attacker extraction
FAIL2BAN_REGEX attacker|reputation|potential[^" ]*(web scan|directory traversal|injection|remote code|iot-malware download)|spammer|mass scanner

# Blacklist generation rules
#BLACKLIST
#    src_ip !~ ^192.168. and dst_port ~ ^22$
#    src_ip ~ ^192.168. and filter ~ malware
```

--------------------------------

### Docker Deployment

Source: https://context7.com/stamparm/maltrail/llms.txt

Instructions for deploying Maltrail using Docker, including building and running the server container and using Docker Compose.

```APIDOC
## Docker Deployment

### Run Server Container
Build and run the Maltrail server container:
```bash
docker run -d \
  --name maltrail \
  --restart=unless-stopped \
  -p 8338:8338/tcp \
  -p 8337:8337/udp \
  -v /etc/maltrail.conf:/opt/maltrail/maltrail.conf:ro \
  -v /var/log/maltrail:/var/log/maltrail \
  ghcr.io/stamparm/maltrail:latest
```

### Update Container
Regularly update the Maltrail container:
```bash
docker stop maltrail
docker pull ghcr.io/stamparm/maltrail:latest
docker start maltrail
```

### Docker Compose Deployment
Create a `docker-compose.yml` file for easier management:
```yaml
version: '3' # Use '3.8' or higher for Compose V2
services:
  maltrail:
    image: ghcr.io/stamparm/maltrail:latest
    container_name: maltrail
    restart: unless-stopped
    ports:
      - "8338:8338/tcp"
      - "8337:8337/udp"
    volumes:
      - ./maltrail.conf:/opt/maltrail/maltrail.conf:ro
      - /var/log/maltrail:/var/log/maltrail
```

Start the services with Docker Compose:
```bash
docker compose up -d
```
```

--------------------------------

### Configure Maltrail Auto-start and Updates with Crontab

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Sets up crontab entries for automatically starting the Maltrail server if it's not running and for performing periodic git pull to update the Maltrail installation. Also configures crontab for the sensor to auto-start and periodic restarts.

```crontab
*/5 * * * * if [ -n "$(ps -ef | grep -v grep | grep 'server.py')" ]; then : ; else python3 /opt/maltrail/server.py -c /etc/maltrail/maltrail.conf; fi
0 1 * * * cd /opt/maltrail && git pull
```

```crontab
*/1 * * * * if [ -n "$(ps -ef | grep -v grep | grep 'sensor.py')" ]; then : ; else python3 /opt/maltrail/sensor.py -c /etc/maltrail/maltrail.conf; fi
2 1 * * * /usr/bin/pkill -f maltrail
```

--------------------------------

### Install Maltrail Sensor on Ubuntu/Debian

Source: https://github.com/stamparm/maltrail/blob/master/README.md

This snippet provides the necessary commands to install Maltrail's sensor component on Ubuntu/Debian systems. It includes installing system dependencies like git, python3, and build tools, followed by installing the pcapy-ng Python package and cloning the Maltrail repository.

```shell
sudo apt-get install git python3 python3-dev python3-pip python-is-python3 libpcap-dev build-essential procps schedtool
sudo pip3 install pcapy-ng
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail
sudo python3 sensor.py
```

--------------------------------

### Automated Maltrail Installation Script for Ubuntu/Debian

Source: https://context7.com/stamparm/maltrail/llms.txt

A bash script to automate the installation of Maltrail on Ubuntu/Debian systems. It installs dependencies, clones the repository, sets up directories, and configures cron jobs for auto-restart and updates.

```bash
#!/bin/bash
set -e

# Install dependencies
sudo apt-get update
sudo apt-get install -y git python3 python3-dev python3-pip python-is-python3 \
  libpcap-dev build-essential procps schedtool
sudo pip3 install pcapy-ng

# Install Maltrail
cd /tmp
git clone --depth 1 https://github.com/stamparm/maltrail.git
sudo mv /tmp/maltrail /opt
sudo chown -R $USER:$USER /opt/maltrail

# Setup directories
sudo mkdir -p /var/log/maltrail
sudo mkdir -p /etc/maltrail
sudo cp /opt/maltrail/maltrail.conf /etc/maltrail

# Configure cron for auto-restart and updates
echo "*/1 * * * * if [ -n \"\$(ps -ef | grep -v grep | grep 'sensor.py')\" ]; then : ; else python3 /opt/maltrail/sensor.py -c /etc/maltrail/maltrail.conf; fi" | sudo crontab - echo "0 1 * * * cd /opt/maltrail && git pull" | crontab - 

echo "Installation complete. Edit /etc/maltrail/maltrail.conf and start services."
```

--------------------------------

### Start Maltrail Server with Docker

Source: https://github.com/stamparm/maltrail/blob/master/README.md

This snippet shows how to start the Maltrail server using a Docker container. It details the `docker run` command, including options for detached mode, container naming, restart policy, port mapping for TCP and UDP, volume mounting for configuration, and specifying the image.

```shell
# Build image
# Start the server
docker run -d --name maltrail --restart=unless-stopped --port 8338:8338/tcp --port 8337:8337/udp -v /etc/maltrail.conf:/opt/maltrail/maltrail.conf:ro ghcr.io/stamparm/maltrail:latest
```

--------------------------------

### Maltrail Sensor Configuration (INI)

Source: https://context7.com/stamparm/maltrail/llms.txt

Example configuration for the Maltrail sensor component, detailing settings for multiprocessing, feed updates, disabled feeds, IP thresholds, update periods, capture buffers, interfaces, filters, logging, heuristics, and custom trails.

```ini
# [Sensor] section configuration

# Number of processes for multiprocessing
PROCESS_COUNT 1

# Use feeds in trail updates
USE_FEED_UPDATES true

# Disabled feeds (comma-separated)
DISABLED_FEEDS turris, ciarmy, policeman, myip, alienvault

# Minimum number of feeds for IP to be considered malicious
IP_MINIMUM_FEEDS 3

# Update trails every 86400 seconds (24 hours)
UPDATE_PERIOD 86400

# Network capture buffer size
CAPTURE_BUFFER 10%

# Interface to monitor
MONITOR_INTERFACE any

# Network capture filter
CAPTURE_FILTER udp or icmp or (tcp and (tcp[tcpflags] == tcp-syn or port 80 or port 1080 or port 3128 or port 8000 or port 8080 or port 8118))

# Sensor name in logs
SENSOR_NAME $HOSTNAME

# Remote server for log collection (UDP)
#LOG_SERVER 192.168.2.107:8337

# Remote Syslog server
#SYSLOG_SERVER 192.168.2.107:514

# Remote Logstash server (JSON format)
#LOGSTASH_SERVER 192.168.2.107:5000

# Enable heuristic detection methods
USE_HEURISTICS true

# Custom trails directory
CUSTOM_TRAILS_DIR ./trails/custom
```

--------------------------------

### Install Certbot and Apache Plugin on Ubuntu/Debian

Source: https://github.com/stamparm/maltrail/wiki/Certbot-integration-Maltrail

Installs Certbot and the Apache plugin required for SSL certificate management on Ubuntu or Debian systems. This is a prerequisite for enabling SSL for Maltrail.

```bash
sudo apt-get install certbot python3-certbot-apache -y
```

--------------------------------

### Maltrail Sensor - Combined Parameters Example

Source: https://github.com/stamparm/maltrail/wiki/CLI-management-for-Maltrail

Provides an example of using multiple parameters simultaneously with the Maltrail sensor to tailor its behavior for specific analysis needs, such as offline analysis with console output and quiet mode.

```bash
python sensor.py -r traffic.pcap -c custom.conf -q --console --offline
```

--------------------------------

### Maltrail Event Filtering and Ignoring Rules

Source: https://context7.com/stamparm/maltrail/llms.txt

Instructions for creating and configuring an ignore rules file for Maltrail to suppress specific types of events. It includes examples for ignoring by source IP, trail information, references, and DNS queries, as well as a regex-based ignore configuration.

```bash
# Create ignore rules file
cat > /etc/maltrail/ignore_events.txt << 'EOF'
# Ignore events by pattern matching
# Format: field operator value

# Ignore specific source IP
src_ip equals 192.168.1.100

# Ignore specific trail info
info contains "false positive"

# Ignore by reference
reference equals "blocklist.de"

# Ignore DNS queries to specific domain
trail contains ".example.com" and type equals "DNS"
EOF

# Configure in maltrail.conf
USER_IGNORELIST /etc/maltrail/ignore_events.txt

# Regex-based ignore
IGNORE_EVENTS_REGEX sql injection|long domain|117.21.225.3|sinkhole
```

--------------------------------

### Deploy Maltrail Server with Docker

Source: https://context7.com/stamparm/maltrail/llms.txt

This provides Docker commands to build and run the Maltrail server container, including persistent volume mappings for configuration and logs. It also shows how to update the container regularly. Docker Compose deployment is also included.

```bash
# Build and run server container
docker run -d \
  --name maltrail \
  --restart=unless-stopped \
  -p 8338:8338/tcp \
  -p 8337:8337/udp \
  -v /etc/maltrail.conf:/opt/maltrail/maltrail.conf:ro \
  -v /var/log/maltrail:/var/log/maltrail \
  ghcr.io/stamparm/maltrail:latest

# Update container regularly
docker stop maltrail
docker pull ghcr.io/stamparm/maltrail:latest
docker start maltrail

# Docker Compose deployment
cat > docker-compose.yml << 'EOF'
version: '3' 
services:
  maltrail:
    image: ghcr.io/stamparm/maltrail:latest
    container_name: maltrail
    restart: unless-stopped
    ports:
      - "8338:8338/tcp"
      - "8337:8337/udp"
    volumes:
      - ./maltrail.conf:/opt/maltrail/maltrail.conf:ro
      - /var/log/maltrail:/var/log/maltrail
EOF

docker compose up -d
```

--------------------------------

### Set up Centralized Maltrail Logging with UDP

Source: https://github.com/stamparm/maltrail/wiki/Miscellaneous

This section outlines the configuration steps for a centralized Maltrail logging setup. On the server, UDP logging is enabled and bound to a specific IP address. On each sensor, the server's IP and port are specified to forward logs. This allows a single Maltrail server to collect logs from multiple sensor installations.

```text
# On server side (e.g., 192.168.10.1):
# In /maltrail.conf, [Server] section:
# UDP_PORT 8337
# UDP_ADDRESS 192.168.10.1

# On client side (e.g., 192.168.10.2, 192.168.10.3, 192.168.10.4):
# In /maltrail.conf, [Sensor] section:
# LOG_SERVER 192.168.10.1:8337
```

--------------------------------

### Maltrail Log Format and Parsing (Bash)

Source: https://context7.com/stamparm/maltrail/llms.txt

Describes the format of Maltrail log files, which are stored in CSV format with a space delimiter. It provides an example log entry and demonstrates how to parse it using standard command-line tools like `awk`.

```bash
# Log files stored in: /var/log/maltrail/YYYY-MM-DD.log
# Format: CSV with space delimiter
# Fields: time sensor src_ip src_port dst_ip dst_port proto trail_type trail trail_info reference

# Example log entry
cat /var/log/maltrail/2025-10-18.log
# Output:
# "2025-10-18 15:48:41.152513" beast 192.168.5.33 32985 8.8.8.8 53 UDP DNS morphed.ru "andromeda (malware)" "(static)"

# Parse log with standard tools
awk '{print $3, $9, $10}' /var/log/maltrail/2025-10-18.log
# Output: source_ip trail trail_info
```

--------------------------------

### Create and Load Custom Trails in Maltrail

Source: https://context7.com/stamparm/maltrail/llms.txt

This demonstrates how to create custom trail definition files for Maltrail, specifying the format as 'trail info reference'. It shows how to create a file, load it automatically on sensor startup, or configure a custom directory or remote URL for trail files.

```bash
# Create custom trail file: trails/custom/mycompany.txt
# Format: trail info reference

# Example custom trail file
cat > trails/custom/mycompany.txt << 'EOF'
# Bad actors targeting our infrastructure
badactor.example.com custom threat (internal)
192.0.2.50 malicious scanner (detected)
malicious-payload.exe dangerous file (incident-2025-001)
EOF

# Sensor automatically loads custom trails on startup
sudo python3 sensor.py

# Or specify custom directory in maltrail.conf
CUSTOM_TRAILS_DIR /etc/maltrail/custom_trails

# Remote custom trails URL
CUSTOM_TRAILS_URL http://www.example.com/custom.txt
```

--------------------------------

### Custom Trail Definitions

Source: https://context7.com/stamparm/maltrail/llms.txt

Learn how to create and manage custom threat intelligence trails for Maltrail. Covers defining trails in files and configuring the sensor to load them.

```APIDOC
## Custom Trail Definitions

### Creating Custom Trail Files
Create text files (e.g., `trails/custom/mycompany.txt`) with the format: `trail info reference`.

**Example File (`trails/custom/mycompany.txt`):**
```
# Bad actors targeting our infrastructure
badactor.example.com custom threat (internal)
192.0.2.50 malicious scanner (detected)
malicious-payload.exe dangerous file (incident-2025-001)
```

### Loading Custom Trails

*   **Automatic Loading:** The sensor automatically loads custom trails from the default `trails/custom/` directory on startup.
    ```bash
    sudo python3 sensor.py
    ```

*   **Custom Directory:** Specify a custom directory in `maltrail.conf`:
    ```
    CUSTOM_TRAILS_DIR /etc/maltrail/custom_trails
    ```

*   **Remote Custom Trails URL:** Configure a URL in `maltrail.conf` to fetch trails remotely:
    ```
    CUSTOM_TRAILS_URL http://www.example.com/custom.txt
    ```
```

--------------------------------

### Automate IP Blocking with Fail2ban and Maltrail

Source: https://context7.com/stamparm/maltrail/llms.txt

This script retrieves attacker IPs from Maltrail's API, adds them to an ipset, and configures iptables to drop traffic from those IPs. It's designed to be run periodically via cron. Ensure ipset and iptables are installed.

```bash
# Get attacker IPs for blocking
curl http://127.0.0.1:8338/fail2ban

# Example output (one IP per line):
# 45.227.253.132
# 185.220.101.34
# 192.168.1.105

# Automated blocking script (run as root cronjob)
#!/bin/bash
ipset -q flush maltrail
ipset -q create maltrail hash:net
for ip in $(curl http://127.0.0.1:8338/fail2ban 2>/dev/null | grep -P '^[0-9.]+$'); do
  ipset add maltrail $ip
done
iptables -I INPUT -m set --match-set maltrail src -j DROP

# Add to crontab for periodic updates
# */1 * * * * /path/to/fail2ban-maltrail.sh
```

--------------------------------

### Fail2ban Integration

Source: https://context7.com/stamparm/maltrail/llms.txt

Integrate Maltrail with Fail2ban to automatically block malicious IP addresses. Includes commands to fetch IPs and a script for automated blocking.

```APIDOC
## Fail2ban Integration

### Get Attacker IPs
Fetch a list of attacker IPs from Maltrail:
```bash
curl http://127.0.0.1:8338/fail2ban
```

### Example Output
```
45.227.253.132
185.220.101.34
192.168.1.105
```

### Automated Blocking Script
This script can be run periodically via cron. Ensure you have `ipset` installed.

`fail2ban-maltrail.sh`:
```bash
#!/bin/bash

ipset -q flush maltrail
ipset -q create maltrail hash:net

for ip in $(curl http://127.0.0.1:8338/fail2ban 2>/dev/null | grep -P '^[0-9.]+$'); do
  ipset add maltrail $ip
done

iptables -I INPUT -m set --match-set maltrail src -j DROP
```

Add to crontab (e.g., every minute):
```crontab
*/1 * * * * /path/to/fail2ban-maltrail.sh
```
```

--------------------------------

### Docker Compose for Maltrail Management

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Instructions for managing Maltrail services using Docker Compose. This includes building the image, starting services in detached mode, stopping services, and rebuilding the image. It also advises using `docker-compose.override.yml` for custom configurations.

```sh
# For both
docker compose up -d
# Update image regularly
docker compose down --remove-orphans
docker compose build
docker compose up -d
```

--------------------------------

### Fixing SystemError in Maltrail (Python)

Source: https://github.com/stamparm/maltrail/wiki/FAQ

This snippet addresses a specific SystemError encountered when starting the Maltrail sensor, often due to the incorrect pcapy library being used instead of pcapy-ng. It provides commands to uninstall the problematic library and install the correct one, ensuring proper functionality, especially on Python 3.x environments.

```shell
pip3 uninstall pcapy
pip3 install pcapy-ng
```

--------------------------------

### Maltrail Sensor - Plugin Usage Example

Source: https://github.com/stamparm/maltrail/wiki/CLI-management-for-Maltrail

Illustrates the usage of the '-p' parameter to enable specific plugins for the Maltrail sensor during real-time analysis. This allows for extended detection capabilities beyond the default set.

```bash
python sensor.py -p strings
```

--------------------------------

### Restart Maltrail Services

Source: https://github.com/stamparm/maltrail/wiki/Certbot-integration-Maltrail

Restarts the Maltrail sensor and server services to apply configuration changes, including newly enabled SSL settings. This ensures that Maltrail is running with the updated configuration.

```bash
systemctl restart maltrail-sensor.service && systemctl restart maltrail-server.service
```

--------------------------------

### Enable Maltrail as Systemd Services

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Copies Maltrail service files to the systemd directory, reloads the systemd daemon, starts and enables the Maltrail server and sensor services.

```sh
sudo cp /opt/maltrail/maltrail-sensor.service /etc/systemd/system/maltrail-sensor.service
sudo cp /opt/maltrail/maltrail-server.service /etc/systemd/system/maltrail-server.service
sudo systemctl daemon-reload
sudo systemctl start maltrail-server.service
sudo systemctl start maltrail-sensor.service
sudo systemctl enable maltrail-server.service
sudo systemctl enable maltrail-sensor.service
systemctl status maltrail-server.service && systemctl status maltrail-sensor.service
```

--------------------------------

### Access Maltrail Trails Database via Web API

Source: https://context7.com/stamparm/maltrail/llms.txt

This demonstrates how to access Maltrail's trails database via the Web API, which is useful for remote sensors or updates. It also covers configuring the server to update trails and enabling sensors to pull these updates. Trails are served compressed.

```bash
# Get current trails database (for remote sensors)
curl http://127.0.0.1:8338/trails

# Update server trails and enable distribution
# In maltrail.conf [Server]:
USE_SERVER_UPDATE_TRAILS true

# Configure sensors to pull from server
# In maltrail.conf [Sensor]:
UPDATE_SERVER http://192.168.2.107:8338/trails

# Trails are served in compressed format
# Sensors automatically decompress and load
```

--------------------------------

### Clipper Endpoint (GET)

Source: https://github.com/stamparm/maltrail/blob/master/trails/static/malware/predatory.txt

Retrieves data related to the clipper.

```APIDOC
## GET /api/Clipper.get

### Description
Retrieves data associated with the clipper.

### Method
GET

### Endpoint
/api/Clipper.get

### Parameters
#### Query Parameters
- **id** (string) - Optional - Identifier for specific clipper data.

### Request Example
```json
{
  "id": "clipper_123"
}
```

### Response
#### Success Response (200)
- **data** (object) - The retrieved clipper data.
```

--------------------------------

### Custom Blacklist Endpoints

Source: https://context7.com/stamparm/maltrail/llms.txt

Define and access custom blacklists via the Maltrail API. Learn how to configure blacklists in `maltrail.conf` and retrieve them using `curl`.

```APIDOC
## Custom Blacklist Endpoints

### Configuration in `maltrail.conf`
Define custom rules for incoming (`BLACKLIST_IN`) and outgoing (`BLACKLIST_OUT`) traffic.

Example:
```
BLACKLIST_OUT
    src_ip !~ ^192.168. and dst_port ~ ^22$
    src_ip !~ ^192.168. and filter ~ scan
    src_ip !~ ^192.168. and filter ~ known attacker

BLACKLIST_IN
    src_ip ~ ^192.168. and filter ~ malware
```

### Access Blacklists via HTTP API
Retrieve the configured blacklists using the following endpoints:

**Outgoing Blacklist:**
```bash
curl http://127.0.0.1:8338/blacklist/out
```

**Incoming Blacklist:**
```bash
curl http://127.0.0.1:8338/blacklist/in
```

### Usage with `ipset`
Example of using the outgoing blacklist with `ipset` for blocking:
```bash
ipset create blacklist_out hash:net
for ip in $(curl http://127.0.0.1:8338/blacklist/out); do ipset add blacklist_out $ip; done
```
```

--------------------------------

### View Maltrail Service Logs with journalctl

Source: https://context7.com/stamparm/maltrail/llms.txt

Commands to view real-time logs for Maltrail sensor and server services using journalctl. This is essential for debugging and monitoring operational activity.

```bash
journalctl -u maltrail-sensor.service -f
journalctl -u maltrail-server.service -f
```

--------------------------------

### Web API - Events Endpoint

Source: https://context7.com/stamparm/maltrail/llms.txt

Access Maltrail's event data through its web API. This endpoint allows fetching events by date and filtering them by keywords. Responses are gzip compressed.

```APIDOC
## Web API - Events Endpoint

### Description
Retrieves security events detected by Maltrail. The API requires basic authentication.

### Method
`GET`

### Endpoint
`/events`

### Query Parameters
*   **date** (string, required) - The date for which to retrieve events (format: `YYYY-MM-DD`).
*   **filter** (string, optional) - A keyword to filter events.

### Request Example
Get events for a specific date:
```bash
curl -u admin:changeme! 'http://127.0.0.1:8338/events?date=2025-10-18'
```

Get events for a specific date and filter by 'malware':
```bash
curl -u admin:changeme! 'http://127.0.0.1:8338/events?date=2025-10-18&filter=malware'
```

### Response
*   The response is gzip compressed JSON.
*   Events are returned in chunks for efficient processing.

#### Success Response (200)
Example structure:
```json
[
  ["2025-10-18 10:23:45", "sensor1", "192.168.1.100", "54321", "8.8.8.8", "53", "UDP", "DNS", "evil.com", "malware c2", "(static)"],
  ["2025-10-18 10:24:12", "sensor1", "192.168.1.101", "43210", "185.130.5.231", "80", "TCP", "IP", "185.130.5.231", "known attacker", "blocklist.de"]
]
```
```

--------------------------------

### Maltrail Sensor - Custom Configuration Example

Source: https://github.com/stamparm/maltrail/wiki/CLI-management-for-Maltrail

Shows how to specify a custom configuration file for the Maltrail sensor using the '-c' parameter. This allows overriding the default 'maltrail.conf' settings.

```bash
python sensor.py -c /path/to/custom/maltrail.conf
```

--------------------------------

### Automate SSL Certificate and Key Combination via Cron

Source: https://github.com/stamparm/maltrail/wiki/Certbot-integration-Maltrail

Sets up a cron job to periodically combine the SSL certificate and private key into a single 'server.pem' file. This is crucial for automated renewal of SSL certificates to keep Maltrail secure.

```bash
# Cron Jobs as Root or for Super User use sudo
cd /opt/maltrail/misc && sudo cat /etc/letsencrypt/live/myserver.com/cert.pem > server.pem && sudo cat /etc/letsencrypt/live/myserver.com/privkey.pem > server.pem && sudo cat /etc/letsencrypt/live/myserver.com/cert.pem >> server.pem
```

--------------------------------

### Define and Use Custom Blacklists in Maltrail

Source: https://context7.com/stamparm/maltrail/llms.txt

This shows how to define custom ingress and egress blacklists in Maltrail's configuration file based on IP addresses, destination ports, and filter types. It also demonstrates how to retrieve these blacklists via the API and use them with ipset.

```bash
# Define custom blacklists in maltrail.conf
BLACKLIST_OUT
    src_ip !~ ^192.168. and dst_port ~ ^22$
    src_ip !~ ^192.168. and filter ~ scan
    src_ip !~ ^192.168. and filter ~ known attacker

BLACKLIST_IN
    src_ip ~ ^192.168. and filter ~ malware

# Access blacklists via HTTP API
curl http://127.0.0.1:8338/blacklist/out
curl http://127.0.0.1:8338/blacklist/in

# Use with ipset blocking
ipset create blacklist_out hash:net
for ip in $(curl http://127.0.0.1:8338/blacklist/out); do ipset add blacklist_out $ip; done
```

--------------------------------

### Combine SSL Certificate and Private Key for Maltrail

Source: https://github.com/stamparm/maltrail/wiki/Certbot-integration-Maltrail

Concatenates the SSL certificate, private key, and certificate again into a single file named 'server.pem'. This is often required by applications that expect a combined PEM file. This command assumes the certificate and key are located in /etc/letsencrypt/live/myserver.com/.

```bash
cd /opt/maltrail/misc
cat /etc/letsencrypt/live/myserver.com/cert.pem > server.pem && cat /etc/letsencrypt/live/myserver.com/privkey.pem > server.pem && cat /etc/letsencrypt/live/myserver.com/cert.pem >> server.pem
```

--------------------------------

### Maltrail Sensor - Console Output Example

Source: https://github.com/stamparm/maltrail/wiki/CLI-management-for-Maltrail

Shows how to configure the Maltrail sensor to print its output directly to the console using the '--console' flag. This is particularly helpful in environments without a graphical user interface.

```bash
python sensor.py --console
```

--------------------------------

### Retrieve Maltrail Events via Web API

Source: https://context7.com/stamparm/maltrail/llms.txt

This shows how to fetch event data from Maltrail using its Web API. You can specify a date and filter events by keywords. The API returns gzip-compressed JSON data, typically in chunks for efficient processing. Authentication credentials are required.

```bash
# Get events for specific date
curl -u admin:changeme! 'http://127.0.0.1:8338/events?date=2025-10-18'

# Get events with filtering
curl -u admin:changeme! 'http://127.0.0.1:8338/events?date=2025-10-18&filter=malware'

# Response is gzip compressed JSON with event data
# Events are returned in chunks for efficient processing

# Example response structure:
# [
#   ["2025-10-18 10:23:45", "sensor1", "192.168.1.100", "54321", "8.8.8.8", "53", "UDP", "DNS", "evil.com", "malware c2", "(static)"],
#   ["2025-10-18 10:24:12", "sensor1", "192.168.1.101", "43210", "185.130.5.231", "80", "TCP", "IP", "185.130.5.231", "known attacker", "blocklist.de"]
# ]
```

--------------------------------

### Enable SSL in Maltrail Configuration

Source: https://github.com/stamparm/maltrail/wiki/Certbot-integration-Maltrail

Modifies the Maltrail configuration file to enable SSL/TLS for secure communication. This requires the 'USE_SSL' parameter to be set to 'true'.

```ini
# maltrail.conf enable SSL
USE_SSL true
```

--------------------------------

### PHP Skimmer Script Example

Source: https://github.com/stamparm/maltrail/blob/master/trails/static/malicious/magentocore.txt

This entry shows a common file path for a PHP script used in web skimmer attacks. Such scripts are often disguised within legitimate website structures, for example, in JavaScript directories, to capture sensitive data from compromised e-commerce sites. The 'ar' prefix might indicate a specific campaign or malware family.

```php
/js/ar/ar906.php

```

```php
/js/ar/ar2497.php

```

```php
/js/ar/ar7938.php

```

--------------------------------

### Maltrail Syslog Integration (Bash)

Source: https://context7.com/stamparm/maltrail/llms.txt

Shows how to configure Maltrail to send logs to a Syslog server by specifying the `SYSLOG_SERVER` in the `maltrail.conf` file. It also mentions Common Event Format (CEF) output.

```bash
# Configure Syslog server in maltrail.conf
SYSLOG_SERVER 192.168.2.107:514

# CEF (Common Event Format) output example
```

--------------------------------

### Maltrail Sensor - Quiet Mode Example

Source: https://github.com/stamparm/maltrail/wiki/CLI-management-for-Maltrail

Demonstrates activating quiet mode for the Maltrail sensor using the '-q' or '--quiet' flags. This suppresses routine operational messages, focusing on critical events.

```bash
python sensor.py -q
```

--------------------------------

### Configure Network Promiscuous Mode

Source: https://context7.com/stamparm/maltrail/llms.txt

Bash commands to enable promiscuous mode on network interfaces, which is necessary for passive network monitoring. It includes commands to enable it and make the setting persistent.

```bash
# Enable promiscuous mode on interfaces (required for passive monitoring)
for dev in $(ifconfig | grep mtu | grep -Eo '^\w+'); do
  sudo ifconfig $dev promisc
done

# Verify promiscuous mode
ifconfig | grep PROMISC

# Make persistent (add to /etc/rc.local or network configuration)
cat >> /etc/rc.local << 'EOF'
for dev in $(ifconfig | grep mtu | grep -Eo '^\w+'); do
  ifconfig $dev promisc
done
EOF
```

--------------------------------

### Web API - Trails Endpoint

Source: https://context7.com/stamparm/maltrail/llms.txt

Access the Maltrail trails database via the web API. This endpoint is used for distributing trails to remote sensors and updating the server's trail database.

```APIDOC
## Web API - Trails Endpoint

### Description
Provides access to the Maltrail trails database. This endpoint can be used to fetch the current trails or to enable updates from a central server.

### Method
`GET`

### Endpoint
`/trails`

### Request Example
Get the current trails database:
```bash
curl http://127.0.0.1:8338/trails
```

### Server Configuration for Updates
To enable trail distribution from a server, set the following in `maltrail.conf` under the `[Server]` section:
```
USE_SERVER_UPDATE_TRAILS true
```

### Sensor Configuration for Updates
To configure sensors to pull trails from a server, set the `UPDATE_SERVER` in `maltrail.conf` under the `[Sensor]` section:
```
UPDATE_SERVER http://192.168.2.107:8338/trails
```

### Response
*   Trails are served in a compressed format.
*   Sensors automatically decompress and load the trails.
```

--------------------------------

### Offline PCAP Analysis with Maltrail Sensor (Web-GUI)

Source: https://github.com/stamparm/maltrail/wiki/Miscellaneous

This command demonstrates how to run the Maltrail sensor in offline mode to analyze a specified .pcap file and display results in the web-GUI. It requires root privileges and the path to the .pcap file.

```shell
sudo python3 sensor.py --offline -r /home/k_mikhail/2017-12-22-malspam-pushing-RemcosRAT.pcap
```

--------------------------------

### Maltrail Server Blacklist Configuration

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Configuration examples for defining blacklist rules in Maltrail. These rules specify conditions based on source IP, destination port, or filter types to either include or exclude traffic. The syntax involves specifying a field, a control operator (~ for matches, !~ for doesn't match), and a regular expression.

```text
BLACKLIST_OUT
    src_ip !~ ^192.168. and dst_port ~ ^22$
    src_ip !~ ^192.168. and filter ~ scan
    src_ip !~ ^192.168. and filter ~ known attacker

BLACKLIST_IN
    src_ip ~ ^192.168. and filter ~ malware
```

--------------------------------

### Maltrail Sensor - Offline Analysis Example

Source: https://github.com/stamparm/maltrail/wiki/CLI-management-for-Maltrail

Demonstrates how to use the '-r' parameter with the Maltrail sensor to perform offline analysis on a specified .pcap file. This is useful for investigating network traffic captured at a different time or location.

```bash
python sensor.py -r /path/to/your/capture.pcap
```

--------------------------------

### Logstash Event Data Format (JSON)

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Example of event data formatted in JSON for sending to a Logstash server via UDP. This format includes key-value pairs representing sensor and event details.

```json
{"timestamp": 1608818692, "sensor": "beast", "severity": "high", "src_ip": "192.168.5.137", "src_port": 48949, "dst_ip": "8.8.8.8", "dst_port": 53, "proto": "UDP", "type": "DNS", "trail": "morphed.ru", "info": "andromeda (malware)", "reference": "(static)"}
```

--------------------------------

### Configure Maltrail as IPS with Bash Script and iptables

Source: https://github.com/stamparm/maltrail/wiki/Miscellaneous

This script demonstrates how to configure Maltrail to act as an Intrusion Prevention System (IPS) by integrating with `ipset` and `iptables` on Linux systems. It flushes the `maltrail` ipset, creates it, populates it with attacker IPs fetched from Maltrail's `/fail2ban` endpoint, and then configures iptables to drop traffic from these IPs. This script requires root privileges and is typically run via cron.

```bash
#!/bin/bash
ipset -q flush maltrail
ipset -q create maltrail hash:net
for ip in $(curl http://127.0.0.1:8338/fail2ban 2>/dev/null | grep -P '^[0-9.]+$'); do ipset add maltrail $ip; done
iptables -I INPUT -m set --match-set maltrail src -j DROP
```

--------------------------------

### Syslog Event Data Format (CEF)

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Example of event data formatted in Common Event Format (CEF) for sending to a Syslog server via UDP. This format includes Maltrail-specific information along with standard CEF fields.

```text
Dec 24 15:05:55 beast CEF:0|Maltrail|sensor|0.27.68|2020-12-24|andromeda (malware)|2|src=192.168.5.137 spt=60453 dst=8.8.8.8 dpt=53 trail=morphed.ru ref=(static)
```

--------------------------------

### Maltrail Detected Event Log Format (CSV)

Source: https://github.com/stamparm/maltrail/blob/master/README.md

Example of a single line entry in the CSV-formatted log file generated by the Maltrail sensor. This format details the time, sensor, source/destination IPs and ports, protocol, trail type, trail name, trail info, and reference.

```text
"2015-10-19 15:48:41.152513" beast 192.168.5.33 32985 8.8.8.8 53 UDP DNS 0000mps.webpreview.dsl.net malicious siteinspector.comodo.com
```

--------------------------------

### Offline PCAP Analysis with Maltrail Sensor (Terminal)

Source: https://github.com/stamparm/maltrail/wiki/Miscellaneous

This command shows how to execute the Maltrail sensor in offline mode for .pcap file analysis, with results directed to the terminal console. It requires root privileges and the path to the .pcap file, along with the '--console' flag.

```shell
sudo python3 sensor.py --offline --console -r /home/k_mikhail/2017-12-22-malspam-pushing-RemcosRAT.pcap
```
Tokens:
Raw