Protect your privacy, see which applications make network connections
Project description
picosnitch
- Receive notifications whenever a new program connects to the network, or when it's modified
- Monitors your bandwidth, breaking down traffic by executable, hash, parent, domain, port, or user over time
- Can optionally check hashes or executables using VirusTotal
- Executable hashes are cached based on device + inode for improved performance, and works with applications running inside containers
- Uses BPF for accurate, low overhead bandwidth monitoring and fanotify to watch executables for modification
- Since applications can call others to send/receive data for them, the parent executable and hash is also logged for each connection
- Focus is on monitoring and detection, and doing that well, this is not a firewall since that would increase complexity, impact performance, and can't be done as securely as sandboxing with something such as firejail, flatpak, or a virtual machine
- Even though executables are hashed, they may still be compromised via shared libraries, if this is a concern you may want to see other host-based intrusion detection systems (HIDS) such as AIDE or something like debsums (with caveats)
- Inspired by programs such as GlassWire, Little Snitch, and OpenSnitch
installation
PPA for Ubuntu and derivatives
sudo add-apt-repository ppa:elesiuta/picosnitch
sudo apt update
sudo apt install picosnitch
- extra dependencies for dash (optional): dash, pandas, and plotly
AUR for Arch and derivatives
- install
picosnitch
manually or using your preferred AUR helper
PyPI for any Linux distribution with Python >= 3.8
- install the BPF Compiler Collection python package for your distribution
- it should be called
python-bcc
orpython-bpfcc
- it should be called
- install picosnitch using pip
pip3 install "picosnitch[full]" --upgrade --user
- create a service file for systemd to run picosnitch (recommended)
picosnitch systemd
- optional dependencies (should already be installed or install automatically)
usage
- running picosnitch
- enable/disable autostart on reboot with
systemctl enable|disable picosnitch
- start/stop/restart with
systemctl start|stop|restart picosnitch
- or if you don't use systemd
picosnitch start|stop|restart
- enable/disable autostart on reboot with
- web user interface for browsing past connections
- start with
picosnitch dash
- visit http://localhost:8050
- start with
- terminal user interface for browsing past connections
- start with
picosnitch view
space/enter
: filter on entrybackspace
: remove filterh/H
: cycle through historyt/T
: cycle time rangeu/U
: cycle byte unitsr
: refresh viewq
: quit
- start with
- show usage with
picosnitch help
configuration
- config is stored in
~/.config/picosnitch/config.json
- restart picosnitch if it is currently running for any changes to take effect
{
"Bandwidth monitor": true, # Log traffic per connection since last db write
"DB retention (days)": 365, # How many days to keep connection logs in snitch.db
"DB sql log": true, # Write connection logs to snitch.db
"DB text log": false, # Write connection logs to conn.log
"DB write limit (seconds)": 10, # Minimum time between writing connection logs
# increasing it decreases disk writes by grouping connections into larger time windows
# reducing time precision, decreasing database size, and increasing hash latency
"Desktop notifications": true, # Try connecting to dbus to show notifications
"Every exe (not just conns)": false, # Check every running executable with picosnitch
# these are treated as "connections" with a port of -1
# this feature is experimental but should work fairly well, errors should be expected as
# picosnitch is unable to open file descriptors for some extremely short-lived processes
# if you just want logs (no hashes) to trace process hierarchy, see execsnoop or forkstat
"Log addresses": true, # Log remote addresses for each connection
"Log commands": true, # Log command line args for each executable
"Log ignore": [], # List of hashes (str), domains (str), or ports (int)
# will omit connections that match any of these from the connection log
# domains will match any that start with the provided string, hashes or ports are exact
# the process name, executable, and hash will still be recorded in record.json
"Set RLIMIT_NOFILE": null, # Set the maximum number of open file descriptors (int)
# it is used for caching process executables and hashes (typical system default is 1024)
# this is good enough for most people since caching is based on executable device + inode
# fanotify is used to detect if a cached executable is modified to trigger a hash update
"VT API key": "", # API key for VirusTotal, leave blank to disable (str)
"VT file upload": false, # Upload file if hash not found, only hashes are used by default
"VT request limit (seconds)": 15 # Number of seconds between requests (free tier quota)
}
logging
- a log of seen executables is stored in
~/.config/picosnitch/exe.log
- this is a history of your notifications
- a record of seen executables is stored in
~/.config/picosnitch/record.json
- this is used for determining whether to create a notification
- it contains known process name(s) by executable, executable(s) by process name, and sha256 hash(es) with VirusTotal results by executable
- the full connection log is stored in
~/.config/picosnitch/snitch.db
- this is used for
picosnitch dash
,picosnitch view
or something like DB Browser - note, connection times are based on when the group is processed, so they are accurate to within
DB write limit (seconds)
at best, and could be delayed if the previous group is slow to hash - notifications are handled by a separate subprocess, so they are not subject to the same delays as the connection log
- this is used for
- if
DB text log
is enabled, the full connection log is also written to~/.config/picosnitch/conn.log
- this may be useful for watching with another program
- it contains the following fields, separated by commas (commas, newlines, and null characters are removed from values)
executable,name,cmdline,sha256,time,domain,ip,port,uid,parent_exe,parent_name,parent_cmdline,parent_sha256,conns,sent,received
- the error log is stored in
~/.config/picosnitch/error.log
- errors will also trigger a notification and are usually caused by far too many or extremely short-lived processes/connections, or suspending your system while a new executable is being hashed
- while it is very unlikely for processes/connections to be missed (unless
Every exe (not just conns)
is enabled), picosnitch was designed such that it should still detect this and log an error giving you some indication of what happened - for most people in most cases, this should raise suspicion that a program may be misbehaving
building from source
- install dependencies listed under installation
- install
python-setuptools
- install picosnitch with
python setup.py install --user
- see other options with
python setup.py [build|install] --help
- you can also run the script
picosnitch.py
directly
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
picosnitch-0.11.0.tar.gz
(39.8 kB
view hashes)
Built Distribution
Close
Hashes for picosnitch-0.11.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1fbc20a450736916e23c9fc9a24ed8fbff0f7914326a90657621b9d5440c2dde |
|
MD5 | 2a37c6bba3c013ceb7cf9d6a06b98508 |
|
BLAKE2b-256 | 021eeca5b16253d1983327971e0594802cd4ba1f21e77b6965b264b461439ab6 |