Skip to content

Security: Spooled-Cloud/spooled-backend

Security

SECURITY.md

Security Policy

Reporting a Vulnerability

We take security seriously. If you discover a security vulnerability, please report it responsibly.

How to Report

Please do NOT report security vulnerabilities through public GitHub issues.

Instead, please report them via email to:

πŸ“§ security@spooled.cloud

Or use GitHub's private vulnerability reporting feature if available.

What to Include

Please include the following information:

  1. Description of the vulnerability
  2. Steps to reproduce the issue
  3. Potential impact of the vulnerability
  4. Suggested fix (if you have one)
  5. Your contact information for follow-up

What to Expect

  • Acknowledgment: Within 48 hours of your report
  • Initial Assessment: Within 7 days
  • Status Updates: Every 7 days until resolution
  • Resolution Timeline: Typically within 90 days

Disclosure Policy

  • We will work with you to understand and resolve the issue
  • We will credit you in the security advisory (unless you prefer to remain anonymous)
  • We ask that you do not publicly disclose the issue until we've had a chance to address it

Security Best Practices

When deploying Spooled Backend, please follow these security guidelines:

Configuration

  • JWT_SECRET: Use a strong, random secret (minimum 32 characters)
    openssl rand -base64 32
  • Database Passwords: Use strong, unique passwords
  • RUST_ENV: Set to production in production environments

gRPC TLS Key Material

Never deploy with a key pair taken from this repository or its history. Releases before 2026-10-12 shipped a development key pair under certs/; it is public and must not protect any deployment. The production Compose file generates a fresh key pair in a private Docker volume on first start; other platforms should generate one outside Git and provide it through their secret manager.

Network Security

  • Run behind a reverse proxy with TLS for REST API (:8080)
  • Use TLS termination for gRPC (:50051) via envoy, nginx, or cloud load balancers
  • Use network policies to restrict database access
  • Don't expose metrics endpoint publicly
  • Configure appropriate CORS settings

Database Security

  • Use SSL for database connections in production
  • Apply principle of least privilege for database users
  • Enable PostgreSQL audit logging

Redis Security

  • Use Redis AUTH in production
  • Don't expose Redis to the internet
  • Consider using TLS for Redis connections

API Security (REST & gRPC)

  • Rotate API keys regularly
  • Use short-lived JWT tokens
  • Implement proper rate limiting
  • Validate and sanitize all inputs
  • Send REST credentials in the Authorization: Bearer header. Query-string credentials (?api_key=, ?token=) are rejected with 401 on every REST endpoint except the four realtime routes β€” /api/v1/ws, /api/v1/events, /api/v1/events/jobs/{id}, /api/v1/events/queues/{name} β€” where browser EventSource and WebSocket cannot set headers. Query strings are captured by reverse-proxy and CDN access logs, tracing spans, browser history and the Referer header, and API keys do not expire by default (CWE-598)
  • Prefer a short-lived JWT over an API key on the realtime routes, and treat any key that has appeared in a URL as compromised
  • Behind a reverse proxy, set TRUSTED_CLIENT_IP_HEADER or TRUSTED_PROXY_HOPS so per-IP rate limiting sees the real client. The leftmost X-Forwarded-For entry is caller-supplied and is never trusted. Without TRUSTED_CLIENT_IP_HEADER, CF-Connecting-IP and X-Real-IP are believed only when the TCP peer is a loopback, private, link-local or unique-local address, so a client that reaches the backend directly cannot choose its own rate-limit bucket; an IPv6 client is limited as its whole /64
  • Email login codes are throttled per client IP (POST /auth/email/start: 3 per minute and 10 per hour) and per address (5 guesses per 10 minutes per client, 20 from all clients); set TURNSTILE_SECRET_KEY to also require a Cloudflare Turnstile token on POST /auth/email/start
  • Stripe Checkout sessions are created by POST /api/v1/billing/checkout and trusted through server-set metadata only; the client_reference_id of a public Payment Link is a URL parameter and cannot be trusted to name an organization
  • For gRPC API-key authentication, send the API key credential as the value of the x-api-key metadata field; x-api-key is the metadata name, not a separate credential
  • Alternatively, send a JWT credential as authorization: Bearer <jwt-token> metadata
  • gRPC health and reflection services are public by default (disable in production if needed)

Container Security

  • Run as non-root user (already configured in Dockerfile)
  • Use read-only filesystem where possible
  • Scan images for vulnerabilities
  • Keep base images updated

Security Features

Spooled Backend includes several security features:

  • Multi-tenant isolation enforced in the application layer: every query filters on the authenticated organization_id (RLS policies exist in the migrations but are inert at runtime β€” see docs/guides/architecture.md)
  • Header-only REST credentials, so keys and tokens stay out of access logs and Referer headers
  • Bcrypt password hashing for API keys (used by both REST and gRPC)
  • JWT authentication with configurable expiration
  • Rate limiting per API key
  • HMAC webhook verification for incoming webhooks
  • Input validation on all endpoints (REST and gRPC)
  • Constant-time comparison for sensitive data
  • Security headers via middleware
  • Queue-scoped authorization across REST, realtime, and gRPC operations
  • Stream revalidation so key revocation, expiry, organization deletion, and scope narrowing take effect on active realtime/gRPC streams
  • gRPC interceptors for authentication and authorization
  • gRPC health service for load balancer health checks
  • SSRF protection for outgoing webhook URLs

SSRF Protection

Outgoing webhook URLs are validated in production to prevent Server-Side Request Forgery attacks:

  • ❌ Private IP ranges (RFC 1918: 10.x.x.x, 172.16-31.x.x, 192.168.x.x)
  • ❌ Loopback addresses (127.x.x.x, localhost, ::1)
  • ❌ Link-local addresses (169.254.x.x, fe80::)
  • ❌ Cloud metadata endpoints (169.254.169.254, metadata.google.internal)
  • ❌ Internal hostnames (.local, .internal, .corp, .lan)
  • ❌ HTTP URLs (HTTPS required in production)
  • ❌ CGNAT ranges (100.64.0.0/10)

DNS resolution is also validated to prevent DNS rebinding attacks.

Vulnerability History

Security fixes are documented in CHANGELOG.md. Deploy the latest release and review GitHub security advisories before operating an internet-facing instance.


Thank you for helping keep Spooled Backend and its users safe!

There aren't any published security advisories