picosnitch：实践指南

准备试用picosnitch之前，先别急着安装；这个项目提供的是监视每个可执行文件的网络流量。从日常自动化的使用方式看，输入边界、依赖和失败处理如果不清楚就很难稳定复用是采用前必须回答的问题。我建议用一项范围明确的真实任务完成最小试跑，重点记录配置时间、输出质量、异常信息和维护痕迹，再与现有方案比较。对愿意先做小范围验证并复查原始文档的团队来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

Picosnitch

• 每当新程序连接到网络或修改时接收通知
• 监控您的带宽，随着时间的推移按可执行文件、哈希、父级、域、端口或用户细分流量
• Web 和终端界面，针对每个连接进行 GeoIP 查找（IP 地理定位，通过 DB-IP）
• 可以选择使用 VirusTotal 检查哈希值或可执行文件
• 可执行哈希值基于设备 + inode 进行缓存，以提高性能
• 检测容器内运行的应用程序，同一应用程序的多个版本根据其哈希值进行区分
• 使用 BPF 进行准确、低开销的带宽监控，并使用 fanotify 来监视可执行文件的修改
• 由于应用程序可以调用其他人的 send/receive 数据，因此还会为每个连接记录父级和祖级可执行文件（带有哈希值）
• 务实简约的设计，专注于 准确检测，在不可能时提供清晰可靠的错误报告

_{More 屏幕截图和 picosnitch 屏幕截图 gallery.} 中的简短演示视频

安装

建议安装系统范围的 pipx 安装。它适用于 Python >= 3.12 的每个 Linux 发行版，并且内核足够新，可以运行现代 libbpf CO-RE 程序。

sudo pipx install picosnitch --global
sudo picosnitch systemd
sudo systemctl enable --now picosnitch

• 要求 pipx >= 1.5.0（这是添加 --global 标志时的情况）；如果您还没有，请参阅 pipx 安装
• sudo picosnitch systemd 写入 /usr/lib/systemd/system/picosnitch.service
• 使用 sudo pipx install 'picosnitch[sql]' --global 安装可选的 MariaDB / MySQL / PostgreSQL 驱动程序，用于 远程日志记录

用途

• Run/enable 守护进程 -sudo systemctl启用|禁用 picosnitch：重新启动时自动启动 -sudo systemctl启动|停止|重新启动 picosnitch：守护进程生命周期
  • 或不使用 systemd：sudo picosnitch start|停止|重新启动
  • 或将其保留在前台：sudo picosnitch start-no-daemon
• picosnitch webui：用于浏览过去连接的网页 UI
  • 访问 http://localhost:5100；使用 PICOSNITCH_HOST / PICOSNITCH_PORT 环境变量覆盖
• picosnitch tui：用于浏览过去连接的终端UI
• sudo picosnitch top：实时事件源（需要 root 来读取守护进程的事件套接字；如果守护进程未运行，则启动和停止其自己的守护进程）
• picosnitch status：显示守护进程pid和systemd服务状态
• picosnitch help：完全使用

配置

配置存储在 /etc/picosnitch/config.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
exec_ring_buffer_pages = 256  # power of two pages sizing the exec event ring buffer
                              # network traffic is aggregated in-kernel, it does not use this
                              # 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)

重新启动 picosnitch 以使任何配置更改生效。

日志记录

Picosnitch 将其磁盘状态划分到 FHS 目录中。所有默认值均采用 systemd 单元（该单元也在首次启动时创建这些单元）。

[database.remote] 可用于另外将每个连接传送到 MariaDB、MySQL 或 PostgreSQL 服务器。它镜像本地 SQLite 架构（connections、executables、domains、addresses）；仅 connections 表名可以被覆盖（通过 connections_table），这允许多个主机共享一台服务器，每个服务器都有一个 connections 表，同时重用共享引用表。 Picosnitch 从不更新或删除远程行（不保留，不进行垃圾收集），因此它旨在保留日志 的系统外副本 [；仅授予 CREATE（首次运行）、INSERT 和 SELECT（id 查找），以便受监控主机上的对手无法重写或删除 picosnitch 的系统外日志。

如果现有远程 executables 表缺少 key_hash 列，则守护程序会报告过时的架构并保持不变；备份并重新创建远程表以启用远程日志记录。

conn.log 是一个 CSV，具有以下字段（逗号、换行符、回车符和 NUL 字符从值中删除）：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。

error.log 中的条目通常由异常大量的新进程或连接触发，由在 picosnitch 可以打开文件描述符之前退出的极其短暂的进程触发，或者在对新的可执行文件进行哈希处理时挂起系统。意外的条目值得调查，因为 picosnitch 的设计目的是在进程偏离其正常观察路径时显示错误。

限制

• Picosnitch 是一个用户空间守护进程。具有足够权限的程序可以更改 picosnitch 或其日志，或者退回到内核不可见的通信通道。使用 [database.remote] 作为连接日志的系统外副本，并考虑使用单独的 router/firewall 进行确认。
• 通过 BPF 检测打开的套接字和原始进程是可靠的，但可执行路径和名称可能不明确或被欺骗。作为对策，picosnitch 对可执行文件本身进行哈希处理；仅对进程可执行文件进行哈希处理，因此哈希不涵盖共享库、脚本和运行时扩展。
• 根据 BPF 程序报告的内容检查打开的文件描述符的设备和索引节点，以检测可执行文件的运行时替换。跨子卷重用 inode 的文件系统 (e.g.btrfs) 会失败此检查，并在启动时自动检测到 (st_dev_mask = 0)。
• 对于生命周期极短的进程，picosnitch 可能无法及时打开文件描述符来散列可执行文件。连接仍然与 picosnitch 拥有的其他所有内容一起记录，以及 error.log 中的条目。
• 大量新进程的涌入可能会导致丢失日志条目，因为 picosnitch 会保留系统流量延迟而不是阻塞追赶。此类事件会被检测、记录和通知，并且可以通过提高 [monitoring].exec_ring_buffer_pages 来缓解。相反，大量新连接会填满内核聚合映射，通过提高 [monitoring].conn_map_max_entries 可以缓解这种情况。