coulomb/emergent-security
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Implement source-backed NetKingdom agent security knowledge pilot

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a101af-e240-7882-a1e3-e37720cbdbea
This commit is contained in:
tegwick 2026-10-03 15:25:04 +02:00
parent caa7da2397
commit a835c11ae7
54 changed files with 3634 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

107
docs/knowledge-maintenance.md Normal file
View file

@ -0,0 +1,107 @@
# Publish, load, refresh, and roll back security knowledge
Install from this trusted repository with `pip install -e '.[test]'` or a wheel
built from the reviewed revision. `emergent-knowledge list` lists cards.
`emergent-knowledge show start --audience codex --json` gives a self-contained
orientation receipt. Use `claude`, `grok`, or `generic` for other adapters.
Place `--repositories /path/to/checkouts` before the subcommand for source checks.
This command hashes only the explicitly inventoried owner files; it never emits
their contents, reads credentials, connects to an API, or requests a grant.
The explicit bundle root (`--bundle`) must come from a trusted release source.
`release.yaml` hashes detect accidental drift; they do not authenticate a
malicious bundle that brings its own hashes. Git/release provenance and owner
review establish trust. Knowledge and prompts are not enforcement boundaries.
## Loading contract
Use one of `knowledge/adapters/{codex,claude,grok,generic}.md` in the owning
session's approved entry point. This repo installs its own AGENTS.md/CLAUDE.md
pointers. No global files, permissions, model defaults, hooks, credentials, or
other repositories' instructions are changed by installation or retrieval.
Require a fresh-session proof that startup and deeper cards were actually read.
An instruction file's existence is insufficient. Record provider/client/model,
loading mode, package digest, scope resolution and source state. Reload on
resume/compaction, provider switch or repository change. Never store private
tenant context in shared receipts. Explicit bootstrap is a supported fallback:
pass the rendered receipt through the client's supported context interface and
label it accordingly; do not call it automatic discovery.
Current provider source references (checked 2026-10-03):
- [Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md):
instruction discovery is scoped to the actual session's directory hierarchy.
- [Claude memory](https://code.claude.com/docs/en/memory): CLAUDE.md and supported
AGENTS.md discovery depend on client configuration; imports load referenced text.
- [Grok instruction compatibility](https://docs.x.ai/build/features/skills-plugins-marketplaces):
Grok Build supports AGENTS.md and Claude instruction files. Verify installed behavior.
These are loading contracts, not promises about unattended execution. Do not
change a blocked glas-harness profile to make a knowledge test pass. Its current
README labels local profiles blocked and remote proof routes unverified. A
direct-client probe does not prove a governed harness session.
## Release checks and limits
Run `python3 -m pytest -q`, `python3 tools/seal_knowledge.py --check`, and
`emergent-knowledge --repositories /path/to/checkouts check`.
Startup content is capped at 5,500 UTF-8 bytes (measure actual provider tokens
in session evidence; bytes are not an exact token count). Deeper cards are
requested by stable ID; no free-form path or tenant query is accepted.
Only reviewed estate-general summaries are distributed. No tenant/private
cards are supported, even if a caller supplies a tenant label. The provider is
chosen from each card's allowlist. Data must be reviewed for its destination
before adding a source or card. Tests reject private cards, path escapes,
symlink escapes, duplicate YAML, tampering, and unreviewed source references.
Verified-file status proves agreement with inventoried bytes, not service health,
authorization, or owner assent. Source changes, withdrawal, supersession and
review expiry withhold the affected card. Missing checkouts/connection leave a
dated offline snapshot; it must not be used to establish current permissions.
An offline bundle cannot learn a withdrawal that happened after its last update;
its review deadline bounds that blind spot, and effects always require the
current owner's authorization path.
## Refresh ownership
Emergent Security maintains the package and tests. Every source remains owned
by its repository; gate-house/net-kingdom adoption and publication review are
tracked in EMERGENT-WP-0002-T02/T09, not presumed accepted. Review at least every
30 days and immediately on relevant owner/source, boundary, capability or scope
changes. A digest mismatch is an investigation trigger, not an auto-update job.
1. Read the changed source and its owner decision/evidence. Resolve conflicting
claims; keep unknown or missing capabilities explicit.
2. Update the relevant cards and source revision/digests in `sources.yaml`, with
last_verified/review_after dates and any lifecycle/supersession markers.
3. Review provider disclosure classification; never snapshot raw credentials or
tenant documents. Bump catalog version for a changed distributed package.
4. Run tests and provider scenarios affected by the change. Then seal with
`python3 tools/seal_knowledge.py` and inspect the manifest diff.
5. Commit, push and sync work records with Repo Manager. Publish the exact
reviewed artifact and retain its digest and evaluation evidence.
`python3 tools/export_knowledge.py /new/directory` exports only sealed knowledge
files plus the release manifest, without overwriting a destination. The CLI can
read that bundle with `--bundle`. For rollback select the prior reviewed bundle
explicitly; recheck source freshness. Never roll back to restore withdrawn or
expired guidance. No recurring service, scheduler or fleet broadcast is installed.
## Evidence and rollout gates
`tools/probe_provider.py` creates read-only, instrumented disposable knowledge
fixtures. Per-run random markers test actual startup and deeper reading; they
are not secrets or part of the release. Raw client diagnostics remain private
under /tmp; publish only reviewed answers and minimal session metadata.
Expected scenario outcomes are in `tests/fixtures/knowledge/scenarios.yaml`.
Review meanings, citations and recommendations, not string similarity alone.
Any unsafe recommendation blocks release. Missing or failed provider sessions
remain explicit gaps. Owner assent, independent adversarial review, actual
repository pilot sessions, and a verified provider matrix are rollout gates.
An acknowledgment proves reach, not understanding. Authorized standing notices
use the existing Statehub mechanism and reference the exact package; they do
not grant authority. Full rollout remains a workplan task until its evidence
exists. A non-normative local pilot is not fleet adoption.