Security Best Practices

Securing your OpenCodeHub instance is critical, especially when exposing it to the internet.

1. HTTPS is Mandatory

In production, never run OpenCodeHub over HTTP. Git operations and login credentials must be encrypted.

• Use a reverse proxy (Nginx, Caddy, Traefik) to handle SSL/TLS.
• See the Deployment Guide for Nginx configuration.
• Set SITE_URL to your HTTPS domain.

2. Generate Strong Secrets

Do not use the default secrets from .env.example.

Generate new 64-character hex secrets for:

• JWT_SECRET
• SESSION_SECRET
• INTERNAL_HOOK_SECRET
• CRON_SECRET
• RUNNER_SECRET
• WORKFLOW_SECRET_ENCRYPTION_KEY
• AI_CONFIG_ENCRYPTION_KEY

openssl rand -hex 32

3. Database Security

• Do not expose your database port (5432) to the public internet.
• Ensure the database user has limited privileges if possible (though migrations require DDL permissions).
• Enable SSL connections to the database by appending ?sslmode=require to your DATABASE_URL.
• Use PostgreSQL for production (not SQLite).
• Enable automated backups.

4. Rate Limiting

OpenCodeHub includes built-in rate limiting.

• Auth: 5 attempts / 15 min
• API: 100 requests / min
• Git: 200 operations / min

You can adjust these in .env if you have a large team behind a NAT, but be careful.

Enable with:

RATE_LIMIT_ENABLED=true

Skip in dev (not recommended for production):

RATE_LIMIT_SKIP_DEV=false

5. CSRF Protection

CSRF protection is enabled by default via double-submit cookie pattern.

• All state-changing operations (POST/PUT/PATCH/DELETE) require a valid CSRF token.
• The token is rotated per session.
• API clients using Bearer tokens are exempt (they use Authorization header instead).

6. Branch Protection

Enable Branch Protection on main for all repositories to prevent:

• Force pushes.
• Deleting the branch.
• Merging without review.
• Merging without passing CI.

Configure in Repository → Settings → Branches:

• Required PR reviews: 1-2
• Required status checks: CI pipeline names
• Dismiss stale reviews: enabled
• Include administrators: optional

7. Private Mode

If your instance is private:

1. Disable public registration by setting ENABLE_REGISTRATION=false (or use invite-only mode).
2. Set default repository visibility to private.
3. Require authentication for all Git operations (HTTP and SSH).

8. Webhook URL Validation

OpenCodeHub validates all outbound webhook URLs to prevent Server-Side Request Forgery (SSRF):

• Blocks private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Blocks localhost (127.0.0.1, [::1])
• Blocks link-local addresses
• Validates URL format and scheme (only http/https)

9. Secret Scanning

OpenCodeHub scans commits for accidentally committed secrets:

• API keys
• Passwords
• Private keys
• Database connection strings

When found, the push is rejected with a message indicating which file and line contained the secret.

10. Personal Access Tokens (PATs)

For API and Git access, use PATs instead of passwords:

1. Go to User Settings → Personal Access Tokens
2. Generate a new token with specific scopes
3. Use the token as the password for Git HTTPS operations
4. Use Authorization: Bearer <token> for API requests

PATs can be revoked individually without changing your password.

11. SSH Key Management

For Git SSH access:

1. Add your public key in Settings → SSH Keys
2. Use SSH URLs for cloning: [email protected]:owner/repo.git
3. Deploy keys (read-only or read-write) can be added per-repository

12. Content Security Policy (CSP)

OpenCodeHub sets strict CSP headers to prevent XSS attacks:

• default-src 'self'
• script-src 'self' 'unsafe-inline' (required for Astro hydration)
• style-src 'self' 'unsafe-inline'
• img-src 'self' data: https:
• connect-src 'self'

Review src/middleware.ts for the full CSP configuration.

13. Audit Logging

All security-relevant actions are logged:

• Login attempts (success and failure)
• Password changes
• Token creations and revocations
• Repository access changes
• Admin actions

Access logs via:

• Admin Panel → Audit Log
• API: GET /api/admin/audit-logs

14. Dependency Security

Keep dependencies up to date:

npm audit
npm audit fix

Consider enabling automated dependency updates via Dependabot or Renovate.

15. Incident Response

If you suspect a security incident:

1. Rotate all secrets immediately (JWT_SECRET, SESSION_SECRET, etc.)
2. Revoke all PATs and ask users to regenerate
3. Check audit logs for unauthorized access
4. Review recent admin actions
5. Force password resets for affected users

