# Sensors

Source: https://www.pingtower.com/docs/addons/sensors/

Checks run on a schedule. Sensors run continuously, subscribed to the kernel, and report the moment something happens on the box the agent runs on.

New in addons 0.2.0. Linux only. Gated behind `agent.enable_sensors`, so a config naming a sensor without that fails at startup, like the privileged addons.

| Sensor | Watches | Needs |
| --- | --- | --- |
| `nftwatch` | The host's nftables ruleset. Reports the moment it changes. Sends only ruleset hashes and object counts, never the rules. | `CAP_NET_ADMIN` |
| `network` | Every inbound TCP connection attempt, through a pass-only eBPF program that can observe and never drop, redirect or rewrite. Aggregated by port and redacted remote prefix. | `CAP_BPF`, `CAP_NET_ADMIN` |
| `authwatch` | SSH and sudo authentication events from the system journal, matched strictly against the distribution's exact message forms. Usernames and raw messages are never sent; remote addresses are reduced to a /24 or /64. | journal read access |
| `filewatch` | An explicit set of files and shallow directory roots. inotify is only a wake-up; every event settles into a stat reconciliation, so an atomic editor replace is a confirmed change. Events carry path, type, owner, mode and SHA-256, never contents. | read access |
| `listeningports` | The kernel's TCP and UDP listener inventory against an explicit baseline. Undeclared and vanished listeners become events. Exact addresses and PIDs never enter events. | none |
| `servicewatch` | An explicit list of systemd units: failures, recoveries, restart-loop crossings, unit-file hash changes, and a service whose command became a different binary. | none |
| `pressure` | Kernel PSI stall triggers for CPU, memory and I/O. One event per crossing, one per recovery. | none |

Several run under the stock unit with an empty capability set. The kernel-attached ones take one narrow capability through a local systemd drop-in; the tarball's README has the exact drop-in for each.

```yaml
agent:
  enable_sensors: [nftwatch, network]

sensors:
  - id: host-firewall
    sensor: nftwatch
    with: { netns: host, settle: 250ms, reconcile: 5m }
  - id: public-ingress
    sensor: network
    with:
      interfaces: [eth0]
      direction: ingress
      ports: [22, 80, 443]
      window: 60s
```

The agent's heartbeat carries `sensors`, `sensor_events` and `sensor_failures`, so a sensor that stops sensing is itself a rule away from paging someone.

<div class="docs-callout note"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><circle cx="8" cy="8" r="6.5"/><path d="M8 7v4M8 5v.5"/></svg><div><span class="t">Privacy is the design, not a setting</span>Every sensor is built so that contents, usernames and exact addresses never leave the box. What reaches the tower is that something changed, where, and a hash.</div>
</div>