
Um sandbox de rede determinístico para testar regras de nftables. Ele usa namespaces de rede Linux efêmeros (netns) e Scapy para validar a lógica de firewall com segurança.
Por que NSE? • Contrato do oráculo • Asserções no fio • Recursos • Requisitos • Instalação • Início rápido • Como funciona • Estrutura do projeto
Testar conjuntos de regras de firewall em um sistema Linux em produção apresenta riscos significativos: regras malformadas podem derrubar sessões de gerenciamento SSH, vazar tráfego em texto claro durante os testes ou deixar tabelas de firewall órfãs ativas no host.
O Network Sandbox Engine (NSE) fornece um ambiente de teste seguro e reproduzível. Ele constrói network namespaces Linux efêmeros, conecta pares de ethernet virtuais, compila conjuntos de regras nftables e injeta pacotes sintéticos de Camada 2 e Camada 3 usando Scapy. Toda a avaliação ocorre dentro do namespace do sandbox: o estado do firewall do host nunca é alterado.
Propriedades arquiteturais principais:
nse_<uuid>) e são completamente removidos durante o encerramento.nse/ tem cerca de 1200 instruções com 98% de cobertura de testes.O NSE cria network namespaces, carrega conjuntos de regras nftables e lê eventos de trace do kernel, portanto é executado como root. Ele não abre um socket, uma porta ou um endpoint RPC de qualquer tipo — é uma biblioteca e uma CLI que você invoca, e mantém privilégios apenas durante a execução.
A versão 2.1.0 removeu a interface web FastAPI/Svelte que versões anteriores incluíam. Essa interface era executada em processo como root a partir da 2.0.0, o que representava uma grande superfície de ataque para uma ferramenta de teste; o código permanece no histórico do git na tag v2.0.0 caso você precise dele.
Um teste de firewall é uma asserção negativa — "este pacote não passou" — e uma asserção negativa não vale nada a menos que se saiba que o instrumento está funcionando. Um monitor de trace que nunca se conectou ao kernel e um firewall que bloqueou tudo produzem saídas idênticas byte a byte.
Portanto, o NSE se recusa a reportar um veredito que não possa demonstrar que mediu:
| Garantia | Mecanismo |
|---|---|
| O monitor foi anexado antes do primeiro pacote de teste | Um canário de prontidão é injetado e reinjetado até que seu rastreamento no kernel seja observado. Sem observação, sem execução. |
| O monitor ainda estava anexado após o último | Um canário de vivacidade é executado após a injeção. Se ele for perdido, o fluxo de veredictos é declarado truncado. |
| O parser entendeu o que o kernel disse | Linhas de rastreamento que não correspondem a nenhum padrão são contadas, e qualquer contagem acima de zero é um erro em vez de um log de depuração. |
| O monitor não morreu silenciosamente | O loop de leitura registra por que ele terminou — parada limpa, EOF inesperado, timeout ou falha — e apenas uma parada limpa é aceitável. |
| Um veredicto ausente não é uma aprovação | O executor da CLI falha quando o número de veredictos observados difere do número esperado, em qualquer direção. |
Os pacotes canário são excluídos dos resultados por trace id, portanto nunca aparecem no seu fluxo de veredictos.
A suíte prova que isso se mantém, em vez de apenas afirmá-lo: make test-blind força
o parser a não entender nada, e a compilação falha a menos que o executor saia
com código diferente de zero. Essa tarefa é executada na CI a cada push.
nft monitor trace relata o que o conjunto de regras decidiu. Ele não consegue relatar o que
saiu de uma interface que o conjunto de regras nunca correspondeu, que é a questão que uma
afirmação de vazamento zero realmente faz. PCAPAsserter cobre isso: um wrapper de AsyncSniffer
que captura em uma interface nomeada e devolve os quadros, para que um teste
possa afirmar que um estímulo produziu nenhum.
from nse import PCAPAsserter
asserter = PCAPAsserter(iface="veth-host")
await asserter.start()
# ... send the stimulus ...
leaked = await asserter.stop()
assert not leaked, leaked
Aplica-se a mesma regra do oráculo de rastreamento, e cabe ao chamador garanti-la: um sniffer que nunca se anexou e um firewall que bloqueou tudo retornam ambos uma lista vazia. Capture o estímulo uma vez com o conjunto de regras limpo e exija que o quadro seja visto antes de afirmar a sua ausência.
O filtro padrão suprime o ruído link-local, e nada mais.
DEFAULT_FILTER exclui ARP e ICMPv6 tipos 133-137 - Neighbour Discovery, que transporta um limite de saltos de 255 e não consegue alcançar um observador remoto. Tudo o resto é capturado, incluindo ICMPv6 echo para um endereço globalmente encaminhável. Um argumento filter é combinado com esse padrão; replace_default_filter=True usa apenas o seu. A válvula de escape existe porque o filtro é compilado em BPF e avaliado no kernel: um pacote que ele exclui nunca chega ao espaço de utilizador, pelo que nenhum consumidor o pode recuperar a jusante. Até à 2.1.2 o padrão lia not arp and not icmp6, o que também descartava ICMPv6 encaminhável - ver
issue #14.