psc

psc (ps container) è uno scanner di processi veloce che utilizza iteratori eBPF e Google CEL per interrogare lo stato del sistema con precisione e contesto completo dei container.

Perché psc?

Accesso rapido a livello kernel con iteratori eBPF

psc utilizza iteratori eBPF per leggere le informazioni sui processi e sui descrittori di file direttamente dalle strutture dati del kernel. Questo approccio è:

• Veloce: gli iteratori eBPF sono altamente efficienti rispetto al filesystem proc, dove gli strumenti tradizionali trascorrono la maggior parte del tempo eseguendo chiamate di sistema
• Completo: accede a informazioni del kernel non tradizionalmente esposte tramite /proc. Ho in mente di aggiungere anche un modo per accedere a determinati campi di task_struct su richiesta per usi avanzati, ma è solo un'idea
• Resistente a manomissioni: aggira completamente il filesystem /proc, fornendo visibilità che non può essere sovvertita da rootkit in userland o trucchi con LD_PRELOAD

Query leggibili con CEL

Gli strumenti Linux tradizionali come ps, lsof e ss sono potenti ma rigidi. Producono formati fissi che richiedono estese operazioni di piping con grep, awk e sed:

# Traditional: Find nginx processes owned by root
ps aux | grep nginx | grep root | grep -v grep

# psc: Express exactly what you mean
psc 'process.name == "nginx" && process.user == "root"'

# Traditional: Find processes with established connections on port 443
ss -tnp | grep ESTAB | grep :443 | awk '{print $6}' | cut -d'"' -f2

# psc: One clear expression
psc 'socket.state == established && socket.dstPort == 443'

psc utilizza il Common Expression Language (CEL) per filtrare i processi. Le espressioni CEL si leggono quasi come un linguaggio naturale, rendendo i tuoi script auto-documentanti e manutenibili. Niente più decifrazioni di pipeline complesse di grep | awk | sed | xargs.

Il flag -o consente di visualizzare esattamente i campi necessari, eliminando del tutto la post-elaborazione:

psc 'socket.state == listen' -o process.name,socket.srcPort

Sono disponibili anche preset di output per stampare rapidamente informazioni comuni:

psc 'socket.type == tcp && socket.dstPort == 443' -o sockets 

Contesto nativo dei container

Gli strumenti tradizionali non hanno il concetto di container. Ottenere informazioni sui container richiede l'analisi dei percorsi cgroup, l'interrogazione dei runtime dei container e la correlazione manuale dei PID:

# Traditional: Find containerized processes (fragile, incomplete)
ps aux | xargs -I{} sh -c 'cat /proc/{}/cgroup 2>/dev/null | grep -q docker && echo {}'

# psc: Native container support
psc 'container.runtime == docker'

psc estrae automaticamente il contesto del container (ID, nome, immagine, runtime, etichette) per Docker, containerd, CRI-O e Podman. Esegui il debug di processi, file e connessioni di rete di qualsiasi container direttamente dall'host:

# Show all processes in a specific container
psc 'container.name == "my-app"' --tree

# Find containers running as root
psc 'container.runtime == docker && process.user == "root"'

# List containers with their images
psc 'container.id != ""' -o process.pid,process.name,container.name,container.image

Compilazione

Requisiti

• Kernel Linux 5.8 o successivo (gli iteratori eBPF sono stati introdotti in questa versione)
• Go 1.25 o successivo
• Clang e LLVM
• Header di sviluppo di libbpf
• Header del kernel Linux
• bpftool (per generare vmlinux.h)

Installa le dipendenze

Su Debian/Ubuntu:

sudo apt-get install clang llvm libbpf-dev linux-headers-$(uname -r) linux-tools-$(uname -r)

Su Fedora/RHEL:

sudo dnf install clang llvm libbpf-devel kernel-devel bpftool

Compila

# Generate vmlinux.h (required once per kernel version)
make vmlinux

# Build the binary
make build

Oppure manualmente:

bpftool btf dump file /sys/kernel/btf/vmlinux format c > bpf/vmlinux.h
go generate ./...
go build -o psc

Installa

sudo make install

Utilizzo

psc richiede privilegi di root per caricare i programmi eBPF.

Utilizzo base

# List all processes
sudo psc

# List all processes as a tree
sudo psc --tree

Filtraggio con espressioni CEL

Passa un'espressione CEL come primo argomento per filtrare i processi:

# Filter by process name
psc 'process.name == "nginx"'

# Filter by user
psc 'process.user == "root"'

# Filter by command line content
psc 'process.cmdline.contains("--config")'

# Filter by PID range
psc 'process.pid > 1000 && process.pid < 2000'

# Combine conditions
psc 'process.name == "bash" || process.name == "zsh"'

Filtraggio container

# Show only containerized processes
psc 'container.id != ""'

# Filter by container runtime (constants: docker, containerd, crio, podman)
psc 'container.runtime == docker'

# Filter by container name
psc 'container.name == "nginx"'

# Filter by container image
psc 'container.image.contains("nginx:latest")'

# Show as tree to see container process hierarchy
psc 'container.runtime == docker' --tree

Filtraggio socket e descrittori di file

Capire perché un processo esiste spesso richiede l'esame dei suoi descrittori di file aperti e delle connessioni di rete:

# Find processes with listening TCP sockets
psc 'socket.type == tcp && socket.state == listen'

# Find processes with established connections
psc 'socket.state == established'

