security-knowledge-os 0.1.0__tar.gz → 0.3.0__tar.gz

security_knowledge_os-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      # TODO: pin these actions to a full commit SHA for supply-chain safety.
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+          fetch-depth: 0 # full history (the manifest-ancestor check needs it)
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install (pinned)
+        run: pip install -e ".[api,llm,dev]" -c constraints.txt
+      # Mirrors the project's own gate (scripts/preflight.py runs `ruff check`,
+      # not `ruff format --check`), so CI enforces exactly what the repo commits
+      # to. (`ruff format --check` is not run repo-wide yet - a separate cleanup.)
+      - name: Ruff (lint)
+        run: ruff check .
+      - name: Mypy (strict)
+        run: mypy
+      # Two tests assert the tracked sbom.json matches the *exact* installed
+      # dependency closure of the maintainer's environment (e.g. build-time
+      # packages like trove-classifiers); they cannot pass in an arbitrary CI
+      # runner and are verified locally via scripts/preflight.py before a
+      # release. Everything else - including the manifest-ancestor check - runs.
+      - name: Tests
+        run: >
+          pytest -q
+          --deselect tests/unit/test_generate_sbom.py::test_no_unknown_licences_for_a_real_specific_osi_classifier
+          --deselect tests/unit/test_preflight_manifest.py::test_real_tracked_sbom_matches_the_current_environment

