Open-source project
stamparm/maltrail avatar
stamparm/maltrail

Maltrail turns network indicators into one-line events

Malicious traffic detection system

8,658 stars1,272 forksPythonMIT

At a glance

What is it?
Maltrail is a two-process detection system: a multithreaded Rust sensor matches domains, URLs, IP addresses, IP:port pairs and User-Agent values against trails, and a Python server stores the resulting events for a plain JavaScript reporting interface. It names known malicious infrastructure precisely and blocks nothing.
Who is it for?
Maltrail suits a network team that already knows which infrastructure matters and accepts that attribution happens somewhere else, because the event model carries no process and no user. It is the wrong tool for anyone expecting blocking, payload inspection or host-level answers, and a retro hunt run without the optional per-day sidecar index does not give exact counts.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • stamparm/maltrail8,658 ★ · +50
Star history
Repository2026-09-222026-11-15
stamparm/maltrail8.6k8.7k

50 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One event line carries the source, the match and the classification

A detection is recorded as a single event containing the source, destination, protocol, matched trail, classification and trail source. The whole record is one line of text:

text
"2026-08-07 09:14:22.117034" gw 10.13.13.2 57809 1.1.1.1 53 UDP DNS malware.bakewithdavid.com "asyncrat (malware)" (static)

Read left to right and the fields are unambiguous. The address and port pair after the source token identify who sent the request, the next pair is the destination, `UDP` and `DNS` give the protocol, the domain is the value that matched, `asyncrat (malware)` is the classification carried by the trail, and `(static)` records where that trail came from. The trailing token is worth more attention than it gets: an event marked `(static)` matched the static trail set rather than a public feed or your own trails. The bare `gw` token sits in the source group, though the field list does not spell out what it names.

What the line does not carry matters as much as what it does. There is no payload, no byte count, no user account, no process name, and no hostname for the infected machine. The match happened on the name that was looked up, not on what came back afterwards. If you need to know which binary arrived or which identity opened it, this line will not tell you, and that answer has to come from a different system.

Sensor and server are two processes that can live on different hosts

The system is two independently deployable processes that can run on the same host or on separate hosts. The sensor is written in Rust, captures with libpcap, and does the detection work: trail matching plus heuristic analysis, producing events. The server is Python, accepts remote events, stores them in the event logs, reads locally available daily logs, and provides the HTTP API and the browser reporting interface.

That split is why there is no capture code in the server and no dashboard code in the sensor. The project states it directly: the sensor does not depend on the reporting interface, and can be deployed on its own when its events are forwarded to another system.

The operational consequence hides in one phrase about what the server reads. A sensor sitting on a border router that writes only to its own `LOG_DIR` has told the server nothing at all. Either the sensor is configured to send to `LOG_SERVER` as well, or the daily log files have to reach the host running `server.py` by some other route. Settle this before deploying: the date picker is an event-density grid over the daily logs available to the server.

Four sinks: LOG_DIR, LOG_SERVER, SYSLOG_SERVER and LOGSTASH_SERVER

Every event has up to four destinations, and each one is a separate configuration key. Writing locally to `LOG_DIR` keeps plain-text daily logs on the sensor itself. Pointing `LOG_SERVER` at a Maltrail server ships the same events over the network for intake. `SYSLOG_SERVER` emits CEF, and `LOGSTASH_SERVER` emits JSON for Logstash. Local and remote logging can both be on, so you can keep a local copy and still forward to a SIEM at the same time.

Two operational extras sit alongside those four. Prometheus metrics are optional, so a sensor can expose its own counters without being wired into anything else, and deployment validation runs through `maltrail-sensor -T`, which is the check to run before a sensor goes anywhere near production traffic.

Forwarding to syslog or to Logstash hands delivery to those systems, so if you need certainty that nothing was dropped, check it at the receiver rather than assuming it from the sensor configuration. The local `LOG_DIR` copy is the only sink you can inspect yourself.

Trails come from 3,000 bundled files, 42 feeds and your own plain text

Indicator coverage is assembled rather than typed in. A full trail build combines a static trail set of more than 3,000 curated files fetched from stamparm/trails, 38 public-feed integrations, and optional operator-supplied trails. On top of that sit plain-text custom trails and whitelists, deliberately kept as text so they can be reviewed and version-controlled with the rest of your configuration instead of living in a database nobody diffs.

The repository layout mirrors that split between shipped data and shipped code. `feeds/` and `data/` hold indicator material, `core/` holds the shared logic, `sensor/` is the Rust capture side, `server.py` is the Python entry point, and `maltrail.conf` sits at the root beside `install.sh`, `install.ps1`, `packaging/` and `docker/`.

Feed granularity leaks into the search syntax. `family:interlock` also matches `interlock-1` and `interlock-2`, the shards in which that particular dump arrives, so you do not need to know the shard layout in advance. The cost is that a family query is wider than the string you typed.

Four install routes in the repository root and the -T check before you span a port

Four installation routes ship with the project, and the table of contents names each one: an installer, building from source, a systemd unit, and Docker. The corresponding files are visible at the root of the repository, with `install.sh` and `install.ps1` covering the two shells, a `packaging/` directory for distribution artifacts, and `docker/` for containers.

Whichever route you take, the first command to run is the deployment validation. A sensor that cannot load its configuration or its trails is the failure you want to catch before it sits on a capture port:

bash
maltrail-sensor -T

The reporting side is one Python script. `server.py` binds the interface at `HTTP_ADDRESS:HTTP_PORT`, and the interface itself is plain JavaScript with a single third-party runtime dependency, PapaParse for CSV parsing, and no build step. There is no compile stage to run before the page works, and no package install in front of it.