See Incident Runbook for detailed procedures.

Security Checklist

Before going live:

• All secrets regenerated (not using defaults from .env.example)
• HTTPS enabled with valid SSL certificate
• Rate limiting enabled
• Database using SSL connections
• Branch protection rules configured
• Public registration disabled (if private instance)
• Storage backend is external (S3/GCS/Azure), not local
• Backup strategy in place
• Audit logging enabled
• Admin users configured with strong passwords + 2FA

10. Accepted Risks (Tracked Vulnerabilities)

OpenCodeHub's CI runs bun run security:audit on every change. The script
fails the build when a new disallowed high/critical advisory is detected.
A small number of advisories are explicitly allow-listed under
known-accepted-vulns.json when the only
remediation is a breaking dependency migration. Each entry below carries
the rationale, mitigation, and planned removal date.

10.1 astro (high)

Advisories: GHSA-xxxx, GHSA-yyyy — XSS, header reflection, and
cache-poisoning advisories affecting the Astro 4.x line. Fix versions
are 5.14+/6.x which require a coordinated breaking migration of every
@astrojs/* adapter (node, react, vercel, tailwind) and a
codebase audit for removed APIs.

Why we accept the risk:

• All affected code paths are in the dev/build toolchain (Astro dev
  server, build-time transforms), not in the production runtime handler
  that we ship as dist/.
• The most severe advisories (server-island XSS, X-Forwarded-Host
  reflection) only apply to features OpenCodeHub does not use.
• We deploy behind a reverse proxy that strips/normalises the Host
  header, mitigating the SSRF-class advisories.
• We run CI with a read-only build worker; the build process never
  serves user input back to itself.

Mitigations applied:

• Production runs behind a hardened reverse proxy (Nginx/Caddy) that
  sets Host to a known value and rejects malformed X-Forwarded-*
  headers.
• Build artifacts are not served from the host that built them; CI
  produces a static dist/ that is deployed to a separate runtime.
• CSP middleware rejects any request whose Host header disagrees
  with SITE_URL.

Removal plan:

• Track migration under issue #N in github-roadmap-issues.json.
• Target: Astro 5 → Astro 6 over two minor release windows.
• Re-evaluate after each upstream Astro patch release.

10.2 nodemailer (high)

Advisories: Requires update to [email protected] (breaking change).
Why we accept the risk:

• OpenCodeHub uses nodemailer for outbound transactional emails (password resets, notifications).
• The vulnerability likely involves an edge case in attachment handling or SMTP response parsing which we do not rely on heavily or which requires an authenticated SMTP server to exploit.
• Updating to v9 is a major breaking change that requires auditing our email templates and SMTP configurations.

Mitigations applied:

• Outbound SMTP connections are configured to only trust strict TLS where possible.
• User-supplied input is sanitized before inclusion in email bodies.

Removal plan:

• Audit nodemailer v9 breaking changes and upgrade in the next minor release window.

10.3 undici (high)

Advisories: Requires update to undici (non-breaking patch available, but blocked by transient dependencies).
Why we accept the risk:

• undici is a sub-dependency of our toolchain (astro, @opentelemetry, etc.).
• Modifying sub-dependencies via overrides can lead to unstable lockfiles in a complex monorepo.
• The vulnerabilities typically involve SSRF or DoS in fetch operations, which we mitigate natively via our own url-validator.ts for webhooks and outbound requests.

Mitigations applied:

• OpenCodeHub uses its own strict SSRF validation for webhooks.
• Production fetch calls to external resources are tightly bounded.

Removal plan:

• Wait for upstream packages (astro, etc.) to bump their undici dependency and update naturally.

10.4 vite (high)

Advisories: Requires update to [email protected] which includes a newer vite version.
Why we accept the risk:

• Similar to the astro vulnerability, Vite is used in the build toolchain.
• The runtime application is served from pre-built static assets and optimized server handlers, not the Vite dev server.

Mitigations applied:

• The Vite dev server is only used in local development, not in production.
• Production builds (npm run build) produce static outputs.

Removal plan:

• This will be resolved alongside the Astro 6/7 migration.

10.5 How to add or remove an entry

1. Edit docs/administration/known-accepted-vulns.json (accepted array).
2. Add the corresponding section above with the rationale, mitigations,
   and target date.
3. Open a tracking issue referencing the GHSA IDs.
4. Re-run bun run security:audit locally to confirm CI parity.