termshark

README

Termshark

A terminal user-interface for tshark, inspired by Wireshark.

V2.4 is out now with packet search and profiles for colors and columns! See the ChangeLog.

If you're debugging on a remote machine with a large pcap and no desire to scp it back to your desktop, termshark can help!

Features

• Read pcap files or sniff live interfaces (where tshark is permitted)
• Filter pcaps or live captures using Wireshark's display filters
• Reassemble and inspect TCP and UDP flows
• View network conversations by protocol
• Copy ranges of packets to the clipboard from the terminal
• Written in Golang, compiles to a single executable on each platform - downloads available for Linux, macOS, BSD variants, Android (termux) and Windows

tshark has many more features that termshark doesn't expose yet! See What's Next.

Install Packages

Termshark is pre-packaged for the following platforms: Arch Linux, Debian (unstable), FreeBSD, Homebrew, MacPorts, Kali Linux, NixOS, SnapCraft, Termux (Android) and Ubuntu.

Building

Termshark uses Go modules. Set GO111MODULE=on then run:

go install github.com/gcla/termshark/v2/cmd/termshark

For versions of Go between 1.14 and 1.17, use

go get github.com/gcla/termshark/v2/cmd/termshark

Then add ~/go/bin/ to your PATH.

For all packet analysis, termshark depends on tshark from the Wireshark project. Make sure tshark is in your PATH.

Quick Start

Inspect a local pcap:

termshark -r test.pcap

Capture ping packets on interface eth0:

termshark -i eth0 icmp

Run termshark -h for options.

Downloads

Pre-compiled executables are available via Github releases. Or download the latest build from the master branch - .

Documentation

See the termshark user guide, and my best guess at some FAQs. For a summary of updates, see the ChangeLog.

Dependencies

Termshark depends on these open-source packages:

• tshark - command-line network protocol analyzer, part of Wireshark
• tcell - a cell based terminal handling package, inspired by termbox
• gowid - compositional terminal UI widgets, inspired by urwid, built on tcell

Note that tshark is a run-time dependency, and must be in your PATH for termshark to function. Version 1.10.2 or higher is required (approx 2013).

Contributors

Thanks to everyone that's contributed ports, patches and effort!

Ross Jacobs 💻 🐛 📓	Hongarc 📖	Ryan Steinmetz 📦	Nicolai Søborg 📦	Elliott Sales de Andrade 💻	Romanos 💻	Denys 🐛
jerry73204 📦	Jon Knapp 📦	Mario Harjac 📦	Andrew Benson 🐛	sagis-tikal 🐛	punkymaniac 🐛	msenturk 🐛
Sandor Szücs 🐛	Dawid Dziurla 🐛 📦	jJit0 🐛	inzel 🐛	thejerrod 🤔	gdluca 🐛	Patrick Winter 📦
Robert Larsen 🤔 📓	MinJae Kwon 🐛	the-c0d3r 🤔	Gisle Vanem 🐛	hook 🐛	Lennart Koopmann 🤔	Fernandez, ReK2 🐛
mazball 🤔	wfailla 🤔	荣怡 🤔	thebyrdman-git 🐛	Clemens Mosig 🐛	Michael Rash 📓	joelparker 📓
Dragos Maftei 🤔	Matthew Giassa 🤔	Sean Abbott 📦	Vincent Wang 🤔	piping 🤔	kevinhwang91 🤔 🐛	Justin Overfelt 🤔
Anthony 🤔	basondole 🐛	zoulja 🐛	freddii 🐛	Thord Setsaas 📖	deliciouslytyped 🐛	factorion 📦
Herby Gillot 📦	nmeum 🤔	Aaron Bieber 🤔	elig0n 🤔

Contact

• The author - Graham Clark (grclark@gmail.com)

License

Documentation

Index

