Wildbox Security Policy & Best Practices

Maturity: Early Evaluation Phase

This page states the security requirements and practices Wildbox aims for. Where the code does not meet them yet, the gap is listed under “Known Open Issues” in the Security status.

Quick Navigation

Critical Security Requirements

Before Production Deployment

Do not deploy Wildbox to production before completing the requirements below.

1. Environment Variables Configuration

Generate .env with random values for every secret, then check it:

make generate-secrets    # scripts/generate_secrets.py, writes .env with mode 0600
make validate-secrets    # refuses placeholders and known weak values

Then set the values that describe your deployment: INITIAL_ADMIN_EMAIL and CORS_ORIGINS (your HTTPS origins only). Do not write secrets by hand or copy them from documentation.

2. Critical Security Variables

The Credentials guide lists every generated value and what it protects. The most sensitive are:

Variable Description Security Level
JWT_SECRET_KEY Signs every login token CRITICAL
API_KEY_HASH_SECRET Keys the HMAC of stored API keys CRITICAL
GATEWAY_INTERNAL_SECRET Proves to the backends that a request came through the gateway CRITICAL
INITIAL_ADMIN_PASSWORD Password of the first administrator CRITICAL
POSTGRES_PASSWORD, REDIS_PASSWORD Datastore passwords CRITICAL
CSPM_CREDENTIAL_KEY Encrypts stored cloud credentials CRITICAL

3. Password Security Requirements

  • Change the first administrator’s password after the first login
  • Use long, unique passwords for every account
  • Rotate secrets with scripts/rotate_secrets.sh, which knows which ones depend on each other

4. Secure Key Generation

scripts/generate_secrets.py uses Python’s secrets module and refuses to emit a value that the services’ own validators would reject. To rotate one secret later, use ./scripts/rotate_secrets.sh --secret <NAME>.

5. Production Security Checklist

  • .env generated by make generate-secrets and accepted by make validate-secrets (Wildbox has no default passwords; a placeholder left in .env is the equivalent)
  • The first administrator’s generated password changed after the first login
  • Environment variables properly configured
  • CORS origins restricted to your domains only
  • DEBUG mode disabled (DEBUG=false)
  • HTTPS enabled for all public endpoints
  • Database access restricted to application only
  • Firewall rules configured
  • Regular security updates scheduled
  • Backup strategy implemented
  • Log monitoring configured
  • Intrusion detection enabled

6. Network Security

Required Firewall Rules

  • Port 22: SSH access (restrict to admin IPs only)
  • Port 443: HTTPS through the gateway (public)
  • Port 80: optional; it answers /health and redirects everything else to HTTPS
  • All other ports: blocked from external access

PostgreSQL and Redis publish no port, and every other service is bound to 127.0.0.1 by docker-compose.yml, so the firewall needs no rule for them. Do not change those bindings: Docker’s own iptables rules can bypass a host firewall. The Deployment guide has the commands.

SSL/TLS Configuration

  • Use Let’s Encrypt or commercial SSL certificates
  • Enable HTTP to HTTPS redirect
  • Configure strong cipher suites
  • Enable HSTS headers

7. Database Security

PostgreSQL

The stack keeps three databases: identity (the default POSTGRES_DB), and guardian and data, created by scripts/init-databases.sql on PostgreSQL’s first start. As shipped, every service connects as the postgres superuser with POSTGRES_PASSWORD. PostgreSQL publishes no port, and in the production configuration only the services that use it can reach it.

A role per service, limited to its own database, narrows what a compromised service can reach. Wildbox does not create such roles; if you add them, give each service its own database URL in .env (DATABASE_URL for identity, GUARDIAN_DATABASE_URL, DATA_DATABASE_URL). For example, for guardian:

CREATE ROLE wildbox_guardian WITH LOGIN PASSWORD '<generated password>';
GRANT CONNECT ON DATABASE guardian TO wildbox_guardian;
-- then, connected to the guardian database:
GRANT USAGE ON SCHEMA public TO wildbox_guardian;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO wildbox_guardian;

Migrations create and alter tables, so the role that runs them at start-up needs more than these grants.

Redis Security

  • Authentication is on: Redis requires REDIS_PASSWORD, which the generator creates
  • No published port: Redis is reachable only on the Compose network
  • Keep noeviction; see Redis memory for why

8. Application Security

Authentication

What Wildbox enforces (details in Authentication and sessions):

  • Access tokens last 30 minutes, with no refresh token
  • Logout revokes the token at identity and at the gateway
  • Account lockout: 5 failed password logins lock an email for 15 minutes

