DOCSEARCHbyAlgolia
Submit Docs

Maltrail Malicious Traffic Detection System

repository·master·Indexed 27 days ago

https://github.com/stamparm/maltrail

A malicious traffic detection system that identifies suspicious domains, URLs, IPs, and User-Agents using blacklists and heuristic mechanisms. It employs a Sensor-Server-Client architecture to monitor network traffic, store event details, and provide a web-based reporting interface for threat analysis.

Tokens
11.9K
Snippets
17
Records
76
Agent score
92%

What's inside Maltrail

  1. Overview of Maltrail Malicious Traffic Detection

    master

    Maltrail is a malicious traffic detection system that identifies threats by matching network traffic against publicly available blacklists (feeds) and static trails compiled from AV reports. It can detect various indicators including:

    • Domain names (e.g., DGA domains)
    • URLs (e.g., known malicious executable paths)
    • IP addresses (e.g., known attackers)
    • HTTP User-Agent headers (e.g., sqlmap)

    It also supports optional advanced heuristic mechanisms to discover unknown threats like new malware.

  2. Maltrail Architecture: Sensor, Server, and Client

    master

    Maltrail follows a Traffic -> Sensor <-> Server -> Client architecture:

    • Sensor: A standalone component running on a monitoring node (e.g., Linux machine connected to a SPAN/mirroring port or a transparent Linux bridge) or a Honeypot. It monitors traffic for blacklisted items.
      • If running on the same machine as the Server, logs are stored locally.
      • If running on a remote machine, it sends event details to the Server via UDP messages.
    • Server: Stores event details and provides back-end support for the reporting web application. It manages the logging directory (LOG_DIR).
    • Client: A "Fat client" web application. To prevent server disruption, data post-processing is done in the user's web browser. The client requests compressed chunks of data for a chosen 24h period, which are processed sequentially to create reports.

    Note: You can use the Sensor as a standalone component without a Server. In this mode, events are stored in a local logging directory and can be examined manually or via CSV tools.

  3. Maltrail System Requirements

    master

    To run Maltrail, ensure your *nix/BSD system meets the following requirements:

    • Python: Version 2.6, 2.7, or 3.x.
    • pcapy-ng: This package must be installed. Note: Do not use the older pcapy library, as it is deprecated and causes issues in Python 3 environments.
    • Sensor Hardware/Permissions:
      • Requires at least 1GB of RAM (more if using multiprocessing or a large CAPTURE_BUFFER).
      • Requires administrative/root privileges to monitor traffic.
    • Server Hardware/Permissions:
      • No special requirements.

  4. Install and run the Maltrail Sensor on SUSE/openSUSE

    master

    To set up a Maltrail Sensor on SUSE or openSUSE systems, install the required system dependencies, install pcapy-ng via pip, clone the repository, and run sensor.py with sudo privileges.

    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

  5. Navigate the Maltrail Reporting Interface

    master

    The reporting interface is divided into three main sections:

    1. Timeline (Top): A sliding timeline for selecting logs from past events. Click the current date label or the calendar icon to activate it. Dates are grouped by months; use the timeline slider to access previous months. Hovering over an event shows a tooltip with the approximate number of events for that date.
    2. Summary (Middle): Provides visual analytics of the selected 24-hour period:
      • Events: A line chart showing total events (Red: IP-based, Blue: DNS-based, Yellow: URL-based).
      • Sources: A stacked column chart showing events per top source.
      • Threats: A pie chart showing the percentage of top threats.
      • Trails: A pie chart showing the percentage of top trails.
      • Note: Clicking any box opens a more detailed graph.
    3. Threat Table (Bottom): A paginated table containing condensed representations of logged events. Each entry represents a unique threat identified by a pair of (src_ip, trail) or (dst_ip, trail).

  6. Configure Maltrail via Crontab

    master

    Use crontab to manage the lifecycle of the server and sensor components.

    Server (User Crontab):

    • Autostart the server if it is not running.
    • Perform a git pull daily at 01:00 to update the repository.

    Sensor (Root Crontab):

    • Autostart the sensor if it is not running.
    • Restart the sensor/process at 02:01 daily using pkill.
    # User crontab (crontab -e)
*/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

# Root crontab (sudo crontab -e)
*/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

  7. Configure Maltrail working environment

    master

    Set up the necessary directories for logs and configuration, then copy the default configuration file to /etc/maltrail/maltrail.conf for editing.

    sudo mkdir -p /var/log/maltrail
sudo mkdir -p /etc/maltrail
sudo cp /opt/maltrail/maltrail.conf /etc/maltrail
sudo nano /etc/maltrail/maltrail.conf

  8. Run Maltrail Server via Docker Compose

    master

    Use Docker Compose to manage the server. To avoid overwriting your configuration during a git pull, copy docker-compose.yml to docker-compose.override.yml and make your edits there.

    # Start the service
docker compose up -d

# Update the image regularly
docker compose down --remove-orphans
docker compose build
docker compose up -d

  9. Build the Maltrail Docker image

    master

    To build the Maltrail Docker image, you must run the build command from the root of the maltrail repository. If you are currently inside the docker/ directory, you must move up one level to the repository root before executing the build to avoid file not found errors.

    cd ..
docker build -f docker/Dockerfile -t maltrail .

  10. Run Maltrail Server via Docker

    master

    Currently, only the server is available as a container image. You can run it using docker run or docker compose.

    # Start the server with Docker run
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 ghcr.io/stamparm/maltrail:latest

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

  11. Install Maltrail on SUSE/openSUSE

    master

    To install Maltrail on SUSE or openSUSE-based systems, install the required system dependencies, the pcapy-ng Python package, and clone the repository to /opt/maltrail.

    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

  12. Install and run the Maltrail Sensor on Ubuntu/Debian

    master

    To set up a Maltrail Sensor on Ubuntu or Debian systems, install the required system dependencies, install pcapy-ng via pip, clone the repository, and run sensor.py with sudo privileges. This configuration uses default settings and monitors the "any" interface.

    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