Spip - Netzwerk-Honeypot-Sensor

Spip ist ein leichter, interaktionsarmer Netzwerk-Honeypot-Sensor. Er lauscht auf beliebigen eingehenden TCP-Verkehr (einfach und TLS), erfasst, was Scanner und Bots senden, und protokolliert jede Verbindung als strukturiertes JSON (ECS-förmig) zur einfachen Aufnahme in Ihr SIEM oder Data Lake.

Spip-Sensoren versorgen HoneyLabs, eine kostenlose, abfragbare Bedrohungsintelligenz-Plattform, die auf den erfassten Daten basiert. Um zu sehen, was Spip in der Praxis sammelt, durchsuchen Sie die Live-Pro-IP-Berichte dort oder den wöchentlichen Bedrohungsbericht, der aus dem Sensornetzwerk generiert wird.

Schnellstart

Voraussetzungen

• Go 1.24.0 oder neuer
• Linux mit iptables
• Root-Zugriff (erforderlich, um die Beispiel-iptables-Regeln anzuwenden)

1. Erstellen Sie den Agent

git clone https://github.com/honeylabshq/Spip-Go.git
cd Spip-Go
go build -o spip-agent ./cmd/spip-agent

2. (Optional) Verwenden Sie den interaktiven Einrichtungshelfer

sudo ./scripts/initial_setup.sh

Dieser Helfer schreibt eine config.toml (er fragt nach einem kurzen name, der in Protokollen verwendet wird), kann selbstsignierte TLS-Schlüssel generieren, konfiguriert optional Loom (URL, sensor_id, token usw.) und wendet optional die PREROUTING iptables-Umleitung an, die in den folgenden Beispielen verwendet wird.

3. Erstellen oder bearbeiten Sie config.toml Minimale config.toml:

name = "spip-agent"
ip = "127.0.0.1"
port = 8080

Optionale Konfigurationsschlüssel:

• cert_path / key_path — aktiviert TLS, wenn beide gesetzt sind; kann relativ zur Konfigurationsdatei sein (das Setup-Skript schreibt relative Pfade, damit die Konfiguration aus jedem Arbeitsverzeichnis funktioniert)
• Protokollausgabe: log_file (lokal) und/oder [loom] (entfernt). Siehe Protokollausgabe unten.
• read_timeout_seconds / write_timeout_seconds — Verbindungs-Timeouts
• rate_limit_per_second / rate_limit_burst — Verbindungsratenbegrenzung
• community_id_seed — optionaler 16-Bit-Seed für Community ID v1 Flow-Hashing (weglassen oder 0 für Standard)

Wenn diese Laufzeittuning-Felder weggelassen oder auf 0 gesetzt werden, verwendet Spip die folgenden Standardwerte:

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

4. Leiten Sie eingehenden TCP zum Agent um (Beispiel, SSH ausgeschlossen)

sudo iptables -t nat -F
sudo iptables -t nat -A PREROUTING -p tcp --dport 22 -j RETURN
sudo iptables -t nat -A PREROUTING -p tcp -j REDIRECT --to-port 8080

5. Führen Sie den Agent aus

./spip-agent -config config.toml

Protokollausgabe

Spip schreibt ECS-Protokolle in ein einzelnes lokales Ziel und kann optional dieselben Protokolle an einen Loom-Server senden:

Also: lokal standardmäßig stdout; mit log_file für eine Datei überschreiben. Optional Loom hinzufügen. Beide verwenden dasselbe ECS-Format.

• Nur lokal: log_file kommentiert/leer lassen (stdout) oder auf einen Pfad setzen.
• Lokal + Loom: lokal wie oben einstellen und einen [loom]-Abschnitt mit url, sensor_id, token hinzufügen (siehe Loom unten).

Protokollformat

Spip gibt jede Verbindung als einzelnes JSON-Objekt aus. Die Ausgabe ist so formatiert, dass sie ECS-kompatibel ist, wobei nur die Felder verwendet werden, die Spip bereitstellen kann (keine ASN/Geo-Anreicherung). Typische produzierte Felder sind:

• @timestamp — RFC3339-Zeitstempel für das Ereignis
• event.id — Sitzungskennung pro Verbindung
• observer.hostname / host.name — Agent name aus der Konfiguration
• source.ip, source.port und destination.ip, destination.port
• network.transport — z.B. tcp
• http.request.body / url.path — wenn die Nutzlast deutlich HTTP ähnelt
• user_agent.original — falls verfügbar

Beispiel (ECS-förmiger) Datensatz von Spip:

{
  "@timestamp": "2025-12-01T19:35:18.123Z",
  "event": {
    "id": "bd30cdc1-95b0-49aa-b8fe-e77230b6a04f",
    "summary": "BitTorrent protocol",
    "original_payload_hex": "426974546f7272656e742070726f746f636f6c",
    "ingested_by": "spip"
  },
  "observer": {"hostname": "spip-agent"},
  "host": {"name": "spip-agent"},
  "source": {"ip": "146.70.1.1", "port": 35882},
  "destination": {"ip": "146.190.1.1", "port": 6881},
  "network": {"transport": "tcp"}
}

