Codumentor logo Codumentor

Security

This guide provides actionable security best practices for production Codumentor deployments. It covers authentication, network configuration, data protection, and operational concerns.

Overview

Codumentor is an AI assistant that interacts with codebases, executes shell commands, and communicates with LLM providers. A production deployment must account for the security implications of each of these capabilities. The recommendations below are organized by area of concern.

Reviewing the design rather than hardening a deployment? See Security Architecture for the process model, the execution sandbox, and the trust boundaries — the document to hand to a security review team.

Authentication

A generated config authenticates by default: auth.provider: "local" with a single admin account whose password is read from CODUMENTOR_ADMIN_PASSWORD. Until that variable is exported the account is disabled, so a fresh install has no usable login rather than an open one. Keep it, or move to a directory-backed provider:

auth.provider: "none" remains available for a single-user machine, but the server refuses to start with it on any bind address other than loopback — an unauthenticated instance on a reachable address hands over conversations, indexed repositories and the agent's shell tools to whoever finds the port. Override only when another boundary genuinely restricts access, with auth.allow_unauthenticated_network_access: true.

See Authentication for configuration details.

Login throttling

Failed logins are throttled per username and per client IP: five consecutive
failures start a 60-second lockout that doubles up to 15 minutes, checked before
the auth provider is contacted (so a guessing run against an LDAP directory stops
producing binds). POST /auth/login is additionally capped at 10 requests per
minute per address. Tune under api.rate_limit — see
Configuration → api.rate_limit. The counters
are in-process, so a multi-worker deployment divides each budget by the worker
count.

Session revocation

Logout invalidates both session tokens server-side, refreshing invalidates the
token it consumed, and deactivating a user or removing a role invalidates every
token they already hold. Nothing to configure; the practical consequence is that
disabling an account takes effect on the next request rather than up to 8 hours
later, and that telling a user to log out of a shared machine is meaningful.

API Security

Bind Address

The API server binds to 127.0.0.1 by default, which means it only accepts connections from the local machine. This is the correct setting for production -- expose the API through a reverse proxy instead of binding to 0.0.0.0. Binding anything else while authentication is off is refused at startup (see Authentication).

api:
  host: "127.0.0.1"
  port: 2638

Reverse Proxy

Place a reverse proxy (nginx, Caddy, etc.) in front of Codumentor to handle:

See Deployment for an nginx configuration example.

HTTPS

Enable HTTPS at the reverse proxy level. Codumentor itself does not handle TLS -- the proxy terminates SSL and forwards requests to the local API server over plain HTTP on the loopback interface.

Shell Tool

The shell tool allows the agent to execute system commands. In production, configure it conservatively:

tools:
  shell_always_allow: false
  shell_timeout: 60

The shell tool executes commands as the user running the Codumentor process. Limit the system privileges of this user to the minimum required.

Data Protection

Conversation Data

Agent conversations and session data are stored in SQLite databases under data/agent_storage/. This data may contain sensitive information from user interactions.

Vector Database

The vector database (data/vector_db/) contains indexed repository content. If your repositories contain proprietary code, protect this directory with appropriate filesystem permissions.

chmod 700 /opt/codumentor/data
chown -R codumentor:codumentor /opt/codumentor/data

Backup Strategy

Include both SQLite databases and the vector database directory in your backup plan. See Deployment for a backup script example.

Plugin Security

Plugins extend Codumentor with additional tools and capabilities. They have full access to the agent runtime, so treat them as trusted code.

Input Validation

Codumentor includes built-in sanitization for user inputs processed by the core tools and API endpoints. However:

Secrets Management

Use environment variable substitution (${VAR_NAME}) for all sensitive values in codumentor.yaml:

models:
  agent_api_key: "${OPENAI_API_KEY}"
  embedding_api_key: "${GOOGLE_API_KEY}"

auth:
  provider: "ldap"
  ldap:
    bind_password: "${LDAP_BIND_PASSWORD}"

Per-User Secrets Plugin

The user_secrets plugin complements deployer-level ${ENV_VAR} substitution with per-user encrypted credentials. Users store named secrets (GitHub PATs, personal API keys, …) via the web UI or TUI; plugins reference them in config with ${secret:<name>}, and the shell tool can receive them as env vars without the LLM ever seeing the value.

See User Secrets plugin for configuration details.

Subprocess Environment Forwarding

Codumentor now uses explicit subprocess environment forwarding by default (including bubblewrap sandboxed commands and worker subprocesses). Child processes do not automatically inherit the full host environment.

Network Security

LDAP Security

When using LDAP authentication:

See Authentication for full LDAP configuration details.

Security Checklist

Use this checklist when preparing a production deployment:

See Also