termshark 0.1.4

🦈 WireShark in the terminal
Documentation

🦈 TermShark

GitHub License GitHub Workflow Status GitHub Release GitHub Downloads (all assets, all releases) Crates.io Version Crates.io Total Downloads docs.rs

WireShark in the terminal. Note that this is a toy project, with a lot of features missing.

📥 Installation

Prerequisits

  • Linux: Install libpcap-dev on Debian, or libpcap-devel on Fedora.
  • Windows: Install Npcap.
    • If you got an error that looks like "wpcap.dll not found", try to add C:\Windows\System32\Npcap to your PATH and restart your shell.
  • MacOSX: libpcap should already be installed.

Using binstall

cargo binstall termshark

Downloading from Releases

Navigate to the Releases page and download respective binary for your platform. Make sure to give it execute permissions.

Compiling from Source

You'll also need Npcap SDK on Windows.

git clone https://github.com/PRO-2684/termshark.git
cd termshark
cargo build --release
# The binary will be available at ./target/release/termshark

📖 Usage

🚀 Quick Start

sudo ./termshark capture # To capture from default device

Alternatively, you can configure with setcap, if you want to capture without root.

⌨️ Keyboard Control

Navigation

  • ↑/↓ or j/k: Select previous/next packet
  • Page Up/Down: Scroll one page at a time (adaptive to terminal size)
  • Home: Jump to first packet
  • End: Jump to last packet
  • w/s: Scroll packet details panel up/down
  • e/d: Scroll hex dump panel up/down

Filtering

  • Enter: Edit or apply filter
  • Esc: Clear filter input, exit editing or disable filter
  • Arrows, backspace, delete etc.: Edit the filter, see keyevent_to_input_request in event.rs for more details.

Application

  • q or Ctrl+C: Quit the application

🔍 Filter Syntax

The filter uses a GitHub-like syntax, i.e. search terms and key:value pairs:

searchterm protocol:tcp source:192.168.1.1 length:>1000

Supported filters:

  • protocol / proto: Filter by protocol (e.g., tcp, udp, icmp)
  • source / src: Filter by source IP address (exact match)
  • destination / dest / dst: Filter by destination IP address (exact match)
  • length / len: Filter by packet length (supports >, <, ranges)

Examples:

protocol:tcp,udp           # TCP or UDP packets
source:192.168.1.100       # From specific source
protocol:tcp length:>1000  # Large TCP packets
HTTP source:192.168.1.1    # Traffic containing "HTTP" from source

See FILTER_SYNTAX.md for detailed documentation.

▶️ CLI Reference

$ termshark --help
Usage: termshark <command> [<args>]

🦈 WireShark in the terminal.

Options:
  --help, help      display usage information

Commands:
  capture           Capture and inspect packets from a device.
  list              List available devices.
  load              Load and inspect packets from a file.

💡 Demos & Samples

asciicast

Here's a list of sample packets for testing. All of them are taken from WireShark wiki, so feel free to visit it for more.

🎉 Credits

  • pcap for interacting with libpcap
  • argh for command line argument parsing
  • ratatui for TUI