Hinweis: Der Agent gibt nur Felder aus, die er aus der Verbindungsnutzlast und den Metadaten ableiten kann. Nachgelagerte Systeme können diese Datensätze anreichern (Geo, ASN usw.), falls gewünscht.

Fingerprinting

Spip kann jedem Verbindungsdatensatz passive Fingerprinting-Felder hinzufügen (ECS-kompatibel, keine Änderung der Nutzlastaufzeichnung):

• Community ID (network.community_id) — V1-Flow-Hash des 5-Tupels (Quell-/Ziel-IP und Port, Protokoll). Wenn der Verkehr über iptables umgeleitet wird, verwendet Spip das ursprüngliche Ziel (vor REDIRECT), sodass der Hash mit dem übereinstimmt, den andere Tools (z.B. Zeek, Suricata) für denselben Flow berechnen würden.
• TLS — Aus dem ClientHello: tls.client.server_name (SNI), tls.client.supported_protocols (ALPN-Liste), tls.client.hash.ja4 (JA4-Fingerabdruck).
• HTTP — Aus der ersten Anfrage: http.request.hash.ja4h (JA4H).
• SSH — Wenn die Nutzlast mit SSH-2.0- beginnt und ein KEXINIT enthält: ssh.client.hash.hassh (Hassh).

All dies sind additive; das bestehende Verhalten (lokales Protokoll, Loom, Nutzlast-Hex, HTTP-Parsing) bleibt unverändert.

Verweise (zur Überprüfung und Zuordnung):
Community ID: Corelight Community ID Spezifikation.
JA4 / JA4H: FoxIO JA4.
Hassh: Salesforce HASSH.
TLS-Fingerprinting verwendet github.com/psanford/tlsfingerprint (MIT).

Loom (optionaler Protokollversand)

Teil von Protokollausgabe: Wenn [loom] enabled = true hat, werden dieselben ECS-Datensätze auch gebündelt und per POST an Ihre Loom-Ingest-URL gesendet. Erforderlich, wenn aktiviert: url, sensor_id, token. Optional: batch_size (Standard 50), flush_interval (z.B. "10s"), insecure_skip_verify (für selbstsignierte Loom-Zertifikate). Der Exporter läuft asynchron und blockiert die Erfassungsschleife nicht; fehlgeschlagene POSTs werden nach stderr protokolliert und der Batch wird verworfen (Fail-Open).

Projektstruktur

.
├── cmd/                 # Hauptanwendungseinstiegspunkt
├── internal/            # Konfiguration, Protokollierung, Netzwerk, TLS, Fingerprinting, Exporteure (z.B. Loom)
├── pkg/                 # Linux-Socket-Helfer (SO_ORIGINAL_DST via syscall)
├── test/                # End-to-End-Testhelfer
└── scripts/             # Dienstprogramm-Skripte (einschließlich `initial_setup.sh`)

Testen

Führen Sie Komponententests aus mit:

go test ./...

End-to-End-Tests erfordern Berechtigungen zur Manipulation von iptables. Führen Sie sie über das Skript aus (vom Repository-Stammverzeichnis):

sudo -E ./scripts/run_e2e_tests.sh

Das Skript richtet die Umgebung und iptables ein. Alternativ den Container-Helfer verwenden: ./scripts/run_e2e_in_container.sh. E2E validiert das Kernverhalten (Nutzlastaufzeichnung, Quelle/Ziel, TLS-Erkennung, Loom-Batching, Fingerprinting).

Hinweise zum HTTP-Parsing und zur Bereitstellung

Spip führt eine bestmögliche HTTP-Anforderungserkennung aus der erfassten Nutzlast durch. Wenn die Nutzlast deutlich einer HTTP-Anfrage ähnelt (gültige Anfragezeile plus grundlegende Header oder ALPN), gibt der Agent http.*, url.path und user_agent.original-Felder aus. Wenn nicht, fällt Spip auf die Speicherung der Nutzlast in event.summary zurück und bewahrt immer die rohe Nutzlast in hexadezimaler Form in event.original_payload_hex.

Da Spip die Quell-IP in seinen Antworten widerspiegelt und beliebigen eingehenden TCP-Verkehr akzeptiert, ist es für die Verwendung als Honeypot-ähnlicher Sensor oder Edge-Collector in kontrollierten/überwachten Umgebungen gedacht, nicht auf beliebigen Benutzerendpunkten.

Initialer Einrichtungshelfer

Führen Sie den interaktiven Helfer vom Repository-Stammverzeichnis aus (erfordert Root bei der Anwendung von iptables-Regeln):

sudo ./scripts/initial_setup.sh

Das Skript fragt nach: einem Kurznamen name (wird in config.toml geschrieben, in Protokollen als observer.hostname / host.name verwendet), Abhör-IP und -Port, optionaler Generierung selbstsignierter TLS-Zertifikate (Pfade werden relativ zur Konfiguration geschrieben, sodass sie aus jedem Verzeichnis funktionieren), optionaler Loom-Konfiguration (URL, sensor_id, token, batch_size, flush_interval, TLS-Verifizierung), Protokolldateipfad und optionaler iptables PREROUTING-Umleitung.