pWarden - Process Behavior Guardian

About pWarden

pWarden learns what "normal" looks like for every process on your system, then watches for deviations in real-time. It's not asking "is this bad?" but rather "is this unusual for this specific process?"

Traditional security tools either look for known bad patterns (signatures) or monitor resources without context. They miss the subtle deviations that indicate a breach, compromised process, or insider threat.

pWarden establishes behavioral baselines automatically, then continuously monitors for anomalies. When a web server suddenly spawns a shell, a database connects to unexpected ports, or any process deviates from its established pattern, pWarden alerts you.

Usage

Basic Usage

Run pWarden in the foreground to see output:

pwarden

Run as a daemon:

pwarden -d

Learning Mode

By default, pWarden runs in learning mode for 24 hours. During this time, it:

Discovers all running processes
Collects behavioral data (network connections, file access, resource usage)
Builds statistical models for each process
Saves baselines to ~/.pwarden/baselines/

Monitoring Mode

After the learning period, pWarden switches to monitoring mode:

Continuously monitors all processes
Compares current behavior against learned baselines
Alerts when anomalies are detected

Signal Handling

SIGTERM / SIGINT: Graceful shutdown
SIGHUP: Reload configuration

Key Features

Automatic Baseline Learning: Observes processes during a learning period to establish normal behavior patterns
Real-time Anomaly Detection: Monitors network connections, file access, and resource usage
Context-Aware: Understands that "unusual" differs for each process
Multiple Alert Channels: Supports stdout, log file, and syslog
Lightweight: Uses Linux proc filesystem for efficient monitoring

Examples

Here are some simulated examples of what pWarden detects:

Example Alert: Network Anomaly

[2025-01-15 14:32:18] ANOMALY DETECTED
  Type: NETWORK_UNKNOWN_CONNECTION
  PID: 2847
  Process: nginx
  Executable: /usr/sbin/nginx
  Severity: 0.92
  Details: Unknown TCP connection to 192.168.1.100:4444
  Baseline: nginx typically connects to ports 80, 443, 8080

This alert indicates that nginx, which normally only connects to web ports, is making an unexpected connection to port 4444, potentially indicating a compromise or data exfiltration attempt.

Example Alert: Resource Anomaly

[2025-01-15 15:45:22] ANOMALY DETECTED
  Type: RESOURCE_SPIKE
  PID: 1923
  Process: postgres
  Executable: /usr/bin/postgres
  Severity: 0.85
  Details: CPU usage spike detected
  Current: 87.3% (baseline: 12.5% ± 3.2%)
  Memory: 2.1GB (baseline: 1.8GB ± 200MB)

PostgreSQL suddenly consuming excessive CPU could indicate a runaway query, denial of service attack, or malicious activity.

Example Alert: File Access Anomaly

[2025-01-15 16:12:07] ANOMALY DETECTED
  Type: FILE_ACCESS_UNKNOWN
  PID: 3156
  Process: apache2
  Executable: /usr/sbin/apache2
  Severity: 0.78
  Details: Access to /etc/shadow (not in baseline)
  Baseline: apache2 typically accesses /var/www/*, /etc/apache2/*

A web server accessing the shadow password file is highly unusual and could indicate an attacker attempting to read system credentials.

Example Baseline

After the learning period, pWarden creates baselines like this for each process:

{
  "pid": 2847,
  "name": "nginx",
  "executable": "/usr/sbin/nginx",
  "baseline_established": "2025-01-14T10:00:00Z",
  "network": {
    "tcp_connections": [
      {"dest_ip": "0.0.0.0", "dest_port": 80, "frequency": 0.98},
      {"dest_ip": "0.0.0.0", "dest_port": 443, "frequency": 0.95},
      {"dest_ip": "127.0.0.1", "dest_port": 8080, "frequency": 0.42}
    ],
    "udp_connections": []
  },
  "resources": {
    "cpu_mean": 2.5,
    "cpu_std": 1.2,
    "memory_mean": 52428800,
    "memory_std": 10485760
  },
  "file_patterns": [
    "/var/log/nginx/*",
    "/etc/nginx/*",
    "/var/www/html/*"
  ]
}

This baseline represents nginx's normal behavior. Any deviation from these patterns will trigger an alert.

Upcoming Features

We're working on exciting new features for future releases:

Web Dashboard: A modern web interface for real-time monitoring, visualization of anomalies, and configuration management