Skip to main content

Security hardening

FleetAMP remains a community-preview project. These controls make a single-instance enterprise proof of concept safer; they do not constitute a production security certification.

Application safeguards​

FleetAMP now provides:

  • localhost-only default HTTP and OpAMP listeners
  • one-time first-login administrator setup
  • Argon2id password verifiers with unique salts and a per-server pepper
  • server-bound, TPM-capable encrypted systemd credentials
  • HttpOnly, SameSite=Strict authenticated session cookies
  • bearer-token authentication for OpAMP connections
  • native TLS for the web UI/API and OpAMP WebSockets
  • optional mutual TLS for OpAMP client-certificate verification
  • startup rejection of remote listeners missing required protection
  • constant-time credential comparison
  • same-origin checks for mutating browser requests
  • configurable request-body limits
  • restrictive browser security headers
  • HTTP read, write, idle, header and shutdown timeouts
  • generic client-facing errors for internal failures
  • public /health and /ready endpoints for load-balancer probes

OIDC, role-based authorization, per-team permissions, certificate-to-agent authorization mapping and formal audit controls remain future work.

First-login administrator setup​

On the first start, FleetAMP creates a cryptographically random setup token that expires after 15 minutes. Retrieve it from the local systemd journal:

# System service
sudo journalctl -u fleetamp -g bootstrap_token --since "15 minutes ago"

# User service
journalctl --user -u fleetamp -g bootstrap_token --since "15 minutes ago"

Open https://fleetamp.example.com/setup, enter the token, and create the first administrator. Use a unique password of at least 16 characters. The setup token is erased after use, and subsequent requests to /setup are redirected to the login page.

FleetAMP never stores or decrypts the password. It stores an Argon2id verifier created from the password, a unique salt, and the local server pepper. Sessions expire after 12 hours and are lost when FleetAMP restarts. Set FLEETAMP_SECURE_COOKIES=true behind HTTPS. An unused bootstrap token is also held only in memory, so every restart invalidates it and creates a replacement until the administrator has been configured.

Fedora Origin: null troubleshooting​

Some local browser or forwarding configurations submit the setup form with Origin: null even when the address bar shows http://localhost:8080/setup. FleetAMP accepts this only when the target hostname and network peer are both loopback and the browser reports a same-origin or same-site request. A null origin for a public hostname or remote peer remains blocked.

If the page reports request origin is not allowed, confirm the diagnostic:

journalctl --user -u fleetamp --since "10 minutes ago" -o cat | \
  grep origin_rejected | tail

Use one hostname consistently, refresh /setup, and retrieve the token created after the most recent restart. Do not add null to FLEETAMP_ALLOWED_ORIGINS; the built-in loopback check is intentionally more restrictive.

Server-bound pepper​

The systemd unit loads an encrypted credential named fleetamp-server-pepper. With host+tpm2, systemd binds it to both the host installation key and TPM2. Copying the SQLite database and encrypted credential to another server will not produce a working login.

sudo install -d -m 0700 /etc/credstore.encrypted
head -c 48 /dev/urandom | base64 | sudo systemd-creds encrypt \
  --with-key=host+tpm2 --name=fleetamp-server-pepper \
  - /etc/credstore.encrypted/fleetamp-server-pepper
sudo chmod 0600 /etc/credstore.encrypted/fleetamp-server-pepper

Use --with-key=host on a server without TPM2. This remains installation-bound but lacks hardware binding. Losing the pepper makes existing administrator credentials unusable, so use an approved recovery design without storing the plaintext pepper beside the database.

Runtime configuration​

Keep independent OpAMP credentials outside Git:

FLEETAMP_HTTP_ADDR=0.0.0.0:8080
FLEETAMP_OPAMP_ADDR=0.0.0.0:4320
FLEETAMP_OPAMP_TOKEN=<at-least-32-random-characters>
FLEETAMP_ALLOWED_ORIGINS=https://fleetamp.example.com
FLEETAMP_SECURE_COOKIES=true
FLEETAMP_HTTP_TLS_TERMINATED=true
FLEETAMP_OPAMP_TLS_TERMINATED=true
FLEETAMP_MAX_REQUEST_BODY_BYTES=1048576

Only transmit login and OpAMP credentials through HTTPS/WSS. Use FleetAMP's native TLS support or terminate TLS at a trusted reverse proxy/load balancer. See TLS and Mutual TLS for native TLS, mTLS, certificate storage, and verification.

AWS proof-of-concept pattern​

Use an isolated AWS account or non-production VPC:

  1. Put the FleetAMP EC2 instance in a private subnet without a public IP.
  2. Use AWS Systems Manager Session Manager instead of opening SSH publicly.
  3. Terminate HTTPS/WSS on an Application Load Balancer with an ACM certificate.
  4. Publish the test hostname in Route 53.
  5. Forward UI/API traffic to port 8080.
  6. Forward /v1/opamp WebSocket traffic to port 4320.
  7. Configure the OpAMP target group's health-check port as 8080 and path as /health.
  8. Allow instance ports 8080 and 4320 only from the ALB security group.
  9. Restrict ALB port 443 to the enterprise test network, VPN or approved source ranges.
  10. Store the OpAMP token in AWS Secrets Manager or encrypted SSM Parameter Store. Protect the server pepper with systemd credentials backed by the instance TPM where available.

Do not expose 8080 or 4320 directly to the internet. Enable ALB access logging, CloudTrail, GuardDuty and operating-system patching according to the enterprise baseline.

OpAMP client authentication​

The agent or Supervisor must send:

Authorization: Bearer <FLEETAMP_OPAMP_TOKEN>

Configure this header through the supported OpAMP client settings and retrieve the token from a protected secret source. A missing or incorrect token is rejected with HTTP 401 before the WebSocket session is accepted.

Rotate the token by updating the server secret and clients through a controlled change window. Current FleetAMP supports one active OpAMP token, so seamless dual-token rotation is not yet available.

Operating-system controls​

The reference systemd unit:

  • runs under a dedicated unprivileged account
  • denies privilege escalation and Linux capabilities
  • uses a private temporary directory and device namespace
  • protects the host filesystem, kernel settings, modules and control groups
  • restricts address families to Unix, IPv4 and IPv6
  • makes only FleetAMP state and log directories writable
  • creates new files with a restrictive 0077 mask

Validate the installed unit with:

systemd-analyze security fleetamp.service
systemctl status fleetamp
journalctl -u fleetamp --since "1 hour ago"

Verification​

Before setup, unauthenticated browser access redirects to /setup. Afterwards, it redirects to /login:

curl -sSI https://fleetamp.example.com/agents
curl -sSI https://fleetamp.example.com/setup

The REST API returns 401 Unauthorized without a valid session. Complete login through the browser and confirm that the session cookie has Secure, HttpOnly, and SameSite=Strict attributes.

Confirm security headers:

curl -sSI https://fleetamp.example.com/agents

Check for Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Referrer-Policy and Permissions-Policy.

Remaining limitations​

Before production use, FleetAMP still needs OIDC integration, RBAC, approval separation, auditable user identity, rate limiting at the platform edge, certificate-to-agent authorization, encrypted shared storage, HA support, penetration testing and a documented vulnerability-response process.

For the current enterprise test, use one non-production agent, synthetic data, restricted networking and no production secrets in Collector configuration.