• Variables
• func AddKeyMapping(km KeyMapping)
• func AddToRecentFiles(pcap string)
• func AddToRecentFilters(val string)
• func ApplyArguments(cmd []string, args []string) ([]string, int)
• func BrowseUrl(url string) error
• func CacheDir() string
• func CacheFile(bin string) string
• func CapinfosBin() string
• func CaptureBin() string
• func ConfFile(file string) string
• func ConvTypes() []string
• func ConvertArgToTShark(arg string) (string, string, bool)
• func CopyCommand(input io.Reader, cb interface{}) error
• func DateStringForFilename() string
• func DefaultPcapDir() string
• func DirOfPathCommand(bin string) (string, error)
• func DirOfPathCommandUnsafe(bin string) string
• func Does256ColorTermExist() error
• func DumpcapBin() string
• func ErrLogger(key string, val string) *io.PipeWriter
• func FileNewerThan(f1, f2 string) (bool, error)
• func FileSizeDifferentTo(filename string, cur int64) (int64, bool)
• func IndentPdml(in io.Reader, out io.Writer) error
• func Interfaces() (map[int][]string, error)
• func IsCommandInPath(bin string) bool
• func IsTerminal(fd uintptr) bool
• func KeyPressIsPrintable(key gowid.IKey) bool
• func KeyValueErrorString(err gowid.KeyValueError) string
• func KillIfPossible(p IProcess) error
• func LoadGlobalMarks(m map[rune]GlobalJumpPos) error
• func LoadOffsetFromConfig(name string) ([]resizable.Offset, error)
• func LocalIPs() []string
• func PcapDir() string
• func PrivilegedBin() string
• func ProfileCPUFor(secs int) bool
• func ProfileHeap()
• func PrunePcapCache() error
• func ReadGob(filePath string, object interface{}) error
• func RemoveFromStringSlice(pcap string, comps []string) []string
• func RemoveKeyMapping(kp vim.KeyPress)
• func ReverseStringSlice(s []string)
• func RootCause(err error) error
• func RunForExitCode(prog string, args []string, env []string) (int, error)
• func RunForStderr(prog string, args []string, env []string, stderr io.Writer) (int, error)
• func RunOnDoubleTicker(ch <-chan struct{}, fn func(), dur1 time.Duration, dur2 time.Duration, ...)
• func RunningRemotely() bool
• func SafePid(p IProcess) int
• func SaveGlobalMarks(m map[rune]GlobalJumpPos)
• func SaveKeyMappings(mappings []KeyMapping)
• func SaveOffsetToConfig(name string, offsets2 []resizable.Offset)
• func SetConvTypes(convs []string)
• func StringInSlice(a string, list []string) bool
• func StringIsArgPrefixOf(a string, list []string) bool
• func TSharkBin() string
• func TSharkPath() (string, *gowid.KeyValueError)
• func TSharkSupportsColor(tshark string) (bool, error)
• func TSharkVersion(tshark string) (semver.Version, error)
• func TSharkVersionFromOutput(output string) (semver.Version, error)
• func TailCommand() []string
• func TemplateToString(tmpl *template.Template, name string, data interface{}) string
• func TrackedGo(fn func(), wgs ...*sync.WaitGroup)
• func TsharkSetting(field string) (string, error)
• func TsharkSettings(fields ...string) (map[string]string, error)
• func ValidateTerm(term string) error
• func WiresharkProfileNames() []string
• func WriteEmptyPcap(filename string) error
• func WriteGob(filePath string, object interface{}) error
• type BadCommandError
  • func (e BadCommandError) Error() string
• type BadStateError
  • func (e BadStateError) Error() string
• type ConfigError
  • func (e ConfigError) Error() string
• type ConvPktsCompare
  • func (s ConvPktsCompare) Less(i, j string) bool
• type GlobalJumpPos
  • func (g GlobalJumpPos) Base() string
• type ICommandDone
• type ICommandError
• type ICommandKillError
• type ICommandOutput
• type ICommandTimeout
• type ICommandWaitTicker
• type IPCompare
  • func (s IPCompare) Less(i, j string) bool
• type IProcess
• type InternalError
  • func (e InternalError) Error() string
• type JumpPos
• type KeyMapping
  • func LoadKeyMappings() []KeyMapping
• type KeyState
• type MACCompare
  • func (s MACCompare) Less(i, j string) bool

Variables

var (
	UserGuideURL         string = "https://termshark.io/userguide"
	FAQURL               string = "https://termshark.io/faq"
	BugURL               string = "https://github.com/gcla/termshark/issues/new?assignees=&labels=&template=bug_report.md&title="
	FeatureURL           string = "https://github.com/gcla/termshark/issues/new?assignees=&labels=&template=feature_request.md&title="
	OriginalEnv          []string
	ShouldSwitchTerminal bool
	ShouldSwitchBack     bool
)

var BadCommand = BadCommandError{}

var BadState = BadStateError{}

var ConfigErr = ConfigError{}

var InternalErr = InternalError{}

var TSharkVersionUnknown = fmt.Errorf("Could not determine version of tshark")

var UnexpectedOutput = fmt.Errorf("Unexpected output")

var Version string = "v2.4.0"

Functions

func AddKeyMapping

func AddKeyMapping(km KeyMapping)

func AddToRecentFiles

func AddToRecentFiles(pcap string)

func AddToRecentFilters

func AddToRecentFilters(val string)

func ApplyArguments

func ApplyArguments(cmd []string, args []string) ([]string, int)

ApplyArguments turns ["echo", "hello", "$2"] + ["big", "world"] into ["echo", "hello", "world"]

