Security
This page explains how Stacklane protects accounts and data, what you should do as an operator, and how to report a vulnerability.
Security model#
Accounts and roles#
Every user belongs to one organization. The organization owns the resources, invoices and API tokens. Within an organization, a user has one of these roles:
| Role | Access |
|---|---|
administrator | Full access, including users and roles |
engineer | Manages resources |
billing | Invoices and company details |
viewer | Read only |
Every customer endpoint limits its queries to the organization of the caller. A customer cannot see or change another organization's data.
Platform staff have a separate staff role: owner, admin, billing or support. Back-office endpoints require a staff role. Only owner and admin can change platform settings. The last owner cannot lose the role.
Passwords#
- Passwords must be 10 to 128 characters long.
- Passwords are hashed with Argon2id. Stacklane stores only the hash.
- When someone signs in with an email address that has no account, Stacklane still runs a password check, so the response time does not show which accounts exist.
- Sign-up and password reset give the same answer whether or not an account exists.
- A password reset signs out all sessions of the user.
Sessions#
When a user signs in, Stacklane creates a session and returns two things:
- An access token. A JWT signed with HS256, with a key derived from the secret key. It is valid for
security.access_token_minutes(10 minutes by default). The browser keeps it in memory and sends it in theAuthorizationheader. - A refresh cookie. It is
HttpOnlyandSameSite=Strict. Whenpublic_urluseshttps, the cookie is alsoSecureand its name has the__Host-prefix.
Every access token names its session. Stacklane checks on every request that the session still exists and the user is still active. When a user signs out, or an administrator removes a session, the access token stops working at once.
When the access token expires, the browser uses the refresh cookie to get a new one:
- Each refresh replaces the refresh secret with a new one. A refresh secret works only once. A reused secret is rejected.
- Refresh and sign-out requests must come from the same origin as
public_url. Stacklane checks theOriginheader, orSec-Fetch-Sitewhen there is noOrigin. - A session can be refreshed for
security.session_days(30 by default). After that, the user must sign in again.
Only a SHA-256 hash of the refresh secret is stored. Expired sessions are removed every hour.
Users can see their active sessions and their sign-in history in the portal.
Two-factor authentication#
Users can turn on two-factor authentication with a TOTP authenticator app. They get 10 recovery codes when they set it up.
- After a correct password, Stacklane returns a single-use challenge instead of a session. The challenge is valid for 5 minutes and allows 5 attempts.
- Each TOTP code works only once. Stacklane stores the last used time step and rejects a code that was already used.
- Recovery codes are stored as hashes and work only once.
- TOTP secrets are encrypted with the secret key.
An organization administrator can require two-factor authentication for all users of the organization. Users without two-factor authentication must then set it up before they can use the portal.
If a user loses both the app and the recovery codes, a server administrator can remove two-factor authentication with stacklane user reset-two-factor.
API tokens#
Users can create personal API tokens for scripts and integrations. A token has a role and an optional expiry date, and can be revoked.
- Clients send the token as
Authorization: APIKey <id>$<secret>. - The secret is shown once. Stacklane only stores a SHA-256 hash of it and compares hashes in constant time.
- A token belongs to the organization, not to a session. It does not need two-factor authentication.
See API for details.
Rate limits#
Stacklane limits how often some actions can be done. Limits are counted per client IP address, per account or per organization.
| Action | Limit |
|---|---|
| All API requests | 1200 per minute per IP address |
| Sign-in | 30 per 10 minutes per IP address, and 10 per 15 minutes per account and IP address |
| Failed sign-ins | After 100 failed attempts for one account, sign-in to that account is blocked until the 15-minute window ends |
| Two-factor codes | 20 per 10 minutes per IP address, and 10 per 15 minutes per account |
| Sign-up | 6 per hour per IP address |
| Password reset and verification email | 10 per 15 minutes per IP address, and 3 per hour per email address |
| Password changes, two-factor changes, new recovery codes, signing out other sessions, showing a hosting account password | 10 per 10 minutes per user |
| New support tickets | 20 per hour per organization |
| Domain availability searches | 60 per 10 minutes per organization |
| Payments | 20 per 10 minutes per organization |
| Payment and DDoS webhooks | 300 per 5 minutes per IP address |
| Control panel sign-in | 30 per 10 minutes per organization |
A request over the limit gets 429 Too Many Requests. The counters are kept in memory and reset when Stacklane restarts.
The panel also protects itself against overload:
- request bodies are limited to 256 KiB
- requests time out after 30 seconds
- above 1024 open requests, new requests get
503at once instead of waiting in a queue
These limits do not stop a large network attack. Use network-level DDoS protection in front of the panel.
Web interface#
- The web interface is served with a strict Content Security Policy. Scripts and styles must come from the panel itself or carry a nonce that changes on every request.
- The policy includes
frame-ancestors 'none', and Stacklane sendsX-Frame-Options: DENY, so the panel cannot be shown in a frame. - All assets use Subresource Integrity.
- Every response has
X-Content-Type-Options: nosniff,Referrer-Policy: same-origin,Cross-Origin-Opener-Policy: same-originand aPermissions-Policythat turns off camera, microphone, geolocation and payment. - API responses have
Cache-Control: no-storeandContent-Security-Policy: default-src 'none'; frame-ancestors 'none'. - When
public_urluseshttps, every response hasStrict-Transport-Security: max-age=63072000; includeSubDomains.
Secrets at rest#
Stacklane encrypts these secrets with XChaCha20-Poly1305, using a key derived from the secret key:
- Proxmox API tokens
- hosting panel credentials
- registrar passwords
- payment provider keys
- the PowerDNS API key
- the DDoS webhook secret
- two-factor secrets
- generated passwords of instances and hosting accounts
The API never returns these secrets after they are saved.
Payments and webhooks#
- Payment webhooks are treated as notifications only. Stacklane does not trust their content. It looks up the payment and asks the provider for its status.
- Settlement is idempotent and runs in one database transaction, so a payment is never booked twice.
- DDoS detector events must be signed with HMAC-SHA256 using the webhook secret. Stacklane rejects requests with a wrong signature or a timestamp more than five minutes old.
Audit log#
Every change writes an audit record with:
- the organization
- the user or API token that made the change
- the source IP address and user agent
- the event name
- the trace ID
Failed sign-ins and failed two-factor codes are also recorded. Organization administrators can read the audit log of their organization in the portal.
The trace ID comes from an incoming W3C traceparent header when there is one. Stacklane returns it in the X-Trace-Id response header. Use it to find the matching log lines and audit records.
Database access#
All database queries use static SQL with bound parameters. The Rust code forbids unsafe blocks.
Hardening recommendations#
Network#
- Keep
server.listenon127.0.0.1. Never expose the HTTP port to the internet. - Put a reverse proxy with TLS in front of Stacklane and use an
httpsaddress inserver.public_url. See Installation. - Set
server.behind_proxy = trueonly when all traffic comes through your proxy. - Use a firewall on the server. Allow only the ports of your proxy and SSH.
- Use network-level DDoS protection for the panel.
- Leave the webhook paths reachable:
/api/billing/v1/webhooks/for payment providers and/api/network/v1/ddos/eventsfor your DDoS detector.
Secret key and backups#
- Do not change the owner or mode of
/etc/stacklane/secret.key(stacklane:stacklane,0600). - Back up the key, but not in the same place as the database backups, or encrypt your backups. Anyone with both can read all stored credentials.
- Keep
/etc/stacklane/stacklane.tomlreadable only byrootand thestacklanegroup. It contains the SMTP password. - Test your restore procedure. See Operations.
Accounts#
- Turn on two-factor authentication for every staff account.
- Give staff the lowest role they need. Use
supportorbillinginstead ofadminwhere you can. - Keep at least two
owneraccounts, so you do not lose access when one person is not available. - Turn off public sign-up in Administration → Platform settings if you do not want customers to create accounts themselves.
- Keep Require a verified email address turned on.
- Remove staff roles from people who leave, with
stacklane user staff --role noneor in the back office.
Integrations#
- Give the Proxmox API token, panel accounts and registrar accounts only the permissions Stacklane needs.
- Use TLS for the connections to Proxmox, the hosting panels and your SMTP server. Keep the PowerDNS API on a private network.
- Rotate integration secrets when someone with access leaves.
Operations#
- Never enable
cloud.simulateorbilling.simulateon a production system. - Install security updates of the operating system.
- Upgrade Stacklane when a new version comes out. Security fixes are released for the latest minor version only.
- Do not weaken the systemd sandbox. If you need changes, use a drop-in file and keep the sandbox settings.
- Review the audit log for
iam.auth.login_failedevents, and watch your proxy log for many429responses.
Reporting a vulnerability#
Do not open public issues for security problems. Use the Report a vulnerability button on the Security tab of the Stacklane repository on GitHub. Include:
- the affected version or commit
- a description and the impact
- steps to reproduce
You get an answer within three working days. You are kept informed until a fix is released.
Supported versions#
Security fixes are released for the latest minor version.
Scope#
In scope:
- the
stacklanebinary - its API and web interface
- the Debian package and systemd unit
Out of scope:
- third-party services that Stacklane connects to
- deployments that expose the HTTP port without TLS