Spip - 네트워크 허니팟 센서

Spip는 경량의 저상호작용 네트워크 허니팟 센서입니다. 임의의 인바운드 TCP 트래픽(일반 및 TLS)을 수신 대기하며, 스캐너와 봇이 전송하는 내용을 캡처하고 각 연결을 구조화된 JSON(ECS 형식)으로 기록하여 SIEM이나 데이터 레이크에 쉽게 수집할 수 있도록 합니다.

Spip 센서는 HoneyLabs를 구동합니다. HoneyLabs는 캡처된 데이터를 기반으로 구축된 무료 쿼리 가능 위협 인텔리전스 플랫폼입니다. Spip가 실제로 수집하는 내용을 확인하려면 라이브 IP별 보고서나 센서 네트워크에서 생성된 주간 위협 보고서를 참조하세요.

ezgif-476608ae440271e4

빠른 시작

필수 조건

Go 1.24.0 이상
iptables를 지원하는 Linux
루트 액세스 권한(예제 iptables 규칙 적용에 필요)

에이전트 빌드

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

(선택 사항) 대화형 설정 도우미 사용

sudo ./scripts/initial_setup.sh

이 도우미는 config.toml을 작성하고(로그에 사용될 짧은 name을 입력 받음), 자체 서명 TLS 키 생성 가능, 선택적으로 Loom(URL, sensor_id, token 등) 구성, 그리고 아래 예제에서 사용되는 PREROUTING iptables 리다이렉트를 선택적으로 적용합니다.

config.toml 생성 또는 편집 최소 config.toml:

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

선택적 구성 키:

cert_path / key_path — 둘 다 설정하면 TLS 활성화; 설정 파일 기준 상대 경로 가능(설정 스크립트는 상대 경로를 작성하므로 모든 작업 디렉터리에서 설정이 작동)
로그 출력: log_file (로컬) 및/또는 [loom] (원격). 아래 로그 출력 참조.
read_timeout_seconds / write_timeout_seconds — 연결 타임아웃
rate_limit_per_second / rate_limit_burst — 연결 속도 제한
community_id_seed — Community ID v1 흐름 해싱용 선택적 16비트 시드(기본값은 생략 또는 0)

이러한 런타임 튜닝 필드가 생략되거나 0으로 설정되면 Spip는 다음 기본값을 적용합니다:

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

인바운드 TCP를 에이전트로 리다이렉트(예: SSH 제외)

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

에이전트 실행

./spip-agent -config config.toml

로그 출력

Spip는 단일 로컬 대상에 ECS 로그를 기록하며, 선택적으로 동일한 로그를 Loom 서버로 전송할 수 있습니다:

대상	설정	동작

즉, 로컬은 기본적으로 stdout이며, 파일을 원하면 log_file로 재정의합니다. 선택적으로 Loom을 추가합니다. 둘 다 동일한 ECS 형식을 사용합니다.

로컬 전용: log_file을 주석 처리하거나 비워 둠(stdout) 또는 경로 설정.
로컬 + Loom: 위와 같이 로컬을 설정하고 url, sensor_id, token이 포함된 [loom] 섹션 추가(아래 Loom 참조).

로그 형식

Spip는 각 연결을 단일 JSON 객체로 내보냅니다. 출력은 Spip가 제공할 수 있는 필드만 사용하여 ECS 호환 형식으로 구성됩니다(ASN/지리 정보 강화 없음). 일반적으로 생성되는 필드:

@timestamp — 이벤트의 RFC3339 타임스탬프
event.id — 연결별 세션 식별자
observer.hostname / host.name — 설정의 에이전트 name
source.ip, source.port 및 destination.ip, destination.port
network.transport — 예: tcp
http.request.body / url.path — 페이로드가 명확히 HTTP와 유사할 때
user_agent.original — 사용 가능할 때

Spip에서 생성된 예시(ECS 형식) 레코드:

{
  "@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"}
}

참고: 에이전트는 연결 페이로드와 메타데이터에서 파생할 수 있는 필드만 내보냅니다. 다운스트림 시스템은 필요에 따라 이러한 레코드를 강화(지리 정보, ASN 등)할 수 있습니다.

핑거프린팅

Spip는 각 연결 레코드에 수동 핑거프린팅 필드를 추가할 수 있습니다(ECS 호환, 페이로드 캡처 변경 없음):

