Awesome

histstat (+)

NOTE - This is a fork of vesche/histstat and you cannot use `pip install <package_name>` to install. See below for details.

Special notes on this fork

This version has implemented the following features:

Utilize IP2Location to add geolocation information to output

Filtering content using a SQL Where like syntax

see --filter param

example: --filter "(command like '%/firefox/%' and country in ('US', 'CA'))"

Will only show content from processes with /firefox/ in cmd path and country of remote IP is USA or Canada

Full list of fields available to query:

Field	DType	Example	Note
date	datetime	-	Can use '2022-04-13' -or- '22-04-13 13:44:54'
time	datetime.time	-	Use '14:45:32'
interface	str	tun0	-
protocol	str	tcp6	Available: tcp, udp, tcp6, udp6
laddr	str	192.168.101.108	-
lport	int	40512	-
raddr	str	23.77.80.28	-
rport	int	443	-
country	str	US	https://en.wikipedia.org/wiki/ISO_3166-1
continent	str	NA	""
status	str	ESTABLISHED	-
user	str	jsd	-
pid	int	2960983	-
procname	str	firefox	-
command	str	/usr/lib/firefox/firefox -contentproc -childID 2444
parents	str	(1) /sbin/init -> (6810) /lib/systemd/systemd --user -> (2960002) /usr/lib/firefox/firefox -no-remote --ProfileManager	-

For query syntax, see: https://pypi.org/project/whereval/

Output to Sqlite DB
- see --sqlite param
Add country / continent redlist/whitelist for marking output as red in console as specified
- Applicable params: --ip2ldb, --rcountry, --rcontinent, --wcountry
- All are comma separated country abbreviations. Continents can be full names.
Flush mode - Flushes stdout on each process run
- see --flush param
Quite mode - Only operational information
- see --quiet param
Limit command column length in output in output
- see --cmdmax param

To use geolocating features in this version, you must get a copy of the IP2Location LITE bin file and locate some location on your computer. The path must be provided in --ip2ldb param

This is a cross-platform command-line tool for obtaining live, rudimentary network connection data on a computer system. This tool was designed for network and security analysts to easily view connections on a system as they occur. It will display useful information about network connections that utilities like netstat typically won't give you such as what time the connection was made, the exact command that created the connection, and the user that connection was made by.

Note for Windows users: Detailed process information will not display unless you're running as NT AUTHORITY\SYSTEM. An easy way to drop into a system-level command prompt is to use PsExec from SysInternals. Run psexec -i -s cmd.exe as Administrator and then run histstat.

Install

Download this repo as zip and unzip to a temp directory
cd to the temp directory
run:

python -m pip install .

On *nix, make available for sudo

After install, get path to histstat script

which histstat

Create Symlink for root

sudo ln -s <full_path_to_histstat> /bin/histstat

Example Usage

$ histstat --help
usage: histstat.py [-h] [-i INTERVAL] [-l LOG] [-p] [-j] [-F] [-q] [-v]
                   [-I INTERFACES] [-m CMDMAX] [-r RCOUNTRY] [-w WCOUNTRY]
                   [-c RCONTINENT] [-g IP2LDB] [-s SFILTER] [-A FLADDR]
                   [-S SQLITE] [-Q QUIT]

history for netstat

optional arguments:
  -h, --help            show this help message and exit
  -i INTERVAL, --interval INTERVAL
                        specify update interval in seconds
  -l LOG, --log LOG     log output to a text file
  -p, --prettify        prettify output
  -j, --json            json output
  -F, --flush           flush output of log file after each interval
  -q, --quiet           do not output to stdout. Only valid if --log is set
  -v, --version         display the current version
  -g IP2LDB, --ip2ldb IP2LDB
                        Path to IP2Location DB file
  -f FILTER, --filter FILTER
                        Filter records using sql like where clause. See readme.md for details
  -S SQLITE, --sqlite SQLITE
                        Store output in SQLite DB
  -m CMDMAX, --cmdmax CMDMAX
                        Maximum command length
  -r RCOUNTRY, --rcountry RCOUNTRY
                        Comma separated list of country codes to flag as red.
                        See https://en.wikipedia.org/wiki/ISO_3166-1
  -w WCOUNTRY, --wcountry WCOUNTRY
                        Comma separated list of country codes that are
                        whitelisted. Only applicable if --rcontinent is used.
                        See https://en.wikipedia.org/wiki/ISO_3166-1
  -c RCONTINENT, --rcontinent RCONTINENT
                        Comma separated list of continent codes to flag as red
  -Q QUIT, --quit QUIT  Quit after n minutes

Output example

(pardon the prefix which was added to simulate the red text)

$ sudo histstat -p --ip2ldb ~/.IP2Location/IP2L.BIN --rcontinent AS,OC,SA,AF --wcountry AU,NZ --rcountry PL,HU,TR --cmdmax 20 --interfaces tun*,wls*

# date     time     proto laddr           lport raddr           rport country         cn status      user       pid     pname                command
# 20-12-05 14:35:47 tcp   192.168.101.118 47396 167.172.147.116 443   United States   NA ESTABLISHED tquinn     1583741 firefox              /usr/lib/firefox/fir...
# 20-12-05 14:35:47 tcp   192.168.101.118 47027 72.251.238.254  443   United States   NA ESTABLISHED -          -       -                    -
# 20-12-05 14:35:47 tcp   192.168.101.118 60249 72.251.238.254  443   United States   NA ESTABLISHED -          -       -                    -
# 20-12-05 14:35:47 tcp   192.168.101.118 52222 104.42.78.153   443   United States   NA ESTABLISHED tquinn     2403251 code                 /usr/share/code/code...
# 20-12-05 14:35:47 tcp   192.168.101.118 51032 104.98.196.29   443   United States   NA CLOSE_WAIT  tquinn     202962  vmware               /usr/lib/vmware/bin/...
# 20-12-05 14:35:47 tcp   192.168.101.118 40242 151.101.194.133 443   United States   NA ESTABLISHED tquinn     2148690 chrome               /opt/google/chrome/c...
- 20-12-05 14:35:47 tcp   192.168.101.118 45919 103.132.192.30  443   Singapore       AS ESTABLISHED -          -       -                    -
# ...

Thanks

Huge thanks to Giampaolo Rodola' (giampaolo) and all the contributers of psutil for the amazing open source library that this project relies upon completely.

Also, thanks to gleitz and his project howdoi, in my refactor of histstat I modeled my code around his command line tool as the code is exceptionally clean and readable.