gomon

gomon detects interesting network activity generated by sandboxed bots or malware samples. It ingests live interfaces or PCAP captures, groups traffic into sliding windows, and emits Suricata-compatible alerts whenever packet-rate or horizontal host-diversity thresholds are exceeded. The tool pairs well with bottle instrumentation and the bottle-warden orchestrator, but it can also run standalone on any host with libpcap.

Features

• Sliding window analysis with configurable duration, packet rate, and destination host diversity thresholds.
• Horizontal scan detection focuses on unique destination hosts (IP only); vertical scans are not yet classified.
• Suricata Eve JSON output to stdout or a file, enriched with sample IDs, C2 hints, and per-window metrics.
• Optional idle-window logging so you can correlate gaps in beaconing against sandbox state.
• Packet capture artifact support: retain the last N packets per destination whenever an alert fires.
• Calibration mode to report per-window thresholds without emitting alerts.
• Graceful signal handling and a final run summary with alert counts and artifact locations.
• Built-in --version flag and runtime banner that show the binary tag or commit automatically (works with go install module@version).

Requirements

• Linux with libpcap development headers (libpcap-dev on Debian/Ubuntu) so gopacket/pcap can open interfaces.
• Permission to read the capture interface (root or a user in the appropriate group). PCAP files can be processed without elevated privileges.
• Go 1.24+ for local builds and tests.

Installation

# Install the CLI directly from the module (uses Go build info for the version string)
go install github.com/cochaviz/gomon@latest

# Or build from source
git clone https://github.com/cochaviz/gomon.git
cd gomon
go build ./cmd/gomon

Verify the binary and see the embedded version:

gomon --version
gomon version v0.1.0   # or dev (<commit>) if built from a workspace

Quick start

# Analyze a capture file for a sandboxed bot with source IP 10.0.0.5
gomon sample.pcap 10.0.0.5 \
  --window 15 \
  --packet-threshold 20 \
  --destination-threshold 25 \
  --eve-log-path /tmp/sample-eve.json

# Stream directly from an interface while preserving packet artifacts
sudo gomon vnet0 10.10.0.20 \
  --c2-ip 203.0.113.4 \
  --sample-id beacon-42 \
  --save-packets 100 \
  --capture-dir /var/log/gomon/captures

At startup gomon prints an ASCII banner and a configuration block containing every flag value plus the detected version string, making it easy to log provenance in automation pipelines.

CLI overview

gomon <input> <src_ip> [flags]

• <input> – Interface name for live capture (e.g. eth0, vnet0) or path to a .pcap/.pcapng file.
• <src_ip> – IP address assigned to the sandboxed bot; alerts are scoped to flows originating from this address.

Key flags

Flag	Description	Default
--window	Analysis window size in seconds.	30
--packet-threshold	Packet rate per window that triggers an alert.	5
--destination-threshold	Unique destination hosts (IP only) per window before flagging a horizontal scan.	10
--scan-detection-mode	Scan detection mode: host-rate, new-host-rate, or filtered-host-rate.	filtered-host-rate
--log-level	Logging verbosity (debug, info, warn, error).	info
--show-idle	Emit idle window events instead of alerts only.	false
--calibrate	Log per-window calibration metrics without emitting alerts.	false
--eve-log-path	Write Eve JSON to this file instead of stdout.	stdout
--capture-dir	Directory for packet capture artifacts saved when alerts fire.	./captures
--save-packets	Number of recent packets per host to persist for each alert.	0 (disabled)
--c2-ip	Optional C2 IP label added to alert metadata.	unset
--sample-id	Identifier that ties alerts back to a sample.	unset
--ignore-dst	Repeatable flag listing destination IPs to exclude from metrics.	none
--version	Print the binary version and exit early.

Internally gomon caps destination tracking at 1024 unique endpoints per window to keep memory usage predictable; windows that exceed the cap log a warning and continue with the sampled set. Scan detection uses host IPs only, so vertical (single-host, multi-port) scans are not yet flagged.

Alert semantics

• Alerts are emitted using Suricata's Eve schema (event_type=alert); optional idle windows use event_type=stats.
• Each record includes the standard Eve fields plus a metadata.gomon object that mirrors threshold settings, measured rates, sample IDs, and C2 hints.
• dst_ips enumerates every unique destination host (IP only) contributing to the scan window.
• The end-of-run summary reports total alerts, idle windows, and capture locations so you can correlate them with instrumentation logs.

Integrating with bottle or bottle-warden

Add gomon to a bottle instrumentation profile so every sandbox run inherits the same thresholds:

cli:
  - command: >
      gomon {{ .VmInterface }} {{ .VmIp }}
      {{- if .C2Ip }}--c2-ip {{ .C2Ip }}{{ end }}
      --sample-id {{ .SampleName }}
      --save-packets 100
      --capture-dir {{ .LogDir }}/captures
    output: file

Because gomon logs Suricata-compatible events, bottle-warden can tail the Eve file you specify (via --eve-log-path) to detect when beaconing stops or spikes.

Development

• Format with gofmt and run tests via:

  go test ./...

• Module path: github.com/cochaviz/gomon
• The CLI entrypoint lives in cmd/cli.go; packet processing and alerting logic are under internal/.

Use --log-level debug when iterating locally to see packet/window accounting and Suricata log writes in real time.