On upgrade cost, the three most recent releases are 3.3 on 2026-08-31, 3.4 on 2026-09-04 and 3.5 on 2026-10-14, and the repository's last push was on 2026-11-02. The licence is MIT, so both processes can be modified and redistributed with only the licence text retained.

Field-aware search where a space means AND and rows are (source, trail) pairs

Search in the reporting interface is field-aware rather than free text. The selectors are `src:`, `dst:`, `port:`, `proto:`, `type:`, `trail:`, `info:`, `family:`, `tag:`, `uid:`, `sev:`, `dir:` and `status:`, plus exclusions, wildcards, CIDR matching and numeric comparisons. Terms separated by spaces are combined as AND, so extra words narrow the result instead of widening it. A term prefixed with `-` excludes, `*` is the wildcard, `src:10.0.0.0/8` matches a range, and `port:>1024` or `count:>=100` compare numbers. Active filters show up as removable chips, which is how you stop a query you assembled in three steps from quietly turning into something broader than you intended.

What you search is already aggregated. Events stream from `/events` and the browser rolls them into threats, one row per distinct `(source, trail)` pair, so two lookups of the same bad domain from one host become a single row carrying a count instead of two separate rows. The grid is sortable, each row opens a detail panel, and triage status, free-text notes and tags belong to the threat rather than to the individual event.

The boundary is that aggregation. It happens in the browser, one day at a time, chosen from a date picker that doubles as an event-density grid over the daily logs the server has. Counts on a threat row are counts for that day and that pair, not a trend, and there is no cross-day view in the same grid. For history, the retro hunt is the tool, and it carries its own limits.

Retro hunts stop at a day limit, a wall-clock budget and a sample cap

`/hunt` searches all retained daily logs for one indicator instead of only the day selected in the picker. That is the difference between asking what happened today and asking whether a domain you just read about appears anywhere inside your retention window.

It is also bounded three ways: by a day limit, by a wall-clock budget and by a sample cap. The wall-clock budget is the one that bites on a busy network, because a month of plain-text logs is a lot to sweep inside a single request. When that budget cuts a day short, the day is reported separately rather than counted as a completed day, which means a finished hunt can still return with a short list of days nobody read in full. A zero-hit answer from a run like that is weaker evidence than it looks.

The optional per-day sidecar index changes the arithmetic: it accelerates the sweep and makes the `/counts` numbers exact. Without the index the sweep still runs, but the `/counts` numbers are not exact. If a migration timeline or a compromise timeline is going to rest on a hunt, enable the index first, otherwise the report rests on an estimate.

Heuristics name suspicious behaviour and block nothing

The sensor does more than match trails. Its heuristics cover scanning, DNS exhaustion, DGA-like lookups, suspicious downloads, proxy probes and suspicious User-Agent values, plus related network activity. These are the detections that fire when nothing in the indicator set matched, and they are what keeps the sensor useful on a network where almost all traffic is ordinary.

The boundary is stated plainly: Maltrail is designed for indicator-based network monitoring, its heuristic detections supplement trail matching, and it is not a replacement for endpoint telemetry or a general-purpose intrusion prevention system. Take that in both directions. A DGA-like lookup is a suspicion about a name and its pattern, not evidence of what a host did with the answer, and answering it means going to the machine. A suspicious download is a transfer noticed on the wire; nothing here inspects the file and nothing stops it, so the blocking decision belongs to a system built to block.

The live view has the same character. New high-severity threats can raise desktop and audible alerts, and both can be muted, so the alerting you keep is a decision rather than a default. `/sensors` shows which sensors are reporting, the version each one runs and how long ago it last checked in. `/geo` draws per-country density for the selected day from each event's external endpoint, leaving unattributable events unmapped instead of guessing at them, and `HOME_LAT` with `HOME_LON` add origin arcs.

Editorial conclusion

Maltrail suits a network team that already knows which infrastructure matters and accepts that attribution happens somewhere else, because the event model carries no process and no user. It is the wrong tool for anyone expecting blocking, payload inspection or host-level answers, and a retro hunt run without the optional per-day sidecar index does not give exact counts. Before installing, settle which host holds the daily logs the server reads, then run `maltrail-sensor -T` to find out whether your trails and configuration load at all.

Frequently asked questions

What are the default login credentials for Maltrail?

The reporting interface is served by `server.py` at `HTTP_ADDRESS:HTTP_PORT`. Treat the address as reachable by anything that can route to it until you check what sits in front of it.

Does Maltrail block the traffic it detects?

No. The sensor identifies communication with known malicious infrastructure and records events. It is described as indicator-based monitoring rather than an intrusion prevention system, so nothing in the design prevents a match from completing.

Can Maltrail search days other than the one on screen?

Yes, through `/hunt`, which searches all retained daily logs for one indicator. Those hunts are bounded by a day limit, a wall-clock budget and a sample cap, and a day cut short by the time budget is reported separately instead of being counted as completed.

Do the Maltrail sensor and server have to run on the same host?

No. They are two independently deployable processes that can run on the same host or on separate hosts, and the sensor does not depend on the reporting interface. The server reads locally available daily logs, so a remote sensor has to send its events with `LOG_SERVER` or have its logs moved.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. stamparm/maltrail on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/stamparm-maltrail.svg)](https://hysenlabs.com/projects/stamparm-maltrail)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/stamparm-maltrail.svg)](https://hysenlabs.com/projects/stamparm-maltrail)

Was this useful?