Administration on PosternProxy Documentation

Security Hardening

Mon, 01 Jan 0001 00:00:00 +0000

Security Hardening#

The PosternProxy install script applies a comprehensive set of security hardening measures. This page documents what is applied and how to verify it.

Application-level hardening#

Authentication#

JWT access tokens with 15-minute TTL
Refresh tokens with 7-day TTL stored in HttpOnly / Secure / SameSite=Strict cookies
bcrypt password hashing at cost factor 12
Login rate limit: 5 attempts/min per IP (enforced by the API and by fail2ban)
Account lockout is not time-based — use fail2ban to block IPs

API security#

Rate limiting: 120 requests/min per IP on authenticated management API routes; 5 login attempts/min per IP; 30 agent WebSocket connection attempts/min per IP
CSRF protection: Double-submit cookie pattern on all state-changing requests
Secure headers on all responses:
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- Strict-Transport-Security: max-age=31536000; includeSubDomains
- Content-Security-Policy: default-src 'self'
Input validation: All user input validated at the handler layer; domain names validated per RFC 1123; ports validated 1–65535; CIDRs parsed and validated; all database queries use parameterized statements (no SQL interpolation)

Encrypted storage#

DNS provider credentials and SSH credentials are encrypted at rest using AES-256-GCM with a key derived from the JWT secret.

Upgrading

Mon, 01 Jan 0001 00:00:00 +0000

Upgrading PosternProxy#

Upgrading the controller#

Build the new binary on your development machine:
```
bash scripts/build.sh
```
Copy the binary to the server:
```
scp posternproxy user@your-server:/tmp/
```

Stop the service, replace the binary, restart:

ssh root@your-server
systemctl stop posternproxy
cp /tmp/posternproxy /usr/local/bin/posternproxy
systemctl start posternproxy

Verify the service started:

systemctl status posternproxy
journalctl -u posternproxy -n 20

Database migrations#

PosternProxy runs embedded migrations automatically on startup. If a new version adds database columns or tables, the migration runs before the service starts serving requests. No manual intervention is needed.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting#

Service not starting#

PosternProxy fails to start#

journalctl -u posternproxy -n 50 --no-pager

Common causes:

Symptom	Cause	Fix
`database is locked`	Another PosternProxy instance is running	`systemctl stop posternproxy; systemctl start posternproxy`
`migration failed`	Bad database state	Restore from backup
`address already in use :81`	Another process owns port 81	`ss -tlnp \| grep 81` to find it
`config.env not found`	Missing config file	Re-run `scripts/install.sh` or create manually

Caddy fails to start#

journalctl -u caddy -n 50 --no-pager
caddy validate --config /etc/caddy/Caddyfile # if using Caddyfile fallback

Common causes: