Security best practices for rostr.

rostr requires all secrets to be stored in environment variables. The application will refuse to start if it detects secrets in config.yaml.

Required variables:

# For Uptime Kuma integration
export ROSTR_UPTIMEKUMA_DB_PASS='your-secure-password'

# For registration API
export ROSTR_REGISTRATION_TOKEN='your-secure-token'

The following files should never be committed to version control:

• .env
• config.yaml (use config.yaml.example as template)
• Any file containing passwords, tokens, or API keys

rostr automatically detects these patterns in config.yaml:

• db_pass:
• password:
• token:
• secret:
• api_key:

If detected with non-empty values, rostr exits with an error.

rostr assumes SSH key-based authentication. Never use passwords in automation.

# Generate SSH key if needed
ssh-keygen -t ed25519 -C "rostr"

# Copy to servers
ssh-copy-id user@server

Generated SSH config should have restricted permissions:

chmod 600 ~/.rostr/generated/ssh_config
chmod 700 ~/.rostr/generated

For automation (audit-os), rostr uses -o StrictHostKeyChecking=no. For interactive use, maintain proper host key verification.

Recommended permissions:

chmod 700 ~/.rostr
chmod 600 ~/.rostr/config.yaml
chmod 600 ~/.rostr/inventory/groups/*.yaml
chmod 700 ~/.rostr/generated
chmod 600 ~/.rostr/generated/*
chmod 700 ~/.rostr/backups
chmod 700 ~/.rostr/logs

IMPORTANT: The registration API listens on port 8888. Proper firewall configuration is critical.

Option 1: Private Network (Recommended)

If your rostr server and n8n are on the same private network, no firewall changes needed.

Option 2: Public Server with Firewall

WARNING: If your rostr server is on a public network, you MUST whitelist your n8n server's IP.

# UFW - allow only n8n server
sudo ufw allow from <n8n-server-ip> to any port 8888

# iptables
sudo iptables -A INPUT -p tcp -s <n8n-server-ip> --dport 8888 -j ACCEPT

NEVER expose port 8888 to the entire internet. Unauthorized access could allow attackers to register malicious servers in your inventory. Always restrict to your n8n server's IP address only.

All /register requests require the X-Registration-Token header.

Restrict which groups can be registered via API:

export ROSTR_ALLOWED_GROUPS='production,staging'

Implement rate limiting in your webhook service, not in rostr.

When you run rostr setup monitoring, it installs Docker in rootless mode:

• No root daemon - Docker daemon runs as your user, not root
• User namespace isolation - Container processes map to unprivileged UIDs
• Reduced attack surface - Container escape has limited impact
• No sudo required - Manage containers without elevated privileges

• Never use sudo with rootless Docker commands
• Container UID 1000 maps to a high host UID (100999+)
• ICMP ping requires slirp4netns (installed automatically)

• Use strong passwords (32+ characters)
• Never expose MariaDB port to public
• Rootless Docker provides additional isolation

# Generate strong password
openssl rand -base64 32

# Store in environment file (not committed)
echo 'ROSTR_UPTIMEKUMA_DB_PASS=...' >> ~/.config/rostr/env
chmod 600 ~/.config/rostr/env

When using git sync:

• Use SSH keys for git authentication
• Never commit secrets
• Review commits before pushing

If using a private repository:

• Limit access to authorized users
• Review access periodically

For sensitive inventories, encrypt backups:

# Create encrypted backup
rostr backup
gpg -c ~/.rostr/backups/latest.csv
rm ~/.rostr/backups/latest.csv

Store encrypted backups offsite:

• Cloud storage (encrypted)
• Separate server
• Local encrypted drive

Logs contain:

• Operation timestamps
• Hostnames and IPs
• Error messages

Logs do NOT contain:

• Passwords
• Tokens
• SSH keys

Implement log rotation:

# Example logrotate config
/home/user/.rostr/logs/*.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
}

Restrict access to:

• Registration API (port 8888) - private network only
• Uptime Kuma (port 3001) - as needed
• MariaDB (port 3306) - localhost only

Use HTTPS for:

• Webhook endpoints
• Uptime Kuma web interface

rostr update

Or for pipx:

pipx upgrade rostr

Periodically update dependencies:

cd ~/.rostr
pip install --upgrade -e .

If registration token is compromised:

1. Generate new token: openssl rand -hex 32
2. Update environment variable
3. Restart registration API
4. Update webhook service
5. Review registration logs

If SSH key is compromised:

1. Generate new key pair
2. Revoke old key on all servers
3. Deploy new key
4. Audit for unauthorized access

When using rostr setup automation:

• Tokens are auto-generated (64 hex characters)
• Stored in config.yaml and systemd service
• Displayed once during setup - save securely

Generated templates include:

• Your SSH public key
• Registration token
• Webhook URL

Store templates securely - they contain authentication credentials.

The registration API runs as a systemd user service:

• No root privileges required
• Runs in your user context
• Logs to ~/.rostr/logs/api.log

Regular security audit:

• Secrets in environment variables only
• No secrets in version control
• File permissions correct
• SSH keys are ED25519 or RSA 4096
• Registration API on private network
• Strong tokens/passwords (32+ chars)
• Logs reviewed for anomalies
• Dependencies updated
• Backups encrypted and tested