Picosnitch

https://elesiuta.github.io/picosnitch/
Admin
Picosnitch is a userspace daemon built on BPF and fanotify that provides per-executable network...
Tokens:9,264
Snippets:69
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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/<pid>/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
```
Tokens:
Raw