Skip to main content

Security

Delegaris holds the keys to start and stop machines across your AWS accounts, so it is worth knowing how it protects them. This page describes what the service does, and what is left to you.

The container​

The standard docker-compose.yml runs the container:

  • as an unprivileged user (UID 10001), not root;
  • with a read-only file system, writing only to the /data volume and a temporary /tmp;
  • with every Linux capability dropped and no-new-privileges set.

The container needs no inbound access except the web port. Slack is reached by the service connecting out, so nothing needs to reach Delegaris from the internet.

HTTPS and the browser​

Run Delegaris behind HTTPS and set PUBLIC_URL to the https:// address. Then:

  • the session cookie is marked Secure, so the browser never sends it over plain HTTP;
  • every response carries Strict-Transport-Security, telling browsers to use HTTPS for a year.

Whatever the address, every response also carries a strict Content Security Policy (scripts, styles and connections from the service itself only; no framing), X-Frame-Options: DENY, X-Content-Type-Options: nosniff and Referrer-Policy: same-origin. API responses are marked not to be cached.

The log warns at startup when PUBLIC_URL is not https:// (other than localhost). See Behind a reverse proxy.

Sessions​

  • Signing in sets a random session token in a cookie that scripts cannot read (HttpOnly) and that browsers do not send with requests from other sites (SameSite=Lax).
  • Only a SHA-256 hash of the token is stored in the database, so a copy of the database does not hand out working sessions.
  • A session lasts SESSION_TTL_HOURS (8 hours by default) from sign-in, and is not extended by use. Sign out deletes it from the database.
  • Administrator and auditor roles given in the web UI are looked up on every request, so giving or taking them away applies at once. Group membership from the directory, and administrator status from the administrator groups and users (Settings > Sign-in > Administrators, or ADMIN_GROUPS and ADMIN_USERS), are read at sign-in and apply from the next sign-in.

Cross-site request forgery​

Every request that changes anything must carry a per-session token in an X-CSRF-Token header, which a page on another site cannot read or send. Requests without it, or with the wrong one, are refused. API tokens are exempt, because a browser never sends them by itself.

Signing in​

  • Throttling. After 5 failed sign-ins for one user name within 5 minutes, further attempts for that name are refused for a while; one address gets five times as many. This protects Active Directory accounts from being locked out by someone guessing. Both numbers can be changed (LOGIN_MAX_FAILURES, LOGIN_FAILURE_WINDOW_SECONDS). Throttling is kept in memory, per copy of the service.
  • Every attempt is recorded, successful or not, with the address it came from. Behind a proxy, set TRUST_PROXY_HEADERS=true so that address is the visitor's, not the proxy's.
  • Active Directory. The service refuses to start with plain LDAP unless LDAP_ALLOW_INSECURE (or the matching choice under Settings > Sign-in) allows it on purpose. Domain controller certificates are checked unless LDAP_TLS_VERIFY=false, and the log warns when they are not. The service account only needs to read.
  • Microsoft Entra ID. The standard authorization code flow with PKCE. The state is checked, and the ID token is checked against Microsoft's published keys. The short-lived cookie that carries the handshake is signed and lasts ten minutes.
  • The local administrator is the break-glass way in, and the log notes at every start that it is enabled. Keep LOCAL_ADMIN_PASSWORD set, with the password kept safe and two-step sign-in on; unset it only if you do not want a break-glass account. See Local administrator.
  • Demo accounts (DEMO_USERS) are for demos only. The log warns whenever they are set.

Two-step sign-in​

Under Settings > Sign-in, administrators can require a code from an authenticator app for nobody, for administrators, or for everyone. It applies to Active Directory, local and demo sign-ins; Entra ID does its own through conditional access.

  • Nothing is signed in until the second step is through. Between the password and the code, who the person is travels in a signed token that lasts five minutes, not a session.
  • Each code is good once, so someone watching the screen cannot reuse it. Wrong codes are throttled.
  • Ten recovery codes are given at set-up, each good once. Only hashes of them are kept.
  • Administrators can reset a person's two-step sign-in. For the local administrator, it can be reset from the host: docker compose exec delegaris python -m app.mfa reset admin with Docker, or sudo delegaris mfa reset admin with the Linux package.

See Two-step sign-in.

Secrets the service keeps​

Some secrets have to be kept in a form the service can use. Others only need to be recognised, and only a hash is kept.

Kept only as a hashKept encrypted in the database
Session tokensAWS secret access keys and session tokens: the service's own (saved under Accounts) and each account's
API tokensThe IAM Identity Center sign-in's tokens
Two-step sign-in recovery codesThe Active Directory service account password and the Entra ID client secret, when saved under Settings > Sign-in
The webhook secret, when saved under Settings > Notifications
Each person's authenticator app secret
The key that signs sign-in handshakes (SECRET_KEY, generated if not set)

