Security

CaudalGhost watches your network; it never interferes. That stance —measure without touching— is also the foundation of its security. This page explains the design that protects you, what we harden over time, and, honestly, what its limits are.

One idea drives everything else: no software is invulnerable. Security isn’t a promise that nothing can break — it’s the work of raising the cost —in time, money, and people— of trying. Everything below moves in that direction.

The design that protects you

• The daemon does not run as root. caudalghostd runs as a dedicated system user, with only two kernel permissions (CAP_BPF and CAP_PERFMON) and no way to escalate (NoNewPrivileges). Installation asks for privileges (sudo) once; daily use doesn’t. It isn’t “root with good manners”: it’s a process that doesn’t even have the capability to do much beyond counting bytes.
• It can’t phone home, by construction. The systemd configuration restricts the daemon to local sockets (AF_UNIX/AF_NETLINK): it cannot open a network connection even if it wanted to. No telemetry, no analytics, no identifiers: your data never leaves the box. And when there’s an update, you install it through your system’s software channels —when you choose— the daemon never reaches out to anyone on its own.
• No network surface. Clients (GUI, terminal, command line) talk to the daemon over a local Unix socket with 0660 permissions and a per-user POSIX ACL. There’s no open TCP port and no web server to attack from outside.
• It only watches. It counts bytes inside the kernel (eBPF). It doesn’t inspect traffic contents, doesn’t block, doesn’t shape. Fewer capabilities = less that can go wrong.
• Your data is local. History lives in a SQLite database on your machine. Nothing leaves the box. (The details are in Privacy and data.)
• Free and auditable. The code is open (AGPL-3.0; the eBPF piece, GPL-2.0). You don’t have to take our word for it: you can read it, compile it, and verify it.

The trust boundary

The security boundary is the daemon. Clients run unprivileged, and the daemon doesn’t take any request on faith just because it came from a client: it validates every one and treats it as potentially hostile until proven safe. A malformed request must never bring it down; at most it closes that connection and carries on.

We back that contract with tests: the protocol parser and the app-attribution logic are put through fuzzing (millions of automatic garbage inputs) and regression tests that guarantee no weird input can cause a crash.

What we harden release over release

Security isn’t a box you tick once. Each release adds layers:

• System sandbox. The service runs under a strict systemd isolation (read-only filesystem, no device access, no new privileges).
• Watched supply chain. Continuous integration audits dependencies on every change: known vulnerabilities, licenses, leaked secrets, and unsafe code patterns. All dependencies come from verified sources.
• Continuous fuzzing. In our own testing (not on your machine), the points that receive untrusted input are hammered with millions of random inputs to surface bugs before they reach you.
• Cleaner builds. The binaries we ship don’t leak internal paths from the developer’s machine — a step toward reproducible builds.

Risks we accept honestly

We’d rather document them than hide them:

• We don’t promise invulnerability. Like any software, CaudalGhost can have bugs. Our commitment is to design to minimize them, fix fast, and tell you the truth.
• A note about the graphical edition. The graphical edition pulls in, through its windowing engine, a system library with a known third-party issue. It does not affect the daemon, the terminal, or the server edition (those don’t use it), and our own code doesn’t touch the affected part. The fix depends on the third-party project updating its stack; we’re tracking it and will apply it as soon as it’s available.
• Best-effort attribution. Associating traffic with the right app happens at capture time, but in rare cases (when the system recycles a process identifier very quickly) it can mis-attribute. That’s a precision limitation, not a security problem.

How to report a problem

If you find a vulnerability, help us with coordinated disclosure:

• Email [email protected] with the [security] prefix in the subject. You may encrypt the email with GPG if you prefer.
• Do not open a public issue for security bugs.
• Include the affected version, the edition (desktop or server), reproduction steps, and estimated impact.

You’ll get an acknowledgment as soon as possible. We work the fix and coordinate disclosure with you; if you wish, we credit you in the release notes. The formal policy lives in the repository’s SECURITY.md file.