Skip to content

usage.md

Latest commit

 

History

History
130 lines (83 loc) · 3.21 KB

usage.md

File metadata and controls

130 lines (83 loc) · 3.21 KB

Usage Examples

This page shows common NetScope workflows after initial setup. If you still need to build the binary, install libpcap, or set capture permissions, start with Getting Started. For the full flag list, see CLI Reference. For persistent configuration, see Configuration.

All examples assume the binary is on your PATH as netscope. If you built from source and did not install it, replace netscope with ./target/release/netscope.

Basic Capture

Capture on the default interface (Ctrl-C to stop):

sudo netscope

Capture on a specific interface, limited to 20 packets:

sudo netscope -i en0 -c 20

Capture only HTTP traffic with hex dumps:

sudo netscope -f "tcp port 80" --hex-dump

Throughput Stats

Show periodic throughput stats with the top 5 flows by bandwidth, suppressing per-packet output:

sudo netscope --quiet --stats --top-flows 5

Change the stats interval to 2 seconds:

sudo netscope --quiet --stats --stats-interval-ms 2000 --top-flows 10

Flow Exports

Write packets to pcap and export the flow table on exit:

sudo netscope --write-pcap capture.pcap --export-json flows.json --export-csv flows.csv

See Exports for format details and sample outputs.

Anomaly Detection

Enable anomaly detection and write alerts to a file:

sudo netscope --anomalies --alerts-jsonl alerts.jsonl

Alerts are also printed to stdout. See Anomaly Detection for threshold tuning.

Web Dashboard

Start the web dashboard:

sudo netscope --web

Open http://127.0.0.1:8080. Customize the bind address and port:

sudo netscope --web --web-bind 0.0.0.0 --web-port 9090

Combine with other features:

sudo netscope --web --quiet --anomalies --stats --top-flows 5

See Web Dashboard for full details.

Pipeline Mode

Enable multi-core processing for high-throughput captures:

sudo netscope --pipeline --quiet --stats --top-flows 5

Specify the number of worker threads:

sudo netscope --pipeline --workers 4 --quiet --stats

Pipeline mode with the web dashboard:

sudo netscope --pipeline --web --quiet --anomalies

See Sharded Pipeline for architecture details and tuning.

Configuration File

Use a TOML config file with CLI overrides:

sudo netscope --config netscope.example.toml --no-promiscuous -c 100

CLI flags always override config file values when explicitly provided. See Configuration for the full schema.

Verbosity

Control log output with -v flags:

Flag Level What you see
(none) WARN Warnings and errors only
-v INFO Capture start/stop, interface info
-vv DEBUG Detailed packet output, config resolution
-vvv TRACE Per-packet trace logs, channel drops 
sudo netscope -vv

At -vv and above, NetScope switches to the detailed per-packet CLI view (including the hex-dump preview) even if --hex-dump is not explicitly set.