security_knowledge_os-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+# Publishes on a version tag (e.g. `v0.1.1`). Uses PyPI Trusted Publishing
+# (OIDC) - NO API token / secret is stored in the repo. One-time setup on
+# PyPI: project -> Publishing -> add a GitHub trusted publisher for
+# repo `kagioneko/security-knowledge-os`, workflow `publish.yml`,
+# environment `pypi`. Until that is configured the publish JOB simply FAILS
+# (it is not skipped) and nothing is uploaded - a failed release, never a
+# silent or partial one.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # TODO: pin these actions to a full commit SHA for supply-chain safety.
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify the tag matches the packaged version
+        run: |
+          pip install build
+          python -m build
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(ls dist/*.whl | sed -E 's/.*-([0-9]+\.[0-9]+\.[0-9]+)-.*/\1/')
+          echo "tag=$tag packaged=$pkg"
+          test "$tag" = "$pkg"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

{security_knowledge_os-0.1.0 → security_knowledge_os-0.3.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: security-knowledge-os
-Version: 0.1.0
+Version: 0.3.0
 Summary: Deterministic security assessment engine + knowledge retrieval + optional LLM assistance
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.12
+Requires-Dist: cryptography>=50.0
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: api
@@ -25,6 +26,15 @@ Description-Content-Type: text/markdown
 
 # Security Knowledge OS
 
+[![PyPI](https://img.shields.io/pypi/v/security-knowledge-os)](https://pypi.org/project/security-knowledge-os/)
+[![Python](https://img.shields.io/pypi/pyversions/security-knowledge-os)](https://pypi.org/project/security-knowledge-os/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+```bash
+pip install security-knowledge-os
+skos assess your-agent.yaml   # deterministic, offline by default; bundled rules/knowledge
+```
+
 > **Language note / 言語について**: This repository (code, docs, commit history) is
 > **English-first by design** — it is written to be consumed by AI coding agents and
 > cites international standards (OWASP, MITRE ATLAS, NIST) directly. The section
@@ -138,7 +148,18 @@ treated as data, never as a control instruction. Details in
 | **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) |
 | **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` |
 
-## Quickstart (M1)
+## Install
+
+Requires **Python 3.12+**. From PyPI (ships the default rules / knowledge /
+safe-test data, so `skos assess` works with no checkout):
+
+```bash
+pip install security-knowledge-os          # engine + CLI
+pip install "security-knowledge-os[api]"   # + the local FastAPI app
+skos assess your-agent.yaml                # your-agent.yaml is an input you write
+```
+
+## Quickstart (M1, from a source checkout)
 
 ```bash
 python3.12 -m venv .venv

{security_knowledge_os-0.1.0 → security_knowledge_os-0.3.0}/PUBLICATION_MANIFEST.md

@@ -1,16 +1,16 @@
-# Publication Manifest — Security Knowledge OS v0.1.0
+# Publication Manifest — Security Knowledge OS v0.3.0
 
 Snapshot of what the first public push contains. Generated for the pre-publication
 review; regenerate with `git ls-files` after any change.
 
-- Commit: `4c004ab` (packaging: bundle default data into the wheel + config fallback so pip install works standalone; allowlist guard rejects private/hidden/symlink incl. ancestor symlinks; sdist ships only tracked public files; cross-review PASS round 38, not yet pushed)
+- Commit: `2627b44` (v0.3.0: 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: **218**
-- Tests: **792** items (791 pass, 1 skip = JA-R02)
+- Tracked files: **244**
+- Tests: **978** items (977 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`
@@ -19,7 +19,7 @@ review; regenerate with `git ls-files` after any change.
   environment, ignoring only its timestamp, without preflight itself
   rewriting that tracked file to check it, round 11 Codex#12)
 - Cross-AI review: Codex (code audit) + Antigravity (adversarial design
-  audit), **thirty-eight rounds** (through round-38), 2026-09-11 -- 2026-09-26. Rounds 1-2
+  audit), **thirty-nine rounds** (through round-39), 2026-09-11 -- 2026-09-26. Rounds 1-2
   (2026-09-11): CHANGES-REQUIRED both times, 19 then 13 findings, all
   fixed — see `REVIEW_CHECKLIST.md` sign-off tables. Rounds 3-6
   (2026-09-12): CHANGES-REQUIRED each time, independent findings each
@@ -774,6 +774,45 @@ review; regenerate with `git ls-files` after any change.
   pytest test run by the release gate) fixed in `4c004ab` (comment only). This is
   the packaging change's cross-review PASS for the PyPI release.
 
+  **Round 39** (2026-09-26, post-publication: reviewed the README PyPI
+  badges/install additions and the new test CI workflow before pushing them):
+  Codex **PASS-with-nits** - no secrets, no dangerous CI settings (contents:
+  read, no pull_request_target, no secret use on untrusted PRs). Nits applied:
+  `persist-credentials: false` on checkout (+ a SHA-pin TODO), and README notes
+  Python 3.12+ and that the assessed YAML is a user-provided input.
+
+  **v0.2.0 Update Packs review** (2026-09-28, scoped to the change set
+  `master..488e0f6`: `app/packs/`, `app/pack_cli.py`, `app/adapters/mcp_config.py`,
+  `app/reviewer/{vocabulary,extensions}.py`, `docs/pack-schema.md`, plus the
+  separate data-only pack source `skos-pack-mcp`). Codex, four rounds, each
+  CHANGES-REQUIRED and fully or partly fixed: round 1 (`c14bc7f`) 16 findings
+  (4 HIGH), round 2 (`30840b5`) 8 new (3 HIGH), round 3 (`6cb990e`) 4 new
+  (1 HIGH), round 4 (`771d870`) 2 new (MEDIUM F29, LOW F30) plus a residual HIGH
+  (F25: a lost `installed.json` made a weakening update look like a first
+  install). F25/F29/F30 fixed in `2e0e99c`; that commit reviewed by
+  Antigravity: **PASS-with-nits**, the one documentation nit fixed in
+  `488e0f6`. Accepted as known limitations (recorded, not fixed): F08
+  (`npm exec` trailing options / `npm_config_registry` still inherit a known
+  package profile in `skos scan mcp`), F26 (same-version replacement drops the
+  displaced copy before the registry commit), F28 (a credential reference or
+  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.
+
 ## Tracked files by area
 
 Per-area counts below were last verified at round 2 (commit `bcd9519`) and
@@ -783,20 +822,20 @@ check enforces (total tracked files, total tests) are kept current above.
 
 | area | files | notes |
 | --- | --- | --- |
-| `app/` | 59 (.py) | engine, models, policy, retrieval, reviewer, llm, storage, eval, cli, main |
-| `tests/` | 83 | 52 test modules + fixtures |
+| `app/` | 77 (.py) | engine, models, policy, retrieval, reviewer, llm, storage, eval, cli, main, packs (Update Pack manager), adapters (MCP config scan, capability labels) |
+| `tests/` | 87 | 56 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 |
-| `scripts/` | 12 | validators, ingest/build_index, assess, evaluate, sbom, secret_scan, preflight, cross-review runner |
-| `docs/` | 9 | see below |
+| `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 |
 | root | 11 | `README.md`, `LICENSE`, `NOTICE`, `pyproject.toml`, `.gitignore`, `.env.example`, `constraints.txt`, `sbom.json` |
 | review docs | 3 | `REVIEW_PACKAGE.md`, `REVIEW_CHECKLIST.md`, `PUBLICATION_MANIFEST.md` |
 
 Docs: `architecture`, `threat-model`, `safety-boundaries`, `knowledge-schema`,
 `rule-schema`, `safe-test-schema`, `knowledge-corpus`, `attribution`,
-`acceptance-criteria`.
+`acceptance-criteria`, `history-rewrite-map`, `pack-schema`.
 
 ## Explicitly excluded (in `.gitignore`)
 
@@ -868,7 +907,7 @@ Safe-test templates (4): `ST-IPI-001`, `ST-MEM-001`, `ST-TOOL-001`, `ST-CRED-001
 
 ## Dependencies (`sbom.json`)
 
-63 components — the project's actual dependency closure (Codex#9, round 7:
+66 components — the project's actual dependency closure (Codex#9, round 7:
 walked outward from every declared root rather than listing every
 installed distribution, which also included `pip` and unrelated
 environment packages; Codex#9, round 8: a package reachable only
@@ -880,7 +919,9 @@ one that is itself a *direct* pyproject.toml entry; Codex#6, round 14:
 requirement, round 9's own fix, had discarded which extras a PARENT
 requirement actually activated on its dependency, hiding this one).
 Core install =
-`pydantic` + `pyyaml`; the rest are `[api]`/`[llm]` extras or dev/test-only.
+`pydantic` + `pyyaml` + (v0.2.0, Update Pack signatures) `cryptography`
+(Apache-2.0 OR BSD-3-Clause) with its dependencies `cffi` (MIT-0) and
+`pycparser` (BSD-3-Clause); the rest are `[api]`/`[llm]` extras or dev/test-only.
 Zero `UNKNOWN` licences. Licences present: MIT, BSD (2/3-Clause), Apache-2.0,
 PSF-2.0 — permissive — plus **`pathspec` and `certifi`, both under MPL-2.0**
 (Codex finding #10, round 2, 2026-09-11, corrected round 3, 2026-09-12: an
@@ -897,7 +938,7 @@ which use Python's native `truststore` instead of `certifi`); `pathspec`
 is a transitive dependency of `mypy` (**not** `ruff`, which declares no
 dependencies of its own per installed-environment metadata) — both
 dev/test-only or extras, never imported by, bundled with, or distributed
-as part of `app/`'s core install. None of the 63 components conflict with
+as part of `app/`'s core install. None of the 66 components conflict with
 Apache-2.0 distribution of this project. Full list in `sbom.json`.
 
 ## §24 evaluation (internal fixtures — not real-world performance)

{security_knowledge_os-0.1.0 → security_knowledge_os-0.3.0}/README.md

@@ -1,5 +1,14 @@
 # Security Knowledge OS
 
+[![PyPI](https://img.shields.io/pypi/v/security-knowledge-os)](https://pypi.org/project/security-knowledge-os/)
+[![Python](https://img.shields.io/pypi/pyversions/security-knowledge-os)](https://pypi.org/project/security-knowledge-os/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+```bash
+pip install security-knowledge-os
+skos assess your-agent.yaml   # deterministic, offline by default; bundled rules/knowledge
+```
+
 > **Language note / 言語について**: This repository (code, docs, commit history) is
 > **English-first by design** — it is written to be consumed by AI coding agents and
 > cites international standards (OWASP, MITRE ATLAS, NIST) directly. The section
@@ -113,7 +122,18 @@ treated as data, never as a control instruction. Details in
 | **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) |
 | **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` |
 
-## Quickstart (M1)
+## Install
+
+Requires **Python 3.12+**. From PyPI (ships the default rules / knowledge /
+safe-test data, so `skos assess` works with no checkout):
+
+```bash
+pip install security-knowledge-os          # engine + CLI
+pip install "security-knowledge-os[api]"   # + the local FastAPI app
+skos assess your-agent.yaml                # your-agent.yaml is an input you write
+```
+
+## Quickstart (M1, from a source checkout)
 
 ```bash
 python3.12 -m venv .venv

{security_knowledge_os-0.1.0 → security_knowledge_os-0.3.0}/app/__init__.py

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

security_knowledge_os-0.3.0/app/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters: derive assessment inputs from real-world configuration."""

security_knowledge_os-0.3.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