Architecture

kilasec is a network-layer firewall for AI traffic. It sits between the agents that want to make API calls and the providers that serve them, decides what's allowed, and forwards the decision (not the payload) to a cloud control plane.

The two halves

              ┌────────────────────────────────────────────────────────────┐
              │  CUSTOMER NETWORK                                          │
              │                                                            │
   ┌────────────────┐   HTTPS_PROXY     ┌──────────────────────┐           │
   │  agent host    │ ────────────────► │  collector (LAN)     │           │
   │  laptop /      │  http://lan:8080  │                      │           │
   │  container /   │   + mitm CA       │  mitmproxy :8080     │           │
   │  pod           │                   │  PDP :8000 (loopback)│           │
   └────────────────┘                   │  PAC :9443           │           │
              │                          └──────┬───────────────┘           │
              │                                 │ decisions only            │
              │                                 │ (no raw payload)          │
              └─────────────────────────────────┼───────────────────────────┘
                                                │
                                                ▼  HTTPS outbound
                                       ┌─────────────────────┐
                                       │   kilasec.com       │
                                       │                     │
                                       │  Caddy (TLS, route) │
                                       │  cloud.app :8000    │
                                       │   /api/v1/ingest/*  │
                                       │   /api/audit /me…   │
                                       │                     │
                                       │  SQLite (per-tenant)│
                                       └─────────────────────┘
                                                ▲
                                                │  HTTPS, session cookie
                                                │
                                       ┌─────────────────────┐
                                       │  admin browser      │
                                       │  /app/ (React SPA)  │
                                       └─────────────────────┘

Collector (on-prem)

• mitmproxy on :8080 — terminates TLS for agent traffic. The first time a client connects, mitmproxy mints a per-connection cert signed by a CA the collector generated on first run. That CA must be trusted on every agent host that goes through the proxy.
• PDP (Policy Decision Point) on 127.0.0.1:8000 — a small FastAPI app that loads policies.yaml and answers POST /evaluate with {action, matched_rule, reason, redacted_args, matched_paths}. Bound to loopback only — never exposed to the LAN.
• PAC server on :9443 — serves the proxy auto-config to DHCP clients. Cert signed by the collector's own mitmproxy CA so the customer never needs a separate certificate authority.
• Cloud uplink — POSTs decisions to /api/v1/ingest/events (and /api/v1/ingest/usage, /api/v1/ingest/agents). One-way: cloud does not call into the collector.

Two lanes onto the collector (devices running Kilasec Connect)

On endpoint devices, the Kilasec Connect client gives traffic two lanes into the same collector and the same policy engine — which lane a request takes changes how it's carried, never whether it's inspected:

	Proxy lane (mitm)	AI-gateway lane (CA-free)
Who uses it	Browsers, desktop apps, anything steered by the OS proxy	AI CLIs / SDKs that honor ANTHROPIC_BASE_URL / OPENAI_BASE_URL
Transport	HTTPS via local proxy :3128; TLS re-terminated with the tenant CA	Plain HTTP on loopback :3129 to the local gateway, which holds ONE upstream TLS connection
CA required on device	Yes (tenant inspection CA)	No — no forged certs, nothing in any trust store
Typical overhead	~2 extra TLS handshakes per fresh connection	~single-digit ms

The gateway is an optimization, not the enforcement boundary: a tool that misses the gateway environment (a shell opened before the agent, a GUI app) falls back to the proxy lane and is inspected identically. Connect's shell hook self-heals stale terminals onto the gateway at their next prompt, and the menu-bar app surfaces when recent AI traffic took the slow lane.

Cloud (kilasec.com)

• Caddy — TLS termination, request routing. Routes /api/* to localhost:8000, /auth/invite/* for onboarding, /install for the collector installer, /app/* for the SPA, root for marketing.
• cloud.app on :8000 — FastAPI. Receives ingest, serves the read API, handles invite redemption and session cookies.
• SQLite — per-tenant tables (events, usage_records, agent_profiles, tenants, collectors, invites, identities, …). Tenant isolation is enforced at every endpoint via Depends(get_tenant_id).
• SPA — React app at /app/. Cookie-authed, talks to the same-origin API via fetch("/api/…").

What crosses the on-prem / cloud boundary

This boundary matters more than any other architectural detail.

Crosses (collector → cloud):

• Verdict (allow / deny / redact / require_approval / log)
• Matched rule name + reason
• Agent identity (name, optional hostname, principal_type, source IP)
• Destination (host / tool / model)
• Method + URL
• For redact: the paths that were masked, never the values
• Workload attribution (process / container / pod) when the eBPF host sensor is running
• Token counts + estimated cost (when collector emits usage)

Never crosses:

• Authorization / x-api-key / Bearer values — scrubbed by the collector before the event is shipped (only a fingerprint may remain).
• Request bodies (prompt/tool content is replaced with a size stub unless the operator explicitly opts in via AGENTFW_SHIP_PROMPT_CONTENT).
• The TLS-inspection CA private key — held tenant-side, not reconstructable from what the cloud stores.

This means the cloud UI cannot reconstruct the raw conversation between an agent and a provider. It can only tell you that a request happened, what kind, to where, with what verdict.

→ See On-prem / cloud boundary for the full list and why it's drawn where it's drawn.

Auth model

Two distinct credential types. They are not interchangeable.

Token	Who holds it	Used for
Tenant API token (agt_…)	One per tenant, stored on the cloud VM	The "default" credential before collectors are enrolled. Carried by the legacy ingest path.
Per-collector token (agt_collector_…)	Each collector, in /etc/kilasec/collector.env	All ingest after enrollment. Lets you revoke one collector without rotating the others.
Session cookie	Browser, set when a user signs in via /auth/invite/{code}	All SPA → API calls. httpOnly so JS can't read it.

Cloud get_tenant_id() resolves any of these to the same tenant_id, checking a token first (Authorization: Bearer, then X-Api-Token) and falling back to the session cookie when no token is present.

Identity model

A source's name is derived by walking a chain of signals, strongest first:

0. Verified agent token — the kilasec_agent package sends a minted token the collector verifies against the cloud. The only authenticated name in the chain.
1. Manual admin override (saved in the cloud identities table)
2. Directory/DHCP-pushed identity
3. Reverse DNS at the collector
4. mDNS / Bonjour on the LAN
5. x-agentfw-agent request header (self-declared)
6. Parsed User-Agent (claude-cli, openai-python, browser, …)
7. AGENTFW_AGENT env var (default unknown_agent)

The display name is resolved at query time, so renames apply retroactively. Audit rows store the raw facts (source_ip, hostname at event time) immutably.

→ Full details: Identity model.

What the system does not do

• It doesn't terminate connections at the cloud — only at the on-prem collector. The cloud sees post-fact decisions, never live traffic.
• It doesn't run the policy engine in the cloud. Each tenant's policy is authored in the cloud and pulled by their collectors, but evaluation happens on the collector, inline. Cloud only knows what got matched.
• It doesn't hold customer secrets. Provider API keys stay on the customer's host; only fingerprints / decisions / redaction trails reach the cloud.

Those are deliberate. They let kilasec ship a security product without becoming a new high-value target on the customer's network.