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.

Authentication

Always enable authentication in production. The default auth.provider: "none" setting is intended for local development only.

• For teams with an existing Gitea instance, use the "gitea" provider.
• For enterprise environments, use the "ldap" provider to integrate with Active Directory or OpenLDAP.
• For a small team without an external directory, use the "local" provider (username/password users in config) — store passwords as ${ENV_VAR} references or pbkdf2_sha256$ hashes, never plaintext in a committed file.
• Restrict access to specific groups using LDAP's require_group setting.
• Set auth.jwt_secret (from an env var) in any networked deployment: it keeps login sessions stable across restarts and encrypts the per-user secret / model-profile / OAuth stores at rest. Without it those stores are written in plaintext.

See Authentication for configuration details.

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.

api:
  host: "127.0.0.1"
  port: 2638

Reverse Proxy

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

• TLS termination (HTTPS)
• Request rate limiting
• Access logging
• Additional security headers (X-Content-Type-Options, Content-Security-Policy, X-Frame-Options)

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

• shell_always_allow: false -- Requires explicit approval before each shell command. This is the default and the recommended setting for any deployment where the API is accessible to multiple users.
• shell_timeout -- Limits how long a single command can run. The default hard cap is 900 seconds (15 minutes); configure a lower value if your workloads don't need long-running commands.

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.

• Restrict filesystem permissions so that only the Codumentor service user can read these files.
• Back up the databases regularly.
• Consider the data retention implications for your organization.

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.

• Only enable plugins you trust. Review the source code of any third-party plugin before enabling it.
• Audit plugin configurations. Plugins can accept arbitrary arguments in codumentor.yaml. Verify that plugin configurations do not expose sensitive data or grant excessive permissions.
• Plugins are not sandboxed. A misbehaving plugin can crash the application or access any data available to the process. The built-in plugins are tested and maintained as part of the project, but custom or third-party plugins carry additional risk.

Input Validation

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

• Custom plugins should validate their own inputs. The plugin framework does not enforce input validation on plugin-provided tools.
• Be aware that LLM-generated tool calls are subject to the same validation as user inputs, but adversarial prompts could attempt to craft unexpected tool arguments.

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}"

• Never commit API keys, passwords, or tokens to configuration files that are checked into version control.
• Use systemd EnvironmentFile, a .env file excluded from version control, or a secrets manager to inject values at runtime.
• If a secret is accidentally committed, rotate it immediately.

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.

• Secrets are encrypted at rest with Fernet. The key is derived from auth.jwt_secret — protect that secret as you would any root credential. Rotation is supported via previous_jwt_secrets; rotated rows are re-encrypted lazily on next read.
• The agent transcript never contains the resolved value under the default binding mode. Values only enter the LLM context if an individual binding opts in with expose_to_agent: true.
• Mode C (expose_to_agent) is process-global. It sets os.environ for the duration of the turn and restores prior state on exit. This is safe for a single-user CLI/TUI deployment but not for multi-user API deployments with concurrent turns, because os.environ is shared across asyncio tasks. Keep it off in production unless turns are serialised or a library genuinely needs the env var.
• Enable the plugin via codumentor.plugins.user_secrets.UserSecretsPlugin and grant user_secrets:manage (already part of power_user and admin roles).

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.

• Default behavior forwards only a minimal baseline (PATH, HOME, LANG, TERM).
• Forward additional values (including specific secrets) by exact name using plugin config allowlists such as sandbox.inherit_env_vars.
• Avoid broad inheritance patterns; prefer narrow per-variable opt-in.
• Legacy full inheritance is available only via explicit compatibility mode (env_mode: inherit_all) and should be treated as a security tradeoff.

Network Security

• Run Codumentor behind a firewall. Only expose the reverse proxy port (typically 443) to the network.
• Restrict LLM server access. If you are running a self-hosted LLM server, ensure it is only accessible from the Codumentor host. Bind the LLM server to 127.0.0.1 or use firewall rules to block external access.
• Use SSH tunnels for remote LLM servers. When the LLM server is on a different machine, forward the port over SSH rather than exposing it on the network. See LLM Server Setup for details.

LDAP Security

When using LDAP authentication:

• Use ldaps:// (LDAP over SSL) for the server_url. Avoid unencrypted ldap:// in production.
• Validate certificates. Keep validate_cert: true (the default). Only disable certificate validation for testing.
• Use a service account with minimal privileges. The bind DN used by Codumentor should only have permission to search users and read group memberships. It should not have write access to the directory.
• Protect the bind password. Always use ${LDAP_BIND_PASSWORD} substitution and provide the password through an environment variable.

See Authentication for full LDAP configuration details.

Security Checklist

Use this checklist when preparing a production deployment:

• Authentication provider is set to "gitea", "ldap", or "local" (not "none")
• auth.jwt_secret is set from an environment variable (persistent sessions + encrypted secret stores)
• API server is behind a reverse proxy with HTTPS
• API binds to 127.0.0.1, not 0.0.0.0
• shell_always_allow is false
• All API keys and passwords use ${ENV_VAR} substitution, or ${secret:<name>} when the credential is per-user
• No secrets are committed to configuration files in version control
• Data directories have restricted filesystem permissions
• LLM server (if self-hosted) is not accessible from the public network
• LDAP uses ldaps:// with certificate validation enabled
• Only trusted plugins are enabled
• Log rotation is configured
• Backups are scheduled for SQLite databases and vector database

See Also

• Authentication -- Authentication provider configuration
• Deployment -- Production deployment checklist
• Configuration -- Full configuration reference