Security

Model

There is one admin user. Login is in two steps:

  1. Password — stored only as an argon2id hash (never in plain text).
  2. Two-factor code (2FA) — a 6-digit code from an authenticator app (Google Authenticator, and any app that follows the same standard).

After a successful login you get an HttpOnly SameSite=Lax session cookie (also flagged Secure when you reached the panel over HTTPS). Logins are rate-limited per client IP (5 tries a minute, with a global backstop of 50 tries a minute). Every action that changes something is CSRF-protected and written to the audit log.

The 2FA step has its own limits, so even someone who knows the password can’t guess codes for long:

Locked out at the 2FA step? Someone who knows your password can keep the 2FA step locked by sending wrong codes, and you can’t sign in to change the password while it lasts. Fix it on the server over SSH:

  1. Run sudo ci-agent set-password and choose a new password.
  2. Run sudo systemctl restart ci-agent.

The restart clears the lock (it is kept in memory only) and ends every session, including the attacker’s half-signed-in ones. Their old password no longer works, so they can’t start the lock again. Then sign in as usual. See Configuration → CLI.

Sessions work like this:

What is 2FA? “Two-factor” means you need two things to log in: something you know (the password) and something you have (your phone with the authenticator app). If someone steals the password, they still can’t get in.

Two-factor authentication (TOTP)

Webhooks authenticate with a 256-bit random URL token (constant-time compare; unknown slug, bad token and archived project are all 404 so projects can’t be enumerated) — see Webhooks.

Treat a webhook URL like an admin password. Whoever has it can start a deploy, and the request can also name what to build. On the /git hook, a git_url (in the JSON body or ?git_url=) replaces the project’s repository for that run. The /zip hook always builds the archive at the zip_url the caller sends. That is the same power as an admin API key’s code choice. Only an admin can see the URL (on the project page, or through an admin API key). If it leaks, click Rotate token on the project’s Deployments tab — the old URL stops working at once.

The automation API (/api/*) only accepts API keys created on the API keys page. It answers nothing until a key exists.

Upgraded from an older version? Older releases had a single API token. On upgrade, the agent turns it into a read-level key named legacy, so existing monitoring keeps working. You’ll see it on the API keys page. Revoke it if nothing uses it any more.

See API & AI agents.

Project env vars and stored git credentials (tokens or passwords for private clones) are encrypted at rest (XChaCha20-Poly1305, key file 0600) and masked (*****) in run logs. Short values under ordinary names (REPLICAS=3) are not masked; give a secret a name that says so (…_PASSWORD, …_TOKEN, …_KEY) and it is masked at any length (which values). The admin panel itself shows env values in cleartext, so anyone logged in to the panel can read them.

Network exposure

The agent speaks plain HTTP by design (TLS belongs to your nginx), and the first-run wizard enforces the safe end state: the admin panel must be bound to a domain and proven reachable through host nginx before the agent rewrites listen to 127.0.0.1 and restarts itself. Verification is spoof-resistant — a request only counts as “via nginx” when its Host matches the bound domain and the TCP peer is loopback and X-Forwarded-For is present, so a forged Host header on the public port cannot trigger a premature lockdown (or fake one to lock the admin out before nginx works). If listen is later set back to a public address (by hand, Direct port access or panel-port on), each login shows a lock to loopback reminder. You can skip it for that login.

After setup, the panel only answers on its own admin domain. Any other domain pointed at the agent gets a plain Under construction page. Webhooks (/hooks/…), the API (/api/…) and Let’s Encrypt challenges are the exceptions — they answer on any host name.

server {
    listen 443 ssl;
    server_name ci.example.internal;
    # ssl_certificate ...; ssl_certificate_key ...;
    location / {
        proxy_pass http://127.0.0.1:8044;
        proxy_set_header Host $host;
        # SSE live logs need buffering off:
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

Accepted trade-offs (by design)

Managing nginx and TLS

The agent runs as the unprivileged ci-agent user. For the few jobs that need root, it uses sudo -n with a NOPASSWD allowlist that the package installs at /etc/sudoers.d/ci-agent-nginx. The list has no wildcards. It allows:

The helpers handle everything that takes input from you:

Both helpers refuse to run unless they really are root, and they never pass your input through a shell.

What this means. The allowlist is narrow in which programs it allows, but fs-helper is full root access to files by design — the File Manager needs it. So the honest summary is: the ci-agent account can act as root on this server. The limit is who can log in to the panel, not the sudo rules. Protect the admin password and your 2FA devices accordingly.

If the sudo rule is missing, the privileged button fails fast and the page tells you so. The manual copy-paste commands still work. The agent re-checks and repairs the allowlist on every start, so it heals itself if the file drifts. TLS cert/key PEMs are written by the unprivileged agent into its own data dir (nginx’s master reads them), so cert issuance needs no sudo. See Domains & TLS.

Server shell and File Manager

Both the host File Manager (/files) and the Server shell are root-equivalent. Use them as you would a root SSH login:

Self-update integrity

The Maintenance page’s update verifies the .deb offline against the release public key embedded in the binary, pinned to a single fingerprint — a valid signature from any other key is rejected — and refuses downgrades. The online buttons (Update now, Download & stage latest) download from the public apt repository but go through the exact same check, so the network is never trusted. Uploading the ci-agent-offline-*.tar.gz bundle is the same check: the .deb and its detached signature are unpacked from it and the bundle’s own bundled public key is ignored, so trust always rests on the embedded key, never one that travels with the upload. The privileged binary swap runs only from systemd’s root pre-start step, and a crash-looping new binary is rolled back automatically. See the UI guide.

systemd sandbox

The shipped unit runs the agent as User=ci-agent, Group=docker, and sets PrivateTmp=yes (a private /tmp). Other common sandbox options are deliberately not set:

On every start the agent also writes a small drop-in, /etc/systemd/system/ci-agent.service.d/10-ci-agent.conf. It re-applies these settings on boxes that were updated from the panel, and adds AmbientCapabilities=CAP_NET_BIND_SERVICE. That lets the agent listen on ports 80 and 443 itself — used only by the tunnel relay in Online mode (see Reverse tunnel); with tunnelling off it changes nothing.

The privileged apply-staged-update pre-start step is the only component that writes /usr/bin.

Common problems and fixes

Problem Fix
Everyone was logged out Normal after a service restart, server reboot or self-update — sessions live in memory. Log in again.
A webhook URL leaked Click Rotate token on the project’s Deployments tab, then update the URL wherever you use it.
Lost every 2FA device and all backup codes Run sudo ci-agent reset-2fa, then sudo systemctl restart ci-agent, and enroll again at the next login.
A Host, Firewall or File Manager action fails with a sudo / “password is required” error The sudo allowlist is missing or was rejected. Restart the service (it repairs the file on start), then check journalctl -u ci-agent for a visudo error.
An API key leaked Click Revoke next to it on the API keys page. It stops working on the next request.