Skip to content

Security model and hardening

This page describes what Aperture protects, how it does it, and where the edges are: the service sandbox, secrets and credentials, sessions and tokens, request checks, and the parts that are open on your network by design. It ends with a hardening checklist and how to report a vulnerability.

Aperture runs as three systemd services on one machine:

Service Runs as Listens on Holds
aperture (nvrd) root, sandboxed APERTURE_HTTP_ADDR (:8971): web app and API the database, secrets, recordings
aperture-go2rtc its own user aperture-go2rtc 127.0.0.1:1984 (API), :8554 (RTSP), :8555 (WebRTC) camera stream links, with their logins
aperture-discovery a temporary system user (DynamicUser) mDNS on the LAN nothing secret

Optional listeners, all off by default: the ONVIF provider (:10101 and WS-Discovery on UDP 3702) and the HomeKit bridge. The installer also installs Mosquitto as the MQTT broker for Home Assistant.

Why nvrd runs as root, and the sandbox around it

Section titled “Why nvrd runs as root, and the sandbox around it”

nvrd starts each backend extension under its own unprivileged user id and changes ownership of that extension’s folder. Dropping a child process to another user and chown need root, so the unit has no User=. Instead the unit (deploy/systemd/aperture.service) confines it:

  • ProtectSystem=strict with ReadWritePaths=/var/lib/aperture: the whole file system is read-only except the state directory,
  • ProtectHome, PrivateTmp, ProtectKernelTunables, ProtectKernelModules, ProtectKernelLogs, ProtectControlGroups, ProtectClock,
  • NoNewPrivileges, RestrictSUIDSGID, RestrictNamespaces, RestrictRealtime, LockPersonality,
  • RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK,
  • memory, task and CPU limits, and OOMPolicy=continue so a misbehaving extension that is killed for memory does not take recording down with it.

NoNewPrivileges does not block the extension drop: it stops a process from gaining privileges across exec, while nvrd only gives them up. Not set, with reasons given in the unit file: PrivateUsers (it would break the per-extension user ids), MemoryDenyWriteExecute (Deno’s JIT needs it), a system-call filter and a capability bounding set (not yet trimmed).

Before every start, /usr/libexec/aperture/aperture-harden re-applies file modes (0711 on the data directory so an extension cannot list its siblings; 0600 on secrets.json, cli.token, the database and go2rtc.yaml) and refuses to start in states that would fail silently, for example a database without its secrets.json.

go2rtc keeps every camera’s stream link, login included, in its config file and hands it to anyone who can reach its API. The native install binds that API to 127.0.0.1:1984, so only nvrd on the same machine reaches it. Browsers never talk to go2rtc’s API: live video goes through nvrd’s authenticated WebSocket proxy. go2rtc’s streams log level is set to error because it otherwise logs the full source link, password included, on every reconnect.

/var/lib/aperture/data/secrets.json (mode 0600) holds four values, generated on first start:

Secret Used for
jwt_secret Signs the 5-minute token between the password and the authenticator-code step. Can be set with APERTURE_JWT_SECRET.
stream_secret Signs the 5-minute live-stream tokens and the 24-hour links to event thumbnails in notifications. Can be set with APERTURE_STREAM_SECRET.
cli_token The local administrator token for nvrctl, also written to cli.token.
enc_key The AES-256-GCM key that encrypts stored credentials (below).

Encrypted with enc_key (internal/secret/cipher.go): SMB and SFTP storage destination passwords and keys, camera ONVIF passwords, and the Eufy account password.

Stored as entered, not encrypted: camera stream links with their logins (go2rtc needs them in clear text), the MQTT password, the OIDC client secret, notification channel settings (bot tokens, SMTP passwords) and webhook signing secrets. They are protected by the file permissions of the data directory, not by encryption.

The key lives in the same directory as the database, so encryption protects a copied database, not a compromised server. If secrets.json is lost, the encrypted credentials have to be entered again; the pre-start check refuses to start with a database but no secrets.json for that reason.

