Documentation · Releases · First capture

!Linux !macOS !windows

Protocol hierarchy visualization in the Netcap web UI — more screenshots

Features

Protocol Analysis

• Packet-layer decoders — Ethernet, IPv4/6, TCP, UDP, DNS, DHCP, ARP, TLS ClientHello/ServerHello, ICMP, NTP, SIP, OSPF, BGP, MPLS, GRE, VXLAN and 802.11; check the installed inventory for enabled paths
• Stream decoders — HTTP/1, TLS handshake metadata, SSH, QUIC Initial ClientHello, SMB, FTP, SMTP, POP3, IMAP, IRC, Kerberos and DCE/RPC. A protocol label does not imply HTTP/2/3 plaintext decoding; see coverage.
• Industrial protocols — Modbus, S7Comm, DNP3, OPC-UA, PROFINET, BACnet, CIP, IEC 62351
• Full TCP/UDP stream reassembly with configurable limits

Web UI

Built-in React (Vite + TypeScript) dashboard in service mode with interactive visualizations:

• Sankey diagrams, treemaps, 3D scatter plots, geo maps, host communication graphs
• Record browsing with JSON/UI views and field-level filtering
• Protocol statistics, connection analysis, host profiling, alert management
• Related-evidence timeline on alerts and connections; Settings → Features switches optional features individually

Security Analysis

• JA4 fingerprinting — BSD-licensed JA4 TLS client fingerprinting; external JA4+ support is available only in opt-in local source builds subject to the FoxIO License
• YARA rules — file scanning with compiled yara-x rules for malware detection
• Magika AI — Google's AI-based file type classification on extracted files
• Credential harvesting — configurable protocol-aware credential capture
• File extraction — extract files from HTTP, FTP, SMTP, POP3, IMAP, SMB, IRC with hashing (MD5, SHA1, SHA256) and MIME detection
• Detection rules — 30+ YAML rule categories covering reconnaissance, exfiltration, web attacks, industrial ports, and more. The expression engine supports source→distinct-destination cardinality (fan-out) detection, an approved-workstation allowlist (IsApprovedWorkstation), and time-of-day helpers (IsBusinessHours, HourOfDay)
• Hunting evidence — DNS query/response pairing with RTT, retransmission and unanswered/late status over UDP and TCP; DCE/RPC calls attributed to interface and operation with fault outcomes; periodic-connection (c2.beacon) detection; signed producer–consumer byte ratio per connection. See Hunting evidence
• Evidence linking — from any record, list the records of the same connection, the DNS answer that resolved its destination, connections opened to an answered address and alerts, as a timeline. See Evidence linking
• OT/ICS threat hunting — function-code level Siemens S7comm detection (write / logic download / logic theft / PLC stop / CPU restart) mapped to CISA AA26-231A; ships internal/rules/examples/s7comm_hunt.yml

Output Formats

• Protocol Buffers (default) — compact binary, accessible from any language
• CSV — configurable separators for data analysis pipelines
• JSON — human-readable structured output
• Elasticsearch — direct bulk indexing for ELK stack analysis

Enrichment

• DNS reverse resolution
• GeoIP geolocation and ASN: bundled DB-IP Lite with optional user-installed

• MAC vendor lookup
• Deep Packet Inspection (optional, via nDPI/libprotoident)
• Hyperscan / Vectorscan acceleration (optional) — build-dependent rule-expression matching. Nmap probe and CMS/DHCP OS catalogue processing are retired; see service identification and database sources.

Integrations

• Prometheus + Grafana — real-time metrics and dashboards
• Elasticsearch + Kibana — full-text search and visualization
• Maltego — 45+ OSINT entity types and transforms

Distributed Capture

Agents stream audit records to a collection server over mutually authenticated TLS 1.3, with pinned keys, acknowledged delivery and reconnects. See docs/distributed-collection.md.

Quick Start

Pre-built binaries are available on the Releases page. To build from source:

