Repository navigation
Developer Experience
Kairo's security should feel like a superpower, not a set of constraints. The Developer Experience layer (Layer 6) is how Kairo communicates with the developer — not through documentation, not through CI failures after the fact, but in the flow of development itself.
During development (NODE_ENV=development), when the Runtime Sentinel intercepts a security issue, Kairo prints a coaching message to the dev server output.
The message:
- Identifies the specific issue and the handler where it occurred
- Explains what Kairo did about it (the vulnerability is already neutralized)
- Suggests the safer pattern with a one-line example
- Links to relevant documentation
The application continues to run. The vulnerability is already handled. The developer is taught — not blocked.
This approach is deliberate. Security education that interrupts the development flow is ignored. Security education delivered at the moment the mistake was made, with the fix immediately visible, is retained.
Example message format:
[kairo] ✦ /search handler: raw SQL with tainted input detected.
Consider: db.query(sql, [ctx.query.q]) — parameterized queries are auto-secured.
Docs: kairo.dev/taint-tracking
This message won't appear in production. Kairo handled it.
A single line of configuration activates full audit mode, which produces a structured record for every request.
Each audit record covers:
| Field | What it contains |
|---|---|
| entropy | The score and its contributing factors (payload, timing, headers, IP history) |
| lattice | Every authorization decision — which relationships were checked, what resolved |
| redaction | Fields stripped from the response and which Lattice rule caused each |
| taint | Taint paths detected during execution and where they were neutralized |
| ghost | Whether this session hit a ghost route earlier and when |
| patches | Any hot-patch bus applications during this request |
| overrides | Any security layer bypasses active on this route |
Records are written to ./kairo-audit.ndjson by default. They can be forwarded to any log aggregator, SIEM, or observability platform.
Running kairo dashboard from the CLI launches a local web interface. It provides a live view of the application's security state.
Attack surface map — every route in the application, with its risk profile, active layers, intent declaration, and Trust Lattice requirements. Useful for identifying routes with missing intent declarations or unexpectedly broad access requirements.
Intent Graph — the directed graph of service-to-service call relationships. Open trust edges (relationships that exist but have not been declared) are surfaced here.
Encryption coverage — which model fields are encrypted, which are redacted, and which have no protection declared. Coverage gaps are visible immediately.
Taint activity — taint paths detected in the last 24 hours, grouped by handler. A handler that appears frequently in taint detections is a signal that its input handling should be reviewed.
Entropy distribution — the distribution of entropy scores across recent traffic. A rising baseline may indicate persistent low-level scanning activity.
Ghost route hits — frequency and source geography of ghost route hits over time. Useful for identifying IP ranges or geographic patterns in scanning behavior.
When a developer explicitly bypasses a security behavior — marking a route trust: 'none', disabling a layer, or accepting a known risk — they provide a reason string. Kairo records the bypass, the reason, the route, and the timestamp.
These records accumulate in the audit log and are surfaced in the dashboard as a Security Decisions timeline — a human-readable history of every deliberate security trade-off made in the codebase.
This serves two purposes: it makes deliberate bypasses visible during code review and security audits, and it creates a record that can satisfy compliance reviewers asking why a given protection is not active on a specific endpoint.
Files generated by kairo new and kairo generate start with security patterns already in place:
- Route handlers include empty intent declaration slots, ready to fill
-
Model definitions include
encrypted()markers automatically applied to fields whose names match sensitivity conventions:password,ssn,token,secret,key,credit_card, and similar - Auth routes include Trust Lattice identity resolver hooks pre-wired
- Database queries default to parameterized form
The developer edits a scaffold. They never start from a blank, insecure file.
@kairo/mcp exposes Kairo's security telemetry to AI coding tools that support the Model Context Protocol. When connected to Claude Code, it allows the AI to:
- Query the current attack surface map for any route
- Read recent security events (taint detections, ghost hits, entropy spikes)
- Run the fuzzer against specific routes and receive structured findings
- Explain every security decision Kairo is making for a given handler
- Apply available hot patches
- Record a security override with a reason
This means an AI coding assistant working on a Kairo project can understand the security context of the code it is reading and writing — without the developer having to provide that context manually in every session.