Security
Security model
This page describes what Kelvar protects, how, and where its limits are. It is written for security teams who need to decide whether to run Kelvar against their code.
#Principles
- Read-only by default. Guards connect with read access. Write-back is a separate application that you opt in to.
- Deny by default. A run has no authority beyond its grant, and a process has no access beyond what its descriptor declares.
- Fail closed. When a check cannot run, Kelvar stops with a clear error. It does not return a placeholder.
- Record everything. Every crossing of a boundary, including refusals, is a row in the append-only ledger.
- Trust verifiers, not models. A fact is marked true only after a deterministic check passes.
#Where your data goes
| Data | Where it lives | Who can read it |
|---|---|---|
| Source code and files | Read in place, on your machine, by tools in a sandbox | The agent's tools, limited to admitted paths |
| File contents an agent reads | Sent to the model provider you chose | That provider, under its terms |
| Findings, runs and the ledger | Your Home directory, ~/.vigil by default | You |
| GitHub and provider tokens | Your Home, passed to the process that needs them | That process |
Kelvar does not send your code anywhere except to the model provider you connect. For a fully local setup, use a local model. See Bring your own model.
#Trust boundaries
The kernel admits requests, forms grants and writes the ledger. It knows nothing about specific providers, tools or models, so it has no code path that treats one vendor differently.
Interfaces are the only way anything enters or leaves. Each is a process with its own descriptor, started with a cleared environment inside a sandbox.
Rooms are where an agent's tools act. A room enforces the operation-level grant itself, so a model cannot argue its way past it.
The model is untrusted. Its output is a request, never a right. What a run may do is computed from descriptors and never read back from anything a model wrote.
#Threats and mitigations
| Threat | Mitigation |
|---|---|
| Prompt injection from content in a repository | Agents hold only the tools their grant allows. A read-only audit has no write or execute tool to misuse, so injected instructions have nothing to act on. |
| Overreach by an agent | The grant is recomputed on every arrival, and a request outside it is refused and recorded. |
| Sandbox escape through a path | A path outside the permitted roots is refused before a tool runs. Processes start with cleared environment and deny-by-default access. |
| Credential leakage | Tokens go to the process that needs them. They are not part of the instructions given to an agent. |
| A model claiming something false | Marks come from verifiers. A claim without a passing verifier stays a claim. |
| Silent failure | Refusals and failed verifications are ledger rows. |
#The combination to avoid
A run that reads untrusted content, holds a tool that can write or execute, and can reach private data is the dangerous combination. Kelvar's default agents avoid it. Audit agents read and do not write. The patch agent writes in an isolated worktree and does not publish. Keep to that separation when you create your own agents. See Permissions and sandboxing.
#Limits you should know
- Marks are narrow. A mark states that one verifier passed. It does not certify that an agent behaved well.
- The model provider sees what the agent reads. Choose it accordingly.
- Sandboxing targets macOS today. On a platform where separate read, write and execute roots cannot be enforced, Kelvar refuses to start the process instead of running it unsandboxed.
- Cloud scanning is a preview. The AWS, Google Cloud and Azure applications answer pings and do not scan. Kelvar makes no claims about live cloud accounts.
- The local API is unauthenticated. It binds to loopback by default. See API reference.
- The built-in scanner is a first pass. It uses a small advisory list and line patterns. See Scanner checks.
#Reporting a vulnerability
Report security issues to the Kelvar team privately, with the version and steps to reproduce. Please do not include your ledger, Home directory or tokens in the report.
#Compliance
Kelvar helps you produce evidence. The ledger records what ran, what was refused and what was verified, which supports audit requests for SOC 2, ISO 27001 and PCI DSS. Kelvar is not itself certified, and using it does not make your organization compliant.