O Maltrail foi concebido para monitorização de rede baseada em indicadores. As suas deteções heurísticas complementam
a correspondência de trilhos, mas não substituem a telemetria de endpoints nem um sistema de prevenção de intrusões
de uso geral.

## Funcionalidades

- Uma construção completa de trilhos que combina mais de 3.000 ficheiros estáticos incluídos, 42 integrações de feeds públicos
  e trilhos opcionais fornecidos pelo operador.
- Um sensor Rust multithreaded que utiliza libpcap, com workers de captura opcionais `PACKET_FANOUT` do Linux.
- Um servidor Python que fornece a interface de relatórios, a receção de eventos e a API HTTP.
- Trilhos personalizados e listas de permissões em texto simples que podem ser revistos e controlados por versões.
- Heurísticas para scanning, 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 remoto do Maltrail, CEF via syslog e saída JSON do Logstash.
- Validação da implementação com `maltrail-sensor -T` e métricas Prometheus opcionais.

## Conteúdo

- [Arquitetura](#arquitetura)
- [Interface de relatórios](#interface-de-relatorios)
- [Desempenho](#desempenho)
- [Instalação](#instalação)
  - [Instalador](#instalador)
  - [Compilação a partir do código-fonte](#compilação-a-partir-do-código-fonte)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Configuração](#configuração)
- [Trilhos](#trilhos)
- [Eventos e API](#eventos-e-api)
- [Operações](#operações)
  - [Monitorização](#monitorização)
  - [Retenção de eventos](#retenção-de-eventos)
- [Documentação](#documentação)
- [Contribuição](#contribuição)
- [Projeto](#projeto)
  - [Licença](#licença)
  - [Mantenedores](#mantenedores)
  - [Patrocinadores](#patrocinadores)
  - [Apresentações e publicações](#apresentações-e-publicações)
  - [Lista negra derivada](#lista-negra-derivada)
  - [Integrações de terceiros](#integrações-de-terceiros)
  - [Agradecimentos](#agradecimentos)

## Arquitetura

O Maltrail consiste em 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

Um worker de captura é usado por padrão. 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 alguns
heurísticas de varredura. No teste documentado, 91% dos alertas de heurística de worker único 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 é necessário.

A metodologia de benchmark, resultados de hardware, saída do profiler, medições de memória e verificações de fanout
ao vivo estão documentadas em [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/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

Opções comuns do instalador:```bash
sh install.sh --role sensor      # Install only the sensor
sh install.sh --ref 3.1.2        # 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

Então, compile 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

Binários de sensor `x86_64` e `aarch64` pré-compilados estão anexados aos lançamentos atuais com checksums SHA-256.
Eles vinculam libpcap estaticamente e têm como alvo glibc 2.28, então a biblioteca C é a única coisa
de que precisam — nada para instalar, tanto no RHEL 8+, Debian 10+, Ubuntu 18.04+ quanto no Leap 15.x. Em
sistemas baseados em musl, como o Alpine Linux, compile a partir do código-fonte.

Binários das versões **3.1.1 e anteriores** não faziam isso: eles vinculavam libpcap dinamicamente e a solicitavam pelo
nome que o host de build AlmaLinux usa. Debian e Ubuntu fornecem a biblioteca idêntica sob o
nome mais antigo `libpcap.so.0.8`, então esses binários param antes mesmo de começar —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

As unidades fornecidas em `packaging/systemd/` executam ambos os processos como o
utilizador sem privilégios `maltrail`. O Systemd cria `/var/log/maltrail` e `/var/lib/maltrail`, restringe
o acesso ao sistema de ficheiros e concede ao sensor `CAP_NET_RAW` e `CAP_NET_ADMIN`.

O instalador configura estas unidades automaticamente. Para uma instalação existente a partir do código-fonte, siga
o procedimento manual de serviço em [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).

Verifique o estado do serviço e os registos com:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

Configuração do contêiner, armazenamento, privilégios e verificações de integridade estão documentados em
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/master/docker/README.md).

## Configuração

O Maltrail lê `maltrail.conf`, que contém configurações separadas de `[Sensor]` e `[Server]`. O
instalador coloca a configuração gerenciada em `/etc/maltrail.conf`.

Opções de sensor usadas com frequência incluem:

| Opção | Finalidade |
| --- | --- |
| `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 |
| `CAPTURE_WORKERS` | Workers de captura, um socket cada; o padrão é `CAPTURE_FANOUT`, portanto um, a menos que algum deles seja definido |
| `LOG_DIR` | Diretório local de log de eventos |
| `TRAILS_FILE` | Banco de dados de trilhas gerado |
| `LOG_SERVER` | Servidor de eventos Maltrail remoto |
| `SYSLOG_SERVER` | Destino ou destinos de syslog CEF |
| `LOGSTASH_SERVER` | Destino ou destinos JSON do Logstash |
| `STATS_ADDRESS` | Listener de métricas Prometheus; desabilitado a menos que configurado |
| `UPDATE_PERIOD` | Intervalo de atualização das trilhas |
| `STATIC_TRAILS_URL` | De onde o conjunto de trilhas estáticas montado é buscado; fixe-o em uma versão datada para controlar quando novo conteúdo chega |
| `USER_WHITELIST` | Indicadores gerenciados pelo operador que não devem gerar alertas |
| `CUSTOM_TRAILS_DIR` | Diretório de trilhas gerenciado pelo operador |
| `STATIC_TRAILS_DIR` | Checkout opcional do repositório de trilhas; usado apenas para exibir a citação da fonte de uma trilha na interface |

`PROCESS_COUNT` se aplica ao sensor Python descontinuado e ao limitador de log de eventos legado; ele
**não** define a contagem de workers do sensor Rust. Configure os workers de captura com `CAPTURE_FANOUT` ou
`CAPTURE_WORKERS` em vez disso.

Execute a verificação de implantação após alterar a configuração:```bash
sensor/target/release/maltrail-sensor -T

Aponte para um lançamento específico `content-YYYYMMDD-HHMM` para fixar uma versão, de modo que uma publicação ruim
não se torne imediatamente global. O conjunto é armazenado em cache ao lado de `TRAILS_FILE`, que é o que torna possível
uma reconstrução offline ou em ambiente isolado; o `sha256` publicado é verificado antes do download, de modo que uma implantação
que atualiza com mais frequência do que o conteúdo muda transfere 65 bytes em vez de 11 MB, e uma
carga útil que não corresponde ao seu digest é recusada em favor do cache.

`update_trails()` publica um novo `TRAILS_FILE` atomicamente e somente após uma compilação bem-sucedida. Feeds
que não retornam nada são relatados pelo nome, de modo que uma implantação não depende silenciosamente de uma fonte que
se aposentou silenciosamente.

Adicione seus próprios indicadores em `CUSTOM_TRAILS_DIR`, e qualquer coisa que nunca deva gerar um evento em
`USER_WHITELIST`. Mantenha ambos fora do diretório de instalação para que uma atualização não possa sobrescrevê-los.

Contribuições estáticas de trails vão para [stamparm/trails](https://github.com/stamparm/trails); novos feeds
vão aqui. De qualquer forma, um indicador precisa de uma classificação e de uma fonte que alguém possa verificar — veja
[Contributing](#contributing).

## Events e API

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>

Aqui está a tradução do conteúdo:

{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)",
  "confidence": 100
}
```
O campo `confidence` (0-100, ou `null` quando indisponível) indica o quão fortemente as fontes respaldam a
listagem: 40 para um único feed, +15 por feed adicional que concorde de forma independente até 100, e nota
máxima para entradas personalizadas e estáticas do próprio operador. Ele é calculado no momento da atualização
do trail a partir da concordância dos feeds em um sidecar `trails.confidence` ao lado de `trails.csv`; um
servidor que puxe trails de um `UPDATE_SERVER` não tem proveniência para pontuar e reporta `null`. Use-o para
priorizar a triagem — uma listagem de feed único em 40 merece uma segunda olhada antes de ganhar uma regra de
firewall.

Uma consulta de subdomínio pode corresponder ao seu domínio pai listado. Consultas de URL verificam
`host/path` antes de verificar apenas o host. O servidor lê o banco de dados de trails mapeado em memória e
observa atualizações de trails sem reinicialização.

Trails públicos estáticos e de feeds estão disponíveis sem autenticação, de forma consistente com o endpoint
`/trails` usado por sensores remotos. Trails personalizados exigem uma sessão autorizada; uma consulta não
autorizada apenas de personalizados é reportada como um erro. Os dados de eventos permanecem autenticados.

## Operações

### Monitoramento

Use `maltrail-sensor -T` como um gate de implantação e configuração. A unit systemd fornecida o executa
como `ExecStartPre`.

Para confirmar que a detecção em si funciona — não apenas que os processos iniciam — execute:```bash
python3 server.py --detect-test
```
Ele reproduz um pcap elaborado de tráfego malicioso emulado (correspondências de trail em uma consulta DNS, um IP, um
`IP:porta`, um caminho de URL e um cabeçalho `Host`, além das heurísticas de injeção SQL, traversal, RCE, XSS, sonda de proxy,
sinkhole, `Host` ausente e varredura de porta/web/infecção) através do sensor instalado
e verifica que cada detecção esperada é acionada. Não requer root, interface ou conjunto de trails
próprio. Uma instalação saudável imprime `20/20 detecção(ões) acionada(s)`.

Quando `STATS_ADDRESS` estiver configurado, monitore pelo menos estas métricas do Prometheus:

| Métrica | Significado operacional |
| --- | --- |
| `maltrail_up == 0` | Nenhum worker de captura está em execução |
| `maltrail_capture_dropped_total` aumentando | O anel de captura está descartando pacotes |
| `maltrail_local_log_errors_total` aumentando | Eventos foram produzidos, mas não puderam ser gravados localmente |
| `maltrail_remote_log_errors_total` aumentando | 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 trails ativo não está sendo atualizado |
| `maltrail_log_dir_free_bytes` | Capacidade restante para armazenamento local de eventos |
| `maltrail_state_saturations_total` aumentando | Um limite de estado de heurística foi atingido |
| `maltrail_throttle_evictions_total` aumentando | A tabela de limitação de eventos está no seu limite, então os eventos são agregados antes do configurado |

A saturação de estado afeta a heurística correspondente; a correspondência exata de trails permanece ativa.

Envie `SIGHUP` ou use `systemctl reload maltrail-sensor` para solicitar uma recarga de trails. Arquivos de trail
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. O índice auxiliar do log de eventos por dia (`USE_EVENT_INDEX`,
`LOG_DIR/index/*.sqlite`, aproximadamente o dobro do tamanho do log em disco) é o que torna `/counts` exato e
`/hunt` rápido; ele é mantido incrementalmente a partir dos próprios logs e pode ser reconstruído com
`server.py --rebuild-index`. A compatibilidade com o sensor descontinuado está documentada em
[`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md).

### Retenção de eventos

O Maltrail não rotaciona nem exclui logs de eventos. Os operadores são responsáveis por definir retenção,
arquivamento e exclusão de acordo com os requisitos de armazenamento e a política organizacional.

Práticas recomendadas:

- Envie a cópia durável de eventos para um servidor Maltrail remoto ou SIEM com `LOG_SERVER`,
  `SYSLOG_SERVER` ou `LOGSTASH_SERVER`.
- Alerte sobre `maltrail_log_dir_free_bytes` com margem suficiente para a taxa de eventos esperada.
- Rotacione, arquive ou remova logs diários locais usando ferramentas externas.
- Mantenha os arquivos necessários para a interface de relatórios descomprimidos em `LOG_DIR`; arquive arquivos comprimidos
  em outro lugar.

Quando o sistema de arquivos de logs está cheio, o sensor não consegue anexar 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.

## Documentação

| Documento | Conteúdo |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) | Instalação, privilégios, configuração e solução de problemas |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ARCHITECTURE.md) | Internals do sensor e fluxo de dados |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) | Diferenças deliberadas em relação ao sensor Python descontinuado |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) | Medições, perfis e resultados de testes |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ROADMAP.md) | Trabalho aberto do sensor |
| [`SekuriPy Labs`](https://www.sekuripy.hr/labs/maltrail/) | Notas de engenharia, benchmarks e artigos técnicos |

## Contribuindo

Adições de trails, manutenção de feeds, relatórios de bugs, documentação e melhorias no sensor são bem-vindos.
Envios de trails devem incluir uma fonte confiável e devem usar a classificação mais restrita
apropriada.

Execute as verificações relevantes antes de enviar código. O gate completo do sensor é:```bash
bash sensor/tools/check.sh
```
It runs formatting, Clippy with warnings denied, and the debug and release test suites. Run the
Python server suite with:```bash
bash tests/run.sh python3
```
## Projeto

### Licença

O Maltrail é distribuído sob a Licença MIT. Consulte [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE).

### Mantenedores

- Miroslav Stampar ([@stamparm](https://github.com/stamparm))
- Mikhail Kasimov ([@MikhailKasimov](https://github.com/MikhailKasimov))

### Patrocinadores

- [Sansec](https://sansec.io/) (2024–2025)
- [Sansec](https://sansec.io/) (2020–2021)

### Apresentações e publicações

- 47.ª Reunião do TF-CSIRT, Praga, 2016
  ([slides](https://web.archive.org/web/20161109135211/https://www.terena.org/activities/tf-csirt/meeting47/M.Stampar-Maltrail.pdf))
- _Detect attacks on your network with Maltrail_, Linux Magazine, 2022
  ([artigo](https://www.linux-magazine.com/Issues/2022/258/Maltrail))
- _Best Cyber Threat Intelligence Feeds_, Silent Push, 2022
  ([análise](https://www.silentpush.com/blog/best-cyber-threat-intelligence-feeds))
- _Research on Network Malicious Traffic Detection System Based on Maltrail_, Nanotechnology
  Perceptions, 2024
  ([artigo](https://nano-ntp.com/index.php/nano/article/view/1915/1497))

### Lista negra derivada

Uma lista apenas de domínios derivada dos rastros estáticos de `malware/` é publicada em
[`maltrail-malware-domains.txt`](https://raw.githubusercontent.com/stamparm/aux/master/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
apropriados para todos os ambientes.

### Integrações de terceiros

- [Porta FreeBSD](https://www.freshports.org/security/maltrail)
- [Plugin de Gateway OPNsense](https://github.com/opnsense/plugins/pull/1257)
- [Projeto D4](https://www.d4-project.org/2019/09/25/maltrail-integration.html)
- [BlackArch Linux](https://github.com/BlackArch/blackarch/blob/master/packages/maltrail/PKGBUILD)
- [Validin](https://x.com/ValidinLLC/status/1719666086390517762)
- [Complemento Maltrail para Splunk](https://splunkbase.splunk.com/app/7211)
- [Decodificador e regras Maltrail para Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules)
- [GScan](https://github.com/grayddq/GScan) (apenas rastros)
- [MalwareWorld](https://www.malwareworld.com/) (apenas rastros)
- [Lista de bloqueio de domínios oisd](https://oisd.nl/?p=inc) (apenas rastros)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (apenas rastros)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (apenas rastros)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (apenas rastros)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (apenas rastros)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (apenas rastros)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (apenas rastros)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (conector de rastros)

### Agradecimentos

- Thomas Kristner
- Eduardo Arcusa Les
- James Lay
- Ladislav Baco (@laciKE)
- John Kristoff (@jtkdpu)
- Michael Münz (@mimugmail)
- David Brush
- @Godwottery
- Chris Wild (@briskets)
- Keith Irwin (@ki9us)
- Simon Szustkowski (@simonszu)