Security¶

KITT includes a security layer for its distributed agent architecture and web API. This covers mutual TLS (mTLS) for agent-server communication, automatic certificate generation, and bearer token authentication for the REST API.

Mutual TLS (mTLS)¶

When KITT agents communicate with the KITT web server, both sides authenticate each other using TLS certificates. This prevents unauthorized agents from connecting and ensures the agent is talking to the legitimate server.

Certificate Chain¶

KITT uses a three-tier certificate chain:

CA certificate -- A self-signed Certificate Authority generated by KITT. This is the root of trust.
Server certificate -- Issued by the CA, used by the KITT web server to prove its identity to agents.
Client certificate -- Issued by the CA, used by each agent to prove its identity to the server.

Both the server and client certificates are signed by the same CA, so each side can verify the other.

Automatic Certificate Generation¶

The cert_manager.py module in security/ generates all certificates automatically when the KITT stack is initialized. No manual OpenSSL commands or external CA infrastructure is required.

# Certificates are generated when starting a stack with the agent component
kitt stack generate my-stack --web --agent
kitt stack start --name my-stack

Certificates are stored in the stack's configuration directory and are mounted into the relevant containers.

CA Fingerprint¶

The CA certificate's SHA-256 fingerprint is displayed when the stack starts. Agents can use this fingerprint to verify they are connecting to the correct server, providing an out-of-band verification mechanism.

Bearer Token Authentication¶

The KITT REST API supports bearer token authentication for programmatic access. This is simpler than mTLS and is intended for direct API usage (scripts, CI pipelines, dashboards).

Configuration¶

Set an authentication token when starting the web server or agent:

# Web server with auth token
kitt web --auth-token my-secret-token

# Agent with auth token
kitt agent start --auth-token my-secret-token

API requests must include the token in the Authorization header:

Authorization: Bearer my-secret-token

Requests without a valid token receive a 401 Unauthorized response.

Note: The agent installation endpoints (/api/v1/agent/install.sh and /api/v1/agent/package) do not require authentication, allowing agents to be bootstrapped from within the network without a token. Authentication is enforced once the agent registers with the server.

Development Mode¶

For local development and testing, security can be relaxed with the --insecure flag:

kitt web --insecure
kitt agent start --insecure

This disables TLS certificate verification and token authentication. The --insecure flag should never be used in production or on untrusted networks.

Cryptography Dependency¶

The TLS certificate generation requires the cryptography Python package, which is an optional dependency. Install it via the web extra:

poetry install -E web

This extra also installs Flask and other web-related dependencies. The cryptography package is not needed for core KITT functionality (running benchmarks, fingerprinting, results management).

Summary¶

Feature	Use Case	Configuration
mTLS	Agent-server communication	Automatic via `cert_manager.py`
Bearer token	REST API access	`--auth-token` flag
Insecure mode	Local development	`--insecure` flag

Next Steps¶

Architecture -- overall system design including the agent and web components
Engine Lifecycle -- how engines run within the secured infrastructure