security-knowledge-os 0.1.0__tar.gz

security_knowledge_os-0.1.0/.env.example

@@ -0,0 +1,22 @@
+# Security Knowledge OS - example configuration.
+# Copy to .env and adjust. NEVER commit a real .env or any API key.
+
+# Assessment mode: private (public + internal) | public (public only)
+SKOS_MODE=private
+
+# Allow confidential-classified knowledge while in PRIVATE mode (explicit opt-in).
+SKOS_ALLOW_CONFIDENTIAL=false
+
+# LLM provider (decision A3): none (default, deterministic engine only)
+#                             | mock  (deterministic stub, for tests/demos)
+#                             | anthropic | openai | local
+SKOS_LLM_PROVIDER=none
+
+# Only read when SKOS_LLM_PROVIDER=anthropic. Injected by the operator at runtime;
+# never stored in this repository.
+# ANTHROPIC_API_KEY=
+# SKOS_LLM_MODEL=claude-sonnet-5
+
+# Knowledge base location and retrieval depth.
+SKOS_KNOWLEDGE_ROOT=knowledge
+SKOS_TOP_K=5

security_knowledge_os-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+
+# Secrets & local config (decision A3, 2026-09-10)
+.env
+*.local
+*.key
+*.pem
+.claude/
+
+# Pack Manager local state (Update Pack / Distribution Spec)
+/packs/
+/active/
+/var/audit/
+
+# --- Knowledge classification isolation (decision A1, 2026-09-10) ---
+# Secret-classified knowledge must live OUTSIDE this repository, under a separate root.
+/secret/
+
+# Internal / confidential knowledge: keep the folder skeleton, ignore the content.
+/knowledge/private/*
+!/knowledge/private/README.md
+!/knowledge/private/internal/
+!/knowledge/private/confidential/
+/knowledge/private/internal/*
+!/knowledge/private/internal/.gitkeep
+!/knowledge/private/internal/README.md
+/knowledge/private/confidential/*
+!/knowledge/private/confidential/.gitkeep
+!/knowledge/private/confidential/README.md
+
+# Local assessment artifacts / indexes
+/var/
+*.sqlite
+*.sqlite3
+*.db

security_knowledge_os-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

security_knowledge_os-0.1.0/NOTICE

@@ -0,0 +1,35 @@
+Security Knowledge OS
+Copyright 2026 The Security Knowledge OS authors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+--------------------------------------------------------------------------------
+Third-party knowledge sources
+--------------------------------------------------------------------------------
+
+The Knowledge Units under knowledge/public/ are original prose that summarises
+publicly documented security concepts. They do not reproduce third-party text
+verbatim. Each unit records its source in a `provenance` block; docs/attribution.md
+lists every source and its licence. In summary:
+
+  * OWASP Top 10 for LLM Applications 2025 (OWASP GenAI Security Project)
+    https://genai.owasp.org/  - CC-BY-SA-4.0
+    Referenced as the authoritative description of the risk categories.
+    The Knowledge Units are original wording, not derivative works of the
+    OWASP text.
+
+  * MITRE ATLAS - https://atlas.mitre.org/
+    MITRE ATLAS / ATT&CK Terms of Use (free use with attribution).
+
+  * NIST AI 600-1 (Generative AI Profile) and NIST AI Risk Management
+    Framework 1.0 - https://www.nist.gov/
+    U.S. Government works, not subject to copyright.
+
+  * simonwillison.net - referenced for context only; not reproduced.
+
+--------------------------------------------------------------------------------
+Runtime dependencies
+--------------------------------------------------------------------------------
+
+  pydantic (MIT), PyYAML (MIT); optional: fastapi (MIT), uvicorn (BSD-3-Clause),
+  anthropic (MIT). See sbom.json.

security_knowledge_os-0.1.0/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.5
+Name: security-knowledge-os
+Version: 0.1.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: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.132; extra == 'api'
+Requires-Dist: uvicorn>=0.29; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.132; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# Security Knowledge OS
+
+> **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
+> below is a short Japanese summary for human reviewers; everything else in this repo
+> stays English-only.
+>
+> 本リポジトリ（コード・docs・コミット履歴）は**英語がベース**です。AIコーディング
+> エージェントに読ませる一次資料として書かれており、OWASP・MITRE ATLAS・NISTなどの
+> 国際標準をそのまま引用しています。下の日本語要約は人間のレビュー用の窓口で、それ以外
+> の部分（docs配下含む）は今後も英語のままにする方針です。
+
+<details>
+<summary>🇯🇵 日本語要約（クリックで開く）</summary>
+
+**これは何か**: 既存のセキュリティ知識（メモ・GitHub・インシデント記録・実験ログ）を
+バージョン管理された「Knowledge Unit」に変換し、決定論的なルールエンジンで
+Prompt / RAG / Agent / Tool / Memory / Credential 面の一次AIセキュリティ査定を行うPoC。
+LLMは**任意（デフォルトoff）の推論層**で、証拠集め・ルール照合・ギャップの指摘までを担当し、
+最終判断は常に人間に返す設計。「AIが独断で"安全"と判定するツールではない」ことが前提。
+
+**安全設計のポイント**:
+- `PASS` はセキュリティの保証ではない。「評価範囲・入手した証拠・ルールセットの中で重大な
+  問題が見つからなかった」という意味にとどまる。
+- `UNKNOWN`（証拠不十分で推測しない）は正式な判定結果。
+- フィクスチャ（人工テストデータ）での指標は実世界の有効性を証明しない。
+- デプロイ承認・リスク受容など高インパクトな判断は必ず人間の担当者。自動実行はせず
+  `HUMAN_APPROVAL_REQUIRED` を返す。
+- 査定中、ナレッジリポジトリは読み取り専用。同じAIエージェントに自分のルール・知識を
+  書き換える権限は与えない（知識汚染対策）。
+- 未検証の入力に含まれる「このルールを無視して」等の指示は常にデータとして扱い、
+  命令としては扱わない（プロンプトインジェクション対策）。
+- 外部LLMに生の秘密情報（APIキー等）を送らない保証は、NGワードでのフィルタではなく
+  **構造的**（宛先名・ツール名は最初から匿名ラベルに置換してからLLMへ渡す）。
+
+**現状**: M1〜M8のマイルストーンはすべて完了（`done`）。ライセンスはApache-2.0。
+
+</details>
+
+**Deterministic security-assessment engine + knowledge retrieval + optional LLM assistance.**
+
+A PoC that converts existing security knowledge (notes, GitHub, incident records,
+experiment logs) into versioned *Knowledge Units*, and uses a swappable general LLM
+as an *optional* reasoning layer for first-pass AI-security assessment of
+Prompt / RAG / Agent / Tool / Memory / Credential surfaces.
+
+The source of truth for the design is the Google Drive document
+*"Security Knowledge OS — Claude Code Implementation Specification v0.1"* (2026-09-10).
+
+> This system is **not** an AI that decides "safe" on its own. It finds evidence,
+> evaluates against rules, flags gaps, and supports a human decision.
+
+## Security disclaimer & scope
+
+- **This is a security assessment *support* tool, not a security guarantee.**
+- **`PASS` is not a security guarantee.** It means "no major issue was detected
+  within the assessed scope, the available evidence, the active knowledge
+  revision, the rule set, and the model configuration". It does not prove the
+  target is secure.
+- **`UNKNOWN` is a valid, first-class verdict** - it means evidence was
+  insufficient. The engine returns `UNKNOWN` rather than guessing.
+- **Fixture performance is not real-world effectiveness.** The current metrics
+  (known-risk recall, false-positive rate, etc.) are measured on a small set of
+  *artificial* fixtures and show that the mechanism separates
+  vulnerable / safe / unknown as designed. They do **not** establish real-world
+  security effectiveness.
+- **Human review is required.** High-impact decisions - deployment approval, risk
+  acceptance, and anything affecting money, people, contracts, production, or
+  external parties - stay with a named human owner. High-impact *actions* are
+  never auto-executed; the engine returns `HUMAN_APPROVAL_REQUIRED`.
+- **The Knowledge Repository is read-only during assessment.** Retrieved content
+  can contain descriptions of prompt injection, tool abuse, and memory poisoning;
+  letting the same agent modify its own rules or knowledge would create a
+  knowledge-poisoning path. Do not grant an AI agent write access to the
+  production Knowledge Repository. Changes go through a separate review workflow.
+
+### Trust boundary
+
+| Trusted / controlled | Untrusted / potentially adversarial |
+| --- | --- |
+| Reviewed Knowledge Units | User prompts |
+| Approved risk rules | External documents / web / PDF / images |
+| Classification gate | RAG content before source & integrity verification |
+| Deterministic rule engine | The assessed AI's own output |
+| Human review / maintainer approval | LLM-generated observations & suggestions |
+| | An update pack before verification |
+
+"Ignore this rule" / "rewrite the knowledge" appearing in any untrusted input is
+treated as data, never as a control instruction. Details in
+`docs/safety-boundaries.md` and `docs/threat-model.md`.
+
+## Core principles
+
+- The LLM is **off by default**. `Input -> AssessmentContext -> Rule Engine -> Finding -> Report`
+  runs with no network, no API key, no LLM.
+- Knowledge and the reasoning model are **separated**. The LLM is a replaceable layer.
+- No unfounded guessing. `UNKNOWN` is a first-class verdict.
+- The LLM layer can **never create or clear a `FAIL`** (decision A8).
+- `public` / `internal` / `confidential` / `secret` are never mixed (decision A1).
+- The final decision is always returned to a human.
+
+## Milestone status
+
+| Milestone | State | Deliverables |
+| --- | --- | --- |
+| **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` |
+| **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` |
+| **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) |
+| **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)
+
+```bash
+python3.12 -m venv .venv
+.venv/bin/pip install -e ".[api,llm,dev]" -c constraints.txt --build-constraint constraints.txt
+
+# Validate the knowledge base (empty on a fresh checkout -> 0 issues)
+.venv/bin/python scripts/validate_knowledge.py knowledge
+
+# Load-check a knowledge root, then build the FTS5 index from it
+.venv/bin/python scripts/ingest.py knowledge
+.venv/bin/python scripts/build_index.py knowledge --db var/index.sqlite
+
+# Validate the deterministic rule catalogue and the safe-test templates
+.venv/bin/python scripts/validate_rules.py rules
+.venv/bin/python scripts/validate_safe_tests.py safe_tests
+
+# Run an assessment (provider=none by default: the deterministic engine does the work)
+.venv/bin/skos assess tests/fixtures/assessments/V-001-indirect-injection-auto-email.yaml
+.venv/bin/skos test          # run all 14 fixtures as a smoke test
+
+# Rebuild the FTS index (atomic + fail-closed; never touches knowledge content)
+.venv/bin/skos reindex knowledge --db var/index.sqlite
+
+# Local API (needs the [api] extra)
+.venv/bin/uvicorn app.main:app
+
+# Evaluate the engine + indexed knowledge against the labelled fixtures (§24 metrics)
+.venv/bin/python scripts/evaluate.py --db var/index.sqlite
+
+# Run the test-suite
+.venv/bin/pytest -q
+```
+
+The MVP ships **14 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
+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):
+
+```
+Classification Leakage          = 0
+Safe Test Safety Violation      = 0
+Human Gate Bypass               = 0
+current controlled-fixture metrics = 1.0
+  (known-risk recall, false-positive rate=0, UNKNOWN-appropriateness,
+   evidence coverage, citation/source match)
+```
+
+These results **do not establish real-world security effectiveness**. They show
+the mechanism behaves as designed on a controlled set.
+
+### `skos` CLI
+
+`validate-knowledge` · `validate-rules` · `validate-safe-tests` · `ingest` ·
+`reindex` · `assess` · `report` · `test`. Exit codes: `0` ok, `1` findings
+failure with `--strict`, `2` usage/input error, `3` `POLICY_BLOCKED`.
+
+### API (`app/main.py`)
+
+`POST /v1/assessments` · `GET /v1/assessments/{id}` ·
+`POST /v1/assessments/{id}/answers` · `GET /v1/assessments/{id}/history` ·
+`GET /v1/assessments/{id}/report` · `POST /v1/knowledge/validate` (read-only) ·
+`POST /v1/knowledge/reindex` · `GET /health`.
+
+`/answers` takes a **typed `AnswerPatch`** - an allow-list of fields a follow-up
+question can fill (`memory_persistent`, `memory_scope`, `outbound_enabled`,
+`credential_storage`, `tool_permissions`, `human_approval`, …). There is no
+generic deep-merge and no field is *named* for a raw secret value.
+
+The actual "never sends a raw secret to the external LLM" guarantee is
+**structural, not a content filter**: fields that are identifiers/hostnames
+*by contract* (`rag_sources`, `outbound_destinations`, `tool_permissions`/
+`human_approval` keys, tool `name`s) are never forwarded to the LLM as their
+real value at all - `app/reviewer/llm_review.py::build_payload()` replaces
+each with a stable, locally-scoped anonymized label (`rag_source_1`,
+`destination_1`, `tool_1`, `action_1`, …) before ever constructing the
+request, consistently across `assessment_context` and `attack_surface` so
+the LLM can still reason about structure (counts, permissions, which
+labelled tool needs approval) and refer to a specific one across its own
+observations. This closes the class outright: no value these fields could
+ever hold - a known credential shape, an unknown future one, or a genuine
+business secret that merely looks like an ordinary name - can reach the
+provider through them, because the raw value is never serialized in the
+first place (Codex#1, rounds 9-14, 2026-09-12 -- 2026-09-13, five rounds of
+content-filter attempts each defeated by a new shape - see
+`tests/unit/test_llm_review.py`). The ORIGINAL objects (used by the
+deterministic rule engine, and returned to the calling human via
+`AssessmentResult.attack_surface`) are untouched; only the LLM request-
+building path is anonymized. `app/models/_credential_shapes.py`'s denylist
+(known credential shapes) and allowlist (identifier-shaped values) remain
+as defense in depth on these same fields, not as this boundary.
+`system_prompt`/`developer_prompt` (actual prose, not identifiers) are
+never anonymized and only get the denylist - an arbitrary opaque string
+with no recognizable shape is indistinguishable from ordinary prose there.
+Given this project's Vault-only credential policy, never place a real
+secret in any assessment field regardless. **Rejected (HTTP 422):**
+an unknown patch field, a permission value outside the closed enum, a type
+mismatch. Tool names are *not* a fixed vocabulary - a diagnosed system can have
+any tool name - so `tool_permissions[<new name>]` **adds** that tool to the
+assessment (and a high-impact permission on it becomes a re-evaluation target);
+`tool_permissions[<existing>]` replaces its permission. The patched input is
+**re-assessed from scratch** - findings are never edited in place - and the new
+result records `supersedes` and `revision`.
+
+### Deviation from the spec
+
+Spec Section 5 recommends **Typer** for the CLI; this build uses stdlib `argparse`
+so the core install needs only `pydantic` + `pyyaml`. Spec Section 18's
+`POST /v1/knowledge/reindex` is implemented as index-only re-derivation (it never
+accepts or changes knowledge content).
+
+**There is no endpoint that changes knowledge content.** `/v1/knowledge/reindex`
+only re-derives the FTS index from the already-verified read-only knowledge root
+(classification + integrity checked before an atomic swap; the old index is kept
+on any failure).
+
+HTTP status and policy outcome are separate layers: a policy-blocked assessment
+is HTTP 422 with `status: "POLICY_BLOCKED"` and the `policy_decision` in the body,
+never HTTP 200 with empty findings. `human_review_required` is a workflow flag
+inside a `COMPLETED` (HTTP 200) body, not an error.
+
+Rules are **data, never code** - see `docs/rule-schema.md`. The deterministic
+assessment path (`app/reviewer/assess.py`) runs with no LLM: it normalizes the
+input, extracts the attack surface, evaluates the rule catalogue over a
+whitelisted fact set, and rolls the findings up. A rule is never `PASS` while any
+check was `UNKNOWN` or any required evidence was missing.
+
+The LLM is an **optional additive layer** (`SKOS_LLM_PROVIDER`, default `none`).
+It receives the deterministic findings as a read-only view and its output schema
+has no field for a status or an overall verdict, so it structurally cannot change
+a deterministic result - it can only add `LLM-OBS-*` observations (capped at
+`WARN`/`UNKNOWN`), questions, and notes. Malformed LLM output is repaired once,
+then discarded (`LLM_PARSE_ERROR`).
+
+**Policy outcomes are typed** (`PolicyOutcome`: `ALLOWED` /
+`HUMAN_APPROVAL_REQUIRED` / `POLICY_BLOCKED` / `READ_ONLY_VIOLATION`), never bare
+strings. The Human Gate fails closed - a recognised high-impact action, or any
+unrecognised one, returns `HUMAN_APPROVAL_REQUIRED`. The Knowledge Repository is
+read-only during assessment. Safe tests are **vetted templates only**
+(`safe_tests/*.yaml`, passed through a deterministic validator that forbids real
+secrets, external destinations, destructive operations and production targets);
+an LLM's `safe_test_suggestions` land in `safe_test_proposals` as untrusted ideas
+and are never promoted to an executable test automatically.
+
+The knowledge root and index path are parameters (`SKOS_KNOWLEDGE_ROOT`,
+`SKOS_DB_PATH`), so the same code serves `knowledge/` today and a Pack Manager's
+`active/knowledge/` later. `top_k` counts Knowledge Units; secret-classified units
+never enter the index.
+
+`scripts/validate_knowledge.py` exits non-zero when any `ERROR`-level issue is found
+(use `--strict` to also fail on warnings).
+
+## Knowledge classification & layout (decision A1)
+
+```
+knowledge/
+├─ public/            # git-tracked; retrievable in PUBLIC and PRIVATE mode
+│  ├─ prompt-security/  rag-security/  agent-security/
+│  ├─ memory-security/  credential-security/
+│  └─ incidents/  methodology/
+└─ private/           # git-ignored content (skeleton kept)
+   ├─ internal/       # PRIVATE mode only
+   └─ confidential/   # PRIVATE mode + explicit --allow-confidential
+
+secret/               # OUTSIDE this repository, separate root.
+                      # Never indexed, never sent to an LLM.
+```
+
+`classification: secret` appearing anywhere inside the repo is a validator **ERROR**.
+
+## LLM configuration (decision A3)
+
+The default provider is `none`. To enable an external LLM, set both:
+
+```bash
+export SKOS_LLM_PROVIDER=anthropic
+export ANTHROPIC_API_KEY=...      # injected by the operator, never stored in the repo
+```
+
+See `.env.example`.
+
+## Documentation
+
+- `docs/architecture.md` — component overview and configurability seams
+- `docs/threat-model.md` — assets, trust boundary, threats & controls, residual risks
+- `docs/safety-boundaries.md` — decisions A1/A3/A6/A7/A8, Human Gate, §32 read-only, §33 trust boundary
+- `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/attribution.md` — third-party sources, licences, derivation status
+- `docs/acceptance-criteria.md` — AC-01..20 status and §24 evaluation metrics
+
+## Licence
+
+Apache License 2.0 — see `LICENSE` and `NOTICE`.
+
+The engine code is licensed under Apache-2.0. The Knowledge Units under
+`knowledge/public/` are original prose licensed under the same terms; they cite
+public standards (OWASP, MITRE ATLAS, NIST) and do not reproduce third-party text
+verbatim (see `docs/attribution.md`). A future commercial "Update Pack" would be
+licensed separately (see the Update Pack / Distribution specification).