# Build (requires libpcap)
go build -o net ./cmd/net/
Build without DPI (fewer C dependencies)
go build -tags=nodpi -o net ./cmd/net/
Build with Hyperscan / Vectorscan acceleration for service probes
(requires libhs via pkg-config; e.g. brew install vectorscan on macOS)
See docs/hyperscan.md for details.
CGO_ENABLED=1 go build -tags hyperscan -o net ./cmd/net/
Capture from PCAP file
./net capture -read traffic.pcap -out nc
Host/account summary, or JSON with provenance and conflicting observations
./net triage --read nc
./net triage --read nc --json
Live capture
sudo ./net capture -iface en0
Analyze one file and keep the local web UI running
./net capture -read traffic.pcap -out browser-audit -http 127.0.0.1:8080
Separate upload/session service
./net capture --service -http 127.0.0.1:7070
Service mode with hot reload (development)
air

Network detections

net capture enables capture-time network detections independently of baseline approval. -network-detection=false disables them; -network-detection-config policy.json loads bounded JSON thresholds, authorized source IPs/CIDRs and versioned indicators (internal/networkdetect/config.go).

| Finding | Evidence / interpretation | | --- | --- | | DNS DGA and tunneling | Distinct randomized apex names or high-entropy TXT labels beneath one parent, capture-time counts and sampled names; behavioral suspicion | | TCP scans and SMTP fan-out | Distinct destination endpoints or mail hosts; retries do not increase cardinality | | Periodic connections (c2.beacon) | Latest 8 TCP connection starts from one source to one service, mean interval ≥ 10 s, coefficient of variation ≤ 0.1 within 1 h; retransmitted SYNs ignored. Updates and monitoring are also periodic | | HTTP scans and periodic requests | http.scan: ≥ 32 distinct paths with ≥ 80% 4xx responses in the window; c2.beacon also measures repeated HTTP transactions within one connection | | Application policy observations | policy.http-on-443, policy.non-tls-on-443, policy.executable-unusual-port and policy.public-smb-ntlm retain observed endpoints; none establishes execution, compromise or successful relay | | ICMP tunneling | Repeated large, high-entropy echo requests; diagnostic traffic can look similar | | SSH transfer and unusual ports | SSH banners, unique contiguous client bytes and service port; encrypted contents and authorization remain unknown | | Stratum, IRC, OAST and Telegram | Protocol/destination observations; legitimate use is possible | | C2, sinkhole and imposter | Configured domain/IP matches with source, version and capture-time validity; no live feed is bundled | | Legacy cleartext-service ports | Payload not recognized as TLS/SSH on a legacy service port; port alone does not identify the application or prove credentials were sent | | Analyst UI | /alerts exposes classification, measured values, scope, limits and original evidence export; /api/network-detection exposes coverage, overflow, skipped late events and stream gaps |

Defaults: 60 s windows, 300 s alert deduplication, 10 distinct DNS names/TCP endpoints/large echoes, 5 SMTP hosts and 10 MiB SSH client payload. State retains at most 4,096 keys, 128 values per window and 1,024 flows with 4 KiB prefixes per direction. A stream gap stops signature/transfer claims for that direction and is reported. Indicator validity uses Unix nanoseconds at capture time. A missing status file or zero configured indicators is displayed as unavailable coverage.

internal/networkdetect/testdata/live/ contains 15 real FlightSim CLI captures at revision 3709d1c6905d9527885c62f66f49a955c7b0d191, generated with Docker --network none and local DNS/API/SSH/SFTP/IRC/Stratum fixtures. C2 intelligence is synthetic lab data; SSH qualification uses a 1 MiB transfer and a 512 KiB threshold. testdata/cases.json separately labels synthetic source-shape and benign controls. Scenario names never enter the detector. beacon has no FlightSim capture and is synthetic only.

Hosts.json retains scoped IP/MAC bindings, Kerberos/SMB accounts, hostname evidence and LDAP/SAMR directory subjects. net triage --read nc --json exposes timestamps, flows and unresolved/conflicting joins. LDAP SASL signing payloads are marked sasl-integrity-not-verified; sealed payloads are not decoded. SAMR user-information queries support NDR32 and NDR64. An account-name match without a directory domain is explicitly qualified in fullNameState. LSARPC lookup operations 14/15 decode NDR32/NDR64 name/SID translations; directory subjects are not assigned to the RPC server. NTLMSSP Identity observations retain user/domain/workstation claims without asserting successful authentication. POP3/IMAP LOGIN and SASL PLAIN/LOGIN use ordered exchanges and stop at acknowledged TLS upgrades. Unframed NTLMSSP Token records are retained as unverified payload observations and excluded from host attribution; HTTP, LDAP and RPC authentication fields produce framed identity observations. TLS hello parsing also follows acknowledged STARTTLS/STLS/AUTH TLS and SOCKS5 CONNECT exchanges through internal/decoder/stream/tls/upgrades.go.

