Package: picosnitch
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🌍 Web and terminal interfaces with GeoIP lookups for each connection (IP Geolocation by DB-IP)🛡️ Can optionally check hashes or executables usingVirusTotal🚀 Executable hashes are cached based on device + inode for improved performance🐳 Detects applications running inside containers, multiple versions of the same app are differentiated based on their hash🕵️ UsesBPFforaccurate, low overhead bandwidth monitoringandfanotifyto 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🧰 Pragmatic and minimalist design focusing onaccurate detection with clear and reliable error reporting when it isn't possibleInstallationAURfor Arch and derivativesDetailsinstallpicosnitchmanuallyor using your preferredAUR helperPPAfor Ubuntu and derivativesDetailssudo add-apt-repository ppa:elesiuta/picosnitchsudo apt updatesudo apt install picosnitchoptionally installdashwithpiporpipxsudo apt install pipxpipx install dashyou may require a newer version ofBCC(unofficial PPA) since the version in theUbuntu repossometimes lags behind itssupported kernelOBSfor Debian and derivativesDetailsvisit theOBS picosnitch pageand follow the instructions for your distributionoptionally installdashwithpiporpipxsudo apt install pipxpipx install dashif you're having issues on bullseye, you may need a newer version ofBCCOBSfor openSUSE Tumbleweed and derivativesDetailssudo zypper addrepo https://download.opensuse.org/repositories/home:elesiuta/openSUSE_Tumbleweed/home:elesiuta.reposudo zypper refreshsudo zypper install picosnitchCoprfor Fedora, Mageia, Mandriva, and derivativesDetailssudo dnf copr enable elesiuta/picosnitchsudo dnf install picosnitchoptionally installdashwithpiporpipxsudo dnf install pipxpipx install dashNixpkgsfor NixDetailsinstall and enable using thepicosnitch service optionaddservices.picosnitch.enable = true;to your Nix configuration file (typically/etc/nixos/configuration.nix)runsudo nixos-rebuild switchworkaround for "Failed to compile BPF module"systemctl stop picosnitchsudo picosnitch start-no-daemonthen send SIGINT (ctrl + c)systemctl start picosnitchPyPIfor any Linux distribution with Python >= 3.8Detailsinstall theBPF Compiler Collectionpython package for your distributionit should be calledpython-bccorpython-bpfccinstall picosnitch usingpiporpipxpipx install "picosnitch[full]"create a service file for systemd to run picosnitch (recommended)picosnitch systemdoptional dependencies (will install fromPyPIwith[full]if not already installed)for dash:dash,pandas, andplotlyfor dash themes:dash-bootstrap-componentsanddash-bootstrap-templatesfor GeoIP lookups:geoip2for notifications:dbus-python,python-dbus, orpython3-dbus(name depends on your distro and should be installed from their repo)for sql server: one ofpsycopg,pymysql,mariadb, orpsycopg2(latter two not included with[full])for VirusTotal:requestsGitHubfor installing from sourceDetailsclone the repo or downloadpicosnitch.pyandsetup.pyinstall theBPF Compiler Collectionpython package for your distributionit should be calledpython-bccorpython-bpfccinstallpsutilinstallpython-setuptoolsinstall picosnitch withpython setup.py install --usersee other options withpython setup.py [build|install] --helpyou can also run the scriptpicosnitch.pydirectlyUsageRunning picosnitchenable/disable autostart on reboot withsystemctl enable|disable picosnitchstart/stop/restart withsystemctl start|stop|restart picosnitchor if you don't use systemdpicosnitch start|stop|restartWeb user interface for browsing past connectionsstart withpicosnitch dashvisithttp://localhost:5100(you change this by setting the environment variablesHOSTandPORT)Terminal user interface for browsing past connectionsstart withpicosnitch viewspace/enter/f: filter on entrye: exclude entrybackspace/F/E: remove filterh/H: step through history (time offset)t/T: cycle time rangeu/U: cycle byte unitsr: refresh viewq: quitShow usage withpicosnitch helpConfigurationConfig is stored in~/.config/picosnitch/config.jsonrestart picosnitch if it is currently running for any changes to take effect{"DBretention(days)":30,# How many days to keep connection logs in snitch.db"DBsqllog":true,# Write connection logs to snitch.db (SQLite)"DBsqlserver":{},# Write connection logs to a MariaDB, MySQL, or PostgreSQL server"DBtextlog":false,# Write connection logs to conn.log"DBwritelimit(seconds)":10,# Minimum time between connection log entries# increasing it decreases disk writes by grouping traffic into larger time windows# reducing time precision, decreasing database size, and increasing hash latency"Dashscrollzoom":true,# Enable scroll zooming on plots"Dashtheme":"",# Select a theme name from https://bootswatch.com/# requires installing https://pypi.org/project/dash-bootstrap-components/# and https://pypi.org/project/dash-bootstrap-templates/ with pip or pipx"Desktopnotifications":true,# Try connecting to dbus to show notifications"Everyexe(notjustconns)":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"GeoIPlookup":true,# GeoIP lookup of IP addresses in user interface (terminal and web)"Logaddresses":true,# Log remote addresses for each connection"Logcommands":true,# Log command line args for each executable"Logignore":[],# List of hashes (str), domains (str), IP subnets (str), or ports (int)# will omit connections that match any of these from the connection log# domains are in reverse domain name notation and will match all subdomains# the process name, executable, and hash will still be recorded in record.json"Logports":true,# Log local and remote ports for each connection"Perfringbuffer(pages)":256,# Power of two number of pages for BPF program# only change this if it is giving you errors (e.g. missed events)# picosnitch opens a perf buffer for each event type, so this is multiplied by up to 18"SetRLIMIT_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"Setst_devmask":null,# Mask device number for open file descriptors (int)# set to 0 to disable verification if it is giving you errors (e.g. FD cache errors)# defaults to 0 if a btrfs partition is detected, otherwise 0xffffffff"VTAPIkey":"",# API key for VirusTotal, leave blank to disable (str)"VTfileupload":false,# Upload file if hash not found, only hashes are used by default"VTrequestlimit(seconds)":15# Number of seconds between requests (free tier quota)}LoggingA log of seen executables is stored in~/.config/picosnitch/exe.logthis is a history of your notificationsA record of seen executables is stored in~/.config/picosnitch/record.jsonthis is used for determining whether to create a notificationit contains known process name(s) by executable, executable(s) by process name, and sha256 hash(es) with VirusTotal results by executableEnableDB sql log(default) to write the full connection log to~/.config/picosnitch/snitch.dbthis is used forpicosnitch dash,picosnitch view, or something likeDB Browsernote, connection times are based on when the group is processed, so they are accurate to withinDB write limit (seconds)at best, and could be delayed if the previous group is slow to hashnotifications are handled by a separate subprocess, so they are not subject to the same delays as the connection logUseDB sql serverto write the full connection log to a MariaDB, MySQL, or PostgreSQL serverthis is independent ofDB sql logand is used for providing anoff-system copy to prevent tampering(useGRANTto assign privileges and seelimitationsfor other caveats)to configure, add the keyclienttoDB sql serverwith valuemariadb,psycopg,psycopg2, orpymysql, you can also optionally settable_nameassign remaining connection parameters formariadb,psycopg, orpymysqltoDB sql serveras key/value pairsEnableDB text logto write the full connection log to~/.config/picosnitch/conn.logthis may be useful for watching with another programit contains the following fields, separated by commas (commas, newlines, and null characters are removed from values)entry time, sent bytes, received bytes, executable path, process name, cmdline, sha256, parent executable, parent name, parent cmdline, parent sha256, user id, local port, remote port, local address, remote address, domainThe error log is stored in~/.config/picosnitch/error.logerrors 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 hashedwhile it is very unlikely for processes/connections to be missed (unlessEvery 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 happenedfor most people in most cases, this should raise suspicion that a program may be misbehavinga program should not be able to hide from picosnitch (either by omission or spoofing another program) without picosnitch reporting an errorseelimitationsbelow for other sources of errorsLimitationsDespite focusing on reliability and notable advantages overexisting tools, picosnitch still has some limitations depending on its use caseWhen used as a security/auditing tool, a program with sufficient privileges might alter picosnitch or its logs, or employ alternative communication mechanisms not monitored by picosnitch and potentially invisible to the kernel, some mitigations includeuseDB sql serverto maintain anoff-system copy of your logscross-checking with astandalone router/firewallto ensure all communication is accounted forusesandboxingsuch asflatpakDetecting open sockets and identifying the process is very reliable withBPF; however, the executable name and path could be ambiguous or spoofed if malicious, as a countermeasure, picosnitch hashes the executable to provide a reliable identifieronly the process executable itself is hashed, leaving out shared libraries (e.g. LD_PRELOAD rootkits), extensions, or scripts which could become compromisedsome possible mitigations include using animmutable OSor tools such asAIDE,fs-verity,IMA/EVM, ordebsums (with caveats)for extremely short-lived processes, picosnitch may not be able to open a file descriptor in time in order to hash it (this is rare)the device and inode of the opened file descriptor are checked against what was reported by the BPF program to detect if the executable was replaced; however, BTRFS uses non-unique inodes, negating this protection (a negligible issue mentioned for completeness)if hashing the executable fails for any reason, the traffic will still be logged with all available information, accompanied by an error notificationA large influx of new processes or connections may lead to some missed log entries as picosnitch preserves system traffic latency rather than impeding it to catch up with processing event callbackssuch incidents will be detected, logged as an error, and you will be notifiedyou can mitigate this by increasingPerf ring buffer (pages)In addition to bugs, please report any other limitations that may have been missed!