stamparm/maltrailSistema de detecção de tráfego malicioso em tempo real que utiliza listas negras públicas, rastros estáticos de malware e análise heurística para identificar ameaças no tráfego DNS, HTTP e IP.
Maltrail é um sistema de detecção de tráfego de rede que identifica comunicação com infraestrutura maliciosa conhecida
e relata anomalias de tráfego selecionadas. Ele compara domínios, URLs, endereços IP,
pares IP:port e valores de User-Agent observados na rede com um conjunto de indicadores chamados
trails.
Uma detecção é registrada como um único evento contendo a origem, o destino, o protocolo, a trail correspondente, a classificação e a fonte da trail:```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)
O Maltrail foi concebido para monitorização de rede baseada em indicadores. As suas deteções heurísticas complementam a correspondência de trilhas, mas não substituem a telemetria de endpoints nem um sistema de prevenção de intrusões de uso geral.
## Recursos
- Um conjunto completo de trilhas que combina mais de 3.000 ficheiros estáticos incluídos, 42 integrações de feeds públicos e trilhas opcionais fornecidas pelo operador.
- Um sensor Rust multithread que utiliza libpcap, com workers de captura Linux `PACKET_FANOUT` opcionais.
- Um servidor Python que fornece a interface de relatórios, a ingestão de eventos e a API HTTP.
- Trilhas personalizadas e listas de permissões em texto simples que podem ser revistas e controladas por versão.
- Heurísticas para varredura, exaustão de DNS, consultas semelhantes a DGA, downloads suspeitos, sondagens de proxy, valores de User-Agent suspeitos e atividade de rede relacionada.
- Registo de eventos local, registo Maltrail remoto, CEF via syslog e saída JSON para Logstash.
- Validação de implementação com `maltrail-sensor -T` e métricas Prometheus opcionais.
## Conteúdo
- [Arquitetura](#architecture)
- [Desempenho](#performance)
- [Instalação](#installation)
- [Instalador](#installer)
- [Compilar a partir do código-fonte](#building-from-source)
- [Systemd](#systemd)
- [Docker](#docker)
- [Configuração](#configuration)
- [Trilhas](#trails)
- [Eventos e API](#events-and-api)
- [Operações](#operations)
- [Monitorização](#monitoring)
- [Retenção de eventos](#event-retention)
- [Documentação](#documentation)
- [Contribuição](#contributing)
- [Projeto](#project)
- [Licença](#license)
- [Mantenedores](#maintainers)
- [Patrocinadores](#sponsors)
- [Apresentações e publicações](#presentations-and-publications)
- [Lista negra derivada](#derived-blacklist)
- [Integrações de terceiros](#third-party-integrations)
- [Agradecimentos](#acknowledgements)
## Arquitetura
O Maltrail é composto por dois processos independentes que podem ser executados no mesmo host ou em hosts separados:```text
┌──────────┐ events (UDP or file) ┌──────────┐
│ sensor │ ───────────────────────► │ server │ ◄── browser
└──────────┘ └──────────┘
Rust Python
libpcap + PACKET_FANOUT reporting UI + API
trail matching + heuristics
O sensor captura tráfego, realiza correspondência de trilhas e análise heurística, e gera eventos.
Ele pode gravar eventos localmente (LOG_DIR), enviá-los para um servidor Maltrail remoto (LOG_SERVER) ou fazer
ambos. Ele também pode emitir CEF via syslog (SYSLOG_SERVER) e JSON para o Logstash
(LOGSTASH_SERVER).
O servidor recebe e armazena eventos remotos, serve logs de eventos disponíveis localmente e fornece a interface web e a API.
O desempenho depende do processador, da composição do tráfego, do tamanho do conjunto de trilhas, do driver de captura e da interface de rede. Os números abaixo medem o caminho de processamento de pacotes do sensor de forma isolada; não são medições de captura ao vivo de ponta a ponta.
Medições representativas em um AMD Ryzen 7 PRO 4750U com heurísticas habilitadas e um conjunto de trilhas de 1,5 milhão de linhas:
Execuções de comparação offline usando a mesma captura gerada, configuração e conjunto de trilhas mediram um custo de estado estacionário por pacote 14–37× menor do que o sensor Python aposentado em todos os sistemas testados. A ferramenta de comparação relata o tempo total do processo separadamente, pois o carregamento de trilhas domina replays curtos. Ela também imprime contagens de eventos; a paridade funcional é testada independentemente pelo corpus de paridade.
Execute a comparação no sistema de destino com:```bash
python3 sensor/tools/bench_compare.py --packets 300000
--trails ~/.maltrail/trails.csv --repeat 3
Por padrão, é utilizado um worker de captura. Workers adicionais podem aumentar a capacidade de captura, mas o hash de fluxo do Linux divide o estado por origem entre os workers e, portanto, reduz a sensibilidade de algumas heurísticas de varredura. No teste documentado, 91% dos alertas de heurística com um único worker permaneceram com dois workers, 86% com quatro e 65% com oito. A correspondência exata de trilhas não foi alterada. Aumente `CAPTURE_FANOUT` somente quando as métricas de descarte de captura mostrarem que isso é necessário.
A metodologia de benchmark, resultados de hardware, saída do profiler, medições de memória e verificações de fanout em tempo real estão documentados em [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/REPORT.md).
## Instalação
### Instalador
O instalador suporta Debian, Ubuntu, Raspberry Pi OS, RHEL, Fedora e openSUSE:```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh
Ele instala dependências, cria um checkout gerenciado em /opt/maltrail, verifica o checksum
do sensor pré-construído, cria uma conta maltrail sem privilégios, instala unidades do systemd, prepara
os diretórios de log e de estado, e inicia o sensor e o servidor. Executar o instalador novamente atualiza
o checkout gerenciado.
Revise o script antes de executá-lo com privilégios elevados. A partir de um checkout existente, o dry run mostra os comandos sem alterar o sistema:```bash sh install.sh --dry-run
Opções comuns do instalador:```bash
sh install.sh --role sensor # Install only the sensor
sh install.sh --ref 3.1.1 # Install a release tag instead of master
sh install.sh --no-service # Install without changing systemd
sh install.sh --dry-run # Print commands without applying them
sh install.sh --uninstall # Remove the managed installation; keep logs and state
O painel está disponível em http://127.0.0.1:8338 após a instalação. Observe que o
HTTP_ADDRESS fornecido é 0.0.0.0, portanto é acessível em todas as interfaces, não apenas em loopback — e
as credenciais padrão são admin / changeme!. Altere USERS e defina HTTP_ADDRESS para
127.0.0.1 (ou coloque o servidor atrás de um proxy reverso com TLS), antes de o host estar em uma
rede não confiável.
A construção inicial das trilhas pode levar vários minutos. O sensor não detecta correspondências de trilhas até que um
conjunto de trilhas válido esteja disponível. A unit do systemd executa a validação -T do sensor antes da inicialização, de modo
que a falta de privilégios, um diretório de log sem permissão de escrita ou um conjunto de trilhas inválido façam a inicialização
falhar visivelmente.
O harness de teste do instalador cobre contêineres Ubuntu, Debian, Fedora, openSUSE e Alpine. O Alpine usa musl e não usa o binário do sensor glibc pré-compilado; compile o sensor a partir do código-fonte nesse ambiente.
O sensor requer Rust 1.74 ou mais recente, cabeçalhos de desenvolvimento do libpcap e as ferramentas de capabilities do sistema. O servidor e o atualizador de trilhas requerem Python 3.6 ou mais recente.
Instale os pacotes da distribuição:```bash
sudo apt-get install cargo libpcap-dev libcap2-bin python3
sudo dnf install cargo libpcap-devel libcap python3
sudo zypper install cargo rust libpcap-devel libcap-progs python311
Em seguida, construa e valide o sensor:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail
cargo build --release --manifest-path sensor/Cargo.toml
sudo setcap cap_net_raw,cap_net_admin=eip \
sensor/target/release/maltrail-sensor
sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail
sensor/target/release/maltrail-sensor -T
sensor/target/release/maltrail-sensor
Inicie o servidor em outro terminal ou em outro host:```bash python3 server.py
Prebuilt `x86_64` e `aarch64` de binários de sensor estão anexados aos lançamentos atuais com somas de verificação SHA-256. Eles têm como alvo glibc 2.28 e exigem libpcap em tempo de execução. Em sistemas baseados em musl, como Alpine Linux, compile a partir do código-fonte.
O sensor Python descontinuado é usado apenas por ferramentas de comparação e paridade. Essas ferramentas exigem adicionalmente `pcapy-ng` e os cabeçalhos de desenvolvimento Python descritos em [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md).
### Systemd
As unidades fornecidas `maltrail-server.service` e `maltrail-sensor.service` executam ambos os processos como o usuário não privilegiado `maltrail`. O Systemd cria `/var/log/maltrail` e `/var/lib/maltrail`, restringe o acesso ao sistema de arquivos e concede ao sensor `CAP_NET_RAW` e `CAP_NET_ADMIN`.
O instalador configura essas unidades automaticamente. Para uma instalação a partir do código-fonte existente, siga o procedimento de serviço manual em [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md).
Verifique o estado do serviço e os logs com:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f
Inicie a implantação do Compose fornecida com:```bash docker compose -f docker/docker-compose.yml up -d
Container configuration, storage, privileges, and health checks are documented in
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/HEAD/docker/README.md).
## Configuration
Maltrail reads `maltrail.conf`, which contains separate `[Sensor]` and `[Server]` settings. The
installer places the managed configuration at `/etc/maltrail.conf`.
Frequently used sensor options include:
| Option | Purpose |
| --- | --- |
| `MONITOR_INTERFACE` | Interface ou interfaces de captura; `any` seleciona todas as interfaces suportadas |
| `CAPTURE_FILTER` | Filtro de captura BPF |
| `CAPTURE_FANOUT` | Número de sockets de captura Linux; o padrão é um |
| `LOG_DIR` | Diretório local de logs de eventos |
| `TRAILS_FILE` | Banco de dados de trilhas gerado |
| `LOG_SERVER` | Servidor de eventos remoto Maltrail |
| `SYSLOG_SERVER` | Destino ou destinos syslog CEF |
| `LOGSTASH_SERVER` | Destino ou destinos JSON Logstash |
| `STATS_ADDRESS` | Listener de métricas Prometheus; desabilitado a menos que configurado |
| `UPDATE_PERIOD` | Intervalo de atualização de trilhas |
| `USER_WHITELIST` | Indicadores gerenciados pelo operador que não devem alertar |
| `CUSTOM_TRAILS_DIR` | Diretório de trilhas gerenciado pelo operador |
`PROCESS_COUNT` aplica-se ao sensor Python descontinuado. Configure os trabalhadores de captura do sensor Rust com `CAPTURE_FANOUT` em vez disso.
Execute a verificação de implantação após alterar a configuração:```bash
sensor/target/release/maltrail-sensor -T
A verificação valida a configuração, os trails, as entradas da whitelist, o filtro de captura, os privilégios, o armazenamento de logs, o suporte a atualizações e as configurações do worker. Uma verificação bem-sucedida inclui contagens positivas de trails e whitelist, em vez de apenas confirmar que os arquivos existem.
Os trails são armazenados como indicadores de texto simples:```text trails/static/malware/ malware-related static trails trails/static/malicious/ malicious infrastructure trails/static/suspicious/ suspicious infrastructure and behavior trails/feeds/*.py public feed integrations
Adicione indicadores locais em `CUSTOM_TRAILS_DIR`. Adicione indicadores que nunca devem gerar alertas
a `USER_WHITELIST`. Manter dados personalizados fora do checkout gerenciado evita que atualizações
os sobrescrevam.
O atualizador reconstrói `TRAILS_FILE` a partir de feeds habilitados, trilhas estáticas incluídas e trilhas personalizadas. Um
novo arquivo é publicado atomicamente apenas após uma compilação bem-sucedida. Feeds vazios ou com falha são relatados
para que uma implantação em execução não dependa silenciosamente de fontes obsoletas ou aposentadas.
As contribuições de trilhas devem incluir o indicador, a classificação e uma fonte verificável. Consulte
[Contribuindo](#contributing) antes de enviar um pull request.
## Eventos e API
O Maltrail registra um evento separado por espaços em branco por detecção, usando aspas CSV quando um valor
contém espaços:```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>
O campo type identifica o que correspondeu, incluindo DNS, IP, IPORT, URL, PATH, HTTP,
UA, PORT e CERT. O campo info contém a classificação da trilha, e reference
identifica a lista estática, o feed, a fonte personalizada ou a heurística que o produziu.
Use /check para consultar um domínio, endereço IP ou URL:```bash
curl 'http://127.0.0.1:8338/check?q=www.sub.evil.example'
Please provide the Markdown content to translate.```json
{
"query": "www.sub.evil.example",
"found": true,
"trail": "evil.example",
"info": "asyncrat (malware)",
"reference": "(static)"
}
Uma consulta de subdomínio pode corresponder ao seu pai listado. Consultas de URL verificam host/path antes de verificar apenas o host. O servidor lê o banco de dados de trilhas mapeado em memória e observa atualizações de trilhas sem reiniciar.
Trilhas públicas estáticas e de feed estão disponíveis sem autenticação, em conformidade com o endpoint /trails usado pelos sensores remotos. Trilhas personalizadas exigem uma sessão autorizada; uma consulta não autorizada apenas personalizada é reportada como não encontrada. Os dados de eventos permanecem autenticados.
Use maltrail-sensor -T como um gate de implantação e configuração. A unit do systemd fornecida o executa como ExecStartPre.
Quando STATS_ADDRESS estiver configurado, monitore pelo menos estas métricas do Prometheus:
A saturação de estado afeta a heurística correspondente; a correspondência exata de trilhas permanece ativa.
Envie SIGHUP ou use systemctl reload maltrail-sensor para solicitar um recarregamento de trilhas. Arquivos de trilha atualizados por outro processo são detectados automaticamente e publicados para os workers sem reiniciar o sensor.
O armazenamento condensado de observáveis (USE_CONDENSED_STORAGE, meta.sqlite) suporta as visualizações de novidade e retro-hunt do servidor. A compatibilidade com o sensor descontinuado está documentada em sensor/docs/COMPATIBILITY.md.
O Maltrail não rotaciona nem exclui logs de eventos. Os operadores são responsáveis por definir a retenção, o arquivamento e a exclusão de acordo com os requisitos de armazenamento e a política organizacional.
Práticas recomendadas:
LOG_SERVER, SYSLOG_SERVER ou LOGSTASH_SERVER.maltrail_log_dir_free_bytes com margem suficiente para a taxa de eventos esperada.LOG_DIR; arquive os arquivos compactados em outro local.Quando o sistema de arquivos de log está cheio, o sensor não pode acrescentar eventos. Os logs de eventos também podem conter endereços IP e domínios que são regulamentados como dados pessoais em algumas jurisdições; a política de retenção deve considerar os requisitos aplicáveis.
Adições de trilhas, manutenção de feeds, relatos de bugs, documentação e melhorias no sensor são bem-vindos. Os envios de trilhas devem incluir uma fonte confiável e usar a classificação mais restrita e apropriada.
Execute as verificações relevantes antes de enviar código. O gate completo do sensor é:```bash bash sensor/tools/check.sh
Ele executa formatação, Clippy com warnings negados, testes de debug e release, e replay de paridade contra
o sensor Python descontinuado. Execute a suíte do servidor Python com:```bash
bash tests/run.sh python3
O Maltrail é distribuído sob a Licença MIT. Consulte LICENSE.
Uma lista apenas de domínios derivada de trails/static/malware é publicada em
maltrail-malware-domains.txt.
Ela pode ser usada como entrada para sistemas de filtragem de DNS, mas os operadores devem revisá-la e testá-la antes de
ativar o bloqueio. Listas de inteligência de ameaças podem conter falsos positivos ou indicadores que não são
adequados para todos os ambientes.
| Tráfego | Tempo por pacote |
|---|
| Echo ICMP, 58 bytes | 101 ns |
| TCP SYN, 70 bytes | 302 ns |
| TLS em massa, 1.473 bytes | 402 ns |
| Consulta DNS com cache quente, 93 bytes | 452 ns |
| Tráfego misto, média de 866 bytes | 552 ns |
| Requisição HTTP, 169 bytes | 602 ns |
| Consulta DNS com nome único, 93 bytes | 1.102 ns |
| Métrica | Significado operacional |
|---|
maltrail_up == 0 | Nenhum worker de captura está em execução |
Aumento de maltrail_capture_dropped_total | O anel de captura está descartando pacotes |
Aumento de maltrail_local_log_errors_total | Eventos foram produzidos mas não puderam ser gravados localmente |
Aumento de maltrail_remote_log_errors_total | Eventos não puderam ser entregues a um destino remoto; com DISABLE_LOCAL_LOG_STORAGE eles são perdidos |
maltrail_trail_generation não avançando | O conjunto de trilhas ativo não está sendo atualizado |
maltrail_log_dir_free_bytes | Capacidade restante para o armazenamento local de eventos |
Aumento de maltrail_state_saturations_total | Um limite de estado heurístico foi atingido |
Aumento de maltrail_throttle_evictions_total | A tabela de limitação de eventos está no seu limite, portanto os eventos são agregados antes do que foi configurado |
| Documento | Conteúdo |
|---|
sensor/docs/INSTALL.md | Instalação, privilégios, configuração e solução de problemas |
sensor/docs/ARCHITECTURE.md | Mecanismos internos do sensor e fluxo de dados |
sensor/docs/COMPATIBILITY.md | Diferenças deliberadas em relação ao sensor Python descontinuado |
sensor/docs/REPORT.md | Medições, perfis e resultados de testes |
sensor/docs/ROADMAP.md | Trabalho em aberto no sensor |
old/README.md | Sensor Python descontinuado, mantido como oráculo de paridade |