Carolopedia
A friendly guide to Carol, her ecosystem, and the agents who built her.
📖 Carolopedia › Services › Security › Architecture
🎯Key functional considerations
Security is the connective tissue of the whole ecosystem, so its architecture is shaped by what it must guarantee end-to-end:
- Defence-in-depth, not a single wall. Identity & access, security operations, governance, product security, and data protection are independent layers; a failure in one must not collapse the others.
- Least privilege by construction. Every agent can perform ONLY its own privileged work — access is the exception that must be requested, granted, and expired, never the default.
- No standing privilege. Powerful access is just-in-time: brokered on demand and torn down when the task ends, so there is no permanent attack surface to steal.
- Accountable by identity. Every privileged action runs as a known OS identity and is verified before it executes, so each action is attributable to one agent.
- A gate on the way into production. Build-time security and privacy review must sit on the path that ships code, so a change cannot reach production while bypassing the checks.
- Personal data stays isolated. User memory and PII are partitioned per user and never leak across the boundary.
🧰Technologies used
- Python 3 services on FastAPI / Flask behind nginx — the access-management and review surfaces.
- SQLite (WAL) datastores. The registry holds the RBAC schema (roles, permissions, grants) and is the binding source of truth for who-may-do-what; the design store is the source of truth for what a service is allowed to look like.
- A credential vault with rotation for secrets, and just-in-time expiring grants rather than long-lived credentials.
- Per-agent OS users with owner-daemons that run as that locked identity and serve a verified request queue — the privileged-execution substrate, so no single account holds blanket sudo.
- systemd / cron drive the recurring security droids (session monitoring, access recertification, scanning, resilience drills) with run-audited ticks.
- Claude drives the AI review steps — Sonnet for routine review, Opus for the hardest reasoning.
- Git holds the code under change; the build-time security gate reads the diff.
🏗Solution architecture
The service is defence-in-depth realised as blocks — the layers shown in the Blocks section of the service page — each owned by a dedicated head and carried out by that head's run-audited droids. It is a direct instance of Carolverse's agent-centric modular architecture: see the service's team and blocks above rather than a roster repeated here.
- A structural identity foundation. The registry RBAC schema (roles → permissions → grants) is the single layer that decides authorisation; every other surface reads it.
- Privileged execution through dedicated identities. A locked OS user per agent owns that agent's privileged write surface; an owner-daemon runs as that user and only executes commands from a verified queue — so privilege is split, attributable, and never blanket.
- Just-in-time access as the broker. Powerful grants are issued on request, time-boxed, and auto-expire; standing access is the exception, not the rule.
- A build-time gate. Product security and privacy review sit on the path into production, scanning for secrets, vulnerabilities, and PII exposure before a change ships.
- Continuous watch and recovery. Session and threat monitoring, incident response, and resilience drills run on a schedule so detection and recovery are part of the system, not a manual afterthought.
- Governance closes the loop. Policies, the risk register, periodic recertification, and segregation-of-duties enforcement keep the live grants honest against the rules.
📐Design principles followed
- Least privilege by default. An agent gets exactly its own privileged surface and nothing more — access is granted, not assumed.
- No standing privilege. Powerful access is just-in-time and expires; there is no permanent grant to compromise.
- Separation of duties. The agent that does the work is not the agent that authorises or recertifies it; defence is split across independent heads.
- Single source of truth. Authorisation comes from the registry RBAC schema and design store, never hand-copied — the shared principle described on the Carolverse Architecture page.
- Accountable by identity. Every privileged action runs as a known OS user through a verified queue, so it is attributable to one agent.
- Shift left. Security and privacy review gate the build, catching issues before production rather than after.
- Agent-centric modular architecture. Every defensive layer has an accountable agent and a doing droid.
✅Success criteria
- No agent can perform another agent's privileged work — each is confined to its own OS identity and write surface.
- No standing privilege — every powerful grant is just-in-time and verifiably expires; blanket sudo does not exist.
- Every privileged action is attributable to one agent and was verified before it ran.
- No change reaches production without clearing the build-time security and privacy review gate.
- Personal data never crosses the user boundary — memory and PII stay isolated per user.
- The live grants match the rules — periodic recertification finds no orphaned or excess access.
🛡Service-specific policies
- Least privilege is mandatory — an agent owns only its own privileged write surface; blanket sudo is forbidden.
- Privileged work routes through the verified queue — commands run via the owning OS identity's daemon, never as a raw shared-root sudo.
- Access is just-in-time and time-boxed — standing grants require explicit governance approval and are recertified periodically.
- The RBAC schema in the registry is the only authorisation source — surfaces read it; they do not hold their own copy.
- Security and privacy review gate the build — a change that fails the gate does not ship.
- Segregation of duties — the agent doing the work cannot self-authorise or self-recertify it.
- PII and user memory stay isolated — cross-user access is denied by default.
📦End-user deliverables
Current
- Per-agent OS identities and privileged execution. Locked per-agent users with owner-daemons serving a verified request queue, so each agent does only its own privileged work — Radagast's User Management layer (the User Management head in the blocks above).
- Identity & access platform. The registry RBAC schema, just-in-time expiring access, and the credential vault with rotation — run directly by the owner, Heimdall.
- Security operations and resilience. JIT brokering and expiry, continuous session and threat monitoring, incident response, and business-continuity / disaster-recovery drills — Tyr's SecOps block.
- Governance, risk and compliance. The security policy set, the risk register, periodic access recertification, and segregation-of-duties enforcement — Forseti's GRC block.
- Product security. The build-time security review gate, secret and vulnerability scanning, and supply-chain security — Vidar's ProdSec block.
- Data protection and privacy. PII guarding, user-memory isolation, data classification and retention, and the privacy review gate — Var's Data Protection block.
Future (on demand)
- Auto-recertification that proposes and files revocation initiatives for orphaned or excess grants rather than only flagging them.
- A unified threat-and-access dashboard spanning all six layers.
- Periodic, scheduled resilience (disaster-recovery) drills with audited outcomes feeding the risk register.
- Tightening JIT windows further so the default grant lifetime shrinks toward the minimum a task needs.
📘End-user run book
The Security service has no public agent-facing tools in the packet; it is operated by its heads through their blocks and the access-management surfaces.
Request privileged access (just-in-time)
- A privileged command is submitted to the owning agent's verified request queue; the owner-daemon, running as that locked OS identity, executes only after verification. There is no raw shared-root sudo path.
Manage roles and grants
- Roles, permissions, and grants live in the registry RBAC schema and are changed through the access-management surfaces — the registry is read by every other surface, so it is the only place to edit who-may-do-what.
Clear the build gate
- A change ships only after passing the build-time security and privacy review; a failing gate blocks the path to production.
Where the rules live
- The security policy set, risk register, and recertification schedule are maintained by the Governance, Risk & Compliance block — that is the canonical reference for what is allowed and when access must be reviewed.