dump sorts timestamped records by default; --sort-time=false preserves storage order. Malformed HTTP target control bytes survive in URL with ReassemblyStatus=invalid-request-target-control-byte; semicolons remain literal query values. SMB1 NT_CREATE_ANDX and SMB2 CREATE/READ/WRITE/CLOSE reconstruction publishes complete, consistent byte ranges up to 32 MiB per file. Missing or conflicting ranges and encrypted SMB transforms are not published as complete files.

Vulnerability findings require schema-2 CPE product/version applicability and an observed software host; exploit findings additionally require a linked CVE. Schema-1 databases require a fresh compatible snapshot (net util -download-dbs); editing their version field is not migration. See the format.

Corpus regression checks

scripts/mta-regression.py --report /path/to/netcap-final-report.md --root /tmp/mta --binary ./net --expected-exercises 121 --expected-pcaps 143 --count-override 2016-07-07=1 fetches and verifies the numbered exercise inventory before replay and writes replay.json, including report/binary hashes and explicit inventory corrections. The final report's 148-PCAP count includes five nonexistent captures: 2016-07-07 publishes one PCAP and six emails, not six PCAPs. All other inventory rows match. --offline reuses receipts without network access; --compare-only --tshark /path/to/tshark compares HTTP/TCP TLS tuples and writes reference.json, including missing and additional observations; missing reference tuples make the command exit nonzero. --audit-misses checks the report's 25 previously missed user facts against structured identities. These checks do not rescore the 289 questions or all 1,667 published facts.

NETCAP_MTA_ROOT=/tmp/mta NETCAP_TSHARK=/path/to/tshark go test -tags nodpi ./internal/collector -run '^TestMTAReportRegressions$' -count=1 runs checksum-pinned HTTP, TLS, SMTP, LDAP and SAMR regressions. The November 2024 NetSupport capture uses LF headers and 194.180.191.64; the evaluation's 194.180.191.164 is a typo. The 2018-10-01 published cf99990b…2560 executable is recovered over SMB1; the final report incorrectly calls that particular transfer SMB2.

Hunting evidence

These fields turn individual records into answers for common hunts: which resolvers are slow or failing, which remote procedures were actually called and whether they succeeded, and which hosts upload more than they download.

| Record | Fields | Purpose and semantics | | --- | --- | --- | | DNS | TransactionStatus, RTT, QueryTransmissions | Find slow, failing, retried or unanswered lookups. Queries and responses are paired at capture time on client/server endpoints, DNS ID and first question name/type/class, separately per capture context and VLAN. Status is query, retransmission, answered, late (> 30 s), unsolicited or reordered (response before query in capture order; RTT unavailable). DNS over TCP is framed per connection, including messages split across or coalesced within segments. State is capped at 65,536 UDP and 256 per-TCP-flow pending queries | | DCERPC | ContextID, InterfaceName, OperationName, FaultStatus, CommunityID | Hunt on what a remote call did, not just which interface was opened. Requests and responses inherit the interface from the connection's Bind/AlterContext context, and responses the operation of their call. A request is an attempt; the Response or Fault carries the outcome. Attribution stops at a stream gap rather than guessing | | Connection | ProducerConsumerRatio | Spot uploads and data staging. (client − server bytes) / (client + server bytes) in [-1, 1]: 1 only sent, -1 only received, 0 balanced or no bytes |

WebUI views:

• Domains shows per-domain median RTT and counts of retried, late,

• Connections shows the producer–consumer ratio with a sent/received label.
• Alerts shows the service, mean interval and jitter behind c2.beacon.

go test -race ./internal/networkdetect
go test -race -tags nodpi,noyara,nomagika ./internal/collector -run '^TestFlightSimCollectorReplay$'

The collector checks replay at 1/2/4/8 workers. The lab requires a 32 MiB tcpdump buffer and a 2 s drain; tests/flightsim-lab/run.sh rejects kernel drops and failed simulator modules before sealing capture hashes.

Evidence linking