# Find processes connected to a specific port
psc 'socket.dstPort == 443'

# Find processes using Unix sockets
psc 'socket.family == unix'

# Find processes with files open in /etc
psc 'file.path.startsWith("/etc")'

Campi disponibili

Campi del processo (process.X):

• name - Nome del processo (stringa)
• pid - ID del processo (int)
• ppid - ID del processo padre (int)
• tid - ID del thread (int)
• euid - ID utente effettivo (int)
• ruid - ID utente reale (int)
• suid - ID utente salvato (int)
• user - Nome utente (stringa)
• cmdline - Linea di comando completa (stringa)
• state - Stato del processo (uint)

Campi delle capacità (process.capabilities.X):

• effective - Maschera di bit delle capacità effettive (uint)
• permitted - Maschera di bit delle capacità consentite (uint)
• inheritable - Maschera di bit delle capacità ereditabili (uint)

Campi dei namespace (process.namespaces.X):

• net - Inode del namespace di rete (int)
• pid - Inode del namespace PID (int)
• mnt - Inode del namespace di mount (int)
• uts - Inode del namespace UTS (int)
• ipc - Inode del namespace IPC (int)
• cgroup - Inode del namespace cgroup (int)

Campi del container (container.X):

• id - ID del container (stringa)
• name - Nome del container (stringa)
• image - Immagine del container (stringa)
• runtime - Runtime del container (stringa)
• labels - Etichette del container (mappa)

Campi file/socket (file.X o socket.X):

• path - Percorso del file (stringa)
• fd - Numero del descrittore di file (int)
• srcPort - Porta di origine (int)
• dstPort - Porta di destinazione (int)
• type - Tipo di socket (tcp, udp)
• state - Stato del socket (per il filtraggio, usa costanti come listen, established)
• family - Famiglia di indirizzi (unix, inet, inet6)
• unixPath - Percorso del socket Unix (stringa)
• fdType - Tipo di FD (file_type, socket_type)

Costanti disponibili

Usale senza virgolette nelle espressioni:

• Runtime: docker, containerd, crio, podman
• Tipi di socket: tcp, udp
• Famiglie di indirizzi: unix, inet, inet6
• Stati del socket (per il filtraggio): established, listen, syn_sent, syn_recv, fin_wait1, fin_wait2, , , , ,

Nota: L'output utilizza nomi di stato in stile ss: ESTAB, LISTEN, SYN-SENT, ecc. Per i socket UDP, vengono mostrati solo UNCONN (non connesso) o ESTAB (connesso) poiché UDP è senza connessione.

Funzioni per stringhe

CEL fornisce funzioni per la manipolazione delle stringhe:

• .contains("sottostringa") - Verifica se la stringa contiene una sottostringa
• .startsWith("prefisso") - Verifica se la stringa inizia con un prefisso
• .endsWith("suffisso") - Verifica se la stringa termina con un suffisso

Opzioni

• --tree, -t - Visualizza i processi come albero
• --no-color - Disabilita l'output colorato
• -o, --output - Colonne di output personalizzate (nomi di campo separati da virgole o preset)

Sottocomandi

• psc fields - Elenca tutti i campi CEL, le costanti e i preset di output disponibili
• psc version - Mostra le informazioni sulla versione

Output personalizzato con -o

Il flag -o consente di specificare esattamente quali campi visualizzare. Puoi utilizzare preset per casi d'uso comuni o specificare singoli campi.

Preset:

• sockets - Informazioni sul processo + dettagli completi del socket (famiglia, tipo, stato, indirizzi, porte)
• files - Informazioni sul processo + dettagli del descrittore di file (fd, tipo, percorso)
• containers - Informazioni sul processo + dettagli del container (nome, immagine, runtime)
• network - Vista di rete compatta (pid, nome, tipo, stato, porte)

# Use a preset
psc 'socket.state == listen' -o sockets
psc 'container.id != ""' -o containers

# Or specify individual fields
psc -o process.pid,process.name,process.user
psc 'socket.state == listen' -o process.pid,process.name,socket.srcPort,socket.state

Quando l'output include campi file/socket e il filtro corrisponde a più file per processo, ogni corrispondenza ottiene la propria riga:

$ psc 'socket.state == listen' -o network

PID      NAME      TYPE   STATE    SRCPORT   DSTPORT
1234     nginx     tcp    LISTEN   80        0
1234     nginx     tcp    LISTEN   443       0
5678     sshd      tcp    LISTEN   22        0

Esempi

Trova tutti i web server:

psc 'process.name == "nginx" || process.name == "apache2" || process.name == "httpd"'

Trova processi in ascolto su porte privilegiate:

psc 'socket.state == listen && socket.srcPort < 1024'

Trova processi in un namespace di rete diverso (utile per l'ispezione di container/pod):

psc 'process.namespaces.net != 4026531840' -o process.pid,process.name,process.namespaces.net

Mostra le capacità per i processi privilegiati:

psc 'process.euid == 0' -o process.pid,process.name,process.capabilities.effective,process.capabilities.permitted

Trova processi che hanno elevato i privilegi tramite binari SUID (UID reale diverso da UID effettivo):

psc 'process.ruid != process.euid'

Trova processi con connessioni a servizi esterni:

psc 'socket.state == established && socket.dstPort == 443'

Mostra le connessioni di rete con colonne personalizzate:

psc 'socket.state == established' -o process.pid,process.name,socket.srcPort,socket.dstPort,socket.dstAddr

Licenza

MIT