Once saved, a credential is never sent back to any client, the web app included:

  • Camera stream links come back with the login replaced by •••••. Leave the dots to keep the stored login, or type over them. A kept login is only filled back in for the same host it was saved for, so editing the address to point at another machine cannot send it the saved password (internal/urlcred).
  • Storage destination secrets, ONVIF passwords, the MQTT password, the OIDC client secret, notification channel settings and extension secret settings are reported only as “set” or “not set”.

Two values an administrator can read back by design: webhook signing secrets (through the API, so a receiver can verify signatures) and the live-view key under Integrations.

  • Passwords are bcrypt hashes. Two-factor uses TOTP with single-use recovery codes, stored hashed. Passkeys use WebAuthn bound to the host name. See Passwords, two-factor and passkeys.
  • Sessions are stored server-side. The cookie holds a random 256-bit token; the database keeps only its SHA-256 hash. The cookie is HttpOnly, SameSite=Lax, and Secure when APERTURE_PUBLIC_URL is https://.
  • Role, camera access and the disabled flag are read on every request, so a change takes effect immediately.
  • There is no account lockout. Requests before sign-in are rate-limited per client address (burst 30, then 10 per second); failed sign-ins are recorded in the activity log.

For a browser session, every POST, PUT, PATCH and DELETE to the API is checked: if the request carries an Origin header (or, without it, a Referer) whose host differs from the request’s Host, it is refused with 403 cross-origin request blocked. The cookie’s SameSite=Lax is a second layer.

A request with neither header is allowed on purpose. Browsers attach Origin to every cross-site POST, so a missing header means a non-browser client such as nvrctl or curl. Bearer-token requests carry no cookie and are not checked.

This is why a reverse proxy must pass the original Host header through. A proxy that sends its upstream address as Host makes every change from the web app fail.

The client address appears in the activity log and the signed-in devices list, and the pre-sign-in rate limit is counted per address. Forwarding headers count only when the connection comes from a trusted proxy, listed in APERTURE_TRUSTED_PROXIES (default 127.0.0.0/8, ::1/128, a proxy on the same machine). From a trusted proxy, Aperture takes the right-most X-Forwarded-For entry that is not itself a trusted proxy, or X-Real-IP when there is no X-Forwarded-For, and believes X-Forwarded-Proto. From anyone else it removes those headers and uses the connection’s own address, so a client that reaches port 8971 directly cannot choose the address it is logged under (internal/clientip).

A proxy on another machine must be listed:

APERTURE_TRUSTED_PROXIES="127.0.0.1, ::1, 192.168.1.5"

List only the proxies. Any device inside a trusted range can claim to be any client. See Client addresses for the details and complete proxy configurations.

Routes are registered only through one function that takes an access declaration: public, signed in, administrator, session only, the scopes a token needs, and whether the {id} in the path is a camera the caller must be allowed to see (internal/api/access.go). One middleware enforces the declaration. At start-up, nvrd walks the whole route table and refuses to boot if any /api route was registered without one, so a forgotten check cannot reach production.

The same declarations generate the OpenAPI document, so the scopes listed in the endpoint reference are the ones the server enforces.

Tokens (apt_…) are for scripts and integrations. The database keeps only a SHA-256 hash, and the token is shown once.

  • A token holds only the scopes you grant, and optionally only some cameras.
  • It can never exceed its owner: it carries the owner’s current role and camera access, it stops working when the owner is disabled, and it is deleted with the owner.
  • Operations that could take over an account or destroy data are session-only and refused to every token, whatever its scopes: users, tokens, passwords, two-factor and passkeys, backup, restore, restart, purge, reindex, extension management.
  • Writes to configuration with a token must send If-Match, so a script cannot overwrite a change it has not seen.

See The API and tokens.

Each backend extension runs in Deno as its own unprivileged user, with resource limits, write access to its own folder only, and network access only to the hosts it declared and you approved. Panels run in a sandboxed iframe and reach the API only through a broker that applies the viewing user’s own permissions. An extension cannot read recordings, the database or secrets. Details: Extension security.