func BrowseUrl

func BrowseUrl(url string) error

func CacheDir

func CacheDir() string

func CacheFile

func CacheFile(bin string) string

func CapinfosBin

func CapinfosBin() string

func CaptureBin

func CaptureBin() string

CaptureBin is the binary the user intends to use to capture packets i.e. with the -i switch. This might be distinct from DumpcapBin because dumpcap can't capture on extcap interfaces like randpkt, but while tshark can, it can drop packets more readily than dumpcap. This value is interpreted as the name of a binary, resolved against PATH. Note that the default is termshark - this invokes termshark in a special mode where it first tries DumpcapBin, then if that fails, TSharkBin - for the best of both worlds. To detect this, termshark will run CaptureBin with TERMSHARK_CAPTURE_MODE=1 in the environment, so when termshark itself is invoked with this in the environment, it switches to capture mode.

func ConfFile

func ConfFile(file string) string

func ConvTypes

func ConvTypes() []string

func ConvertArgToTShark

func ConvertArgToTShark(arg string) (string, string, bool)

func CopyCommand

func CopyCommand(input io.Reader, cb interface{}) error

func DateStringForFilename

func DateStringForFilename() string

Down to the second for profiling, etc

func DefaultPcapDir

func DefaultPcapDir() string

DefaultPcapDir returns ~/.cache/pcaps by default. Termshark will check a couple of user settings first before using this.

func DirOfPathCommand

func DirOfPathCommand(bin string) (string, error)

func DirOfPathCommandUnsafe

func DirOfPathCommandUnsafe(bin string) string

func Does256ColorTermExist

func Does256ColorTermExist() error

func DumpcapBin

func DumpcapBin() string

func ErrLogger

func ErrLogger(key string, val string) *io.PipeWriter

func FileNewerThan

func FileNewerThan(f1, f2 string) (bool, error)

func FileSizeDifferentTo

func FileSizeDifferentTo(filename string, cur int64) (int64, bool)

Returns true if error, too

func IndentPdml

func IndentPdml(in io.Reader, out io.Writer) error

