security-knowledge-os 0.2.0__tar.gz → 0.4.0__tar.gz

{security_knowledge_os-0.2.0 → security_knowledge_os-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: security-knowledge-os
-Version: 0.2.0
+Version: 0.4.0
 Summary: Deterministic security assessment engine + knowledge retrieval + optional LLM assistance
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -141,11 +141,11 @@ treated as data, never as a control instruction. Details in
 | --- | --- | --- |
 | **M1 — Skeleton + Schema + Validator** | done | directory tree, `app/models/*`, `app/ingestion/validator.py`, `scripts/validate_knowledge.py`, `docs/knowledge-schema.md` |
 | **M2 — Knowledge Loader + FTS5 Retrieval** | done | `app/ingestion/{loader,chunker}.py`, `app/storage/{db,repository}.py`, `app/retrieval/{base,bm25,hybrid,index}.py`, `scripts/{ingest,build_index}.py` |
-| **M3 — Deterministic Rule Engine** | done | `app/models/rule_clause.py`, `app/reviewer/{facts,clause_eval,rule_loader,rule_engine,normalize,attack_surface,evidence,rollup,assess}.py`, `rules/**` (7 rules), `scripts/validate_rules.py`, `docs/rule-schema.md` |
+| **M3 — Deterministic Rule Engine** | done | `app/models/rule_clause.py`, `app/reviewer/{facts,clause_eval,rule_loader,rule_engine,normalize,attack_surface,evidence,rollup,assess}.py`, `rules/**` (8 rules), `scripts/validate_rules.py`, `docs/rule-schema.md` |
 | **M4 — LLM Adapter + Reviewer** | done | `app/llm/{base,mock,anthropic_client,factory}.py`, `app/models/{reviewer_output,llm_io}.py`, `app/reviewer/{llm_review,questions}.py`, `assess()` full, `scripts/assess.py` |
-| **M5 — Safe Test + Human Gate** | done | `app/models/policy_outcome.py`, `app/policy/{human_gate,knowledge_guard,safe_test}.py`, `app/storage/integrity.py`, `safe_tests/**` (4 templates), `scripts/validate_safe_tests.py` |
+| **M5 — Safe Test + Human Gate** | done | `app/models/policy_outcome.py`, `app/policy/{human_gate,knowledge_guard,safe_test}.py`, `app/storage/integrity.py`, `safe_tests/**` (5 templates), `scripts/validate_safe_tests.py` |
 | **M6 — Orchestrator + CLI + API** | done | `app/models/report.py`, `app/reviewer/report.py`, `app/cli.py` (`skos`), `app/main.py` (FastAPI), `app/retrieval/index.py::reindex_atomic` |
-| **M7 — Fixtures + Evaluation + starter KUs** | done | `knowledge/public/**` (14 KUs), `tests/fixtures/assessments/{safe,vulnerable,unknown}/`, `app/eval/metrics.py`, `scripts/evaluate.py`, JA retrieval (trigram) |
+| **M7 — Fixtures + Evaluation + starter KUs** | done | `knowledge/public/**` (15 KUs), `tests/fixtures/assessments/{safe,vulnerable,unknown}/`, `app/eval/metrics.py`, `scripts/evaluate.py`, JA retrieval (trigram) |
 | **M8 — Docs + hardening** | done | Security disclaimer (AC-15–18), KU `provenance` schema, `docs/{attribution,threat-model,architecture}.md`, `sbom.json`, `scripts/{secret_scan,generate_sbom,preflight}.py` |
 
 ## Install
@@ -193,16 +193,17 @@ python3.12 -m venv .venv
 .venv/bin/pytest -q
 ```
 
-The MVP ships **14 public Knowledge Units** (`knowledge/public/`; 13 from
+The MVP ships **15 public Knowledge Units** (`knowledge/public/`; 13 from
 published standards - OWASP LLM Top 10 2025, MITRE ATLAS, NIST AI RMF / AI 600-1;
-one in Japanese - plus one, KU-0014, an original write-up of a vulnerability
-class this project's own pre-publication review process actually found). Each
+one in Japanese - plus KU-0014, an original write-up of a vulnerability
+class this project's own pre-publication review process actually found, and
+KU-0015, a summary of published research on prompt injection as role confusion). Each
 unit carries `provenance` (source title, URL, version, licence, derivation
 status, last-verified date). See `docs/knowledge-corpus.md` and
 `docs/attribution.md`.
 
 **Internal fixture evaluation** (`scripts/evaluate.py`, 14 artificial fixtures ×
-14 indexed KUs):
+15 indexed KUs):
 
 ```
 Classification Leakage          = 0
@@ -354,7 +355,7 @@ See `.env.example`.
 - `docs/knowledge-schema.md` — Knowledge Unit schema (front matter + `provenance` + body)
 - `docs/rule-schema.md` — data-only rule schema and operators
 - `docs/safe-test-schema.md` — safe-test schema, validator rules, Human Gate, read-only guard
-- `docs/knowledge-corpus.md` — the 14 shipped Knowledge Units and their sources
+- `docs/knowledge-corpus.md` — the 15 shipped Knowledge Units and their sources
 - `docs/attribution.md` — third-party sources, licences, derivation status
 - `docs/acceptance-criteria.md` — AC-01..20 status and §24 evaluation metrics
 

{security_knowledge_os-0.2.0 → security_knowledge_os-0.4.0}/PUBLICATION_MANIFEST.md

@@ -1,16 +1,16 @@
-# Publication Manifest — Security Knowledge OS v0.2.0
+# Publication Manifest — Security Knowledge OS v0.4.0
 
 Snapshot of what the first public push contains. Generated for the pre-publication
 review; regenerate with `git ls-files` after any change.
 
-- Commit: `316e8c6` (v0.2.0: Update Packs + `skos scan mcp`; PyPI 0.1.0 was `a7f463d`)
+- Commit: `4ac7982` (v0.4.0: role-confusion KU-0015 / rule PI-004 / safe test ST-RC-001 + urllib3 2.8.0; v0.3.0 `2627b44` added whole-agent capability labels for the `capgraph` pack; 0.2.0 was `316e8c6`, 0.1.0 `a7f463d`)
 - History: rewritten once on 2026-09-20, before first publication, to normalise author/committer identity to the
   GitHub no-reply address (one commit message also scrubbed of a local account name). Every commit's tree is
   identical before and after, so the reviewed content is the published content; commit hashes cited in the
   review records below are the **pre-rewrite** ones - see `docs/history-rewrite-map.md` for old -> new.
 - Licence: **Apache-2.0** (`LICENSE`, `NOTICE`, `pyproject.toml`)
-- Tracked files: **242**
-- Tests: **943** items (942 pass, 1 skip = JA-R02)
+- Tracked files: **248**
+- Tests: **992** items (991 pass, 1 skip = JA-R02)
 - `scripts/preflight.py`: **PASS** (now also verifies the documented
   quickstart `pip install -e` command installs every declared extra,
   pins `constraints.txt`, AND passes `--build-constraint constraints.txt`
@@ -798,6 +798,32 @@ review; regenerate with `git ls-files` after any change.
   empty value in a URL, or a flag with no value, is reported as a literal
   secret - a false positive).
 
+  **v0.3.0 capability-label review** (2026-09-29, scoped to `master..2627b44`:
+  `app/adapters/capgraph.py`, the `skos scan mcp --client` / `_agent.yaml` /
+  `capability-labels.json` changes in `app/adapters/mcp_config.py` and
+  `app/cli.py`, plus the separate data-only `capgraph` pack source). Codex,
+  three rounds, each CHANGES-REQUIRED and fixed: round 1 (`5b6a115`) 10
+  findings (4 HIGH: package impersonation via launcher path or environment,
+  server identity bound to file names, browser and memory profiles claiming
+  absent capabilities); round 2 (`75f146f`) residuals plus 2 new (HIGH: a pack
+  failing verification treated as not installed); round 3 (`2cc494b`) one
+  residual HIGH (`pnpm exec`/`yarn exec` run a local command) and one LOW
+  (npx server arguments). Fixed in `970a1b1`, reviewed by Antigravity:
+  **PASS-with-nits**; the test nit was added in `2627b44`. The medium-rule
+  suppression Codex flagged as G10 is documented in the pack README (engine
+  policy), not changed.
+
+  **v0.4.0 role-confusion review** (2026-10-07 -- 2026-10-08, scoped to
+  `3fdd7f8..62fea58`: KU-0015, rule PI-004 and fact `has_unapproved_shell_tool`,
+  safe test ST-RC-001, urllib3 2.7.0 -> 2.8.0 for PYSEC-2026-4175/4176/4177).
+  Codex round 1 (`43ca56f`) **CHANGES-REQUIRED**: 1 must-fix (KU-0015 claimed a
+  model-side fix was required although the source paper evaluates no defence)
+  and 5 nice-to-have (PI-004 checked all high-impact tools, RAG-only scope not
+  stated, loose test assertions, ST-RC-001 conflated a gate block with no role
+  confusion, stale counts); all fixed in `416229d`. Codex round 2 (`bd61f34`)
+  **PASS-with-nits**, all round-1 findings confirmed resolved; the one test nit
+  (unknown check with manual_review stays UNKNOWN) added in `62fea58`.
+
 ## Tracked files by area
 
 Per-area counts below were last verified at round 2 (commit `bcd9519`) and
@@ -807,11 +833,11 @@ check enforces (total tracked files, total tests) are kept current above.
 
 | area | files | notes |
 | --- | --- | --- |
-| `app/` | 76 (.py) | engine, models, policy, retrieval, reviewer, llm, storage, eval, cli, main, packs (Update Pack manager), adapters (MCP config scan) |
-| `tests/` | 86 | 55 test modules + fixtures |
-| `knowledge/` | 24 | 14 public KUs + `private/` skeleton (README + 2 `.gitkeep`) + category `.gitkeep`s |
-| `rules/` | 13 | 7 rule YAMLs + category `.gitkeep`s |
-| `safe_tests/` | 4 | 4 vetted templates |
+| `app/` | 77 (.py) | engine, models, policy, retrieval, reviewer, llm, storage, eval, cli, main, packs (Update Pack manager), adapters (MCP config scan, capability labels) |
+| `tests/` | 88 | 57 test modules + fixtures |
+| `knowledge/` | 25 | 15 public KUs + `private/` skeleton (README + 2 `.gitkeep`) + category `.gitkeep`s |
+| `rules/` | 14 | 8 rule YAMLs + category `.gitkeep`s |
+| `safe_tests/` | 5 | 5 vetted templates |
 | `scripts/` | 13 | validators, ingest/build_index, assess, evaluate, sbom, secret_scan, preflight, cross-review runner, issue_license |
 | `docs/` | 11 | see below |
 | `reviews/` | 2 | `.gitignore` + `README.md` only — cross-review output `.md`/`.log` files are gitignored, never tracked |
@@ -833,13 +859,15 @@ Docs: `architecture`, `threat-model`, `safety-boundaries`, `knowledge-schema`,
 Verified: no `secret/`, no `.env`, no private-KU content tracked
 (`scripts/preflight.py`).
 
-## Public Knowledge Units (14)
+## Public Knowledge Units (15)
 
 All `classification: public`, `status: reviewed`. 13 are `derivation: summary`
 (original prose, no verbatim third-party text, citing a published standard).
 KU-0014 is `derivation: original` / `source_type: incident` — a first-party
 write-up of a vulnerability class found by this project's own pre-publication
-cross-AI review (rounds 9-14), not sourced from any external standard. Full
+cross-AI review (rounds 9-14), not sourced from any external standard.
+KU-0015 is `derivation: summary` / `source_type: manual` — own-prose summary of a
+published research paper (arXiv:2603.12277), no verbatim text. Full
 list + per-unit sources in `docs/knowledge-corpus.md`; licence analysis in
 `docs/attribution.md`.
 
@@ -859,12 +887,14 @@ list + per-unit sources in `docs/knowledge-corpus.md`; licence analysis in
 | KU-0012 | governance | NIST AI RMF 1.0 |
 | KU-0013 | methodology (Japanese) | MITRE ATLAS + OWASP LLM06 |
 | KU-0014 | incident | original (this project's own cross-AI review, rounds 9-14) |
+| KU-0015 | prompt-security | arXiv:2603.12277 (ICML 2026), summarised not reproduced |
 
 Source licences: OWASP CC-BY-SA-4.0 · MITRE ATLAS Terms of Use · NIST public
-domain · KU-0014 original (no external licence applies). No content in the
+domain · KU-0014 original (no external licence applies) · KU-0015 summarises an
+arXiv paper (arXiv non-exclusive licence; no text reproduced). No content in the
 repo is under terms incompatible with Apache-2.0 redistribution.
 
-## Rules (7)
+## Rules (8)
 
 `rules/` — data-only YAML, operators `{eq, ne, in, contains, is_unknown}`, facts
 from `app/reviewer/facts.py::FACT_SPEC` (whitelist).
@@ -872,6 +902,7 @@ from `app/reviewer/facts.py::FACT_SPEC` (whitelist).
 | id | severity | category | detects |
 | --- | --- | --- | --- |
 | PI-003 | high | rag-security | indirect injection + outbound path |
+| PI-004 | high | prompt-security | declared untrusted retrieval + shell tool (role confusion) |
 | MEM-001 | high | memory-security | persistent memory + untrusted ingestion |
 | TOOL-001 | high | agent-security | high-impact tool without approval |
 | TOOL-000 | medium | agent-security | tool permissions unspecified -> UNKNOWN |
@@ -879,7 +910,7 @@ from `app/reviewer/facts.py::FACT_SPEC` (whitelist).
 | GOV-001 | medium | governance | high-impact actions without approval coverage |
 | OUT-001 | medium | agent-security | outbound enabled without a destination allow-list |
 
-Safe-test templates (4): `ST-IPI-001`, `ST-MEM-001`, `ST-TOOL-001`, `ST-CRED-001`.
+Safe-test templates (5): `ST-IPI-001`, `ST-MEM-001`, `ST-TOOL-001`, `ST-CRED-001`, `ST-RC-001`.
 
 ## Fixtures
 

{security_knowledge_os-0.2.0 → security_knowledge_os-0.4.0}/README.md

@@ -115,11 +115,11 @@ treated as data, never as a control instruction. Details in
 | --- | --- | --- |
 | **M1 — Skeleton + Schema + Validator** | done | directory tree, `app/models/*`, `app/ingestion/validator.py`, `scripts/validate_knowledge.py`, `docs/knowledge-schema.md` |
 | **M2 — Knowledge Loader + FTS5 Retrieval** | done | `app/ingestion/{loader,chunker}.py`, `app/storage/{db,repository}.py`, `app/retrieval/{base,bm25,hybrid,index}.py`, `scripts/{ingest,build_index}.py` |
-| **M3 — Deterministic Rule Engine** | done | `app/models/rule_clause.py`, `app/reviewer/{facts,clause_eval,rule_loader,rule_engine,normalize,attack_surface,evidence,rollup,assess}.py`, `rules/**` (7 rules), `scripts/validate_rules.py`, `docs/rule-schema.md` |
+| **M3 — Deterministic Rule Engine** | done | `app/models/rule_clause.py`, `app/reviewer/{facts,clause_eval,rule_loader,rule_engine,normalize,attack_surface,evidence,rollup,assess}.py`, `rules/**` (8 rules), `scripts/validate_rules.py`, `docs/rule-schema.md` |
 | **M4 — LLM Adapter + Reviewer** | done | `app/llm/{base,mock,anthropic_client,factory}.py`, `app/models/{reviewer_output,llm_io}.py`, `app/reviewer/{llm_review,questions}.py`, `assess()` full, `scripts/assess.py` |
-| **M5 — Safe Test + Human Gate** | done | `app/models/policy_outcome.py`, `app/policy/{human_gate,knowledge_guard,safe_test}.py`, `app/storage/integrity.py`, `safe_tests/**` (4 templates), `scripts/validate_safe_tests.py` |
+| **M5 — Safe Test + Human Gate** | done | `app/models/policy_outcome.py`, `app/policy/{human_gate,knowledge_guard,safe_test}.py`, `app/storage/integrity.py`, `safe_tests/**` (5 templates), `scripts/validate_safe_tests.py` |
 | **M6 — Orchestrator + CLI + API** | done | `app/models/report.py`, `app/reviewer/report.py`, `app/cli.py` (`skos`), `app/main.py` (FastAPI), `app/retrieval/index.py::reindex_atomic` |
-| **M7 — Fixtures + Evaluation + starter KUs** | done | `knowledge/public/**` (14 KUs), `tests/fixtures/assessments/{safe,vulnerable,unknown}/`, `app/eval/metrics.py`, `scripts/evaluate.py`, JA retrieval (trigram) |
+| **M7 — Fixtures + Evaluation + starter KUs** | done | `knowledge/public/**` (15 KUs), `tests/fixtures/assessments/{safe,vulnerable,unknown}/`, `app/eval/metrics.py`, `scripts/evaluate.py`, JA retrieval (trigram) |
 | **M8 — Docs + hardening** | done | Security disclaimer (AC-15–18), KU `provenance` schema, `docs/{attribution,threat-model,architecture}.md`, `sbom.json`, `scripts/{secret_scan,generate_sbom,preflight}.py` |
 
 ## Install
@@ -167,16 +167,17 @@ python3.12 -m venv .venv
 .venv/bin/pytest -q
 ```
 
-The MVP ships **14 public Knowledge Units** (`knowledge/public/`; 13 from
+The MVP ships **15 public Knowledge Units** (`knowledge/public/`; 13 from
 published standards - OWASP LLM Top 10 2025, MITRE ATLAS, NIST AI RMF / AI 600-1;
-one in Japanese - plus one, KU-0014, an original write-up of a vulnerability
-class this project's own pre-publication review process actually found). Each
+one in Japanese - plus KU-0014, an original write-up of a vulnerability
+class this project's own pre-publication review process actually found, and
+KU-0015, a summary of published research on prompt injection as role confusion). Each
 unit carries `provenance` (source title, URL, version, licence, derivation
 status, last-verified date). See `docs/knowledge-corpus.md` and
 `docs/attribution.md`.
 
 **Internal fixture evaluation** (`scripts/evaluate.py`, 14 artificial fixtures ×
-14 indexed KUs):
+15 indexed KUs):
 
 ```
 Classification Leakage          = 0
@@ -328,7 +329,7 @@ See `.env.example`.
 - `docs/knowledge-schema.md` — Knowledge Unit schema (front matter + `provenance` + body)
 - `docs/rule-schema.md` — data-only rule schema and operators
 - `docs/safe-test-schema.md` — safe-test schema, validator rules, Human Gate, read-only guard
-- `docs/knowledge-corpus.md` — the 14 shipped Knowledge Units and their sources
+- `docs/knowledge-corpus.md` — the 15 shipped Knowledge Units and their sources
 - `docs/attribution.md` — third-party sources, licences, derivation status
 - `docs/acceptance-criteria.md` — AC-01..20 status and §24 evaluation metrics
 

{security_knowledge_os-0.2.0 → security_knowledge_os-0.4.0}/REVIEW_PACKAGE.md

@@ -133,7 +133,7 @@ secret/          OUTSIDE the repository. Never indexed, never sent to an LLM.
 - Retrieval filters by `is_retrievable(classification, mode, allow_confidential)`
   in SQL **and** re-checks each returned chunk (defence in depth); a leak raises
   `PolicyBlocked`.
-- All 14 shipped Knowledge Units are `classification: public`.
+- All 15 shipped Knowledge Units are `classification: public`.
 - `PolicyOutcome` enum: `ALLOWED` / `HUMAN_APPROVAL_REQUIRED` / `POLICY_BLOCKED` /
   `READ_ONLY_VIOLATION` (typed, never a bare string).
 
@@ -149,7 +149,7 @@ secret/          OUTSIDE the repository. Never indexed, never sent to an LLM.
 | JA-R02 (cross-language retrieval) | out of MVP scope; test skipped |
 | Update Pack / Pack Manager | not in this codebase (M9-M10, separate track); the ZIP-import attack surface it introduces is future work |
 | snapshot consistency vs. a COORDINATING writer | whole-tree re-verification catches ordinary concurrent updates; a writer that swaps directory generations during the verification pass itself is accepted (trust boundary: the tree root must not be writable by untrusted parties; a writer with write access can replace a rule directly). See `docs/threat-model.md` (Codex#1, round 23) |
-| trigram tokenizer | substring matching; can over-retrieve on a large corpus (fine for 14 KUs) |
+| trigram tokenizer | substring matching; can over-retrieve on a large corpus (fine for 15 KUs) |
 
 ## 10. How to run
 

{security_knowledge_os-0.2.0 → security_knowledge_os-0.4.0}/app/__init__.py

@@ -1,3 +1,3 @@
 """Security Knowledge OS - deterministic security assessment engine."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

security_knowledge_os-0.4.0/app/adapters/capgraph.py

@@ -0,0 +1,219 @@
+"""Capability labels for one agent, derived from its MCP client config.
+
+Each server gets six labels - ``untrusted_input``, ``sensitive_read``,
+``egress``, ``exec``, ``write``, ``persistence`` - valued ``True`` /
+``False`` / ``None`` (unknown). A label is ``True`` only when the config
+(package identity, launch options) establishes it, and ``False`` only when
+the absence is established the same way; a server the scanner does not know
+keeps every label ``None``. Tool descriptions are never used: they can lie.
+
+The agent is the union of its servers and the client's own built-in tools,
+combined with a three-valued OR (any ``True`` -> ``True``; all ``False`` ->
+``False``; otherwise ``None``). When the client is not declared, nothing is
+known about its built-in tools, so an aggregate ``False`` becomes ``None``.
+
+The result feeds the ``capgraph`` Update Pack (``extensions.capgraph``) and
+is also written as ``capability-labels.json`` for runtime enforcement (for
+example a gateway that decides trust from the same labels). Only server
+names from the config appear in either output (project paths are replaced by
+opaque ids), never configuration values.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from app.adapters.mcp_config import ServerScan
+
+LABELS = ("untrusted_input", "sensitive_read", "egress", "exec", "write", "persistence")
+# Written to extensions.capgraph; every key becomes a ``capgraph_<key>`` fact.
+FACT_KEYS = (*LABELS, "flow_gated", "egress_gated")
+SCHEMA = "capgraph/v0"
+AGENT_FILE_STEM = "_agent"  # reserved: no server may be written under this name
+CLIENTS = ("claude-code", "none")
+
+Label = bool | None
+
+
+@dataclass(frozen=True)
+class _Caps:
+    """What a known package can do beyond the MCP scanner's own facts."""
+
+    sensitive_read: Label = None
+    persistence: Label = None
+    write_scope: str | None = None  # "fs" = the scanner's fs_scope
+    # the scanner's "no shell" does not mean "no code": a browser runs
+    # JavaScript on the pages it drives
+    exec_unknown: bool = False
+
+
+# By exact (ecosystem, package) identity, like the scanner's own profiles.
+_KNOWN: dict[tuple[str, str], _Caps] = {
+    # scope-dependent: see _labels()
+    ("npm", "@modelcontextprotocol/server-filesystem"): _Caps(None, True, "fs"),
+    # private repositories/messages behind the token; pushes can change CI
+    ("npm", "@modelcontextprotocol/server-github"): _Caps(True, True, "remote"),
+    ("npm", "@modelcontextprotocol/server-gitlab"): _Caps(True, True, "remote"),
+    ("npm", "@modelcontextprotocol/server-slack"): _Caps(True, None, "remote"),
+    # a browser reaches intranet pages and the host's services, submits forms
+    # and can store content that is loaded again later (Codex capgraph G03)
+    ("npm", "@modelcontextprotocol/server-puppeteer"): _Caps(None, None, "remote", True),
+    ("npm", "@playwright/mcp"): _Caps(None, None, "remote", True),
+    ("npm", "@modelcontextprotocol/server-brave-search"): _Caps(False, False, "none"),
+    # what it stores is loaded into later sessions; what it holds - and where
+    # the file is - is not visible (Codex capgraph G04)
+    ("npm", "@modelcontextprotocol/server-memory"): _Caps(None, True, None),
+    ("npm", "@wonderwhy-er/desktop-commander"): _Caps(True, True, "root"),
+    # fetch can reach localhost and intranet URLs
+    ("pypi", "mcp-server-fetch"): _Caps(None, False, "none"),
+    ("pypi", "mcp-server-git"): _Caps(None, None, "project"),
+    ("pypi", "mcp-server-time"): _Caps(False, False, "none"),
+}
+
+# Built-in tools of an agent client, by --client name. "none" declares a
+# client without built-in tools (e.g. a custom agent that only uses MCP).
+_CLIENTS: dict[str, dict[str, Label]] = {
+    # Bash, Read/Edit/Write, WebFetch/WebSearch
+    "claude-code": {
+        "untrusted_input": True, "sensitive_read": True, "egress": True,
+        "exec": True, "write": True, "persistence": True,
+    },
+}
+
+
+@dataclass
+class ServerLabels:
+    name: str  # the scan's file stem (used in notes and file names)
+    server: str  # exact server name in the config
+    scope: str  # "global" or "project-<id>"
+    labels: dict[str, Label]
+    write_scope: str | None
+
+
+@dataclass
+class AgentLabels:
+    client: str | None
+    servers: list[ServerLabels]
+    labels: dict[str, Label] = field(default_factory=dict)
+    contributors: dict[str, list[str]] = field(default_factory=dict)
+
+    def facts(self) -> dict[str, Label]:
+        """The ``extensions.capgraph`` block. The gates (``flow_gated``,
+        ``egress_gated``) are not visible in a config: they are left for the
+        operator and asked when a combination they guard applies."""
+        return {**self.labels, "flow_gated": None, "egress_gated": None}
+
+    def notes(self) -> list[str]:
+        out = []
+        if self.client is None:
+            out.append(
+                "client not declared (--client): its built-in tools are unknown, so no label "
+                "is claimed absent"
+            )
+        for label in LABELS:
+            if self.contributors.get(label):
+                out.append(f"{label} <- {', '.join(self.contributors[label])}")
+        return out
+
+
+def _labels(scan: ServerScan) -> ServerLabels:
+    f = scan.facts
+    labels: dict[str, Label] = {
+        "untrusted_input": f.get("ingests_untrusted_content"),
+        "sensitive_read": None,
+        "egress": f.get("can_send"),
+        "exec": f.get("shell_exec"),
+        "write": f.get("can_write"),
+        "persistence": None,
+    }
+    write_scope: str | None = None
+    caps = None
+    if scan.package is not None and scan.ecosystem is not None:
+        caps = _KNOWN.get((scan.ecosystem, scan.package))
+    if caps is not None:
+        labels["sensitive_read"] = caps.sensitive_read
+        labels["persistence"] = caps.persistence
+        write_scope = caps.write_scope
+        if caps.exec_unknown:
+            labels["exec"] = None
+        if caps.write_scope == "fs":
+            scope = f.get("fs_scope")
+            write_scope = scope if scope in ("project", "home", "root") else None
+            # the whole home directory or / holds credentials and private files;
+            # a project directory may (.env) but that is not visible here
+            labels["sensitive_read"] = True if scope in ("home", "root") else None
+    if labels["exec"] is True and f.get("sandboxed") is not True:
+        # an unsandboxed shell reads and writes anything the user can
+        labels["sensitive_read"] = labels["write"] = labels["persistence"] = True
+        write_scope = write_scope or "root"
+    if labels["write"] is False and labels["exec"] is False and labels["persistence"] is None:
+        labels["persistence"] = False
+    return ServerLabels(scan.name, scan.server, scan.scope, labels, write_scope)
+
+
+def _or(values: list[Label]) -> Label:
+    if any(v is True for v in values):
+        return True
+    if values and all(v is False for v in values):
+        return False
+    return None
+
+
+def agent_labels(scans: list[ServerScan], client: str | None) -> AgentLabels:
+    if client is not None and client not in CLIENTS:
+        raise ValueError(f"unknown client {client!r} (known: {', '.join(CLIENTS)})")
+    servers = [_labels(s) for s in scans]
+    builtin = _CLIENTS.get(client) if client else None
+    agent = AgentLabels(client, servers)
+    for label in LABELS:
+        values = [s.labels[label] for s in servers]
+        sources = [s.name for s in servers if s.labels[label] is True]
+        if builtin is not None:
+            values.append(builtin[label])
+            if builtin[label] is True:
+                sources.insert(0, f"client:{client}")
+        value = _or(values)
+        if value is False and client is None:
+            value = None
+        agent.labels[label] = value
+        agent.contributors[label] = sources
+    return agent
+
+
+def labels_json(agent: AgentLabels, source_name: str) -> str:
+    doc = {
+        "schema": SCHEMA,
+        "source": source_name,
+        "client": agent.client,
+        "agent": agent.labels,
+        "contributors": agent.contributors,
+        # identify a server by (scope, exact name) - the file stem is only a
+        # file name and may be renamed to stay unique (Codex capgraph G02)
+        "servers": [
+            {
+                "server": s.server, "scope": s.scope, "file": s.name,
+                "labels": s.labels, "write_scope": s.write_scope,
+            }
+            for s in agent.servers
+        ],
+    }
+    return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
+
+
+def agent_yaml(agent: AgentLabels, source_name: str) -> str:
+    import yaml
+
+    body = yaml.safe_dump(
+        {"name": f"agent:{source_name}", "extensions": {"capgraph": agent.facts()}},
+        sort_keys=False,
+        allow_unicode=True,
+    )
+    header = [
+        f"# generated by `skos scan mcp` from {source_name} (the whole agent: every server"
+        + (f" + client {agent.client}" if agent.client else "") + ")",
+        "# null = not established by the config. Answer what you can, then `skos assess` this"
+        " file.",
+    ]
+    header += [f"# note: {n}" for n in agent.notes()]
+    return "\n".join(header) + "\n" + body