What it does not provide, so plan around it:

  • No multi-factor authentication: restrict who can reach the gateway
  • No email verification requirement at login: limit who can register

API Security

  • Rate limiting enabled on all endpoints
  • API key rotation every 90 days
  • Input validation on all user inputs
  • SQL injection protection via parameterized queries

9. Monitoring & Logging

Required Monitoring

  • Authentication failures
  • Unauthorized access attempts
  • Database connection anomalies
  • High resource usage
  • Service health status

Log Requirements

  • Centralized logging (ELK stack, Splunk, etc.)
  • Log retention policy (minimum 90 days)
  • Log integrity protection
  • Automated alerting on security events

10. Backup & Recovery

Backup Strategy

  • Daily automated backups of all databases
  • Encrypted backup storage
  • Off-site backup replication
  • Regular restore testing
  • Recovery time objective: < 4 hours
  • Recovery point objective: < 1 hour

11. Incident Response

Preparation

  • Document incident response procedures
  • Define roles and responsibilities
  • Establish communication channels
  • Create contact lists for emergencies
  • Regular tabletop exercises

12. Compliance Considerations

Depending on your use case, ensure compliance with:

  • GDPR (EU data protection)
  • SOC 2 (security controls)
  • ISO 27001 (information security)
  • NIST Cybersecurity Framework
  • Industry-specific regulations

13. Managing Dependency Vulnerabilities

How dependencies are kept free of known advisories:

  • Python: every service installs from a hash-pinned requirements.txt compiled from requirements.in (make lock). make lock-security (scripts/upgrade_vulnerable_requirements.sh) moves only the packages with a known advisory, and the weekly Pip Security Upgrades workflow opens a pull request with the result. Dependabot does not handle pip.
  • npm, Docker base images and GitHub Actions: Dependabot opens the update pull requests.
  • Gates: PR Validation fails a pull request that introduces a critical advisory; the Main Advisories workflow checks main daily and keeps one issue open while any critical advisory is present.

The current state is on the Security status page and in the repository’s Dependabot alerts.

Your deployment:

  • Rebuild the images after every update; they are built from the repository, so pulling the code alone changes nothing that is running (see Updating).
  • Subscribe to GitHub Security Advisories and the releases page.
  • Test updates in staging before production.

Security Features Implemented

1. Authentication & Authorization

  • JWT tokens signed with HS256 (minimum 32-character secret), valid for 30 minutes, without refresh
  • Revocation on logout: the gateway refuses the token’s jti on every worker and the jti is blacklisted in Redis; logout answers 503 rather than success if either cannot be confirmed
  • Failed-login lockout: 5 failures lock an email for 15 minutes
  • Password hashing with Argon2id through fastapi-users’ PasswordHelper; see Authentication and sessions
  • Bearer token authentication on all protected endpoints
  • API keys, stored as HMAC-SHA256 digests
  • Team roles (owner, admin, member) and platform superusers

2. API Security

  • Restricted CORS at the gateway (the origins in CORS_ORIGINS, never a wildcard)
  • Security headers: HSTS, X-Frame-Options, X-Content-Type-Options, CSP
  • Input validation on all endpoints
  • Parameterized queries (no SQL injection)
  • XXE protection (defusedxml)
  • Rate limiting at the gateway, per client address and per team

3. Code Security

  • No eval() calls (secure JSON serialization)
  • No hardcoded secrets in code
  • No plaintext password logging (the initial administrator password is no longer printed)
  • Secure random generation for tokens/keys
  • Error handling without exposing internals

4. Infrastructure Security

  • Secrets required (no defaults in docker-compose)
  • Environment-based configuration
  • TLS/SSL support
  • Network segmentation in the production configuration (docker-compose.prod.yml; verified in CI, see the Security status)
  • Health checks configured
  • Monitoring hooks ready

Security Incident Contacts

If you discover a security vulnerability, follow SECURITY.md:

  1. Do not create a public issue
  2. Report it privately on GitHub (new advisory), or by email to fabrizio.salmi@gmail.com
  3. Include detailed reproduction steps
  4. Provide your contact information
  5. Allow 48 hours for an acknowledgment

Bug Bounty Program

We value security researchers. Valid vulnerability reports receive:

  • Critical: Recognition
  • High: Recognition
  • Medium: Recognition
  • Low: Acknowledgment

Additional Resources

History of This Page

The first versions of this page (September and November 2025) carried a list of the fixes made at the time. Security changes since then are recorded release by release in CHANGELOG.md, and what is still open is on the Security status page.