This is an automated email from the ASF dual-hosted git repository. luigidemasi pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel-kit.git
commit 6f642fb3e849c507ced891a4614ac99a7f7cd52f Author: Luigi De Masi <[email protected]> AuthorDate: Mon Nov 9 19:15:21 2026 +0100 Fix #156: verify and correct the process side-effect inventory Fixes #156 Co-authored-by: OpenAI Codex <[email protected]> --- CHANGELOG.md | 8 +++ docs/security-model.md | 143 ++++++++++++++++++++++++------------------ docs/security-model.yaml | 50 ++++++++------- docs/security-verification.md | 57 +++++++++++++++-- 4 files changed, 169 insertions(+), 89 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 95ba9893..b01fb646 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,8 +20,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add target-specific Maven staging and maintainer-triggered index publication. Kit keeps its released Knowledge runner pin; group and version overrides allow explicit adoption. +### Fixed + +- Preserve legitimate init layouts containing unrelated symlinks and normal permissions on new generated files. +- Exclude VCS, build and dependency trees from graphs; support up to 256 MiB of recognized sources while retaining per-file limits and validation before XML sniffing. +- Derive Claude MCP grants from the workflow manifest and validate catalog cache version components. + ### Added +- **Verified process inventory (#156)** — correct CLI/Ship/Knowledge host effects and clock assumptions, distinguish source evidence from runtime observations, and record the six verification outcomes. + - **Knowledge runtime boundaries (#158)** — enforce offline CPU tokenizer initialization, cover query/cap/fallback and transport behavior, document native caches, and accept conventional CVE severity spellings. - **Generated and cached path confinement (#157)** — refuse descendant symlinks before init/catalog writes and validate catalog versions before extraction or replacement. diff --git a/docs/security-model.md b/docs/security-model.md index a33b0ff3..00a8cf27 100644 --- a/docs/security-model.md +++ b/docs/security-model.md @@ -12,11 +12,11 @@ | Field | Value | | --- | --- | | Project | Apache Camel Kit — the Kit and Knowledge products (`apache/camel-kit`) | -| Version / source baseline | Kit `0.4.2-SNAPSHOT` (source baseline commit `70796c02`); Knowledge `0.0.3-SNAPSHOT` (baseline commit `9c8173cb`) | +| Version / source baseline | Kit `0.4.2-SNAPSHOT`; Knowledge `0.0.3-SNAPSHOT`; main `2863e915` plus PR #6 and verification fixes #153–#158 | | Repository layout | Monorepo since commit `9c8173cb`: `kit/` and `knowledge/` with independent release lines | -| Date | 2026-10-22; revised 2026-10-27 after review round 2; revised 2026-11-02 after review round 3 | +| Date | 2026-10-22; policy decisions 2026-10-27; verification revision 2026-11-09 | | Author(s) | Camel-Kit maintainers; drafted with the threat-model-producer procedure in draft-first mode for [apache/camel-kit#5](https://github.com/apache/camel-kit/issues/5) | -| Status | **DRAFT — policy ratified, acceptance pending verification.** All thirteen §4.14 questions were answered by a maintainer on 2026-10-27 (§4.14.1). Acceptance is blocked on the verification items V1–V6 of §4.14.2: tested parser guarantees, graph confinement and bounds, narrower Claude MCP defaults, a verified per-process side-effect inventory, init and download path controls, and verification of the Knowledge section; each item has a tracking issue (#153–#158). Claims tagged *(i [...] +| Status | **DRAFT — implementation verification complete; maintainer acceptance pending.** Policy decisions remain those recorded on 2026-10-27. Changes for #153–#158 implement V1–V6 with [source and executable evidence](security-verification.md). Acceptance/merge and publication under #131 remain maintainer actions; this revision does not claim their approval. | **Version binding.** This model is versioned with the project. A report against Camel-Kit version *N* is triaged against the model as it stood at *N*, not at `HEAD`. Camel Ship is a Technology Preview *(documented — README, @@ -32,8 +32,7 @@ assumptions, but also introduces specific surfaces and trust boundaries related workflow execution, graph parsing of migration sources, and dynamic classloader resolution")*. **Inherited properties bind before they are verified.** Where this document records that the enforcement of an -inherited property is unverified or incomplete (today: the confinement and bounded-resource clauses of the graph -source-reading contract, §4.8 P1), the property still binds and a report that breaks it is triaged `VALID`; the gap +inherited property is unverified or incomplete, the property still binds and a report that breaks it is triaged `VALID`; the gap is tracked as a §4.14.2 verification item, never disclaimed in §4.9 *(maintainer, 2026-10-27 — Q2)*. **Provenance legend.** *(documented)* = stated in Camel-Kit's own documentation, source-level Javadoc, shipped @@ -42,14 +41,14 @@ cited. *(maintainer, date)* = stated by a maintainer in answer to a §4.14 quest apache/camel-kit#6, or as a recorded decision. *(inferred)* = reasoned from code structure or the absence of a feature; every *(inferred)* tag names the §4.14.2 verification item (`Vn`) that will settle it. -**Draft confidence.** 200 documented / 33 maintainer / 21 inferred tags. Update as §4.14.2 items are -verified. +**Verification basis.** Source references and executable results are recorded per item in +[security-verification.md](security-verification.md). Historical policy decisions remain attributed +to their maintainers; automated evidence does not imply human approval. **Products covered.** This model covers both products of the monorepo: **Kit** in `kit/` (families A–E, G and H in §4.2) and **Knowledge** in `knowledge/` (families K and K2, §4.4a). Knowledge joined this model by maintainer decision after the consolidation in [apache/camel-kit#2](https://github.com/apache/camel-kit/issues/2) -*(maintainer, 2026-10-27 — Q11)*; its statements are drafted from code and the Knowledge README and await -verification (V6). External MCP servers remain out of scope (family F). References to the product README below mean +*(maintainer, 2026-10-27 — Q11)*; its statements are supported by source and executable evidence (V6). External MCP servers remain out of scope (family F). References to the product README below mean `kit/README.md` unless they name `knowledge/README.md`. **Purpose (one paragraph).** Camel-Kit is a developer tool that adds structured workflows ("skills", Markdown @@ -98,7 +97,7 @@ metadata; Kit configures it for each harness, and it also serves MCP clients tha | Family | Representative entry points | Touches outside the process? | In this model? | | --- | --- | --- | --- | - | **A. Workspace CLI** — `init`, `doctor`, `doc`, `nextId`, `plan analyze`, `graph *` (`camel-kit-core` commands, services, generators, catalog downloaders; `camel-kit-main` JBang launcher; `camel-jbang-plugin-kit`) | picocli commands | Writes the target workspace; reads `~/.camel-kit/config.properties`; `init` downloads catalogs over HTTPS unless `--no-fetch`; version probes spawn `java`, `jbang`, `camel`, `mvn`/`mvnw`, `pi` | **In** | + | **A. Workspace CLI** — `init`, `doctor`, `doc`, `nextId`, `plan analyze`, `graph *` (`camel-kit-core` commands, services, generators, catalog downloaders; `camel-kit-main` JBang launcher; `camel-jbang-plugin-kit`) | picocli commands | Writes the target workspace; reads `~/.camel-kit/config.properties`; `init` downloads catalogs over HTTPS unless `--no-fetch`; prerequisite probes spawn `java`, `jbang`, `camel` (including `camel test --help`) and `mvn` when no wrapper exists; see §4.5 [...] | **B. Graph analysis** (`camel-kit-graph`: Pom, Java, Groovy, XML route, Mule XML, DataWeave, BizTalk, YAML route, Config parsers plus the cross-linker and property-binding post-processors) | `camel-kit graph …`; `init --here` auto-analysis | Reads the analysed tree; writes `.camel-kit/project-graph.json`; no network, no child process *(documented — `ParserSourceReadingContractTest`; [V1 evidence](security-verification.md#v1-source-reading))* | **In** — the analysed tree is untrusted input | | **C. Skills, templates, traits, agent registry, workflow manifest** (`kit/camel-kit-core/src/main/resources/{skills,templates,agents,workflow}`) | installed by `init` into the workspace | Nothing by itself; the harness executes the instructions with its own permissions; generated MCP configs make the harness launch MCP servers through `jbang` at pinned coordinates | **In** as shipped instructions and generated configuration; the harness and the model are out (§4.3) | | **D. Ship controller** (Technology Preview; `camel-kit-core` `ship/**`, `command/ship`) | `camel-kit ship`, `/camel-ship` delegates | Spawns `pi`/`node` (Pi backend), `/usr/bin/setsid`, `/bin/kill`, its own `java`; writes `.camel-kit/ship/state` or `$CAMEL_KIT_SHIP_STATE_HOME`; publishes into the live project; HTTPS to Maven Central through family E | **In** | @@ -146,7 +145,7 @@ metadata; Kit configures it for each harness, and it also serves MCP clients tha Docker and the coding harnesses belong to their projects. Kit's generated configuration for them is in (§4.8 P4, P10). Knowledge is maintained in this repository and is in this model (§4.4a). - **The content of the upstream sources Knowledge indexes.** Apache documentation, release notes, advisories and - catalog metadata are ingested at release tags from Apache repositories, Maven Central, Apache JIRA, NVD and CIRCL + catalog metadata are ingested from selected Apache product refs, Maven Central, Apache JIRA, NVD and CIRCL; version discovery also reads camel-website main (§4.4a); hostile content there would require a compromised upstream source (§4.7). What that content says is data for the consumer, never an instruction. - **Vulnerabilities in transitive dependencies not reachable through Camel-Kit code**, as in the umbrella model @@ -223,7 +222,7 @@ trusted")*. Maven Central response, or by another local account — never when it requires the developer's own OS account. - **K (Knowledge server and index):** in-model if reachable from a tool argument, from a release-list, manifest or archive response, from the cache directory contents, or by another local account — never when it requires the - developer's own OS account. **K2 (indexer):** its inputs are upstream Apache sources at release tags; a finding needs + developer's own OS account. **K2 (indexer):** its inputs are upstream Apache sources at selected product refs plus camel-website main discovery; a finding needs hostile upstream content (§4.7, out) unless the indexer breaks its own path or process boundary. - **F, G, H:** out; route to the owning project or to the Apache Camel Security Model. @@ -268,8 +267,8 @@ Knowledge README, code and executable checks recorded in [V6 evidence](security- on the supported bundled CPU path; it is not an OS sandbox or permission to install arbitrary native-library overrides. `OfflineModelsTest` exercises both model initialization orders. - *Indexer* (`knowledge/indexer`, `IndexerMain`): a maintainer-run build tool that "runs during CI/CD to produce the - pre-built index artifact", invoked by the `-Prebuild-index` profile and the `Index Release` workflow. It clones - Apache repositories at release tags with JGit, converts AsciiDoc, downloads Camel Catalog JARs, fetches Apache JIRA + pre-built index artifact", invoked by the `-Prebuild-index` profile and the `Index Release` workflow. It reads camel-website main for version discovery, then clones + selected Apache product refs with JGit, converts AsciiDoc, downloads Camel Catalog JARs, fetches Apache JIRA issues and enriches advisories from NVD with a CIRCL fallback, then writes the Lucene index *(documented — `IndexerMain` Javadoc; `knowledge/README.md`)*. It never runs inside the shipped server. @@ -295,7 +294,7 @@ Knowledge README, code and executable checks recorded in [V6 evidence](security- *(documented — `knowledge/README.md`, "Index Distribution")*. Search results are the upstream authors' text and are data for the consumer (§4.4; `context-authority.md`). 4. *Indexer ← upstream sources.* Inputs are `apache/camel`, `apache/camel-website`, `apache/camel-quarkus` and - `apache/camel-spring-boot` at release tags, Camel Catalog JARs from Maven Central, Apache JIRA, NVD and CIRCL + `apache/camel-spring-boot` at selected product refs, plus camel-website main for version discovery, Camel Catalog JARs from Maven Central, Apache JIRA, NVD and CIRCL *(documented — `knowledge/README.md`, "Data Sources", "CVE enrichment and fallback")*. These are trusted upstream sources; a hostile document would require a compromised Apache repository or mirror (§4.7). @@ -339,35 +338,51 @@ a report against `0.0.2` is triaged on what that release documents. *(documented — `ShipSecureFilesystem` Javadoc: "Internal bounded read policy for Ship trees"; unsupported filesystems fail closed)*. - **Concurrency.** Graph parsers run in a thread pool bounded by the CPU count and results are merged - deterministically *(inferred — V4)*. Ship holds run and project mutation locks for live-tree operations + deterministically *(documented — `GraphBuilder`; V4 source inventory)*. Ship holds run and project mutation locks for live-tree operations *(documented — `ShipPublicationService` Javadoc)*; "ordinary process interruption is recoverable … but Ship is not a daemon or a guarantee against OS or power loss" *(documented — `docs/commands.md`)*. -- **Time.** Only timeouts and deadlines depend on the clock (stage timeout default 10 minutes; native task deadlines) - *(documented — `docs/commands.md`, `docs/ship-native.md`)*; no security decision depends on wall-clock trust. -- **Network.** Outbound HTTPS only, to fixed or operator-configured origins; the JVM's standard proxy and TLS system - properties are honoured by the Ship resolver *(documented — `ShipMavenResolver` session comment)*. Knowledge needs - a cache filesystem that "must support advisory file locks and atomic moves" *(documented — `knowledge/README.md`)*. - -**Per-process side-effect inventory.** Negative claims are scoped to the process and configuration that support them -*(maintainer, 2026-10-27 — Q6)*. A cell marked *documented* cites a source or a code constant; a cell marked -*inspected* comes from code inspection and is *(inferred — V4)* until a maintainer verifies it. - -| Process (configuration) | Listening sockets | Child processes | Network | Filesystem writes | Environment read | Telemetry | Limits | +- **Time.** Wall-clock time is used for audit metadata, native task expiration, evidence ordering, + release/version metadata and enrichment cooldowns. Clock changes can affect persisted deadlines + *(documented — `ShipNativeWorker`, `ShipLocalStamp`, `ShipMainValidator`, `VersionResolver`, `IndexerMain`, `CveParser`)*. +- **Network.** Policy is component-specific: Kit downloaders use HTTPS; Knowledge also permits local + files and loopback HTTP; serving HTTP is opt-in; external workers retain their own network behavior. + Ship's resolver honors JVM proxy/TLS properties. Knowledge cache updates require advisory file locks + and atomic moves *(documented — downloader/resolver implementations and `knowledge/README.md`)*. + +**Per-process side-effect inventory.** Each row is tied to concrete implementation sources below. +“No direct call” describes the named first-party code path, not a guarantee about arbitrary JVM +startup agents, configured native libraries or external tools. [Verification evidence](security-verification.md#v4-process-inventory) +distinguishes source audit, dependency behavior and executable observations; it does not claim human +maintainer approval. Negative claims apply only to the listed process and configuration. + +| Process/configuration | Listening sockets | Child processes | Network | Filesystem writes | Environment and configuration inputs | Telemetry | Limits | | --- | --- | --- | --- | --- | --- | --- | --- | -| **Kit CLI** `camel-kit` / `camel kit`: `init`, `doctor`, `doc`, `nextId`, `plan analyze`, `graph` | none (inspected) | version probes only: `java -version`, `jbang version`, `camel --version`, `mvn`/`mvnw`, `pi -a` *(documented — `PrerequisiteChecker`, `DoctorService`, `docs/agent-architectures.md`)* | `init` without `--no-fetch`: HTTPS to `repo1.maven.org`, `raw.githubusercontent.com/apache/camel`, `api.github.com` (Kamelet listing) and `search.maven.org`; redirects followed except HT [...] -| **Graph analysis** (inside the CLI process) | none (inspected) | none *(documented — `ParserSourceReadingContractTest`; [V1 evidence](security-verification.md#v1-source-reading))* | none *(documented — `ParserSourceReadingContractTest`; [V1 evidence](security-verification.md#v1-source-reading))* | `.camel-kit/project-graph.json` or the `--output` path *(documented — `GraphGenerateCommand`)* | none (inspected) | none (inspected) | 60 s per parser including POM; 16 MiB/source, 64 MiB agg [...] -| **Ship controller** `camel-kit ship` | none (inspected) | `pi` and `node` (Pi backend), `/usr/bin/setsid`, `/bin/kill`, the controller's own `java` for evidence *(documented — `PiWorker`, `LocalCommandRunner`, `EvidenceRunner`)* | HTTPS to Maven Central through the resolver; no redirects; checksum `fail` *(documented — `ShipMavenResolver`)* | `.camel-kit/ship/state/` or `$CAMEL_KIT_SHIP_STATE_HOME`; the live project only through journaled publication *(documented — `docs/commands.md`, [...] -| **Ship Pi worker** (`--backend pi`) | Pi's own process | Pi's tools — `bash`, `edit`, `write` in EXECUTE — started in the staging cwd, which is a working directory, not a confinement *(documented — `PiWorker` Javadoc)* | whatever Pi and its provider need — external behaviour, outside this model (§4.3); launched with `--offline`, `--no-extensions`, `--no-skills`, `--no-context-files` *(documented — `PiWorker` arguments)* | *Intended:* the staging workspace and its session directory unde [...] -| **Ship evidence JVMs** | none (inspected) | none (inspected) | none by design: every non-direct endpoint stubbed *(documented — `docs/commands.md`)* | private `HOME` and `TMPDIR` under the run; frozen read-only copy *(documented — `EvidenceRunner`)* | scrubbed to `LANG`, `LC_ALL`, `HOME`, `TMPDIR`, `GIT_CEILING_DIRECTORIES` and controller-provided variables *(documented — `EvidenceRunner`)* | none (inspected) | 64 MiB log cap; stage timeout *(documented — `EvidenceRunner`)* | -| **Knowledge MCP server** (default configuration) | none — stdio *(documented — `knowledge/README.md`)*; HTTP/SSE only with `quarkus.http.host-enabled=true` | none *(inferred — V6)* | first query only: the configured releases endpoint, manifest and asset URLs over `https` (`http` only to a loopback host), each redirect target checked before the hop *(documented — `IndexDownloader`; apache/camel-kit#143)*; nothing else *(inferred — V6)* | `~/.camel-kit/knowledge-index` or `knowledge.inde [...] -| **Knowledge indexer** (maintainer tool: `-Prebuild-index`, `index-release.yml`) | none (inspected) | none — JGit runs in-process (inspected) | `github.com` (clones, `ls-remote`), `raw.githubusercontent.com`, Maven Central, `issues.apache.org`, `services.nvd.nist.gov`, `vulnerability.circl.lu` *(documented — `knowledge/README.md`, `VersionResolver`, `JiraFetcher`, `CveParser`)* | `knowledge/indexer/src/main/resources/apache-camel/{repos,catalog-cache,embedding-cache,cve-cache}` and the [...] +| Kit CLI: init, doctor, doc, nextId, plan analyze, graph | No direct listener in these command paths [I1]. | Init/doctor prerequisites invoke java -version, jbang version, camel --version; init also invokes camel test --help. Doctor invokes mvn -version if no wrapper is present. Probes inherit environment [I1]. | Init fetchers use HTTPS Maven Central, raw GitHub, GitHub API and Maven Search; redirects except HTTPS downgrade; no independent checksum/signature. Other listed implementation [...] +| Graph analysis/visualization in CLI | No direct listener [I3]. | No direct launcher [I3]. | No direct fetch in source-parsing path [I3]. | Generate: project-graph.json or --output; visualize: project-graph.html or --output [I3]. | Selected paths; source placeholders are data, not process-environment substitution [I3]. | No first-party export call found [I3]. | CPU-limited pool, sorted merge; all parsers including POM 60 s; source 16 MiB/file and 256 MiB total; 100000 visited entries. C [...] +| Ship controller | No direct listener [I4]. | Pi: setsid launches node with Pi script; kill cleanup helper. Evidence: controller Java. Native mode writes tasks for external host [I4]. | Fixed https://repo.maven.apache.org/maven2/; no redirects, checksum fail for downloaded artifacts; preexisting local artifacts trusted. JVM proxy/TLS settings apply [I4]. | State root; private Maven repository (stateRoot/catalog-repository or --maven-repository); run/lock/dispatch/evidence artifacts. Liv [...] +| Ship Pi worker | External Pi/provider behavior. | Pi tools selected by stage; staging cwd is not confinement [I5]. | External Pi/provider behavior. Offline/no-extensions/no-skills/no-context-files arguments do not create an OS network restriction [I5]. | Intended staging/session paths; same-account-reachable paths remain accessible. Native hosts have separate external policies [I5]. | Full captured controller environment; bounded Git discovery for EXECUTE [I5]. | External Pi/provider b [...] +| Ship evidence JVMs | No listener requested by inspected launcher/payload; no OS socket restriction [I6]. | Direct Java launch, payload in process; no OS process restriction [I6]. | Non-direct endpoints stubbed by validator; no OS egress restriction [I6]. | Private HOME/TMP, accepted frozen tree, stdout/stderr; nested payload JARs extracted under private JVM temp. Same OS account remains privilege boundary [I6]. | Environment cleared then fixed LANG/LC_ALL/HOME/TMPDIR, controller variab [...] +| Knowledge MCP, default stdio | HTTP host disabled by property; opt-in HTTP/SSE changes this. Runtime proof is configuration-specific [I7]. | No first-party launcher; OfflineTokenizer disables CUDA child discovery and implicit JNA ldconfig lookup [I7]. | Index releases/manifests/assets when needed; HTTPS/loopback HTTP and local file inputs; validated redirects. Models/tokenizer data are classpath resources. OfflineTokenizer enforces offline CPU initialization: no metadata/telemetry or n [...] +| Knowledge indexer, maintainer build process | No direct listener [I8]. | JGit/AsciidoctorJ called in process; no first-party launcher; shared OfflineTokenizer policy disables implicit CUDA/JNA subprocess discovery [I8], [D1]. | GitHub/raw files, Maven Central, Apache JIRA, NVD, CIRCL; shared offline CPU embedding initialization above. This is implemented origins, not an OS allowlist [I8], [D1]. | Selected resources root apache-camel/{repos,catalog-cache,jira-cache,embedding-cache,cve-c [...] + + +[I1]: ../kit/camel-kit-core/src/main/java/org/apache/camel/kit/service/DoctorService.java +[I2]: ../kit/camel-kit-core/src/main/java/org/apache/camel/kit/catalog/CatalogDownloader.java +[I3]: ../kit/camel-kit-graph/src/main/java/org/apache/camel/kit/graph/GraphBuilder.java +[I4]: ../kit/camel-kit-core/src/main/java/org/apache/camel/kit/ship/worker/LocalCommandRunner.java +[I5]: ../kit/camel-kit-core/src/main/java/org/apache/camel/kit/ship/worker/PiWorker.java +[I6]: ../kit/camel-kit-core/src/main/java/org/apache/camel/kit/ship/evidence/EvidenceRunner.java +[I7]: ../knowledge/mcp/src/main/java/org/apache/camel/kit/knowledge/mcp/IndexDownloader.java +[I8]: ../knowledge/indexer/src/main/java/org/apache/camel/kit/knowledge/indexer/IndexerMain.java +[D1]: ../knowledge/embedding/src/main/java/org/apache/camel/kit/knowledge/embedding/OfflineTokenizer.java +[D2]: ../knowledge/embedding/src/main/java/org/apache/camel/kit/knowledge/embedding/OnnxEmbeddingProvider.java Camel-Kit never runs `git` against the live project: Ship bounds Git discovery at the staged workspace with `GIT_CEILING_DIRECTORIES` so "Git commands run by the Execute worker, by local commands, or by validation inside it do not reach the project's repository" *(documented — `docs/commands.md`)*; neither product commits or pushes (inspected), and the generated Copilot hook and Pi guard deny `git push` by the agent *(documented — `docs/agent-architectures.md`)*. Deletions are confined to generated assets inside the project (refusing symbolic -links), controller-owned state, caches and private temporary directories *(documented — `GeneratedAssetCleaner`, +links), controller-owned state, caches and private temporary directories *(documented — `GeneratedAssetCleaner`, `InitService`, `ConfinedPaths`, `IndexDownloader`)*. --- @@ -390,7 +405,7 @@ Camel-Kit is a family of postures. The knobs that move the security envelope: | `camel-kit ship --maven-repository PATH` | `<state root>/catalog-repository` | Private repository for validation payloads. "Checksum enforcement applies to downloads only, so protecting the repository between runs belongs to the caller" *(documented — `ShipMavenResolver` Javadoc)*. | Documented. | | `CAMEL_KIT_SHIP_STATE_HOME` | unset → `.camel-kit/ship/state/` in the project | Relocates run records, retained evidence, Pi transcripts and the staged workspace *(documented — `docs/commands.md`)*. | Documented; location choice is the developer's (§4.10). | | `camel-kit ship --stage-timeout` | `10m` | Bounds one stage attempt. | Documented. | -| `knowledge.index.path` (`KNOWLEDGE_INDEX_PATH`) | unset | Uses a local index directory in place: no network, no cache *(documented — `knowledge/README.md`)*. | Documented (development, tests, air-gapped use). | +| `knowledge.index.path` (`KNOWLEDGE_INDEX_PATH`) | unset | Uses a local index directory in place: no index-acquisition network or index cache; native-library caches still apply *(documented — `knowledge/README.md`)*. | Documented (development, tests, air-gapped use). | | `knowledge.index.url` (`KNOWLEDGE_INDEX_URL`) | unset → release discovery | Explicit manifest URL; `https` and `file` are accepted anywhere, `http` only to a loopback host (`localhost`, `127.0.0.0/8`, `::1`) — a plaintext manifest from a remote host is refused before any request, and so is a redirect to one *(documented — `knowledge/README.md`; `IndexDownloader.requireFetchableUri`; apache/camel-kit#143)*. | Documented; an operator-selected origin is trusted input (§4.10). | | `knowledge.index.version` (`KNOWLEDGE_INDEX_VERSION`) | unset → newest compatible published index | Exact index pin; never falls back to another version *(documented — `knowledge/README.md`)*. | Documented. | | `knowledge.index.releases-url`, `knowledge.index.cache-dir` | `https://api.github.com/repos/apache/camel-kit/releases`, `~/.camel-kit/knowledge-index` | Discovery endpoint and cache location *(documented — `knowledge/README.md`)*. | Documented; operator input. | @@ -399,7 +414,7 @@ Camel-Kit is a family of postures. The knobs that move the security envelope: | `camel.main.profile` and other Camel knobs in generated projects | Camel's | Belong to the generated integration and the umbrella model. | Downstream (§4.10). | The **insecure-default cases** were ruled on 2026-10-27: the generated Claude MCP wildcard pre-approval is not the -accepted posture and must be narrowed before acceptance (Q3, V3); the Maven pre-approval stands as documented; snapshot +accepted posture and is narrowed by V3 (Q3, V3); the Maven pre-approval stands as documented; snapshot repositories stay as a development convenience with their mutability documented (Q4). --- @@ -416,8 +431,8 @@ Per-entry-point trust table. "Caller" is the developer unless stated otherwise. | `~/.camel-kit/config.properties`, `.camel-kit/config.properties` | properties | no — operator | — | | `camel-kit graph <sub> [root]` | file bodies, names and link targets under `root` | **yes** | Same as `init --here`; confinement to `root` and bounded time and memory are claimed by P1, with enforcement verified under V2 | | `camel-kit graph …` output, `.camel-kit/project-graph.json` | graph JSON consumed by skills | derived from the tree | Treat as data in prompts *(documented — umbrella "Reading route sources")* | -| `camel-kit doc check/stale/unstale <file>` | YAML frontmatter of pipeline artifacts | model-authored → **yes** | Parsed as data with a bounded YAML tree parser *(inferred — V4)*; digests are staleness markers only (§4.9) | -| `camel-kit plan analyze` | `implementation-plan.md` task metadata | model-authored → **yes** | Same | +| `camel-kit doc check/stale/unstale <file>` | YAML frontmatter of pipeline artifacts | model-authored → **yes** | Parsed as data by `FrontmatterHandler` (Jackson YAML); no separate byte quota is claimed here; digests are staleness markers only (§4.9) | +| `camel-kit plan analyze` | `implementation-plan.md` task metadata | model-authored → **yes** | Parsed as data by `PlanAnalyzer`; no project execution | | `camel-kit nextId <slug>` | slug → `docs/camel-kit/NNN-slug/` | no — operator | — | | `camel-kit ship --text`, `--document PATH` | context for the model | supplied by the developer; **content is loaded context** for the model | Do not pass secrets; third-party documents can carry instruction-like text (§4.3, §4.10) | | `camel-kit ship` native result envelope (`--result PATH`; `bob2-native`, `copilot-native`, `claude-native`, `codex-native`) | stage result JSON and file proposals | **yes** — model output | Controller: strict JSON schema (`FAIL_ON_UNKNOWN_PROPERTIES`, no coercion); a proposal is written only for the approved route and test paths, `pom.xml` and `.camel-kit/config.properties`, after a known-secret scan; then the same candidate checks as the Pi backend (§4.8 P5–P9) | @@ -432,7 +447,14 @@ Per-entry-point trust table. "Caller" is the developer unless stated otherwise. | Knowledge configuration (`knowledge.index.*`, `KNOWLEDGE_INDEX_*`, `quarkus.http.*`) and a local `knowledge.index.path` | properties, environment, directory | no — operator | — | | Knowledge cache directory (`~/.camel-kit/knowledge-index`) | version directories, `current`, `etag`, staging | same user only | Server: version directories must be real directories; marker and validator rebound on activation; staging cleaned under the update lock (§4.8 P13) | -**Size, shape and rate.** Ship states its limits (§4.8 P11). Graph input bounds are 16 MiB per source, 64 MiB aggregate recognized source and 100,000 filesystem entries; every parser has a 60-second timeout (P1). `init` downloads are whole artifacts with a 30–60 s request timeout *(documented — downloader +**Knowledge JVM-wide initialization policy.** `OfflineTokenizer` sets `ai.djl.offline=true`, +`RUST_FLAVOR=cpu` and `ai.djl.util.cuda.fork=false`. If `jna.platform.library.path` is absent, +it sets it to the empty string to prevent JNA from launching `ldconfig`; an explicit value is +preserved. These are process-wide settings, not tokenizer-local options, and can affect other +DJL/JNA users in the same JVM. Knowledge is a standalone process; applications sharing its +embedding library must account for this initialization policy. + +**Size, shape and rate.** Ship states its limits (§4.8 P11). Graph input bounds are 16 MiB per source, 256 MiB aggregate recognized source and 100,000 filesystem entries; every parser has a 60-second timeout (P1). `init` downloads are whole artifacts with a 30–60 s request timeout *(documented — downloader constants)*. --- @@ -503,8 +525,11 @@ violation warrants coordinated disclosure and a CVE; **hardening** means it is f phase only *(documented — `ParserSourceReadingContractTest`; [V1 evidence](security-verification.md#v1-source-reading))*; YAML routes and configuration use Jackson's tree model, DataWeave and properties are regular-expression scans *(documented — `ParserSourceReadingContractTest`; [V1 evidence](security-verification.md#v1-source-reading))*. `GraphBuilder` applies a 60-second timeout to every parser, including the POM parser. A timeout discards that parser's partial result. `GraphParser` refuses file links and outside-root - inputs, bounds each source to 16 MiB, aggregate recognized source to 64 MiB, and discovery to - 100,000 filesystem entries. Reads enforce the per-file bound again. The selected root may itself + inputs, bounds each source to 16 MiB, aggregate recognized source to 256 MiB, and discovery to + 100,000 visited filesystem entries. VCS and build/dependency directories named `.git`, `.svn`, + `.hg`, `target`, `build` and `node_modules` below the selected root are pruned before traversal. + Exceeding a discovery or source limit fails graph generation with a diagnostic; init reports a warning. + Reads enforce the per-file bound again. The selected root may itself be an operator-chosen alias. See [V2 evidence](security-verification.md#v2-graph-inputs). Cancellation is cooperative inside a daemon thread; it bounds the caller's wait, not a hard JVM heap or CPU quota. These controls do not claim protection against a same-account process @@ -521,10 +546,12 @@ violation warrants coordinated disclosure and a CVE; **hardening** means it is f it is in scope. An intentional operator-selected destination is authorized" *(maintainer, 2026-10-27 — Q9)*. Retired generated assets are deleted only when inside the project, through no symbolic link, and only regular files *(documented — `GeneratedAssetCleaner`)*; generated file replacements use atomic writes *(documented — `AtomicFileWriter`)*; existing - `.codex/config.toml` / `opencode.json` are merged, not replaced *(documented — `docs/architecture.md`)*. `InitService` preflights shared generated paths and the selected agent trees before writing; - `ConfinedPaths` refuses pre-existing descendant links (including generated file leaves). - Explicitly selected target aliases remain supported. Citrus and Forage validate version components - and cache ancestry; Citrus also checks extracted paths and derived reference destinations. + `.codex/config.toml` / `opencode.json` are merged, not replaced *(documented — `docs/architecture.md`)*. `InitService` preflights the exact generated leaves and their ancestors, plus Camel-owned skill, + shared-guide and template subtrees before writing. `ConfinedPaths` refuses links in these managed + paths; unrelated worktrees, custom skills and existing data may contain links. New atomic writes + use umask-default permissions and replacements retain existing POSIX modes. + Explicitly selected target aliases remain supported. Catalog, Citrus and Forage validate version + components; Citrus and Forage also validate cache ancestry; Citrus also checks extracted paths and derived reference destinations. Knowledge extracts into fresh staging and refuses unsafe activation paths. See [V5 evidence](security-verification.md#v5-generated-and-extracted-paths). *Violation:* a file created, replaced or deleted outside the target directory, or a deletion through a symlink. *Severity:* security-critical when @@ -918,7 +945,7 @@ Suitable as a suppression or negative-prompt list for scanners and AI-assisted t - **Lucene `QueryParser` fed with tool arguments**: query text is escaped with `QueryParser.escape` and results are bounded (P14). - **ONNX Runtime native library loaded in the Knowledge server**: the bundled embedding model and reranker are - packaged at build time and copied to a private temporary directory; no runtime model download (§4.4a). + packaged at build time; the embedding model uses private temporary files and the reranker loads model bytes in memory; native libraries have their own cache/temp paths; no runtime model download (§4.4a). - **The Knowledge indexer clones repositories and calls Apache JIRA, NVD and CIRCL**: a maintainer-run build tool on trusted upstream sources, not part of the shipped server (§4.4a). - **Scanner hits in `examples/`, `tools/`, `camel-kit-dispatch/`, `src/test/**`**: `OUT-OF-MODEL: @@ -931,7 +958,7 @@ Suitable as a suppression or negative-prompt list for scanners and AI-assisted t - A new CLI command, parser or input format that reads external content; a parser moving to a later compilation phase or to symbol resolution against the analysed tree's classpath. - A change to the graph parser timeout or the POM parser path, or the addition of size, memory or symbolic-link - checks in `camel-kit-graph` (which closes V2 items and promotes P1 tags). + checks in `camel-kit-graph` (review V2 coverage and P1 claims). - Knowledge: a new tool, a tool argument that names a path, URL or command, the SSE transport enabled by default, a new download origin or manifest scheme, a change to the `IndexDownloader` transport rule or redirect validation, a new index format channel, authentication added to the transport, the indexer promoted into the runtime server, or @@ -941,7 +968,7 @@ Suitable as a suppression or negative-prompt list for scanners and AI-assisted t redirect policy. - `init` writing outside the target directory or under `$HOME`; Ship state moving back to a user-level default. - A new generated harness asset that grants permissions, installs hooks or auto-approves tools; a change to an - existing allow-list, hook or guard policy. Completion of V3 promotes P10 to the accepted posture. + existing allow-list, hook or guard policy. Keep V3 regression coverage aligned with P10. - A new remote repository or coordinate in `distribution.properties`, or signature/checksum verification added to `init` downloads (which would move that item from §4.9 to §4.8). - Ship supporting Spring Boot or Quarkus projects, non-Linux hosts, binary or deletion proposals, or leaving @@ -1039,10 +1066,7 @@ tags read *(maintainer, 2026-10-27 — Qn)*. ### 4.14.2 Verification items blocking acceptance -Answering the policy questions did not mark the implementation work complete. Every remaining *(inferred — Vn)* tag -routes to one of these items; the model is accepted when each is verified by a maintainer or closed by a change. -Until then a report that matches an open item is triaged on the model's claim (§4.13). Each item is tracked in its -own issue, linked below. +The following changes implement the six verification items. Evidence records what was tested and what was source-audited; it does not imply maintainer approval or issue closure. A report is always triaged on the claimed boundary (§4.13), even when implementation work is in flight. - **V1 — Per-parser regression coverage (Q1; #153): implemented.** `ParserSourceReadingContractTest` exercises all nine parsers, with observable output and hostile source canaries. See [V1 evidence](security-verification.md#v1-source-reading), including mutation controls. A demonstrated breach remains `VALID` under P1. @@ -1050,11 +1074,8 @@ own issue, linked below. - **V3 — Narrower Claude MCP grants (Q3; #155): implemented.** Fresh and repeated generation emit exactly the manifest-listed MCP grants. Real Claude Code 2.1.316 probes cover allowed and unlisted tools for all three servers, plus wildcard/removal controls. [V3 evidence](security-verification.md#v3-claude-permissions). -- **V4 — Verified per-process side-effect inventory (Q6; #156) → §4.5, §4.4a.** Maintainer verification of every row of the - §4.5 inventory — Kit CLI, graph analysis, Ship controller, Pi worker, evidence JVMs, Knowledge server, Knowledge - indexer — for listeners, child processes, network origins, filesystem writes, environment reads, telemetry and - actual parser limits. *Interim triage:* inspected statements stay *(inferred)*; a breach of a claimed property is - `VALID`. +- **V4 — Per-process side-effect inventory (Q6; #156): implemented.** Every row has source references and configuration scope; missing CLI probes/configuration, graph HTML, Ship repository writes, native caches, indexer outputs and clock behavior are corrected. [V4 evidence](security-verification.md#v4-process-inventory) records the verification method. This is source/runtime evidence for maintainer review, not a claim of maintainer sign-off. + - **V5 — Init and download path controls (Q7, Q9; #157): implemented.** Regression tests cover shared init outputs, every agent, generated leaves, cache ancestors, malicious versions and archive paths for Citrus, Forage and Knowledge. [V5 evidence](security-verification.md#v5-generated-and-extracted-paths). Redirected writes remain `VALID`. - **V6 — Knowledge verification (Q11; #158): implemented.** Tool argument/cap tests, pinned/temp fallback tests, real-model offline probes and packaged stdio/SSE checks are recorded in [V6 evidence](security-verification.md#v6-knowledge). Native caches are disclosed, DJL offline initialization is enforced and ordinary severity spellings work. Existing #143/#142 hardening remains covered. A P12–P14 breach remains `VALID`. @@ -1099,7 +1120,5 @@ file changes. | `knowledge/README.md` (transport, tools, index distribution, cache rules, data sources, CVE enrichment, release lines), root `README.md` | §4.1, §4.2, §4.4a, §4.5, §4.5a, §4.8 P12–P14, §4.9, §4.11a | | Knowledge source: `IndexDownloader`, `IndexResolverConfig`, `KnowledgeMcpServer`, `LuceneSearchService`, `OnnxEmbeddingProvider`, `IndexerMain`, `VersionResolver`, `JiraFetcher`, `CveParser` | §4.4a, §4.5, §4.6, §4.8 P11–P14, §4.11a | -> **Self-check status:** every section is substantive; no bullet belongs in a code review or audit report; only the -> three sanctioned provenance tags are used; §4.9 and §4.10 are at least as substantive as §4.8; §4.6 is a -> per-entry-point table; §4.13 is a closed set with citations; every *(inferred)* tag names a §4.14 question with a -> proposed answer. **Status: DRAFT until the §4.14 waves are answered.** +> **Review status:** implementation evidence for V1–V6 is recorded separately from policy. +> Maintainer acceptance and publication under #131 remain pending. diff --git a/docs/security-model.yaml b/docs/security-model.yaml index b307c3d4..14faf39d 100644 --- a/docs/security-model.yaml +++ b/docs/security-model.yaml @@ -14,13 +14,13 @@ products: version: 0.0.3-SNAPSHOT latest_release: 0.0.2 (published under the former io.github.luigidemasi coordinates) index_release_channel: knowledge-index-v1-YYYY.MM.DD-HHMMSS -kit_source_baseline_commit: 70796c02 -knowledge_source_baseline_commit: 9c8173cb +kit_source_baseline_commit: 2863e915 +knowledge_source_baseline_commit: 2863e915 repository_layout_commit: 9c8173cb -revised_at_commit: a19d0529 +verification_revision: "2026-11-10; main 2863e915 plus PR6 and #153-#158" date: "2026-10-22" last_review_round: "2026-10-27" -status: "draft - policy ratified 2026-10-27; acceptance pending verification items V1-V6 (tracked in #153-#158); revised 2026-11-02 after review round 3" +status: "draft - policy ratified 2026-10-27; implementation verification for #153-#158 complete; maintainer acceptance and publication #131 pending (2026-11-09)" canonical: docs/security-model.md umbrella_model: https://camel.apache.org/manual/security-model.html reporting: @@ -109,9 +109,9 @@ component_families: entry_points: [-Prebuild-index build, index-release.yml workflow] in_model: true section: "4.4a" - reachability: Its inputs are upstream Apache sources at release tags, trusted; a finding needs hostile upstream content (adversary not in scope) unless the indexer breaks its own path or process boundary. + reachability: Its inputs are selected upstream Apache product refs plus camel-website main discovery, trusted; a finding needs hostile upstream content (adversary not in scope) unless the indexer breaks its own path or process boundary. -processes_inventory_status: See 4.5 - each row records what the process does to the host and whether the statement is documented, code-inspected (V4) or maintainer-verified. +processes_inventory_status: Source-audited per-process inventory with concrete implementation references and configuration-scoped runtime evidence in security-verification.md V4; no human sign-off implied. entry_points: - entry: camel-kit init @@ -256,7 +256,7 @@ configuration_variants: security_relevant: false - knob: knowledge.index.path (KNOWLEDGE_INDEX_PATH) default: unset - effect: Uses a local index directory in place; no network, no cache. + effect: Uses a local index directory in place; no index-acquisition network or index cache; native-library caches still apply. security_relevant: true stance: documented (air-gapped and development use) - knob: knowledge.index.url (KNOWLEDGE_INDEX_URL) @@ -281,7 +281,7 @@ configuration_variants: claimed_properties: - id: P1 - property: "Source-reading contract inherited from the umbrella model: no project code execution, project class loading, runtime placeholder/secret resolution, network or child processes; output is data. GraphParser confines inputs, refuses file links, limits source files to 16 MiB, recognized source total to 64 MiB and discovery to 100000 entries. GraphBuilder times out every parser including POM after 60 seconds, discards its partial result and cancels its daemon task. Cancellation [...] + property: "Source-reading contract inherited from the umbrella model: no project code execution, project class loading, runtime placeholder/secret resolution, network or child processes; output is data. GraphParser confines inputs, refuses file links, limits source files to 16 MiB, recognized source total to 256 MiB and discovery to 100000 visited entries. Discovery prunes .git, .svn, .hg, target, build and node_modules directories below the selected root; source/discovery overflow f [...] violation_symptom: Child process, class loaded or defined from the source, outbound connection, read of a file outside the analysed root (including through a symbolic link), placeholder resolved, non-termination, or unbounded memory during graph analysis. severity: security-critical (VALID regardless of the verification status in V1/V2) provenance: "Contract: umbrella and maintainer (2026-10-27, Q1/Q2). Controls: GraphParser, GraphBuilder, SecureXml and BizTalk parsers. Regressions: ParserSourceReadingContractTest, GraphInputBoundaryTest; security-verification.md V1/V2." @@ -294,9 +294,9 @@ claimed_properties: property: init confines its writes to the operator-selected target directory and removes only what it generated, through no symlink. An untrusted tree or a symbolic link that redirects a write outside the target is in scope; an intentionally operator-selected destination is authorized. violation_symptom: File created, replaced or deleted outside the operator-selected target, or a write or deletion redirected through a symbolic link. severity: security-critical when reachable from an attacker-controllable input (analysed tree, registry data); otherwise correctness - provenance: "Contract: maintainer (2026-10-27, Q9). InitService/ConfinedPaths preflight shared and selected-agent outputs; GeneratedAssetCleaner guards deletion; generated file replacements use AtomicFileWriter. InitWriteConfinementTest covers static hostile descendant links and selected-root aliases." + provenance: "Contract: maintainer (2026-10-27, Q9). InitService/ConfinedPaths preflight generated leaves/ancestors and Camel-owned skill/shared/template subtrees; unrelated worktrees and data links are allowed; new atomic files use umask-default modes and replacements preserve existing POSIX modes; GeneratedAssetCleaner guards deletion; generated file replacements use AtomicFileWriter. InitWriteConfinementTest covers static hostile descendant links and selected-root aliases." - id: P4 - property: Pinned, named-repository supply chain for everything fetched or configured; Ship resolver uses fixed HTTPS Maven Central, checksum fail, no redirects, exact coordinates, size caps, SHA-256 content identity, isolated URLClassLoader payloads. Kit's own handling of what it downloads is in scope - catalog JSON is read from the JAR stream in memory, Citrus schema entries are written only inside the cache directory after lexical containment and descendant-link checks; Citrus/Fora [...] + property: Pinned, named-repository supply chain for everything fetched or configured; Ship resolver uses fixed HTTPS Maven Central, checksum fail, no redirects, exact coordinates, size caps, SHA-256 content identity, isolated URLClassLoader payloads. Kit's own handling of what it downloads is in scope - catalog JSON is read from the JAR stream in memory, Citrus schema entries are written only inside the cache directory after lexical containment and descendant-link checks; Catalog/Cit [...] violation_symptom: Unpinned coordinate, repository outside the named lists, download accepted on checksum mismatch (Ship), artifact outside its exact path, payload class loaded from elsewhere, or a downloaded artifact that escapes the cache directory or executes code through Kit's parsing or extraction. severity: security-critical provenance: documented (mcp-setup.md, distribution.properties, ShipMavenResolver, ShipJvmPayloadBootstrap, CatalogDownloader, CitrusSchemaDownloader, ForageCatalogService); in-scope clause maintainer (2026-10-27, Q7) @@ -329,11 +329,11 @@ claimed_properties: property: Generated harness assets carry the accepted least-privilege posture - read-only Ship workers, read-only Codex roles, Copilot deny hook, Pi guard policy, no HTTP port for the Camel and Citrus MCP servers, and MCP grants aligned with the manifest allowed_tools (no runtime mutation or control tools) - as availability filters for Codex (enabled_tools), Copilot (tools), Pi (directTools) and Qwen (includeTools), as Bob 2's auto-approval list, with Codex, Copilot, Qwen and OpenCod [...] violation_symptom: "Generated asset grants more than the accepted posture: a worker with edit/shell tools, a filter or auto-approval list wider than manifest allowed_tools, a prompt-mode target auto-approved, or a hook/guard failing open on a documented pattern. Former wildcard exception applied only to the pre-V3 template (review of #6, 2026-10-27); newly generated wildcards are regressions. Any demonstrated breach is evaluated on its impact." severity: hardening; security-critical when the widened grant reaches a credential or destructive action without a prompt - provenance: "documented (docs/agent-architectures.md, docs/ship-claude.md, docs/ship-native.md, templates/mcp-configs/*, templates/claude/settings.json, Claude Code permissions reference); current Claude grant - maintainer, 2026-10-22 (review of #6); accepted posture - maintainer, 2026-10-27 (Q3)" + provenance: "documented (docs/agent-architectures.md, docs/ship-claude.md, docs/ship-native.md, templates/mcp-configs/*, templates/claude/settings.json, Claude Code permissions reference); historical wildcard grant - maintainer, 2026-10-22 (review of #6); accepted posture - maintainer, 2026-10-27 (Q3); implementation and generated-host checks - V3, security-verification.md" - id: P11 - property: Stated resource bounds - route/Citrus YAML 2 MiB, native result 16 MiB and 1000 files, Pi prompt 1 MiB, Pi log 16 MiB, session 64 MiB, evidence log 64 MiB, stage timeout 10m, resolver 64 roots/512 artifacts/128 MiB JAR/4 MiB POM, tree quotas, migration-context depth 3 and 50 nodes; all graph parsers including POM 60 s each, source16 MiB/file and64 MiB total, discovery100000 entries (serves P1); Knowledge tool results at most 25 per call, release pages at most 2 MiB and 10 p [...] + property: Stated resource bounds - route/Citrus YAML 2 MiB, native result 16 MiB and 1000 files, Pi prompt 1 MiB, Pi log 16 MiB, session 64 MiB, evidence log 64 MiB, stage timeout 10m, resolver 64 roots/512 artifacts/128 MiB JAR/4 MiB POM, tree quotas, migration-context depth 3 and 50 nodes; all graph parsers including POM 60 s each, source 16 MiB/file and 256 MiB total, discovery 100000 entries (serves P1); Knowledge tool results at most 25 per call, release pages at most 2 MiB and [...] violation_symptom: A limit not enforced at its documented value. - severity: hardening + severity: hardening except graph source-reading boundary breaches, which are security-critical under P1 provenance: documented (ShipArtifactLimits, ShipNativeWorker, PiWorker, EvidenceRunner, ShipMavenResolver, ShipTreePolicy, docs/commands.md, KnowledgeMcpServer, IndexDownloader) - id: P12 property: Knowledge server transport - stdio by default with no listening socket; the HTTP/SSE transport exists only when the operator enables it (quarkus.http.host-enabled=true) on the configured host and port. @@ -341,7 +341,7 @@ claimed_properties: severity: security-critical provenance: "application.properties and knowledge/README.md; packaged stdio and explicit loopback SSE probe recorded in security-verification.md V6. HTTP/SSE has no built-in authentication; configure bind host explicitly." - id: P13 - property: Knowledge index acquisition integrity - a local knowledge.index.path is used in place without network; otherwise a published knowledge-index-v1-* release (newest compatible, or the exact pinned version) or an explicitly configured manifest is fetched with bounded pages and deadlines, the manifest must match the release tag, format version 1, the bundled embedding model and 384 dimensions, the archive SHA-256 must equal the manifest value before unpacking, zip entries are co [...] + property: Knowledge index acquisition integrity - a local knowledge.index.path is used in place without index-acquisition network; otherwise a published knowledge-index-v1-* release (newest compatible, or the exact pinned version) or an explicitly configured manifest is fetched with bounded pages and deadlines, the manifest must match the release tag, format version 1, the bundled embedding model and 384 dimensions, the archive SHA-256 must equal the manifest value before unpacking, [...] violation_symptom: An archive accepted on SHA-256 mismatch; an entry written outside the staging or version directory; a version name outside the safe-name rules accepted; a pinned client using another version or the classpath fallback; a manifest from a different release tag accepted; a remote fetch or redirect issued over non-loopback http; activation of a partially unpacked version. severity: security-critical (integrity and path escape) provenance: documented (knowledge/README.md "Index Distribution", IndexDownloader, LuceneSearchService, apache/camel-kit#143) @@ -478,7 +478,7 @@ known_non_findings: why: Query text is escaped with QueryParser.escape; results are bounded (P14). disposition: KNOWN-NON-FINDING - pattern: ONNX Runtime native library loaded in the Knowledge server - why: The bundled embedding model and reranker are packaged at build time and copied to a private temp directory; no runtime model download. + why: Bundled resources are packaged at build time; embedding model uses private temporary files, reranker loads bytes in memory; native libraries use separate cache/temp paths; no runtime model download. disposition: KNOWN-NON-FINDING - pattern: The Knowledge indexer clones repositories and calls Apache JIRA, NVD and CIRCL why: Maintainer-run build tool on trusted upstream sources; not part of the shipped server (4.4a). @@ -599,15 +599,16 @@ verification_items: work: Replace mcp__camel__*, mcp__camel-knowledge__* and mcp__citrus__* with explicit per-tool grants aligned with the workflow manifest allowed_tools, and verify the generated behaviour in Claude Code. interim_triage: "New generated wildcard grants violate P10. Historical configuration-only reports retain the pre-V3 disposition; demonstrated breaches remain evaluated on impact." status: "implemented" - evidence: "ClaudeGeneratorTest, ShippedAssetStructureTest; actual Claude Code 2.1.316 generated-output probe with12 permission/dispatch cases; security-verification.md V3" + evidence: "ClaudeGeneratorTest verifies manifest-rendered grants; actual Claude Code 2.1.316 generated-output probe with 12 permission/dispatch cases; security-verification.md V3" - id: V4 tracking: apache/camel-kit#156 title: Verified per-process side-effect inventory from: [Q6] sections: ["4.5", "4.4a"] work: Maintainer verification of each row of the 4.5 inventory - Kit CLI, graph analysis, Ship controller, Pi worker, evidence JVMs, Knowledge server, Knowledge indexer - covering listeners, child processes, network origins, filesystem writes, environment reads, telemetry and actual parser limits, scoped to the process and configuration that support each statement. - interim_triage: Code-inspected statements remain inferred; a breach of a claimed property is VALID. - status: open + interim_triage: "Source audit and runtime observations are explicitly distinguished from maintainer approval; breaches of claimed properties remain VALID." + status: "implemented" + evidence: "All seven rows source-audited against named implementation classes and pinned dependency behavior; scoped executable checks recorded in security-verification.md V1-V6. Maintainer acceptance remains separate." - id: V5 tracking: apache/camel-kit#157 title: Init and download path controls through symbolic links @@ -626,14 +627,21 @@ verification_items: interim_triage: A breach of P12-P14 is VALID. status: "implemented" - evidence: "KnowledgeInputBoundaryTest, LuceneFallbackBoundaryTest, OfflineModelsTest, existing IndexDownloader/ReleaseDiscovery regressions and packaged stdio/SSE probe; security-verification.md V6" + evidence: "KnowledgeInputBoundaryTest, LuceneFallbackBoundaryTest, OfflineModelsTest, existing IndexDownloader/IndexDiscoveryTest regressions and packaged stdio/SSE probe; security-verification.md V6" revision_triggers: - New CLI command, parser or input format reading external content; parser moving to later compilation phase or symbol resolution. - - Change to the graph parser timeout or the POM parser path, or addition of size, memory or symbolic-link checks in kit/camel-kit-graph (closes V2 items). + - Change to the graph parser timeout or the POM parser path, or addition of size, memory or symbolic-link checks in kit/camel-kit-graph (review V2 coverage). - A new Knowledge tool, a tool argument that names a path, URL or command, the SSE transport enabled by default, a new download origin or manifest scheme, a change to the IndexDownloader transport rule or redirect validation, a new index format channel, authentication added to the transport, or the indexer promoted into the runtime server. - Change to default oversight mode, default backend, Pi tool lists or flags, tree policy rules/quotas, expression gate, secret-scan rules, resolver origin/checksum/redirect policy. - init writing outside the target directory or under $HOME; Ship state moving to a user-level default. - - New or changed generated harness asset granting permissions, installing hooks or auto-approving tools; completion of V3 (promotes P10 to the accepted posture). + - New or changed generated harness asset granting permissions, installing hooks or auto-approving tools; keep V3 coverage aligned with P10. - New remote repository or coordinate in distribution.properties; verification added to init downloads; Kit's Knowledge pin moving to org.apache.camel coordinates. - Ship supporting Spring Boot/Quarkus, non-Linux hosts, binary or deletion proposals, or leaving Technology Preview. - Any report that is a MODEL-GAP. + +knowledge_jvm_initialization_policy: + ai.djl.offline: true + RUST_FLAVOR: cpu + ai.djl.util.cuda.fork: false + jna.platform.library.path: "Set to empty only if absent; explicit values are preserved" + scope: "Process-wide; affects other DJL/JNA users sharing the Knowledge embedding JVM" diff --git a/docs/security-verification.md b/docs/security-verification.md index 6277ca6c..cf228dea 100644 --- a/docs/security-verification.md +++ b/docs/security-verification.md @@ -26,8 +26,11 @@ parser/dependency changes. Website impact: not required; this pins existing beha `GraphInputBoundaryTest` exercises actual parsing and `GraphBuilder`: outside file links, directory links, an operator-selected root alias, direct supplied outside/oversized lists, 16 MiB and 16 MiB+1 sources, aggregate overflow, large unrelated artifacts and a deliberately -slow POM parser. Production bounds are 16 MiB per input, 64 MiB aggregate recognized source -and 100,000 visited entries. Sources are checked before parser sniffing and bounded again +slow POM parser. Production bounds are 16 MiB per input, 256 MiB aggregate recognized source +and 100,000 visited entries. VCS/build/dependency subtrees (`.git`, `.svn`, `.hg`, `target`, +`build`, `node_modules`) are excluded before traversal. Regressions cover a 256 MiB accepted +source set, overflow, copied-resource exclusion, and direct unsafe XML-sniff candidates. +Sources are checked before parser sniffing and bounded again when read. The POM pass uses the same timeout policy as the remaining parsers. The baseline reproduced file-link escape, missing POM timeout and oversized-input acceptance. @@ -39,8 +42,8 @@ same-account directory substitution. Website impact: required; graph reference u ## V3: Claude permissions -`ClaudeGeneratorTest` tests fresh and repeated generation; `ShippedAssetStructureTest` compares -the shipped settings to the manifest. Both require exactly the 46 current MCP grants, with no +`ClaudeGenerator` renders MCP grants from the workflow manifest; `ClaudeGeneratorTest` checks +fresh and repeated generation against that manifest. It requires exactly the 46 current MCP grants, with no server-wide wildcard or duplicate. Existing Read and Maven command grants are unchanged. Actual Claude Code 2.1.316 was run with generated settings, isolated configuration, a benign @@ -72,9 +75,12 @@ staging, version names and fallback. Baseline probes demonstrated outside writes for init/Citrus/Forage, including deletion of an outside directory selected by a malicious Forage version. All outside paths were test fixtures. -The fix rejects unsafe versions and pre-existing descendant links before writes/deletions. +The fix rejects unsafe Catalog/Citrus/Forage versions and links in generated paths before +writes/deletions. Positive init fixtures retain links in worktrees, custom skills, agent files, +Maven wrapper siblings, data, schemas, flow docs and Ship state. Managed skill links still fail. Generated file leaves are replaced through AtomicFileWriter rather than truncated in place; six hard-link regressions prove outside sentinels remain unchanged for init and Citrus outputs. +Fresh atomic writes use umask-default modes; replacement modes are preserved. An explicitly chosen root alias is allowed. Extraction creates ordinary files and never materializes ZIP symlink metadata. These checks do not provide descriptor-relative isolation against concurrent same-account directory substitution; existing same-account exclusions apply. @@ -109,10 +115,11 @@ Packaged transport verification uses `tools/verify_knowledge_runtime.py` with a index: stdio initialize/list-tools/first query, and explicit loopback SSE initialize/list-tools/ query without authorization. It inspects the child process's sockets and syscall trace where available; JVM local-interface discovery is reported separately from application network. -Website impact: required; Knowledge runtime/reference updated. Published Knowledge0.0.2 is not +Website impact: required; Knowledge runtime/reference updated. Published Knowledge 0.0.2 is not retroactively changed by these source fixes. + ### Packaged V6 observation (2026-11-09) The checked-in probe passed on Temurin 21.0.8+9 with runner SHA-256 @@ -124,3 +131,41 @@ unauthenticated initialization/query. Lifetime syscall traces contained only the exec, no child executable and no application service connection/send. JVM netlink and UDP port-zero interface discovery was recorded separately. The packaged runner contained all five model/tokenizer resources and no `knowledge-index/` payload. + +## V4: process inventory + +Every §4.5 row was checked against the following sources; this is a source audit, supplemented +by the named runtime tests above, rather than a human maintainer attestation: + +| Row | Sources and verification scope | +| --- | --- | +| CLI | PrerequisiteChecker/ProcessRunner actual argument vectors and inherited environment; DoctorService wrapper existence check versus mvn execution; OpenCodeGenerator global/ancestor/environment configuration; InitService and Doc/NextId command destinations; CatalogDownloader/CitrusSchemaDownloader/ForageCatalogService origins and request settings. External probes retain their own effects. | +| Graph | GraphBuilder/GraphParser concurrency, deterministic merge and bounds; GraphGenerateCommand/GraphVisualizeCommand JSON/HTML outputs; V1/V2 executable tests. | +| Ship controller | LocalCommandRunner, PiWorker, EvidenceRunner, ShipMavenResolver, ShipNativeWorker, ShipPublicationService: launch vectors, repository and state writes, native handoff, deadlines and publication. Existing controller regression suite remains required. | +| Pi worker | PiWorker.runRpc arguments, environment and working directory; no OS confinement. External Pi/provider implementation is not asserted to be silent or isolated. | +| Evidence JVM | EvidenceRunner/ShipJvmPayloadBootstrap and Camel validation: private environment/temp, classpath and stubbing policy. No claim of an OS socket/process sandbox. | +| Knowledge server | IndexDownloader, IndexResolverConfig, LuceneSearchService, KnowledgeMcpServer, application.properties and shared OfflineTokenizer; V6 tests and packaged-process probe. | +| Indexer | IndexerMain, ApacheCamelDomain, VersionResolver, JiraFetcher, CveParser: initial camel-website main discovery, selected product refs, source/cache roots including jira-cache, index.output and its sibling index.json, client-specific limits; shared embedding/native effects. No blanket filesystem/network quota. | + +Dependency audit used resolved DJL 0.36.0, ONNX Runtime 1.19.0 and JNA 5.8.0 source/binary behavior: +DJL InputStream tokenizer factories call Ec2Utils.callHome; generic platform detection consults +CUDA before applying flavor, and JNA can invoke ldconfig unless its platform search path is set. +V6 fixes these observed effects and preserves expected cache/native extraction writes. +The enforced DJL properties and default empty JNA platform path are JVM-wide; explicit JNA +platform paths are preserved. This is a standalone-process policy, not per-tokenizer isolation. ONNX +embedding external-data files and reranker in-memory model loading are described separately. + +Negative inventory cells describe inspected application operations and the recorded runtime +configuration. They do not waive P1–P14 or promise behavior for arbitrary external tools, +JVM startup agents or operator-selected native libraries. Website impact: not required for this +source inventory correction; behavior-changing fixes include Antora updates in V2/V3/V5/V6. +Publication of the accepted security model remains tracked by #131. + +## Review follow-up (2026-11-10) + +The compatibility follow-up narrows init preflight, preserves umask defaults for new generated +files, renders Claude MCP grants from the workflow manifest, and prunes graph build/VCS/dependency +trees. The aggregate graph budget is 256 MiB; the 16 MiB per-source and 60-second parser bounds +remain. Filename filtering precedes validation, and XML content sniffing follows it. +The Python host probes remain explicit evidence reproducers, not CI jobs; Java regressions run +in the normal reactor. Earlier dated host observations describe their original artifacts.
