### Install and Enable Service Source: https://elesiuta.github.io/picosnitch Installs picosnitch system-wide using pipx, sets up the systemd service, and enables it to start on boot. ```bash sudo pipx install picosnitch --global sudo picosnitch systemd sudo systemctl enable --now picosnitch ``` -------------------------------- ### Install optional SQL drivers Source: https://elesiuta.github.io/picosnitch/configuration Install the necessary drivers to enable remote logging functionality using pipx. ```bash sudo pipx install 'picosnitch[sql]' --global ``` -------------------------------- ### Launch Web UI Source: https://elesiuta.github.io/picosnitch Starts the web interface. The default address is http://localhost:5100, which can be overridden using PICOSNITCH_HOST and PICOSNITCH_PORT environment variables. ```bash picosnitch webui # http://localhost:5100 (override with PICOSNITCH_HOST / PICOSNITCH_PORT) ``` -------------------------------- ### Configure remote MariaDB logging Source: https://elesiuta.github.io/picosnitch/configuration Example configuration for shipping logs to a MariaDB server with a per-host table. ```toml [database.remote] client = "mariadb" host = "logs.example.internal" port = 3306 user = "picosnitch" password = "..." database = "picosnitch" connections_table = "connections_workstation1" ``` -------------------------------- ### Launch Terminal UI Source: https://elesiuta.github.io/picosnitch Starts the curses-based read-only interface, suitable for SSH or headless environments. ```bash picosnitch tui ``` -------------------------------- ### Restart Picosnitch Service Source: https://elesiuta.github.io/picosnitch/configuration Command to apply changes made to the configuration file. ```bash sudo systemctl restart picosnitch ``` -------------------------------- ### Stream Live Events Source: https://elesiuta.github.io/picosnitch Streams real-time connection events. Requires root privileges to access the daemon's local socket. ```bash sudo picosnitch top ``` -------------------------------- ### Picosnitch config.toml Configuration Source: https://elesiuta.github.io/picosnitch/configuration The default configuration file structure for Picosnitch, defining database, data, log, desktop, monitoring, and VirusTotal settings. ```toml [database] enabled = true # write connection logs to /var/lib/picosnitch/picosnitch.db (SQLite) retention_days = 30 # how many days to keep connection logs in the local database # (the remote database is append-only; see [database.remote]) write_limit_seconds = 10 # minimum time between connection log entries # increasing it groups traffic into larger time windows, decreasing # disk writes, time precision, and database size text_log = false # also write a CSV connection log to /var/log/picosnitch/conn.log [database.remote] # optional: also write connection logs to an external SQL server # used for off-system / tamper-evident logs (see Logging below). # mirrors the local SQLite schema (connections, executables, # domains, addresses). # set `client` to "mariadb", "psycopg", "psycopg2", or "pymysql"; # add the rest of the connection parameters as key/value pairs and # optionally `connections_table` to override the default; this lets # multiple hosts share one server with a `connections` table each # while reusing the shared `executables`/`domains`/`addresses` [data] owner = "root" # owner for files in /var/lib/picosnitch, /var/log/picosnitch, group = "root" # and /var/cache/picosnitch mode = "0644" # mode applied to those files (directories add execute bits) # config.toml stays root:root 0600 because it can contain credentials [log] addresses = true # log remote addresses for each connection commands = true # log command line args for each executable ports = true # log local and remote ports for each connection ignore_ports = [] # list of ints; matching connections are omitted from the log ignore_domains = [] # list of strings in reverse-dns notation (matches all subdomains) ignore_ips = [] # list of IPs/CIDRs (e.g. "192.168.0.0/16") ignore_sha256 = [] # list of executable sha256 hashes # the process name, executable, and hash are still recorded [desktop] user = "" # username to send notifications to; defaults to $SUDO_UID notifications = true # show desktop notifications via notify-send (libnotify) geoip_lookup = true # annotate remote addresses with a country code in the TUI/webui # uses the DB-IP Country Lite CSV cached under /var/cache/picosnitch [monitoring] every_exe = false # check every running executable, not just ones that open sockets # these are treated as "connections" with a port of -1 # experimental; expect occasional errors for short-lived processes # if you only want process logs (no hashes), see execsnoop / forkstat perf_ring_buffer_pages = 256 # power of two pages for the exec and dns perf buffers # network traffic is aggregated in-kernel, it does not use these # only change this if you are seeing missed-event errors conn_map_max_entries = 65536 # size of the in-kernel per-connection aggregation map # only raise this if you see near-capacity eviction warnings # rlimit_nofile = 65536 # optional int; raises RLIMIT_NOFILE for the daemon # picosnitch caches one file descriptor per (device, inode); # set this if you see "Too many open files" errors # st_dev_mask = 0 # optional int; masks the device number reported for opened fds # auto-detected at startup; only set this to override the default # for filesystems that reuse inodes across subvolumes (e.g. btrfs) [virustotal] api_key = "" # VirusTotal API key, leave blank to disable file_upload = false # upload the executable when its hash isn't already known # leave false to only submit hashes request_limit_seconds = 15 # seconds between requests (free-tier quota) ``` -------------------------------- ### Query top 10 executables by received bytes Source: https://elesiuta.github.io/picosnitch/schema Retrieves the top 10 executables by bytes received in the last 24 hours. ```sql SELECT e.name, e.exe, SUM(c.recv) AS bytes_in FROM connections c JOIN executables e ON e.id = c.exe_id WHERE c.contime >= unixepoch('now', '-1 day') GROUP BY c.exe_id ORDER BY bytes_in DESC LIMIT 10; ``` -------------------------------- ### Query distinct executable and remote domain pairs Source: https://elesiuta.github.io/picosnitch/schema Retrieves every distinct executable and remote domain pair seen in the last week. ```sql SELECT DISTINCT e.name, e.exe, d.domain FROM connections c JOIN executables e ON e.id = c.exe_id JOIN domains d ON d.id = c.domain_id WHERE c.contime >= unixepoch('now', '-7 days') ORDER BY e.name, d.domain; ``` -------------------------------- ### Connection table indexes Source: https://elesiuta.github.io/picosnitch/schema Composite indexes to optimize queries by time and executable relationships. ```sql CREATE INDEX idx_contime ON connections(contime); CREATE INDEX idx_exe_id_contime ON connections(exe_id, contime); CREATE INDEX idx_pexe_id_contime ON connections(pexe_id, contime); CREATE INDEX idx_gpexe_id_contime ON connections(gpexe_id, contime); ``` -------------------------------- ### executables table schema Source: https://elesiuta.github.io/picosnitch/schema Defines the structure for storing unique executable metadata. ```sql id INTEGER PRIMARY KEY exe TEXT NOT NULL -- absolute path, e.g. /usr/bin/curl name TEXT NOT NULL -- /proc//comm, e.g. curl cmdline TEXT NOT NULL -- argv joined with NUL -> spaces sha256 TEXT NOT NULL -- sha256 of the executable file itself UNIQUE(exe, name, cmdline, sha256) ``` -------------------------------- ### connections table schema Source: https://elesiuta.github.io/picosnitch/schema Defines the structure for storing connection logs, referencing executables, addresses, and domains. ```sql contime INTEGER NOT NULL -- unix time, seconds send INTEGER NOT NULL -- bytes sent in this window recv INTEGER NOT NULL -- bytes received in this window events INTEGER NOT NULL -- number of raw socket events merged exe_id INTEGER NOT NULL REFERENCES executables(id) pexe_id INTEGER NOT NULL REFERENCES executables(id) -- parent gpexe_id INTEGER NOT NULL REFERENCES executables(id) -- grandparent uid INTEGER NOT NULL family INTEGER NOT NULL -- AF_INET=2, AF_INET6=10, 0=unknown protocol INTEGER NOT NULL -- IPPROTO_* (TCP=6, UDP=17), 0=unknown lport INTEGER NOT NULL rport INTEGER NOT NULL laddr_id INTEGER NOT NULL REFERENCES addresses(id) raddr_id INTEGER NOT NULL REFERENCES addresses(id) domain_id INTEGER NOT NULL REFERENCES domains(id) netns INTEGER NOT NULL -- socket's network namespace inode ``` -------------------------------- ### Query connections by shell grandparent Source: https://elesiuta.github.io/picosnitch/schema Retrieves all connections opened by a process whose grandparent was a shell (bash, zsh, or fish). ```sql SELECT datetime(c.contime, 'unixepoch') AS t, e.name, d.domain, c.rport FROM connections c JOIN executables e ON e.id = c.exe_id JOIN executables gp ON gp.id = c.gpexe_id JOIN domains d ON d.id = c.domain_id WHERE gp.name IN ('bash', 'zsh', 'fish') ORDER BY c.contime DESC; ``` -------------------------------- ### domains table schema Source: https://elesiuta.github.io/picosnitch/schema Defines the structure for storing unique domain names. ```sql id INTEGER PRIMARY KEY domain TEXT NOT NULL UNIQUE ``` -------------------------------- ### addresses table schema Source: https://elesiuta.github.io/picosnitch/schema Defines the structure for storing unique IP addresses. ```sql id INTEGER PRIMARY KEY addr TEXT NOT NULL UNIQUE -- IPv4 or IPv6 in canonical text form ``` -------------------------------- ### CSV log format Source: https://elesiuta.github.io/picosnitch/schema The field structure for the flat CSV log file at /var/log/picosnitch/conn.log. ```text entry time, sent bytes, received bytes, event count, executable path, process name, cmdline, sha256, parent executable, parent name, parent cmdline, parent sha256, grandparent executable, grandparent name, grandparent cmdline, grandparent sha256, user id, address family, protocol, local port, remote port, local address, remote address, domain, network namespace ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.