pktscope 0.2.0

A Wireshark-style terminal packet analyzer — lightweight, keyboard-driven, scriptable Wireshark alternative for the terminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

use std::path::PathBuf;

use clap::{Parser, Subcommand};

#[derive(Parser, Debug)]
#[command(
    name = "pktscope",
    version,
    about = "A Wireshark-style terminal packet analyzer"
)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Command,
}

#[derive(Subcommand, Debug)]
pub enum Command {
    /// List available network interfaces
    ListInterfaces,

    /// Capture packets from a live interface
    Capture {
        /// Network interface to capture on (defaults to capture.default_interface in config)
        #[arg(short, long)]
        interface: Option<String>,

        /// BPF capture filter (applied at libpcap level)
        #[arg(short, long)]
        filter: Option<String>,

        /// Save captured packets to a pcap file
        #[arg(short, long)]
        write: Option<PathBuf>,

        /// Write in PCAPNG format instead of classic pcap (with -w)
        #[arg(long)]
        pcapng: bool,

        /// Output as JSON lines instead of TUI
        #[arg(long)]
        json: bool,

        /// Snap length (max bytes per packet captured)
        #[arg(short, long, default_value_t = 65535)]
        snaplen: i32,

        /// Maximum number of packets to keep in memory
        #[arg(long, default_value_t = 100_000)]
        buffer_size: usize,

        /// Stop after capturing this many packets (one-shot mode)
        #[arg(short = 'c', long)]
        count: Option<u64>,

        /// Stop after this many seconds
        #[arg(short = 'G', long)]
        duration: Option<u64>,
    },

    /// Read and analyze packets from a pcap file
    Read {
        /// Path to the pcap file
        file: PathBuf,

        /// BPF display filter
        #[arg(short, long)]
        filter: Option<String>,

        /// Output as JSON lines instead of TUI
        #[arg(long)]
        json: bool,

        /// Maximum number of packets to keep in memory
        #[arg(long, default_value_t = 100_000)]
        buffer_size: usize,
    },

    /// Always-on egress monitor daemon (capture → correlate → detect → alert)
    Monitor {
        #[command(subcommand)]
        action: MonitorAction,
    },

    /// Attach the inspector TUI to a running egress monitor daemon
    Inspect {
        /// Runtime state directory (used to locate the daemon socket)
        #[arg(long)]
        state_dir: Option<PathBuf>,

        /// Override the daemon socket path directly
        #[arg(long)]
        socket: Option<PathBuf>,

        /// One-shot: print status + live connections + recent alerts as JSON and exit
        #[arg(long)]
        json: bool,
    },

    /// Diff two pcap files by packet content
    Diff {
        /// First pcap file
        file_a: PathBuf,
        /// Second pcap file
        file_b: PathBuf,
    },
}

#[derive(Subcommand, Debug)]
pub enum MonitorAction {
    /// Run the monitor (foreground unless --daemonize)
    Run {
        /// Network interface to capture on
        #[arg(short, long)]
        interface: String,

        /// BPF capture filter
        #[arg(short, long)]
        filter: Option<String>,

        /// Snap length
        #[arg(long, default_value_t = 65535)]
        snaplen: i32,

        /// Override the runtime state directory (db/socket/pidfile)
        #[arg(long)]
        state_dir: Option<PathBuf>,

        /// Offline country .mmdb (DB-IP Lite); see scripts/fetch-geoip.sh
        #[arg(long)]
        geoip_country_db: Option<PathBuf>,

        /// Offline ASN .mmdb (DB-IP Lite)
        #[arg(long)]
        geoip_asn_db: Option<PathBuf>,

        /// Short (5s) learning window so all signals fire quickly
        #[arg(long)]
        demo: bool,

        /// Detach into the background (double-fork)
        #[arg(long)]
        daemonize: bool,

        /// Disable desktop notifications (log only)
        #[arg(long)]
        no_notify: bool,
    },

    /// Show the running daemon's status
    Status {
        #[arg(long)]
        state_dir: Option<PathBuf>,
        /// Emit JSON
        #[arg(long)]
        json: bool,
    },

    /// Ask the running daemon to stop
    Stop {
        #[arg(long)]
        state_dir: Option<PathBuf>,
    },
}