Skip to content

security-hardening.mdx

Latest commit

 

History

History
147 lines (104 loc) · 7.15 KB

security-hardening.mdx

File metadata and controls

147 lines (104 loc) · 7.15 KB
title Security & Hardening
description Secure secrets, TLS, and operational access before running Pullbase in production.

Pullbase manages critical infrastructure. Follow these guidelines to reduce risk when operating at scale.

Secret management

  • Store PULLBASE_JWT_SECRET, PULLBASE_WEBHOOK_SECRET_KEY, and database credentials in your secret manager (AWS Secrets Manager, HashiCorp Vault, etc.). Inject them into Docker at runtime rather than committing them to disk.
  • Mount GitHub App private keys from a read-only path (/config/github-app.pem) and restrict filesystem permissions so only the Pullbase container can read them.
  • Rotate agent tokens regularly. Tokens are hashed at rest, but compromised tokens allow full configuration access for that server.
  • Use unique credentials per environment when possible.

TLS configuration

Pullbase supports two approaches for securing connections:

Option 1: Native TLS

Pullbase can handle TLS directly without a reverse proxy:

PULLBASE_TLS_ENABLED=true
PULLBASE_TLS_CERT_PATH=/etc/pullbase/certs/server.crt
PULLBASE_TLS_KEY_PATH=/etc/pullbase/certs/server.key

For development, you can rely on Pullbase to auto-generate self-signed ECDSA P-256 certificates when TLS is enabled and cert/key files are missing (or use the --generate-dev-certs flag). Never use self-signed certificates in production.

Native TLS is ideal for:

  • Simple deployments without existing reverse proxy infrastructure
  • Direct agent-to-server communication
  • Reduced architectural complexity

Option 2: Reverse proxy TLS termination

For production environments with existing infrastructure:

  • Deploy a reverse proxy (NGINX, Traefik, Caddy, or cloud load balancer) in front of Pullbase.
  • Terminate TLS at the reverse proxy using CA-signed certificates.
  • Ensure agents connect to the HTTPS endpoint, not the internal HTTP port.
  • Distribute the CA chain to agents if using internal PKI.
  • Set X-Forwarded-Proto: https so secure cookies remain marked Secure even when TLS is terminated upstream.
# Example: NGINX TLS termination
server {
    listen 443 ssl http2;
    server_name pullbase.example.com;
    
    ssl_certificate /etc/ssl/certs/pullbase.crt;
    ssl_certificate_key /etc/ssl/private/pullbase.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
Never expose the internal HTTP port directly to the internet. Agent tokens and user credentials are transmitted in requests.

Agent TLS verification

Agents validate the TLS certificate of the Pullbase server:

  • Set CACERT_PATH to a CA bundle that trusts your certificate.
  • Never enable SKIP_TLS_VERIFY=true in production—it disables certificate validation.
  • Keep CA bundles up to date across your fleet.

Access control

  • Create dedicated viewer accounts for read-only dashboards and audits.
  • Enforce strong passwords (12+ characters with complexity) and rotate admin credentials periodically.
  • Restrict CLI usage to secure workstations. Store admin tokens in environment variables only temporarily.
  • Monitor audit logs (stored in the audit_log table) for suspicious activity. Integrate with your SIEM by streaming logs from the container.
  • CORS policy: In production, only explicitly configured origins (PULLBASE_CORS_ORIGINS) and same-origin requests are allowed. Avoid setting PULLBASE_ENV=development in production—it enables permissive localhost origins.

Database hardening

Pullbase supports SQLite (default) and PostgreSQL. Choose hardening steps based on your deployment.

SQLite (single-instance deployments)

  • Store pullbase.db outside the container on a persistent volume with strict file permissions (chmod 600).
  • Schedule file-level backups (e.g., sqlite3 pullbase.db ".backup /backups/pullbase-$(date +%Y%m%d).db").
  • Enable WAL mode for better concurrency: PRAGMA journal_mode=WAL; (applied automatically by Pullbase).
  • Keep the database file on fast local storage; network-attached storage may introduce latency.

PostgreSQL (high-availability deployments)

  • Enable TLS connections between Pullbase and PostgreSQL. Set PULLBASE_DB_SSLMODE=require or PULLBASE_DB_SSLMODE=verify-full.
  • Grant Pullbase a least-privilege Postgres role (ownership of the pullbasedb database only).
  • Schedule automated backups using pg_dump and test restore procedures.

General

  • Without the database, you lose environment definitions, tokens, and drift history. Test restores regularly.

Network segmentation

  • Place Pullbase in a private subnet behind a load balancer. Expose only port 443 (TLS) via the reverse proxy.
  • Allow outbound connections only to required destinations: your Git provider, webhook endpoints, and package repositories.
  • Restrict inbound traffic between agents and Pullbase using security groups or firewall rules.

Agent security

  • Run agents with minimal privileges. Grant access only to files and services defined in config.yaml.
  • For containerized agents, carefully consider host filesystem mounts—they effectively grant root access.
  • Rotate agent tokens regularly. Create a new token, update the agent, then revoke the old token.
  • Monitor agent status for unexpected disconnections or authentication failures.

Webhook notification security

When configuring notification webhooks for environments:

  • Use HTTPS endpoints only. Pullbase validates TLS certificates by default.
  • Validate webhook source. If your receiving service supports it, verify requests come from your Pullbase server's IP.
  • Keep webhook URLs confidential. Treat them like secrets; leaked URLs could be used for social engineering.
  • Monitor webhook failures. Failed deliveries may indicate network issues or compromised endpoints.

Webhooks are retried 3 times with exponential backoff (1s, 2s, 4s). Configure alerts in your receiving service for gaps in expected notifications.

Logging & monitoring

  • Forward container logs to your log aggregation platform. Use PULLBASE_LOG_FORMAT=json for structured logging.
  • Collect agent logs (especially when running as systemd units) for drift diagnostics.
  • Monitor GitHub App rate limits and webhook delivery failures; increasing poll intervals or adjusting webhook retries can prevent throttling.
  • Consider adding synthetic checks that call /api/v1/healthz to detect API regressions.

Upgrades and patching

  • Pin Pullbase and agent images (pullbaseio/pullbase:vX.Y.Z) to avoid unintended upgrades.
  • Review release notes (GitHub Releases) and test upgrades in staging. Watch migration logs closely.
  • Apply OS patches to hosts running agents—Pullbase focuses on desired state, not OS patch management.
Document your disaster recovery plan: bootstrap steps, database restore procedures, certificate replacement, and token rotation. Regular tabletop exercises help ensure you can rebuild Pullbase quickly if needed.