Community ID (network.community_id) — 5-튜플(소스/대상 IP 및 포트, 프로토콜)의 v1 흐름 해시. iptables를 통해 트래픽이 리다이렉트될 때 Spip는 원래 대상(REDIRECT 이전)을 사용하므로 해시가 동일한 흐름에 대해 다른 도구(예: Zeek, Suricata)가 계산하는 값과 일치합니다.
TLS — ClientHello에서: tls.client.server_name (SNI), tls.client.supported_protocols (ALPN 목록), tls.client.hash.ja4 (JA4 핑거프린트).
HTTP — 첫 번째 요청에서: http.request.hash.ja4h (JA4H).
SSH — 페이로드가 SSH-2.0-로 시작하고 KEXINIT를 포함할 때: ssh.client.hash.hassh (Hassh).

이 모든 것은 추가적입니다. 기존 동작(로컬 로그, Loom, 페이로드 16진수, HTTP 파싱)은 변경되지 않습니다.

참조 (검증 및 출처 표시용):
Community ID: Corelight Community ID 스펙.
JA4 / JA4H: FoxIO JA4.
Hassh: Salesforce HASSH.
TLS 핑거프린팅은 github.com/psanford/tlsfingerprint (MIT)을 사용합니다.

Loom (선택적 로그 전송)

로그 출력의 일부: [loom]에 enabled = true가 설정되면 동일한 ECS 레코드가 배치되어 Loom 수집 URL에 POST됩니다. 활성화 시 필요: url, sensor_id, token. 선택 사항: batch_size (기본값 50), flush_interval (예: "10s"), insecure_skip_verify (자체 서명 Loom 인증서용). 내보내기는 비동기로 실행되며 캡처 루프를 차단하지 않습니다. 실패한 POST는 stderr에 기록되고 배치는 삭제됩니다(fail-open).

프로젝트 구조

.
├── cmd/                 # 메인 애플리케이션 진입점
├── internal/            # 설정, 로깅, 네트워크, TLS, 핑거프린팅, 내보내기 (예: Loom)
├── pkg/                 # Linux 소켓 도우미 (syscall을 통한 SO_ORIGINAL_DST)
├── test/                # 엔드투엔드 테스트 도우미
└── scripts/             # 유틸리티 스크립트 (`initial_setup.sh` 포함)

테스트

다음으로 단위 테스트 실행:

go test ./...

엔드투엔드 테스트는 iptables를 조작할 권한이 필요합니다. 리포지토리 루트에서 스크립트를 통해 실행:

sudo -E ./scripts/run_e2e_tests.sh

스크립트가 환경과 iptables를 설정합니다. 또는 컨테이너 도우미 사용: ./scripts/run_e2e_in_container.sh. E2E는 핵심 동작(페이로드 캡처, 소스/대상, TLS 감지, Loom 배치, 핑거프린팅)을 검증합니다.

HTTP 파싱 및 배포 참고 사항

Spip는 캡처된 페이로드에서 최선의 HTTP 요청 감지를 수행합니다. 페이로드가 명확히 HTTP 요청처럼 보일 때(유효한 요청 라인 및 기본 헤더 또는 ALPN) 에이전트는 http.*, url.path, user_agent.original 필드를 내보냅니다. 그렇지 않으면 Spip는 페이로드를 event.summary에 저장하고 원시 페이로드 16진수를 event.original_payload_hex에 항상 보존합니다.

Spip는 응답에 소스 IP를 반영하고 임의의 인바운드 TCP 트래픽을 허용하므로, 제어/모니터링 환경에서 허니팟 스타일 센서 또는 에지 수집기로 사용하기 위한 것이며 일반 사용자 엔드포인트용이 아닙니다.

초기 설정 도우미

리포지토리 루트에서 대화형 도우미 실행(iptables 규칙 적용 시 root 필요):

sudo ./scripts/initial_setup.sh

스크립트가 다음을 입력 받습니다: 짧은 name(config.toml에 기록, 로그에서 observer.hostname / host.name으로 사용됨), 수신 IP 및 포트, 선택적 자체 서명 TLS 인증서 생성(경로는 설정 파일 기준 상대 경로로 기록되어 모든 디렉터리에서 작동), 선택적 Loom 구성(URL, sensor_id, token, batch_size, flush_interval, TLS 확인), 로그 파일 경로, 선택적 iptables PREROUTING 리다이렉트.

인기

Spip-Go