Some parts of Aperture answer without a login. Know which, and firewall them.

go2rtc’s RTSP server on port 8554 serves every camera as rtsp://<server>:8554/cam_<id> without a password. The camera id is 32 random hex characters, which is the only thing keeping a stream private, and the address is shown in the app, published to Home Assistant and handed out by the ONVIF provider. Anyone on the network who learns it can watch. Allow port 8554 only from the machines that need it, such as Home Assistant. See ONVIF and RTSP.

When turned on under Integrations › ONVIF & HomeKit, the ONVIF provider answers on port 10101 and, optionally, WS-Discovery on UDP 3702. It is unauthenticated by design: anyone on the LAN can list the cameras, get their stream addresses and fetch snapshots. Keep it off unless another recorder needs it, and only on a trusted network.

The HomeKit bridge publishes cameras to Apple Home after pairing with the code shown in the app. It needs mDNS on the LAN. Keep it off unless you use it. See HomeKit.

Home Assistant integration goes through an MQTT broker. MQTT carries camera snapshots and accepts commands such as arming and changing the recording mode. If you let the broker accept connections from the network, require a username and password. See Home Assistant.

A share link (/s/<token>) lets anyone with the link view one exported clip until it expires, is revoked or reaches its view limit, optionally behind a password. Disabling the account that made it revokes it. The server keeps the clip for as long as the link works, so a link that never expires holds its clip until you revoke it. A notification image link is signed and works for 24 hours. Both are capability links: whoever has the link has access. See Export and share.

Without a login, the API answers only: /version, /system/health, /system/version, /setup/status, the sign-in endpoints, the single sign-on start and callback, the live WebSocket (which needs a stream token), the signed thumbnail link, and /setup while no account exists.

Outside the API, the web app’s own files, share pages under /s/ and the static files of enabled extension panels under /ext/<id>/ are served without a login. Panel files carry no data; data reaches a panel only through the broker.

  1. Finish setup at once. Until the first administrator exists, anyone who can open the page can create it.
  2. Use HTTPS through a reverse proxy, and set APERTURE_PUBLIC_URL to the https:// address so cookies are marked Secure. Pass Host, X-Forwarded-Proto and X-Forwarded-For, and list a proxy on another machine in APERTURE_TRUSTED_PROXIES, as shown above. See Reverse proxy.
  3. Reach it from outside through a VPN (WireGuard, Tailscale) rather than a port forward. Aperture has no account lockout, and a VPN keeps the sign-in page off the internet entirely.
  4. Firewall the server. Browsers need the web port (or only the proxy, if you bind APERTURE_HTTP_ADDR="127.0.0.1:8971" with the proxy on the same machine); players need 8554; WebRTC uses 8555. Never expose go2rtc’s API on 1984.
  5. Put cameras on their own VLAN and block their internet access, so they can talk to Aperture but not to their vendor’s cloud or to the rest of your network.
  6. Turn on two-factor or passkeys for every administrator, and keep a second administrator account.
  7. Give tokens the least they need: only the scopes required, restricted to specific cameras, with an expiry. Revoke tokens you no longer use.
  8. Keep ONVIF and HomeKit off unless you use them, and protect the MQTT broker with a password if it is reachable from the network.
  9. Protect the data directory and backups. They hold password hashes, authenticator secrets and camera logins.
  10. Use camera accounts with the least rights the stream needs, not the camera’s admin account, where the camera allows it.
  11. Check the activity log from time to time and run Verify chain.
  12. Keep Aperture and the operating system updated. See Updates.

Report security problems privately through GitHub’s security advisories for the repository: open github.com/TheOriUHD/aperture/security/advisories/new and describe what you found and how to reproduce it. Please do not open a public issue for a vulnerability. Do not include real camera addresses, passwords or footage in the report.

Related: Passwords, two-factor and passkeys, What leaves your network, Extension security.