The secrets in the right-hand column are encrypted (Fernet: AES-128-CBC with an HMAC-SHA256 check) with a key that is not in the database: ENCRYPTION_KEY if you set it, otherwise a key made on first start and kept in /data/encryption.key. A copy of the database on its own, such as a backup or the nightly upload to S3, does not carry the means to read them. They are also never sent back to the browser (forms say "Saved. Leave empty to keep it").

  • Keep the key safe and keep a copy of it with your backups: a restored database cannot use its stored secrets without it. If you lose it, enter the secrets again.
  • Every copy of the service that shares a database needs the same key (see High availability). A copy started with a different key refuses to start rather than misread them.
  • Anyone who has both the database and the key, or the running container, can still read the secrets. Protect the /data volume (/var/lib/delegaris with the Linux package) and the PostgreSQL database as you would the keys themselves.
  • Prefer an IAM role for the service and Assume a role in the account for each account. Then no AWS secret is stored at all.
  • If you would rather sign-in secrets lived with the host, set them in .env (or /etc/delegaris/delegaris.env with the Linux package) instead of under Settings > Sign-in.

The activity log​

Every sign-in, sign-out and failed attempt, every action on a resource (start, stop, reboot, keep-on, tag change, Remote Desktop download, approval request and decision, request for access), and every administrative change (accounts, the service's AWS credentials, access rules, roles, settings, friendly names, branding, two-step sign-in, API tokens) is recorded in Activity with who did it, from which address, on what, and whether it worked.

  • Each entry is also written to the container log as a line of JSON.
  • The log can be copied to S3 every 15 minutes for a SIEM; see Activity log to S3.
  • AWS calls through an assumed role carry the person's name into CloudTrail as the role session delegaris-<username>.
  • Actions taken with an API token are recorded under the token owner's name, with the token's name.

See Activity log.

API tokens​

API tokens are for scripts and pipelines. See API tokens.

  • Nobody may have tokens until an administrator chooses administrators or everyone. Switching tokens off stops all of them at once.
  • A token is shown once, when it is made. Only a SHA-256 hash is kept.
  • A token acts as the person who made it, with their access as the directory last described them at sign-in. Access rules, approvals and protected resources apply exactly as in the browser.
  • A token reaches the everyday actions only: who am I, listing resources, actions on resources, server groups and bookings. It can never reach settings, rules, accounts or sign-in, and cannot make another token.
  • Tokens can be given an expiry, administrators can revoke anyone's, and the time and address of each token's last use are recorded.

Webhooks and outbound addresses​

Microsoft Teams and webhook addresses entered under Settings > Notifications are checked when they are saved or tested. The address must be http:// or https://, and any address that is, or looks up to, this machine (loopback), a link-local address such as the EC2 metadata service at 169.254.169.254, or an unspecified address is refused. A webhook can therefore not be pointed at the instance's credentials or at the service itself. Addresses on your private network are allowed, so internal receivers work.

When a webhook secret is set, every post carries an X-Delegaris-Signature: sha256=… HMAC of its body, so the receiver can check it came from Delegaris. What a receiver answers is never shown to anyone, only its status code.

Addresses given in the environment (TEAMS_WEBHOOK_URL, WEBHOOK_URL) are taken as the host administrator's choice and are not checked in this way.

Uploaded images​

Branding images are checked to be the file type they claim to be. They are served with their own restrictive Content Security Policy, so an uploaded SVG opened on its own cannot run scripts or load anything.

Least privilege in AWS​

  • The service's own identity needs only sts:AssumeRole on DelegarisRole in other accounts, and read-only access to AWS list prices (pricing:GetProducts). iam/hub-role.yaml adds s3:PutObject on a backup or audit bucket only if you name one.
  • The role in each account allows listing, starting, stopping and tagging only the services you switch on. EC2 and RDS tagging is limited to that account's own resources. kms:CreateGrant is allowed only for grants to AWS services, for starting instances with encrypted volumes. The role trusts only the identity you name, can require an external ID, and its sessions last at most an hour.
  • Permissions are checked at the moment of the action, against the resource's tags in AWS, not against what the browser showed. Re-tagging something takes effect immediately.
  • Protected resources (tagged Delegaris = protected by default) can be started, stopped, rebooted, kept on or re-tagged by administrators only, whatever the rules say. See Protected resources.
  • People cannot approve their own requests. See Approvals.
  • Remote Desktop files contain an address and a user name, never a password.

See Member account role for the exact permissions.

Sharing the host

On EC2, raising the metadata hop limit to 2 lets every container on the instance use the instance role. The role is narrow, but it leads to start and stop rights in your accounts. Do not run containers you do not trust on the same host.