lanekeeper-security
Security requirements and proof patterns for Lanekeeper (S1–S25). Covers Entra sign-in and sessions, default-deny authorization, agent and sentinel identity, mTLS and the KMS-backed CA, Secret Manager
SKILL.md.claude/skills/lanekeeper-security/SKILL.md
GitHubLanekeeper security
Security comes first in this project's priorities (D61). The requirements live in docs/security.md. This skill helps you find the ones that apply to your change, implement them the way the rest of the codebase does, and prove each one with a test.
Step 1: Find the requirements that apply
Start with the S# list in your prompt's metadata table, then add any the change touches:
| Change touches | Requirements |
|---|---|
| Routes, handlers, MCP tools | S4 (guard), S11 (validation), S12 (output), S14 (MCP), S14b (redaction) |
| Sign-in, sessions, users, roles | S1, S2, S3, S4 |
| Tokens, keys, webhook URLs, any secret | S7, S8, S21 |
| Audit events | S9 |
| File paths, NFS operations | S11 (NfsPath), S17 (cap-std, deny globs) |
| User regexes, search | S11 (linear-time regex with size limits) |
| Markdown, docs, any HTML | S12 (ammonia, CSP, Trusted Types) |
| Agent or sentinel | S5, S6, S16, S17, S25 |
| Helm, NetworkPolicy, Dockerfile | S16, S18, S20 |
Cargo.toml, package.json, CI workflows |
S19, S20 |
| Logs, metrics, errors | S10, S21 (no contents, secrets or environment values) |
Step 2: Implement it the house way
- Authorization is declared, not scattered. Register each route with
#[guarded(role = …)]and use theRequireRole<R>orActiveUserextractors. Pending and disabled users fail before your handler runs. Never check roles inside handler bodies as the only control. - Validate at the edge with typed parsers:
NfsPath,CompareRef,PathMappingRuleandTenantId;- never a raw
Stringpath into the agent or sentinel; - inside the agent, every file operation goes through the cap-std
Dirrooted at the mount.
- No blind writes. Every NFS write and delete carries the expected hash. A mismatch returns a conflict and writes nothing.
- Secrets are
Secret<T>.- Constant-time comparisons.
- Envelope encryption for GitHub tokens: a fresh AES-256-GCM data key per token, wrapped with KMS. The associated data is the user id plus the credential id, which binds each ciphertext to its owner.
- Secret Manager for runtime secrets.
- Treat untrusted text as data.
- Config and doc text in MCP output goes inside a labelled data block.
- Values flagged by the secret scan are redacted (
[REDACTED: N chars, rule]). - No server component sends user content to an LLM.
- Render safely. Markdown goes through pulldown-cmark, then ammonia's allowlist, on the server. The web app never uses
dangerouslySetInnerHTML; the lint enforces it, with one sanitised-docs exception. - Read environment variable names, not values. The agent reads values only for the allowlist (D88).
- Least privilege everywhere.
- The agent's RBAC has no Secret list permission.
- Containers are non-root, with a read-only root filesystem, the RuntimeDefault seccomp profile and all capabilities dropped.
- NetworkPolicies deny by default.
- The sentinel's systemd unit has an empty capability bounding set.
- Nothing listens that doesn't need to.
Step 3: Prove it
Every S# you touch needs a named test that fails if the protection is removed. references/proof-patterns.md lists the test shape that suits each requirement. The ones reviewers ask for most:
- the route-table guard test, extended with your new routes;
- a log-capture test asserting no secret, file content or environment value appears;
- traversal and symlink tests for any path input;
- a 409 test for every write path;
- an XSS corpus test for anything that renders HTML;
- a test that a planted fake key never appears in MCP output.
Step 4: Update the threat model
Add or update your component's section in docs/threat-model.md using STRIDE: Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, and Elevation of privilege. For each threat, name its mitigation and the S# it maps to, then list any residual risk honestly. A human signs this off before go-live.
Red flags (stop and fix, or escalate)
- A handler or tool without a declared role.
Stringpaths crossing into the agent or sentinel.unwraporexpecton input-derived data.- Any
unbounded_channel,OFFSETpagination, or query without aLIMIT. - A secret inside
format!,tracingfields or error messages. - A new dependency that isn't justified, fails
cargo deny, or is less than 14 days old. - GitHub Actions referenced by tag instead of commit SHA.
- Exported HTML from the design handoff pasted into the app.
- Calling the config-server's
/update-resourcesfrom anywhere except the agent'sNotifyConfigServerpath. The endpoint is unauthenticated (Q37), so every call must be audited and require Operator.
When a requirement conflicts with a feature
Don't trade security away quietly. Write the conflict in your plan or PR: which requirement, which feature, and what options you see. Then stop. Only a human can relax a requirement, and only by recording it in docs/decisions.md.