IndentPdml reindents XML, disregarding content between tags (because we knoe PDML doesn't use that capability of XML)

func Interfaces

func Interfaces() (map[int][]string, error)

Use tshark's output, because the indices can then be used to select an interface to sniff on, and net.Interfaces returns the interfaces in a different order.

func IsCommandInPath

func IsCommandInPath(bin string) bool

func IsTerminal

func IsTerminal(fd uintptr) bool

func KeyPressIsPrintable

func KeyPressIsPrintable(key gowid.IKey) bool

func KeyValueErrorString

func KeyValueErrorString(err gowid.KeyValueError) string

KeyValueErrorString returns a string representation of a gowid KeyValueError intended to be suitable for displaying in a termshark error dialog.

func KillIfPossible

func KillIfPossible(p IProcess) error

func LoadGlobalMarks

func LoadGlobalMarks(m map[rune]GlobalJumpPos) error

func LoadOffsetFromConfig

func LoadOffsetFromConfig(name string) ([]resizable.Offset, error)

func LocalIPs

func LocalIPs() []string

func PcapDir

func PcapDir() string

A separate dir from CacheDir because I need to use inotify under some circumstances for a non-existent file, meaning I need to track a directory, and I don't want to be constantly triggered by log file updates.

func PrivilegedBin

func PrivilegedBin() string

PrivilegedBin returns a capture binary that may require setcap privileges on Linux. This is a simple UI to cover the fact that termshark's default capture method is to run dumpcap and tshark as a fallback. I don't want to tell the user the capture binary is termshark - that'd be confusing. We know that on Linux, termshark will run dumpcap first, then fall back to tshark if needed. Only dumpcap should need access to live interfaces; tshark is needed for extcap interfaces only. This is used to provide advice to the user if packet capture fails.

func ProfileCPUFor

func ProfileCPUFor(secs int) bool

func ProfileHeap

func ProfileHeap()

func PrunePcapCache

func PrunePcapCache() error

func ReadGob

func ReadGob(filePath string, object interface{}) error

func RemoveFromStringSlice

func RemoveFromStringSlice(pcap string, comps []string) []string

func RemoveKeyMapping

func RemoveKeyMapping(kp vim.KeyPress)

func ReverseStringSlice

func ReverseStringSlice(s []string)

func RootCause

func RootCause(err error) error

func RunForExitCode

func RunForExitCode(prog string, args []string, env []string) (int, error)

func RunForStderr

func RunForStderr(prog string, args []string, env []string, stderr io.Writer) (int, error)

func RunOnDoubleTicker

func RunOnDoubleTicker(ch <-chan struct{}, fn func(), dur1 time.Duration, dur2 time.Duration, loops int)

func RunningRemotely

func RunningRemotely() bool

func SafePid

func SafePid(p IProcess) int

func SaveGlobalMarks

func SaveGlobalMarks(m map[rune]GlobalJumpPos)

func SaveKeyMappings

func SaveKeyMappings(mappings []KeyMapping)

func SaveOffsetToConfig

func SaveOffsetToConfig(name string, offsets2 []resizable.Offset)

func SetConvTypes

func SetConvTypes(convs []string)

func StringInSlice

func StringInSlice(a string, list []string) bool

func StringIsArgPrefixOf

func StringIsArgPrefixOf(a string, list []string) bool

func TSharkBin

func TSharkBin() string

func TSharkPath

func TSharkPath() (string, *gowid.KeyValueError)

TSharkPath will return the full path of the tshark binary, if it's found in the path, otherwise an error

func TSharkSupportsColor

func TSharkSupportsColor(tshark string) (bool, error)

Depends on empty.pcap being present

func TSharkVersion

func TSharkVersion(tshark string) (semver.Version, error)

func TSharkVersionFromOutput

func TSharkVersionFromOutput(output string) (semver.Version, error)

func TailCommand

func TailCommand() []string

func TemplateToString

func TemplateToString(tmpl *template.Template, name string, data interface{}) string

Must succeed - use on internal templates

func TrackedGo

func TrackedGo(fn func(), wgs ...*sync.WaitGroup)

func TsharkSetting

func TsharkSetting(field string) (string, error)

$ env TMPDIR=/foo tshark -G folders Temp Temp: /foo Personal configuration: /home/gcla/.config/wireshark Global configuration: /usr/share/wireshark

func TsharkSettings

func TsharkSettings(fields ...string) (map[string]string, error)

func ValidateTerm

func ValidateTerm(term string) error

func WiresharkProfileNames

func WiresharkProfileNames() []string

func WriteEmptyPcap

func WriteEmptyPcap(filename string) error

func WriteGob

func WriteGob(filePath string, object interface{}) error

Types

type BadCommandError

type BadCommandError struct{}

func (BadCommandError) Error

func (e BadCommandError) Error() string

type BadStateError

type BadStateError struct{}

func (BadStateError) Error

func (e BadStateError) Error() string

type ConfigError

type ConfigError struct{}

func (ConfigError) Error

func (e ConfigError) Error() string

type ConvPktsCompare

type ConvPktsCompare struct{}

ConvPktsCompare is a unit type that satisfies ICompare, and can be used for numerically comparing values emitted by the tshark -z conv,... e.g. "2,456 kB"

func (ConvPktsCompare) Less

func (s ConvPktsCompare) Less(i, j string) bool

type GlobalJumpPos

type GlobalJumpPos struct {
	JumpPos
	Filename string `json:"filename"`
}

func (GlobalJumpPos) Base

func (g GlobalJumpPos) Base() string

For ease of use in the template

type ICommandDone

type ICommandDone interface {
	ProcessCommandDone()
}

type ICommandError

type ICommandError interface {
	ProcessCommandError(err error) error
}

type ICommandKillError

type ICommandKillError interface {
	ProcessKillError(err error) error
}

type ICommandOutput

type ICommandOutput interface {
	ProcessOutput(output string) error
}

type ICommandTimeout

type ICommandTimeout interface {
	ProcessCommandTimeout() error
}

type ICommandWaitTicker

type ICommandWaitTicker interface {
	ProcessWaitTick() error
}

type IPCompare

type IPCompare struct{}

IPCompare is a unit type that satisfies ICompare, and can be used for numerically comparing IP addresses.

func (IPCompare) Less

func (s IPCompare) Less(i, j string) bool

type IProcess

type IProcess interface {
	Kill() error
	Pid() int
}

type InternalError

type InternalError struct{}

func (InternalError) Error

func (e InternalError) Error() string

type JumpPos

type JumpPos struct {
	Summary string `json:"summary"`
	Pos     int    `json:"position"`
}

Need to publish fields for template use

type KeyMapping

type KeyMapping struct {
	From vim.KeyPress
	To   vim.KeySequence
}

func LoadKeyMappings

func LoadKeyMappings() []KeyMapping

type KeyState

type KeyState struct {
	NumberPrefix    int
	PartialgCmd     bool
	PartialZCmd     bool
	PartialCtrlWCmd bool
	PartialmCmd     bool
	PartialQuoteCmd bool
}

type MACCompare

type MACCompare struct{}

MacCompare is a unit type that satisfies ICompare, and can be used for numerically comparing MAC addresses.

func (MACCompare) Less

func (s MACCompare) Less(i, j string) bool