Answers "what else happened in this connection or because of this lookup" without manual joins. Links are computed from the output directory when asked, so they work for finished and live captures and do not depend on worker count. With -capture-evidence (default true), packet ingress records a scope ledger in capture-manifest.json. After finalization, the linker qualifies records by capture RunID, local sensor, capture-wide interface index and VLAN stack. PCAPNG interface numbering is normalized across sections. DNS resolution links remain temporal candidates, not proof that a lookup caused a connection.

| Link | Basis | | --- | --- | | Same connection | Record has the connection's Community ID and a timestamp within the Connection observation's first–last packet span. A reused 5-tuple is a different observation, and only the latest snapshot of an observation is shown | | Resolved by DNS | Latest DNS response whose A/AAAA answer is the connection's destination, sent to the connection's client, at most -evidence-links-window before the connection started | | Connection to answer | From a DNS response: connections from the same client to an answered address starting within the window after it | | Alert | Rule alert whose matched record carries the Community ID, within the same span | | Same flow | Records with the Community ID but no containing Connection observation, within ± the window |

Per-packet records (TCP, TLSRecord, PacketContext, PKTAP) and records without a computed Community ID (fallback hashes) are not linked. Network-detection alerts carry evidence rather than a matched record, so they are not linked. Known Connection observations suppress fallback flow links when no unique observation contains the target. Duplicate type/Community ID/timestamp selectors are rejected; use the exact type and ordinal instead. Each directory's index has a 64 MiB accounted storage budget as well as its record limit.

| Scope status | Meaning | | --- | --- | | verified | Community ID occurred in exactly one packet scope; cross-protocol links require the same scope | | ambiguous | Community ID occurred in multiple interfaces/VLANs; all links for it are withheld | | pending | Scope ledger is not finalized; scoped claims are withheld | | overflow | The 32,768-entry scope ledger overflowed; scoped claims are withheld globally | | missing | No packet scope for this record; links are withheld. Filtered offline inputs deliberately do not claim preserved interface metadata | | legacy | No scope ledger, including captures made with -capture-evidence=false; results are explicitly labelled candidates within the directory |

| Option | Default | Purpose | | --- | --- | --- | | -evidence-links / NC_EVIDENCE_LINKS | true | Serve /api/evidence/related; switchable at runtime in Settings → Features | | -evidence-links-window | 1h | DNS answer → connection window and Community ID window outside connections | | -evidence-links-max-records | 1000000 | Records indexed per output directory; beyond it results say they are truncated | | -evidence-links-max-links | 500 | Related records returned per query |

The WebUI shows the timeline in alert details (for rule alerts) and in expanded Connections rows. The API selects a record by type+ordinal, by observationId (Connection), by type+communityId+time (Unix ns), or by the content-bound id returned by a previous query:

curl 'http://127.0.0.1:8080/api/evidence/related?observationId=<id>'
net investigate related -read out -type HTTP -ordinal 0

Each link states its kind and basis; notes explain truncation and when no connection contains the record. References include the audit-file fileSha256 and an id derived from type, file digest, capture RunID, scope-manifest digest and ordinal. captureManifestSha256 binds the selected capture/scope witness. Replacing or extending that file invalidates its old references rather than rebinding them. Index construction rejects files changing during the scan. Linked record buttons open another related-evidence timeline; Back returns to the original target. Links are not available to capture-time rules: records are written in a different order than they are captured, so a rule could not see the same links at every worker count.

Capture-time DNS context

-dns-resolution-context (NC_DNS_RESOLUTION_CONTEXT, default false) enables an independent capture-time snapshot on Connection records. The collector pairs UDP DNS at serialized ingress and copies context before dispatch; workers never query mutable cross-flow state. Fields 65–67 are DNSResolvedName, DNSResolvedAt (UTC ns) and DNSResolutionState (resolved or unobserved; empty when disabled). A new observation retains its first packet's context, including after later answers or cache eviction.

Only paired, successful, non-truncated, single-question IN A/AAAA responses on UDP port 53 with an ASCII direct matching answer name contribute. Context expires at the answer TTL, capped at 1 h, and is isolated by capture-wide interface/VLAN and client/destination IP. TCP DNS and CNAME chains are not contributors yet. The answer cache and pending query table each cap at 65,536 entries. unobserved is missing context, not a verdict that no resolution occurred.

