mshark

README

mShark - Mini Wireshark written in Go

Installation

Download release from Releases Page.

Or install using go install (requires Go 1.23+ but may work with older versions):

CGO_ENABLED=0 go install -ldflags "-s -w" -trimpath github.com/shadowy-pycoder/mshark/cmd/mshark@latest

This will install the mshark binary to your $GOPATH/bin directory.

If you are getting a Permission denied error when running mshark, try running

sudo setcap cap_net_raw+ep ~/go/bin/mshark

Usage

mshark -h

                ______   __                            __
               /      \ |  \                          |  \
 ______ ____  |  $$$$$$\| $$____    ______    ______  | $$   __
|      \    \ | $$___\$$| $$    \  |      \  /      \ | $$  /  \
| $$$$$$\$$$$\ \$$    \ | $$$$$$$\  \$$$$$$\|  $$$$$$\| $$_/  $$
| $$ | $$ | $$ _\$$$$$$\| $$  | $$ /      $$| $$   \$$| $$   $$
| $$ | $$ | $$|  \__| $$| $$  | $$|  $$$$$$$| $$      | $$$$$$\
| $$ | $$ | $$ \$$    $$| $$  | $$ \$$    $$| $$      | $$  \$$\
 \$$  \$$  \$$  \$$$$$$  \$$   \$$  \$$$$$$$ \$$       \$$   \$$

Packet Capture Tool by shadowy-pycoder

GitHub: https://github.com/shadowy-pycoder/mshark

Usage: mshark [OPTIONS]
Options:
  -h    Show this help message and exit.
  -D    Display list of interfaces and exit.
  -b int
        The maximum size of packet queue. (default 8192)
  -c int
        The maximum number of packets to capture.
  -e string
        BPF filter expression. Example: "ip proto tcp"
  -f value
        File extension(s) to write captured data. Supported formats: stdout, txt, pcap, pcapng
  -i string
        The name of the network interface. Example: eth0 (default "any")
  -p    Promiscuous mode. This setting is ignored for "any" interface. Defaults to false.
  -s int
        The maximum length of each packet snapshot. Defaults to 65535.
  -t duration
        The maximum duration of the packet capture process. Example: 5s
  -v	Display full packet info when capturing to stdout or txt.

Example

mshark -p -f=txt -f=stdout -f=pcapng -i eth0 -e="port 53"

The above command will capture packets containing port 53 (assumed to be DNS queries) from the eth0 interface and write the captured data to stdout, txt, and file in pcapng format. Files are created in the current working directory.

Output:

- Interface: eth0
- Snapshot Length: 65535
- Promiscuous Mode: true
- Timeout: 0s
- Number of Packets: 0
- Packet Buffer Size: 8192
- BPF Filter: "port 53"
- Verbose: false

With -v flag enabled, you will see more detailed information:

Supported layers

• Ethernet
• IPv4
• IPv6
• ARP
• ICMP
• ICMPv6
• TCP
• UDP
• DNS
• HTTP
• SNMP
• FTP
• SSH
• TLS

Roadmap

• Online packet capture to stdout, txt, pcap and pcapng files
• Offline packet capture from pcap and pcapng files
• Add proper parsing for SNMP messages
• Add packet generation and packet injection functionality

Documentation

Overview

Package mshark is a simple packet capture tool

Index

• func InterfaceByName(name string) (*net.Interface, error)
• func OpenLive(conf *Config, pw ...PacketWriter) error
• type Config
• type PacketWriter
• type Writer
  • func NewWriter(w io.Writer, verbose bool) *Writer
  • func (mw *Writer) WriteHeader(c *Config) error
  • func (mw *Writer) WritePacket(timestamp time.Time, data []byte) error

Functions

func InterfaceByName

func InterfaceByName(name string) (*net.Interface, error)

InterfaceByName returns the interface specified by name.

func OpenLive

func OpenLive(conf *Config, pw ...PacketWriter) error

OpenLive opens a live capture based on the given configuration and writes all captured packets to the given PacketWriters.

Types

type Config

type Config struct {
	Device       *net.Interface // The name of the network interface ("any" means listen on all interfaces).
	Snaplen      int            // The maximum length of each packet snapshot.
	Promisc      bool           // Promiscuous mode. This setting is ignored for "any" interface.
	Timeout      time.Duration  // The maximum duration of the packet capture process.
	PacketCount  int            // The maximum number of packets to capture.
	PacketBuffer int            // The maximum size for packet buffer (Default: 8192)
	Expr         string         // BPF filter expression.
}

type PacketWriter

type PacketWriter interface {
	WritePacket(timestamp time.Time, data []byte) error
}

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

func NewWriter

func NewWriter(w io.Writer, verbose bool) *Writer

NewWriter creates a new mshark Writer.

func (*Writer) WriteHeader

func (mw *Writer) WriteHeader(c *Config) error

WriteHeader writes a header to the writer.

The header contains metadata about the capture, such as the interface name, snapshot length, promiscuous mode, timeout, number of packets, and BPF filter.

The header is written in the following format:

• Interface: eth0
• Snapshot Length: 65535
• Promiscuous Mode: true
• Timeout: 5s
• Number of Packets: 0
• Packet Buffer Size: 8192
• BPF Filter: "ip proto tcp"
• Verbose: true

func (*Writer) WritePacket

func (mw *Writer) WritePacket(timestamp time.Time, data []byte) error

WritePacket writes a packet to the writer, along with its timestamp.

Timestamps are to be generated by the calling code.