docs: define security contract and adoption-gated roadmap - #276
Merged
Conversation
This was referenced Aug 11, 2026
dgenio
marked this pull request as ready for review
August 11, 2026 05:29
Copilot stopped reviewing on behalf of
dgenio due to an error
August 11, 2026 05:29
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the project’s positioning and security documentation to clarify Weaver Kernel’s current security claims, boundaries, and maturity, while adding a gate-driven roadmap.
Changes:
- Refines package/README messaging around “execution enforcement and audit” and adds explicit non-claims.
- Reworks
docs/security.mdto align with a new concise security contract and adds operational caveats. - Adds new foundational docs:
docs/security-contract.mdandROADMAP.md.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| pyproject.toml | Updates the project description to match the new product positioning. |
| docs/security.md | Reframes the security model around the contract and adds maturity/operational caveats. |
| docs/security-contract.md | Introduces a concise, auditable statement of current security claims and assumptions. |
| ROADMAP.md | Adds a gate-driven roadmap aligned to security hardening priorities. |
| README.md | Major rewrite: clearer boundary, non-claims, quickstart, and doc pointers. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+7
to
+19
| | Threat | Current mitigation | | ||
| |---|---| | ||
| | Tool-space interference | Capability registry + policy gate before Kernel-mediated execution | | ||
| | Confused deputy / cross-principal token reuse | Tokens bind `principal_id`; verification rejects a different principal | | ||
| | Token tampering | HMAC-SHA256 signature verification | | ||
| | Token replay after expiry | Expiry is checked during token verification | | ||
| | Raw tool output reaching the default LLM-safe path | `RawResult` is transformed by the Context Firewall into a bounded `Frame` | | ||
| | PII / PCI leakage | Firewall redaction + allowed-field enforcement on supported egress paths | | ||
| | Deeply nested secret leakage | Redaction fails closed at the configured depth boundary; nested containers are elided rather than returned verbatim | | ||
| | Handle expansion escaping the grant | Handle expansion re-checks principal binding and persisted grant constraints | | ||
| | Sensitive arguments/results leaking into audit | Trace arguments/errors pass through redaction; result summaries are built from post-firewall data rather than raw driver output | | ||
| | Privilege escalation through WRITE / DESTRUCTIVE classes | Policy engine applies role / justification rules | | ||
| | Audit mutation | Durable trace stores can use HMAC hash chaining to make mutation/interior deletion/reordering evident | |
Comment on lines
+56
to
+61
| | Constraint | Expansion behavior | | ||
| |---|---| | ||
| | `max_rows` | Requests above the cap are rejected or clamped according to the API path. | | ||
| | `allowed_fields` | Out-of-scope fields are rejected; default projection cannot reveal disallowed fields. | | ||
| | `scope` | Stored scope is merged into the query and conflicting scope is rejected. | | ||
| | `principal_id` | A different/omitted principal is rejected. | |
Comment on lines
+85
to
+88
| import asyncio | ||
| import os | ||
|
|
||
| ```python | ||
| import asyncio, os | ||
| os.environ["WEAVER_KERNEL_SECRET"] = "my-secret" | ||
| os.environ["WEAVER_KERNEL_SECRET"] = "replace-me-for-real-deployments" |
| principal=principal, | ||
| ) | ||
| print(expanded.table_preview) # [{'title': 'Buy milk'}] | ||
| print(kernel.explain(frame.action_id)) |
This was referenced Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
docs/security-contract.mdwith the exact current guarantee, complete-mediation limits, action-binding gap, authentication boundary, policy-interoperability direction, and security-claim vocabulary.ROADMAP.mdwith falsification criteria, supported-path security blockers, one-on-ramp-before-breadth, reproducible evidence, external trust, interoperability-led distribution, and kill/reposition criteria.docs/security.mdto remove stale “v0.1” wording and make current multi-worker, MCP, rate-limit, authentication, redaction and token-scope limitations visible.Why
A red-team review found that the previous adoption plan overclaimed category whitespace and underweighted the trust boundary of an in-process security library. The repo also already tracks concrete security-contract gaps (#181, #170, #226, #263, #103, #199, #245, #258) that should outrank speculative feature growth.
This PR deliberately changes claims and sequencing, not runtime enforcement behavior.
Developer/user impact
agent-kernelGitHub slug is intentionally retained; naming churn is not on the critical path.Validation
Documentation/package-metadata only; no runtime code changed. CI should still validate the README-linked package metadata and repository checks. This is intentionally a draft until automated checks confirm the rewritten docs do not break repository conventions.
Related
#103 #104 #170 #173 #181 #199 #219 #226 #245 #253 #258 #263