Network IDS

IDS de rede offline em Python que processa PCAP/PCAPNG em streaming, normaliza eventos e aplica regras comportamentais com janelas temporais. Detecta varreduras verticais, varreduras horizontais e rajadas TCP SYN.

Estado: v1.0.0 com funcionalidades congeladas. O foco atual é estabilidade, documentação e correções.

Resultado verificado

• 26 eventos sintéticos processados e três alertas esperados produzidos;
• scan vertical, scan horizontal e SYN burst detectados;
• tráfego benigno avaliado com zero alertas;
• IDs determinísticos, cooldown e rejeição de eventos fora de ordem;
• códigos de saída 0, 2 e 10 exercitados.

Funcionalidades

• IPv4 e IPv6;
• TCP, UDP, ICMP e ICMPv6;
• leitura streaming com Scapy;
• configuração YAML estrita;
• janelas deslizantes;
• cooldown e deduplicação;
• severidade, evidências e IDs determinísticos;
• mapeamento MITRE ATT&CK;
• relatórios JSON gravados atomicamente;
• PCAPs benigno e malicioso reproduzíveis.

Instalação

cd network-ids
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Demonstração

python scripts/generate_detection_samples.py
python -m network_ids analyze samples/benign.pcap --config rules.yml --json artifacts/benign-report.json
python -m network_ids analyze samples/detections.pcap --config rules.yml --json artifacts/detections-report.json

Resultado esperado:

Events: 26
Alerts: 3
[HIGH] vertical_scan source=10.30.0.10 count=6
[MEDIUM] horizontal_scan source=10.30.0.11 count=5
[HIGH] syn_burst source=10.30.0.12 count=15

Inspeção de eventos

python -m network_ids inspect samples/first-events.pcap
python -m network_ids inspect capture.pcap --limit 20

Cada linha é um evento JSON com timestamp, IPs, protocolo, portas, flags TCP e tamanho.

Regras

Edite rules.yml. Cada regra possui enabled, threshold, window_seconds, cooldown_seconds e severity. Campos desconhecidos, tipos incorretos, severidades inválidas e números não positivos são rejeitados.

Regra	Comportamento	MITRE ATT&CK
vertical_scan	Uma origem acessa várias portas do mesmo destino	T1046
horizontal_scan	Uma origem acessa vários destinos na mesma porta	T1046
syn_burst	Uma origem envia muitos SYN em uma janela curta	T1498.001

Códigos de saída

• 0: análise concluída;
• 2: entrada ou configuração inválida;
• 10: alertas encontrados quando --fail-on-alert é usado.

Testes

python -m pytest -q
python -m ruff check .

Documentação

• Arquitetura
• Threat model
• Avaliação sintética
• Plano original
• Evidências da versão

Status da versão

A versão 1.0.0 está congelada. Consulte CHANGELOG.md e SECURITY.md.

Limitações

• análise offline de um arquivo por execução;
• regras focadas em TCP SYN;
• thresholds precisam ser calibrados para cada ambiente;
• IP de origem pode ser falsificado;
• fragmentação, túneis e tráfego criptografado reduzem a visibilidade;
• o mapeamento MITRE representa uma hipótese analítica, não atribuição;
• o corpus sintético comprova a lógica, não representa taxa real de detecção.

Licença

MIT