Picosnitch

Installation

AUR for Arch and derivatives

PPA for Ubuntu and derivatives

OBS for Debian and derivatives

OBS for openSUSE Tumbleweed and derivatives

Copr for Fedora, Mageia, Mandriva, and derivatives

Nixpkgs for Nix

PyPI for any Linux distribution with Python >= 3.8

GitHub for installing from source

Usage

Configuration

{
  "DB retention (days)": 30, # How many days to keep connection logs in snitch.db
  "DB sql log": true, # Write connection logs to snitch.db (SQLite)
  "DB sql server": {}, # Write connection logs to a MariaDB, MySQL, or PostgreSQL server
  "DB text log": false, # Write connection logs to conn.log
  "DB write limit (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
  "Dash scroll zoom": true, # Enable scroll zooming on plots
  "Dash theme": "", # 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
  "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
  "GeoIP lookup": true, # GeoIP lookup of IP addresses in user interface (terminal and web)
  "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), 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
  "Log ports": true, # Log local and remote ports for each connection
  "Perf ring buffer (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
  "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
  "Set st_dev mask": 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
  "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

Limitations