Spip-Go

Sensor de rede Spip escrito em Go

3. Crie ou edite config.toml config.toml mínimo:

Chaves de configuração opcionais:

• cert_path / key_path — habilita TLS se ambos definidos; podem ser relativos ao arquivo de configuração (o script de configuração escreve caminhos relativos para que o config funcione a partir de qualquer diretório de trabalho)
• Saída de log: log_file (local) e/ou [loom] (remoto). Veja Saída de log abaixo.
• read_timeout_seconds / write_timeout_seconds — timeouts de conexão
• rate_limit_per_second / rate_limit_burst — limitação de taxa de conexão
• community_id_seed — semente opcional de 16 bits para hashing de fluxo Community ID v1 (omitir ou 0 para padrão)

Se esses campos de ajuste de tempo de execução forem omitidos ou definidos como 0, o Spip aplica os seguintes padrões:

• read_timeout_seconds: 30
• write_timeout_seconds: 10
• rate_limit_per_second: 20
• rate_limit_burst: 50000

4. Redirecione o TCP de entrada para o agente (exemplo, excluindo SSH)

5. Execute o agente

Saída de log

Spip escreve logs ECS em um único destino local e pode opcionalmente enviar os mesmos logs para um servidor Loom:

Portanto: local padrão é stdout; substitua com log_file para um arquivo. Opcionalmente adicione Loom por cima. Ambos usam o mesmo formato ECS.

• Apenas local: deixe log_file comentado/vazio (stdout) ou defina um caminho.
• Local + Loom: defina local como acima e adicione uma seção [loom] com url, sensor_id, token (veja Loom abaixo).

Formato do log

Spip emite cada conexão como um único objeto JSON. A saída é formatada para ser compatível com ECS usando apenas os campos que o Spip pode fornecer (sem enriquecimento ASN/geo). Campos típicos produzidos incluem:

• @timestamp — timestamp RFC3339 para o evento
• event.id — identificador de sessão por conexão
• observer.hostname / host.name — name do agente da configuração
• source.ip, source.port e destination.ip, destination.port
• network.transport — ex.: tcp
• http.request.body / url.path — quando o payload claramente se assemelha a HTTP
• user_agent.original — quando disponível
• event.summary — payload bruto para sondagens não-HTTP
• event.original_payload_hex — hex do payload bruto (sempre preservado)
• Fingerprinting (integrado) adiciona network.community_id, tls.client.*, http.request.hash.ja4h, ssh.client.hash.hassh quando aplicável.

Exemplo de registro (formato ECS) produzido pelo Spip:

Nota: o agente apenas emite campos que pode derivar do payload e metadados da conexão. Sistemas downstream podem enriquecer esses registros (geo, ASN, etc.) se desejado.

Fingerprinting

Spip pode adicionar campos de fingerprinting passivo a cada registro de conexão (compatível com ECS, sem alteração na captura de payload):

• Community ID (network.community_id) — hash de fluxo v1 do 5-tuplo (IP de origem/destino e porta, protocolo). Quando o tráfego é redirecionado via iptables, o Spip usa o destino original (antes do REDIRECT) para que o hash corresponda ao que outras ferramentas (ex.: Zeek, Suricata) calculariam para o mesmo fluxo.
• TLS — Do ClientHello: tls.client.server_name (SNI), tls.client.supported_protocols (lista ALPN), tls.client.hash.ja4 (fingerprint JA4).
• HTTP — Da primeira requisição: http.request.hash.ja4h (JA4H).
• SSH — Quando o payload começa com SSH-2.0- e contém um KEXINIT: ssh.client.hash.hassh (Hassh).

Todos esses são aditivos; o comportamento existente (log local, Loom, hex do payload, parsing HTTP) permanece inalterado.

Referências (para verificação e atribuição):
Community ID: Corelight Community ID spec.
JA4 / JA4H: FoxIO JA4.
Hassh: Salesforce HASSH.
TLS fingerprinting uses github.com/psanford/tlsfingerprint (MIT).

Loom (envio de log opcional)

Parte da saída de log: quando [loom] tem enabled = true, os mesmos registros ECS também são agrupados e enviados via POST para sua URL de ingestão Loom. Necessário quando habilitado: url, sensor_id, token. Opcionais: batch_size (padrão 50), flush_interval (ex.: "10s"), insecure_skip_verify (para certificados Loom autoassinados). O exportador roda assincronamente e não bloqueia o loop de captura; POSTs com falha são registrados no stderr e o lote é descartado (fail-open).

Estrutura do Projeto

Testes

Execute testes unitários com:

Testes fim a fim exigem privilégios para manipular iptables. Execute-os através do script (a partir da raiz do repositório):

O script configura o ambiente e o iptables. Alternativamente, use o auxiliar de contêiner: ./scripts/run_e2e_in_container.sh. E2E valida o comportamento principal (captura de payload, origem/destino, detecção TLS, agrupamento Loom, fingerprinting).

Notas sobre parsing HTTP e implantação

Spip realiza detecção de requisições HTTP de melhor esforço a partir do payload capturado. Quando o payload claramente se assemelha a uma requisição HTTP (linha de requisição válida mais cabeçalhos básicos ou ALPN), o agente emite campos http.*, url.path e user_agent.original. Quando não, o Spip recorre ao armazenamento do payload em event.summary e sempre preserva o hex do payload bruto em event.original_payload_hex.

Como o Spip reflete o IP de origem em suas respostas e aceita tráfego TCP de entrada arbitrário, ele é destinado ao uso como sensor estilo honeypot ou coletor de borda em ambientes controlados/monitorados, não em endpoints de usuário arbitrários.

Assistente de configuração inicial

Execute o assistente interativo a partir da raiz do repositório (requer root ao aplicar regras de iptables):

O script solicita: um name curto (escrito no config.toml, usado nos logs como observer.hostname / host.name), IP e porta de escuta, geração opcional de certificado TLS autoassinado (caminhos são escritos relativos ao config para funcionar de qualquer diretório), configuração opcional de Loom (URL, sensor_id, token, batch_size, flush_interval, verificação TLS), caminho do arquivo de log e redirecionamento opcional iptables PREROUTING.