type: Connection
expression: 'DNSResolutionMatches(DNSResolutionState, DNSResolvedName, DNSResolvedAt, TimestampFirst, "example.test", 60000000000)'

DNSResolutionMatches is a pure predicate on immutable record fields: exact DNS name comparison (case/trailing-dot normalized), nonnegative bounded age, and resolved state. Settings → Features has a separate switch applying to the next analysis; expanded Connections rows display the snapshot. Go/Rust qualification checks enabled/disabled fields and rule alerts at 1/2/4/8 workers.

Feature switches

Settings → Features lists optional features with their flag and environment variable. GET /api/features returns them; POST /api/features {"name":"evidence-links","enabled":false} switches one until the process exits. Query features (evidence linking) apply to the next request; capture features (network detections) apply to the next analysis started from the WebUI.

Behavioral monitoring

capture -behavior and agent -behavior enable passive, sensor/interface/VLAN- scoped observations. Capture defaults to

/Behavior.json

; agents use the user-config netcap/behavior// directory. Select an existing baseline explicitly with -behavior-baseline .

./net capture -read traffic.pcap -out capture -behavior -http localhost:8080
./net capture -iface en0 -out live -behavior -behavior-sensor office-router

| Contract | Behavior | | --- | --- | | Discovery | ARP/DHCP/NDP device bindings, TCP SYN service edges, DNS queries/resolvers and authoritative DHCP/IPv6 router-advertisement prefixes; -behavior-prefix supplies configured CIDRs | | Learning | Defaults to 7 days of capture-time coverage and 100 observations; -behavior-learning and -behavior-min-samples tune the criteria | | Approval | GET /api/behavior returns the snapshot; POST /api/behavior/change takes {action, ids, reason, version} for approve, pause, resume, relearn, reset, acknowledge, approve-changes, suppress or unsuppress; acknowledgement retains reviewed fact IDs/reason without changing trust, suppression or dedup | | Monitoring | Unknown facts remain candidates; approval creates a new baseline version. Alerts include the expected/observed fact and original baseline identity in MatchedRecord | | Bounds | -behavior-max-facts defaults to 10,000; overflow is visible and prevents approving incomplete learning | | Persistence | Atomic checkpoints every second and on shutdown; a single-writer file lock prevents concurrent baseline mutation | | Alerts | Alert.ncap.gz is appended and synced per alert, readable before capture finishes; malformed history is rejected without overwriting it | | Live API | GET /api/alerts/stream emits SSE alerts with durable-history cursors; reconnect using Last-Event-ID. At most 8 readers; slow-client write deadline 10 s; replacement/truncation produces a gap | | Health | /api/behavior/health and Coverage and health show observed sensor/interface/VLAN scopes, admitted packets/queue occupancy/drop counts, detector/storage errors, baseline/history bytes and agent ACK/pending/rejected/dropped batches. BehaviorHealth.json (schema 1, ≤64 KiB) retains the last sample at shutdown; unsupported counters remain null. Linux packet-socket kernel deltas accumulate with their sample timestamp; libpcap kernel counters are currently unavailable | | WebUI | /behavior provides scoped inventory, candidates, explicit baseline decisions, evidence pivots, decision history and a bounded live feed; Device/Host/Connection details show labels, services, peers, country/ASN context and prefix-relative direction through /api/behavior/asset, then link to /behavior?asset=

NETCAP_BEHAVIOR_BROWSER=1 go test -race ./cmd/capture/webui -run '^TestBehavioralBrowserDelivery$' -count=1 -timeout 120s
NETCAP_BEHAVIOR_PRESSURE=1 go test ./internal/collector -run '^TestBehavioralCollectorPressure$' -count=1 -timeout 90s

net investigate flows --read Connection.ncap.gz \
  --start-ns "$START_NS" --end-ns "$END_NS" \
  --filter 'InSubnet(SrcIP, "192.0.2.0/24")' --group-by srcIP
net investigate packet-evidence --read exercise.pcapng \
  --bpf 'host 192.0.2.1 and tcp port 80' --out evidence.zip
net investigate collect-flows --listen 127.0.0.1:2055 --out ./fresh-output --duration 1m
net investigate exported-flows --read ./fresh-output/FlowExports.jsonl \
  --exporter 192.0.2.10:50000 --format netflow-v9 --domain 7 \
  --start-ns "$START_NS" --end-ns "$END_NS" --time-basis receive