O Maltrail foi projetado para monitoramento de rede baseado em indicadores. Suas detecções heurísticas complementam
a correspondência de trails, mas não substituem a telemetria de endpoint ou um sistema de prevenção de intrusão
de uso geral.

## Recursos

- Uma construção completa de trails combinando mais de 3.000 arquivos estáticos incluídos, 42 integrações de feeds públicos,
  e trails opcionais fornecidos pelo operador.
- Um sensor Rust multithread usando libpcap, com workers de captura Linux `PACKET_FANOUT` opcionais.
- Um servidor Python fornecendo a interface de relatórios, ingestão de eventos e API HTTP.
- Trails personalizados em texto simples e whitelists que podem ser revisados e versionados.
- Heurísticas para varredura, esgotamento de DNS, consultas do tipo DGA, downloads suspeitos, sondagens de proxy,
  valores de User-Agent suspeitos e atividades de rede relacionadas.
- Registro de eventos local, registro remoto do Maltrail, CEF sobre syslog e saída Logstash JSON.
- Validação de implantação com `maltrail-sensor -T` e métricas Prometheus opcionais.

## Conteúdo

- [Arquitetura](#architecture)
- [Interface de relatórios](#reporting-interface)
- [Desempenho](#performance)
- [Instalação](#installation)
  - [Instalador](#installer)
  - [Compilação a partir do código-fonte](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Configuração](#configuration)
- [Trails](#trails)
- [Eventos e API](#events-and-api)
- [Operações](#operations)
  - [Monitoramento](#monitoring)
  - [Retenção de eventos](#event-retention)
- [Documentação](#documentation)
- [Contribuindo](#contributing)
- [Projeto](#project)
  - [Licença](#license)
  - [Mantenedores](#maintainers)
  - [Patrocinadores](#sponsors)
  - [Apresentações e publicações](#presentations-and-publications)
  - [Blacklist derivada](#derived-blacklist)
  - [Integrações de terceiros](#third-party-integrations)
  - [Agradecimentos](#acknowledgements)

## 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 hashing 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 heurísticos com um único worker permaneceram com dois workers, 86% com quatro e 65% com oito. A correspondência exata de trilhas permaneceu inalterada. Aumente `CAPTURE_FANOUT` apenas quando as métricas de perda de captura mostrarem que é necessário.

A metodologia de benchmark, os resultados de hardware, a saída do profiler, as medições de memória e as verificações de fanout em tempo real estão documentados em [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md).

## Instalação

### Instalador

O instalador é verificado em doze distribuições Linux — Debian, Ubuntu, Fedora, Rocky, AlmaLinux, Arch, openSUSE Leap e Tumbleweed, e Alpine — além de FreeBSD e macOS, em cada versão, com o resultado completo registrado em [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat). O Raspberry Pi OS e outros sistemas ARM de 64 bits usam a compilação `aarch64`; o ARM de 32 bits não possui sensor pré-compilado e deve compilá-lo a partir do código-fonte.```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

Em seguida, 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 pré-compilados do sensor estão anexados às versões atuais com checksums SHA-256: Linux `x86_64`
e `aarch64` para glibc e musl, macOS em Apple silicon e Intel, FreeBSD `amd64`, e
Windows `x86_64`.

As compilações glibc ligam a libpcap estaticamente e têm como alvo glibc 2.28, pelo que a biblioteca C é a única coisa
de que precisam — nada para instalar, tanto em RHEL 8+, Debian 10+, Ubuntu 18.04+ como em Leap 15.x. As compilações musl
são totalmente estáticas, pelo que o Alpine não precisa de nada. A compilação Windows é de 64 bits e requer Windows 10 ou posterior mais
[Npcap](https://npcap.com) instalado antes de arrancar — `wpcap.dll` é uma dependência de tempo de carregamento,
pelo que sem ela o loader recusa o executável em vez de falhar na captura. O arquivo diz isso
também.

Binários de **3.1.1 e anteriores** não o faziam: ligavam a libpcap dinamicamente, e pediam-na pelo
nome que o seu host de compilação AlmaLinux usa. Debian e Ubuntu fornecem a biblioteca idêntica sob o
nome mais antigo `libpcap.so.0.8`, pelo que esses binários param antes de arrancar —```
./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
usuário sem privilégios `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 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 logs com:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

A configuração do contêiner, o armazenamento, os privilégios e as 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ê o `maltrail.conf`, que contém configurações separadas de `[Sensor]` e `[Server]`. O
instalador coloca a configuração gerenciada em `/etc/maltrail.conf`.

As 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 do Linux; o padrão é um |
| `CAPTURE_WORKERS` | Workers de captura, um socket cada; o padrão é `CAPTURE_FANOUT`, portanto um, a menos que um deles seja definido |
| `LOG_DIR` | Diretório local de log de eventos |
| `TRAILS_FILE` | Banco de dados de trails gerado |
| `LOG_SERVER` | Servidor remoto de eventos do Maltrail |
| `SYSLOG_SERVER` | Destino ou destinos de syslog CEF |
| `LOGSTASH_SERVER` | Destino ou destinos de JSON do Logstash |
| `STATS_ADDRESS` | Listener de métricas do Prometheus; desabilitado a menos que configurado |
| `UPDATE_PERIOD` | Intervalo de atualização dos trails |
| `STATIC_TRAILS_URL` | De onde o conjunto estático de trails montado é obtido; 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 trails gerenciado pelo operador |
| `STATIC_TRAILS_DIR` | Checkout opcional do repositório de trails; usado apenas para mostrar a citação da fonte de um trail na UI |

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

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

Aponte-o para uma versão específica `content-YYYYMMDD-HHMM` em vez disso, para fixar uma versão, de modo que uma publicação defeituosa não se torne imediatamente global. O conjunto é armazenado em cache ao lado de `TRAILS_FILE`, o que é o que faz funcionar uma reconstrução offline ou em rede isolada; o `sha256` publicado é verificado antes do download, pelo 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 um payload que não corresponde ao seu digest é recusado em favor da cache.

`update_trails()` publica um novo `TRAILS_FILE` atomicamente e apenas após uma compilação bem-sucedida. Os feeds que não retornam nada são reportados por nome, para que uma implantação não dependa silenciosamente de uma fonte que se retirou discretamente.

Adicione os 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 os possa substituir.

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

## Events and 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>

## 🎯 Objetivos de Aprendizagem

Ao final deste módulo, você será capaz de:

- ✅ Compreender a arquitetura do sistema de plugins do Artemis
- ✅ Criar plugins personalizados para necessidades específicas de segurança
- ✅ Implementar verificações de segurança personalizadas
- ✅ Integrar APIs e serviços externos
- ✅ Testar e depurar plugins de forma eficaz
- ✅ Empacotar e distribuir plugins

## 📋 Pré-requisitos

Antes de começar, certifique-se de ter:

- **Java 17+** instalado
- **Maven 3.8+** para gerenciamento de dependências
- **Conhecimento básico de Java** (interfaces, anotações, genéricos)
- **Familiaridade com conceitos de segurança** (XSS, SQLi, SSRF, etc.)
- **IDE** (IntelliJ IDEA, Eclipse ou VS Code)
- **Artemis** instalado e funcionando

## 🏗️ Arquitetura de Plugins

### Visão Geral do Sistema de Plugins

O Artemis utiliza um sistema de plugins baseado em **Java SPI (Service Provider Interface)** que permite estender funcionalidades sem modificar o núcleo da aplicação.

### Tipos de Plugins

| Tipo | Descrição | Caso de Uso |
|------|-----------|-------------|
| **Scanner** | Analisa alvos em busca de vulnerabilidades | Detecção de XSS, SQLi, SSRF |
| **Reporter** | Gera relatórios em diferentes formatos | PDF, JSON, HTML, SARIF |
| **Notifier** | Envia notificações sobre descobertas | Slack, Discord, Email |
| **Analyzer** | Analisa e correlaciona resultados | Detecção de falsos positivos |
| **Integration** | Integra com ferramentas externas | Jira, GitHub, DefectDojo |

### Ciclo de Vida do Plugin

```java
public interface ArtemisPlugin {
    // Chamado quando o plugin é carregado
    void initialize(PluginContext context) throws PluginException;
    
    // Chamado quando o plugin é iniciado
    void start() throws PluginException;
    
    // Chamado quando o plugin é parado
    void stop() throws PluginException;
    
    // Chamado quando o plugin é descarregado
    void destroy() throws PluginException;
    
    // Retorna metadados do plugin
    PluginMetadata getMetadata();
}

my-artemis-plugin/
├── pom.xml
├── src/
│   └── main/
│       ├── java/
│       │   └── com/
│       │       └── example/
│       │           └── plugin/
│       │               ├── MyScannerPlugin.java
│       │               └── MyPluginMetadata.java
│       └── resources/
│           └── META-INF/
│               └── services/
│                   └── com.example.artemis.plugin.ArtemisPlugin

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>com.example</groupId>
    <artifactId>my-artemis-plugin</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <artemis.version>1.0.0</artemis.version>
    </properties>
    
    <dependencies>
        <!-- Artemis Plugin API -->
        <dependency>
            <groupId>com.artemis</groupId>
            <artifactId>artemis-plugin-api</artifactId>
            <version>${artemis.version}</version>
            <scope>provided</scope>
        </dependency>
        
        <!-- Dependências adicionais -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>2.0.9</version>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
            </plugin>
            
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.0</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

package com.example.plugin;

import com.artemis.plugin.ArtemisPlugin;
import com.artemis.plugin.PluginContext;
import com.artemis.plugin.PluginException;
import com.artemis.plugin.PluginMetadata;
import com.artemis.scanner.ScannerPlugin;
import com.artemis.scanner.ScanResult;
import com.artemis.scanner.ScanTarget;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.List;
import java.util.concurrent.CompletableFuture;

/**
 * Plugin de scanner personalizado para Artemis.
 * 
 * Este plugin demonstra como criar um scanner personalizado
 * que pode ser integrado ao pipeline de segurança do Artemis.
 */
public class MyScannerPlugin implements ArtemisPlugin, ScannerPlugin {
    
    private static final Logger logger = LoggerFactory.getLogger(MyScannerPlugin.class);
    
    private PluginContext context;
    private boolean running = false;
    
    @Override
    public void initialize(PluginContext context) throws PluginException {
        logger.info("Inicializando MyScannerPlugin...");
        this.context = context;
        
        // Validar configuração
        if (context.getConfiguration() == null) {
            throw new PluginException("Configuração do plugin não encontrada");
        }
        
        logger.info("MyScannerPlugin inicializado com sucesso");
    }
    
    @Override
    public void start() throws PluginException {
        logger.info("Iniciando MyScannerPlugin...");
        this.running = true;
        logger.info("MyScannerPlugin iniciado");
    }
    
    @Override
    public void stop() throws PluginException {
        logger.info("Parando MyScannerPlugin...");
        this.running = false;
        logger.info("MyScannerPlugin parado");
    }
    
    @Override
    public void destroy() throws PluginException {
        logger.info("Destruindo MyScannerPlugin...");
        this.context = null;
        logger.info("MyScannerPlugin destruído");
    }
    
    @Override
    public PluginMetadata getMetadata() {
        return new MyPluginMetadata();
    }
    
    @Override
    public CompletableFuture<List<ScanResult>> scan(ScanTarget target) {
        return CompletableFuture.supplyAsync(() -> {
            logger.info("Escaneando alvo: {}", target.getUrl());
            
            List<ScanResult> results = new java.util.ArrayList<>();
            
            try {
                // Implementar lógica de scan personalizada aqui
                // Este é um exemplo simplificado
                
                // Verificar headers de segurança
                checkSecurityHeaders(target, results);
                
                // Verificar configurações de CORS
                checkCorsConfiguration(target, results);
                
                // Verificar exposição de informações
                checkInformationDisclosure(target, results);
                
            } catch (Exception e) {
                logger.error("Erro durante o scan: {}", e.getMessage(), e);
            }
            
            return results;
        });
    }
    
    private void checkSecurityHeaders(ScanTarget target, List<ScanResult> results) {
        // Implementação da verificação de headers
        logger.debug("Verificando headers de segurança para: {}", target.getUrl());
        // Lógica de verificação aqui
    }
    
    private void checkCorsConfiguration(ScanTarget target, List<ScanResult> results) {
        // Implementação da verificação de CORS
        logger.debug("Verificando configuração CORS para: {}", target.getUrl());
        // Lógica de verificação aqui
    }
    
    private void checkInformationDisclosure(ScanTarget target, List<ScanResult> results) {
        // Implementação da verificação de exposição de informações
        logger.debug("Verificando exposição de informações para: {}", target.getUrl());
        // Lógica de verificação aqui
    }
}

package com.example.plugin;

import com.artemis.plugin.PluginMetadata;

import java.util.List;
import java.util.Map;

/**
 * Metadados do MyScannerPlugin.
 */
public class MyPluginMetadata implements PluginMetadata {
    
    @Override
    public String getId() {
        return "my-scanner-plugin";
    }
    
    @Override
    public String getName() {
        return "My Custom Scanner Plugin";
    }
    
    @Override
    public String getVersion() {
        return "1.0.0";
    }
    
    @Override
    public String getDescription() {
        return "Plugin de scanner personalizado para verificações de segurança";
    }
    
    @Override
    public String getAuthor() {
        return "Seu Nome";
    }
    
    @Override
    public String getLicense() {
        return "MIT";
    }
    
    @Override
    public List<String> getDependencies() {
        return List.of();
    }
    
    @Override
    public Map<String, Object> getConfigurationSchema() {
        return Map.of(
            "timeout", Map.of(
                "type", "integer",
                "default", 30,
                "description", "Timeout em segundos para operações de scan"
            ),
            "maxDepth", Map.of(
                "type", "integer",
                "default", 3,
                "description", "Profundidade máxima de crawling"
            ),
            "enabledChecks", Map.of(
                "type", "array",
                "default", List.of("headers", "cors", "info-disclosure"),
                "description", "Verificações habilitadas"
            )
        );
    }
}

com.example.plugin.MyScannerPlugin

# Compilar o plugin
mvn clean package

# O JAR será criado em target/my-artemis-plugin-1.0.0.jar

# Copiar o plugin para o diretório de plugins do Artemis
cp target/my-artemis-plugin-1.0.0.jar /path/to/artemis/plugins/

# Ou usar o comando de instalação do Artemis
artemis plugin install target/my-artemis-plugin-1.0.0.jar

# Verificar se o plugin foi carregado
artemis plugin list

public class ConfigurablePlugin implements ArtemisPlugin {
    
    private PluginConfiguration config;
    
    @Override
    public void initialize(PluginContext context) throws PluginException {
        this.config = context.getConfiguration();
        
        // Acessar configurações
        int timeout = config.getInt("timeout", 30);
        String apiKey = config.getString("apiKey", "");
        List<String> targets = config.getStringList("targets");
        
        // Validar configurações obrigatórias
        if (apiKey.isEmpty()) {
            throw new PluginException("apiKey é obrigatória");
        }
    }
}

public class EventAwarePlugin implements ArtemisPlugin, EventListener {
    
    @Override
    public void onEvent(PluginEvent event) {
        switch (event.getType()) {
            case SCAN_STARTED:
                logger.info("Scan iniciado: {}", event.getData());
                break;
            case SCAN_COMPLETED:
                logger.info("Scan concluído: {}", event.getData());
                break;
            case VULNERABILITY_FOUND:
                handleVulnerability(event.getData());
                break;
            default:
                logger.debug("Evento não tratado: {}", event.getType());
        }
    }
    
    private void handleVulnerability(Map<String, Object> data) {
        // Processar vulnerabilidade encontrada
    }
}

public class ApiIntegrationPlugin implements ArtemisPlugin {
    
    private final HttpClient httpClient;
    
    public ApiIntegrationPlugin() {
        this.httpClient = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    }
    
    public CompletableFuture<String> sendToExternalApi(ScanResult result) {
        return CompletableFuture.supplyAsync(() -> {
            try {
                String json = objectMapper.writeValueAsString(result);
                
                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://api.example.com/vulnerabilities"))
                    .header("Content-Type", "application/json")
                    .header("Authorization", "Bearer " + apiKey)
                    .POST(HttpRequest.BodyPublishers.ofString(json))
                    .build();
                
                HttpResponse<String> response = httpClient.send(
                    request, 
                    HttpResponse.BodyHandlers.ofString()
                );
                
                return response.body();
                
            } catch (Exception e) {
                throw new CompletionException(e);
            }
        });
    }
}

package com.example.plugin;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;

import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.*;

class MyScannerPluginTest {
    
    private MyScannerPlugin plugin;
    
    @Mock
    private PluginContext mockContext;
    
    @BeforeEach
    void setUp() {
        MockitoAnnotations.openMocks(this);
        plugin = new MyScannerPlugin();
    }
    
    @Test
    void testInitialize() throws PluginException {
        when(mockContext.getConfiguration()).thenReturn(mock(PluginConfiguration.class));
        
        assertDoesNotThrow(() -> plugin.initialize(mockContext));
    }
    
    @Test
    void testInitializeWithoutConfiguration() {
        when(mockContext.getConfiguration()).thenReturn(null);
        
        assertThrows(PluginException.class, () -> plugin.initialize(mockContext));
    }
    
    @Test
    void testMetadata() {
        PluginMetadata metadata = plugin.getMetadata();
        
        assertNotNull(metadata);
        assertEquals("my-scanner-plugin", metadata.getId());
        assertEquals("1.0.0", metadata.getVersion());
    }
}

class MyScannerPluginIntegrationTest {
    
    private ArtemisTestServer testServer;
    private MyScannerPlugin plugin;
    
    @BeforeEach
    void setUp() throws Exception {
        testServer = new ArtemisTestServer();
        testServer.start();
        
        plugin = new MyScannerPlugin();
        plugin.initialize(createTestContext());
        plugin.start();
    }
    
    @AfterEach
    void tearDown() throws Exception {
        plugin.stop();
        plugin.destroy();
        testServer.stop();
    }
    
    @Test
    void testScanDetectsMissingHeaders() {
        ScanTarget target = ScanTarget.builder()
            .url(testServer.getUrl("/no-security-headers"))
            .build();
        
        List<ScanResult> results = plugin.scan(target).join();
        
        assertFalse(results.isEmpty());
        assertTrue(results.stream()
            .anyMatch(r -> r.getType().equals("MISSING_SECURITY_HEADER")));
    }
}

my-artemis-plugin-1.0.0.jar
├── META-INF/
│   ├── MANIFEST.MF
│   └── services/
│       └── com.example.artemis.plugin.ArtemisPlugin
├── com/
│   └── example/
│       └── plugin/
│           ├── MyScannerPlugin.class
│           └── MyPluginMetadata.class
└── plugin.properties

plugin.id=my-scanner-plugin
plugin.name=My Custom Scanner Plugin
plugin.version=1.0.0
plugin.author=Seu Nome
plugin.license=MIT
plugin.description=Plugin de scanner personalizado para verificações de segurança
plugin.mainClass=com.example.plugin.MyScannerPlugin
plugin.apiVersion=1.0

# Empacotar o plugin
mvn clean package

# Assinar o plugin (opcional)
gpg --detach-sign target/my-artemis-plugin-1.0.0.jar

# Publicar no repositório
artemis plugin publish \
    --file target/my-artemis-plugin-1.0.0.jar \
    --repository https://plugins.artemis.example.com

# Habilitar logs de depuração
artemis --log-level DEBUG plugin load my-plugin.jar

# Verificar dependências do plugin
artemis plugin inspect my-plugin.jar

# Validar estrutura do plugin
artemis plugin validate my-plugin.jar

public class MyPlugin implements ArtemisPlugin {
    
    private static final Logger logger = LoggerFactory.getLogger(MyPlugin.class);
    
    @Override
    public void initialize(PluginContext context) throws PluginException {
        logger.debug("Configuração: {}", context.getConfiguration());
        logger.info("Plugin inicializado");
        logger.warn("Recurso não disponível, usando fallback");
        logger.error("Falha ao conectar", exception);
    }
}

// ❌ Ruim
public void process() {
    try {
        doSomething();
    } catch (Exception e) {
        // Ignorar silenciosamente
    }
}

// ✅ Bom
public void process() throws PluginException {
    try {
        doSomething();
    } catch (SpecificException e) {
        logger.error("Falha ao processar: {}", e.getMessage(), e);
        throw new PluginException("Falha no processamento", e);
    }
}

// ❌ Ruim
public String readFile(String path) {
    BufferedReader reader = new BufferedReader(new FileReader(path));
    return reader.readLine(); // Vazamento de recurso
}

// ✅ Bom
public String readFile(String path) throws IOException {
    try (BufferedReader reader = new BufferedReader(new FileReader(path))) {
        return reader.readLine();
    }
}

// ❌ Ruim
public class MyPlugin {
    private List<ScanResult> results = new ArrayList<>();
    
    public void addResult(ScanResult result) {
        results.add(result); // Não é thread-safe
    }
}

// ✅ Bom
public class MyPlugin {
    private final List<ScanResult> results = 
        Collections.synchronizedList(new ArrayList<>());
    
    public void addResult(ScanResult result) {
        synchronized (results) {
            results.add(result);
        }
    }
}

// ❌ Ruim
public class MyPlugin {
    private static final String API_KEY = "hardcoded-key"; // Nunca faça isso
}

// ✅ Bom
public class MyPlugin {
    private String apiKey;
    
    @Override
    public void initialize(PluginContext context) throws PluginException {
        this.apiKey = context.getConfiguration().getString("apiKey");
        if (apiKey == null || apiKey.isEmpty()) {
            throw new PluginException("apiKey é obrigatória");
        }
    }
}

O campo `confidence` (0-100, ou `null` quando indisponível) indica quão fortemente as fontes
sustentam a listagem: 40 para um único feed, +15 por cada feed adicional que concorda
independentemente até 100, e pontuação máxima para as entradas personalizadas e estáticas do
próprio operador. É calculado no momento da atualização do trail a partir da concordância dos feeds
num sidecar `trails.confidence` junto ao `trails.csv`; um servidor que obtém 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 com 40 merece uma segunda análise antes de ganhar uma regra de
firewall.

Uma consulta de subdomínio pode corresponder ao seu parent listado. As consultas de URL verificam
`host/path` antes de verificar apenas o host. O servidor lê a base de dados de trails mapeada em
memória e observa atualizações de trails sem reiniciar.

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

## Operações

### Monitorização

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

Para confirmar que a própria deteção funciona — não apenas que os processos arrancam — execute:```bash
python3 server.py --detect-test

`--keep` também reproduz `sensor/tests/corpus/` no mesmo log e imprime quais das formas que o
dashboard renderiza de forma diferente têm um evento por trás delas, para que um ícone, cor ou glifo
ausente seja visível em vez de presumido. Os carimbos de data/hora são deslocados para que o dia mais
recente seja hoje. É necessário um binário do sensor (`cargo build --release --manifest-path sensor/Cargo.toml`).

Os dados da demonstração pública são regenerados a partir de uma execução desse tipo:```bash
python3 sensor/tools/gen_demo_js.py --from DIR/logs   # tops up html/js/demo.js

Ele executa formatação, Clippy com avisos negados e as suítes de teste de debug e release. Execute a suíte do servidor Python com:```bash
bash tests/run.sh python3

Ele faz compilação cruzada do sensor com mingw-w64, extrai a biblioteca de espaço de usuário do Npcap do seu instalador
(um arquivo NSIS, portanto nada é instalado) e executa o resultado sob o Wine — toda a suíte de testes,
`-T` contra a configuração fornecida, o corpus pcap comparado byte a byte com o binário
nativo, e o servidor respondendo a `/ping` sob um Python do Windows. A captura ao vivo é a única coisa que
ele não consegue cobrir; isso requer o driver de kernel do Npcap e uma máquina Windows real. Os pré-requisitos são
`gcc-mingw-w64-x86-64`, `wine` e `p7zip-full`.

## Projeto

### Licença

**TL;DR:** O Maltrail é licenciado sob MIT, mas o conjunto de dados Maltrail Trails tem termos separados. A consulta/referência independente de IOC é permitida; o uso sistemático do Trails como fonte de inteligência em um produto ou serviço comercial requer permissão/licenciamento.

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

Esse é o motor. O conjunto de trails estático é um trabalho separado sob termos separados: gratuito para uso
defensivo interno, pesquisa e ensino, mas um produto comercial, serviço, oferta de MSSP ou MDR, ou um
feed redistribuído precisa de uma licença. Um motor MIT não torna o conteúdo livre para venda — consulte
[`LICENSE.md`](https://github.com/stamparm/trails/blob/main/LICENSE.md) em
[stamparm/trails](https://github.com/stamparm/trails) antes de distribuí-lo em algo pelo qual você cobra.

### 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 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))

### Integrações de terceiros

- [FreeBSD Port](https://www.freshports.org/security/maltrail)
- [OPNsense Gateway Plugin](https://github.com/opnsense/plugins/pull/1257)
- [D4 Project](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)
- [Maltrail Add-on for Splunk](https://splunkbase.splunk.com/app/7211)
- [Maltrail decoder and rules for Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules)
- [GScan](https://github.com/grayddq/GScan) (apenas trails)
- [MalwareWorld](https://www.malwareworld.com/) (apenas trails)
- [oisd domain blocklist](https://oisd.nl/?p=inc) (apenas trails)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (apenas trails)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (apenas trails)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (apenas trails)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (apenas trails)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (apenas trails)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (apenas trails)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (conector de trail)

### 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)