This is an automated email from the ASF dual-hosted git repository.
oscerd pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kafka-connector.git
The following commit(s) were added to refs/heads/main by this push:
new 1374f3c3ed Add project Security Model, SECURITY.md and AGENTS.md
(#1771)
1374f3c3ed is described below
commit 1374f3c3ed8b89df4dde707fa7d1ea743dcf24da
Author: Andrea Cosentino <[email protected]>
AuthorDate: Fri May 15 11:57:08 2026 +0200
Add project Security Model, SECURITY.md and AGENTS.md (#1771)
Introduces docs/modules/ROOT/pages/security-model.adoc following the Apache
Camel security-model house style: the trust model (a connector configuration is
trusted, operator-authored route code), the configuration/data trust boundary,
the in-scope CKC glue vulnerability classes, what is delegated to the Apache
Camel security model and to the Kafka Connect runtime, and operator hardening
responsibilities.
Adds a root SECURITY.md pointer (ASF private reporting process,
[email protected]) and an AGENTS.md with AI-agent rules of engagement plus a
Security Model summary, both mirroring apache/camel. Links the new page from
the docs navigation.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
---
AGENTS.md | 382 +++++++++++++++++++++++++
SECURITY.md | 38 +++
docs/modules/ROOT/nav.adoc | 1 +
docs/modules/ROOT/pages/security-model.adoc | 415 ++++++++++++++++++++++++++++
4 files changed, 836 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..95773dd0b7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,382 @@
+# Apache Camel Kafka Connector - AI Agent Guidelines
+
+Guidelines for AI agents working on this codebase.
+
+## Project Info
+
+Camel Kafka Connector (CKC) packages Apache Camel components — via the Camel
+Kamelets catalog — as Kafka Connect source and sink connectors, so any Camel
+component can be used in Kafka Connect without writing code.
+
+- Version: 4.21.0-SNAPSHOT
+- Java: 17+
+- Build: Maven 3.9+
+- Kafka Connect: 3.9.x
+- Tracks the Apache Camel and Camel Kamelets release train (component
+ behaviour and security come from those projects, not from CKC).
+
+## AI Agent Rules of Engagement
+
+These rules apply to ALL AI agents working on this codebase.
+
+### Attribution
+
+- All AI-generated content (GitHub PR descriptions, review comments, issue
+ comments) MUST clearly identify itself as AI-generated and mention the human
+ operator. Example: "_Claude Code on behalf of [Human Name]_"
+
+### PR Volume
+
+- An agent MUST NOT open more than 10 PRs per day per operator to ensure human
+ reviewers can keep up.
+- Prioritize quality over quantity — fewer well-tested PRs are better than many
+ shallow ones.
+
+### Git branch
+
+- An agent MUST NEVER push commits to a branch it did not create.
+- If a contributor's PR needs changes, the agent may suggest changes via
+ review comments, but must not push to their branch without explicit
+ permission.
+- An agent should prefer to use its own fork to push branches instead of the
+ main `apache/camel-kafka-connector` repository. It avoids filling the main
+ repository with a long list of uncleaned branches.
+- Branch naming: `fix/<ISSUE_NUMBER>` for bug fixes,
+ `feature/<ISSUE_NUMBER>-<short-slug>` for features,
+ `quick-fix/<short-slug>` for trivial chores. Include the GitHub issue number
+ when one exists.
+- After a Pull Request is merged or rejected, the branch should be deleted.
+
+### GitHub Issue Ownership
+
+- The issue tracker is **GitHub** (`apache/camel-kafka-connector` issues),
+ numeric IDs. There is no JIRA for this repository.
+- An agent MUST ONLY pick up issues not already assigned to a human.
+- Before starting work, comment on the issue stating the operator is taking it.
+- Reference the issue in the PR (`Fixes #<ISSUE_NUMBER>`) so it closes on
merge.
+
+### PR Description Maintenance
+
+When pushing new commits to a PR, **always update the PR description** (and
+title if needed) to reflect the current state of the changeset. Use
+`gh pr edit --title "..." --body "..."` after each push.
+
+### PR Reviewers
+
+When creating a PR, **always identify and request reviews** from the most
+relevant committers:
+
+- Run `git log --format='%an' --since='1 year' -- <affected-files> | sort |
uniq -c | sort -rn | head -10`
+ to find who has been most active on the affected files.
+- Use `git blame` on key modified files to identify who wrote the code being
+ changed.
+- Cross-reference with the
+ [committer list](https://home.apache.org/committers-by-project.html#camel)
+ (CKC shares the Apache Camel committer base).
+- Request review from **at least 2 relevant committers** using
+ `gh pr edit --add-reviewer`.
+- When all comments are addressed and checks are green, re-request review so
+ reviewers know the changeset is ready again.
+
+### Merge Requirements
+
+- An agent MUST NOT merge a PR if there are any **unresolved review
+ conversations**.
+- An agent MUST NOT merge a PR without at least **one human approval**.
+- An agent MUST NOT approve its own PRs — human review is always required.
+
+### Code Quality
+
+- Every PR must include tests for new functionality or bug fixes (in `core/`
+ or `tests/`).
+- Every PR must include documentation updates where applicable.
+- Do NOT use Records or Lombok unless already present in the file being edited.
+- Do NOT change public API signatures without justification; maintain
+ backwards compatibility for public APIs.
+- Do NOT add new dependencies without justification.
+- All generated files must be regenerated and committed (CI checks for
+ uncommitted changes).
+
+### Generated Artifacts — Do Not Hand-Edit
+
+Large parts of this repository are **generated** from the Camel Kamelets
+catalog and templates. Editing them by hand will be overwritten and will fail
+CI:
+
+- `connectors/*` connector modules — generated by
+ `tooling/camel-kafka-connector-generator-maven-plugin` from
+ `connectors/template-connector-pom.xml` /
+ `template-connecotr-kamelet-pom.xml`.
+- `camel-kafka-connector-catalog/` — generated catalog metadata.
+- `docs/modules/ROOT/pages/reference/connectors/*` — generated connector
+ reference docs (and the `// connectors: START/END` block in `nav.adoc`).
+
+Change the **generator, templates, or `core/` glue** and regenerate; never
+patch a single generated connector module to fix a cross-cutting issue.
+
+### Asynchronous Testing: Use Awaitility Instead of Thread.sleep
+
+Do **NOT** use `Thread.sleep()` in test code — it leads to flaky, slow,
+non-deterministic tests. Use
[Awaitility](https://github.com/awaitility/awaitility).
+
+- New test code MUST NOT introduce `Thread.sleep()` calls.
+- When modifying existing test code that contains `Thread.sleep()`, migrate it
+ to Awaitility.
+- Always set an explicit `atMost` timeout to avoid hanging builds.
+- Use `untilAsserted` / `until` with a clear predicate — do not replace a sleep
+ with a busy-wait loop.
+
+### Issue Investigation (Before Implementation)
+
+Before implementing a fix, **thoroughly investigate** the issue's validity and
+context. CKC is thin glue over Apache Camel — a reported "bug" is often
+behaviour of the wrapped Camel component or the Kafka Connect runtime, not CKC.
+
+1. **Validate the issue**: Confirm it is real and reproducible. Determine
+ whether the cause is CKC `core/` glue, a wrapped Camel component, a Kamelet,
+ or Kafka Connect itself.
+2. **Check git history**: `git log --oneline <file>` and `git blame <file>` on
+ the affected code; read commit messages and linked issues.
+3. **Search for related issues**: Look for prior discussions, rejected
+ approaches, or intentional design decisions in GitHub issues/PRs.
+4. **Locate the right layer**: If the root cause is in Apache Camel or the
+ Kamelets catalog, the fix belongs upstream and CKC consumes it on the next
+ dependency bump — do not re-implement it in the glue.
+5. **Check if the "fix" reverts prior work**: If your change reverts a prior
+ intentional commit, stop and reconsider; if still justified, acknowledge it
+ in the PR description.
+
+**Present your findings** to the operator before implementing. Flag risks,
+ambiguities, and cases where the issue may be invalid or belong upstream.
+
+### Knowledge Cutoff Awareness
+
+AI agents have a training-data cutoff. **Never make authoritative claims about
+external project state based solely on training knowledge.**
+
+- When an issue, PR, or code references a specific version of Camel, Kamelets,
+ Kafka, or any dependency, **verify it exists** (web search, Maven Central,
+ release notes) before relying on or questioning it.
+- If uncertain whether something exists or has changed, say so and verify — do
+ not confidently assert something is wrong based on potentially stale
+ knowledge.
+
+### Git History Review (When Reviewing PRs)
+
+- Check `git log` and `git blame` on modified files for conflicts with prior
+ intentional decisions.
+- Verify "fixes" don't revert deliberate behaviour without justification.
+- Confirm changes to generated artifacts were produced by regeneration, not by
+ hand-editing.
+
+### Documentation Conventions
+
+When writing or modifying `.adoc` documentation:
+
+- Internal links within the CKC docs use `xref:` (e.g.
+ `xref:user-guide/basic-configuration.adoc[Basic configuration]`).
+- Cross-project links to Apache Camel / Kamelets / Kafka docs use absolute
+ `https://camel.apache.org/...` or `https://kafka.apache.org/...` URLs (CKC
+ is a separate Antora component published on the same site).
+- New top-level pages must be added to `docs/modules/ROOT/nav.adoc` outside
+ the generated `// connectors: START/END` block.
+
+## Security Model
+
+CKC has a documented security model that defines who is trusted, where the
+trust boundaries sit, what counts as a CKC vulnerability, and what is
+delegated to Apache Camel or the Kafka Connect operator. The canonical
+document is
+[`docs/modules/ROOT/pages/security-model.adoc`](docs/modules/ROOT/pages/security-model.adoc).
+Use it when triaging security reports, deciding whether a finding warrants a
+CVE, or reviewing a security-sensitive PR.
+
+For the vulnerability **reporting** convention, [`SECURITY.md`](SECURITY.md) at
+the repository root is the entry point. CKC is an Apache Camel sub-project: an
+agent that discovers or is handed a suspected vulnerability MUST NOT open a
+public issue, PR, or mailing-list post — follow the private Apache Camel
+process in `SECURITY.md` and stop.
+
+### Trust assumptions
+
+- **CKC contributors** are trusted to ship secure defaults in the `core/`
+ glue, the SMTs and the generator.
+- **The connector configuration author** (whoever submits a config via the
+ Kafka Connect REST API or worker properties) is **fully trusted**. A
+ connector configuration is route code: `camel.source.url` / `camel.sink.url`
+ accept any Camel endpoint URI, `camel.beans.aggregate=#class:fqcn` and
+ `#class:` object properties load arbitrary classes, SMT options name classes
+ to load. Code execution by a configuration author is **by design** and is
+ **not** a CKC vulnerability — the direct analogue of "route author is fully
+ trusted" in Camel.
+- **The Kafka Connect operator** is **fully trusted**: REST API auth and
+ exposure, converters, secret externalisation, JVM and OS user, installed
+ plugins. Their misconfiguration is not a CKC vulnerability unless a CKC
+ default exposed it.
+- **Kafka topic producers (sink side) and external systems (source side)** are
+ **untrusted**. This is the primary attacker model.
+
+The fundamental trust boundary is between **the connector configuration plus
+the Camel/Kamelet route it builds** (trusted) and **the data flowing through
+that route** (untrusted). CKC glue must not turn an untrusted record or
+payload into endpoint redirection, a Camel control header, or code on its own.
+
+### What is in scope (CKC glue only)
+
+- **Untrusted data steering route topology** — a record/payload changing the
+ `.toD()` endpoint, bean, data format, or idempotency expression that the
+ configuration did not specify.
+- **CKC-mapped header injection** — the `CamelHeader.` / `CamelProperty.`
+ prefix mapping in `CamelSinkTask` / `CamelSourceTask` / `TaskHelper` letting
+ untrusted data become a `Camel*` dispatch header in a default config.
+- **Secret disclosure by CKC code** — bypassing the `SensitiveUtils`-based
+ masking of config in CKC's startup log, or leaking a secret through a record
+ or SMT.
+- **Deserialization/parsing added by the glue or a bundled SMT** over
+ untrusted record data (not inside a wrapped component/data format).
+- **Insecure CKC defaults** exposing any of the above with no configuration.
+
+### What is out of scope
+
+- A **connector configuration** that runs code or reaches any endpoint
+ (`exec:`, arbitrary URI, `#class:` bean, SMT class option). Configuration
+ authoring is trusted.
+- Anything reachable only because the **Kafka Connect REST API** is
+ unauthenticated or exposed, or because the **config topic** is clear-text —
+ Kafka Connect responsibilities.
+- Vulnerabilities in the **wrapped Camel component, data format, expression
+ language or Kamelet** — governed by the
+ [Apache Camel Security
Model](https://camel.apache.org/manual/security-model.html)
+ and triaged by the Camel PMC. "Connector X wraps component Y with CVE-Z" is
+ not a CKC finding by itself.
+- **DoS / resource exhaustion** through unbounded routes or oversized records.
+- Third-party transitive CVEs not reachable through CKC code.
+- Scanner output with no PoC demonstrating an actual trust-boundary breach in
+ CKC glue.
+
+### Operator hardening checklist
+
+When reviewing or recommending a deployment, surface the following:
+
+- Authenticate and network-isolate the Kafka Connect REST API — write access
+ to it equals code execution in the worker JVM.
+- Externalise secrets with a Kafka Connect `config.providers` /
+ `ConfigProvider`; restrict the config topic and REST API.
+- Set `camel.remove.headers.pattern` (and/or `camel.map.headers=false` /
+ `camel.map.properties=false`) on sinks fed by untrusted producers so
+ attacker-supplied `CamelHeader.Camel*` headers are not promoted.
+- Treat `camel.sink.url`, `camel.source.url`, `camel.beans.*`, `#class:`
+ properties and SMT class options as trusted code; never template them from
+ untrusted input.
+- Pin and patch the Camel/Kamelets train; track advisories at
+ https://camel.apache.org/security/.
+
+### Contributor review checklist (for security-sensitive PRs)
+
+When reviewing a PR that touches `core/` glue, header mapping, an SMT, or the
+generator:
+
+- Does the change let record/payload data influence route topology? The route
+ built in `CamelKafkaConnectMain` must be a pure function of the
+ configuration.
+- Does it widen the `CamelHeader.` / `CamelProperty.` header-mapping gate, or
+ weaken `camel.remove.headers.pattern`?
+- Does it add `ObjectInputStream` or external-entity-resolving parsing over
+ untrusted record data in the glue or an SMT? Type conversion must go through
+ Camel's `TypeConverter`; class selection must come from configuration.
+- Does it log a raw config map or record body at a default level, or bypass
+ the sensitive-key masking?
+- Does the change paper over an unsafe Camel component/Kamelet default in the
+ glue instead of fixing it upstream?
+
+## Structure
+
+```
+camel-kafka-connector/
+├── parent/ # Shared dependency / version management
+├── core/ # The connector glue (NOT generated):
+│ # CamelSourceTask / CamelSinkTask,
+│ # CamelKafkaConnectMain, TaskHelper,
+│ # *ConnectorConfig, transforms/ (SMTs)
+├── buildingtools/ # Build/checkstyle support
+├── tooling/ # Generator + catalog/docs Maven plugins
+│ # and the connector model
+├── connectors/ # ~220 GENERATED connector modules
+├── archetypes/ # Maven archetypes for custom connectors
+├── camel-kafka-connector-catalog/ # GENERATED catalog metadata
+├── tests/ # Integration tests
+├── distribution/ # Assembly / packaging
+└── docs/ # AsciiDoc docs (Antora component)
+```
+
+The security-relevant code lives almost entirely in `core/`. Everything in
+`connectors/` and `camel-kafka-connector-catalog/` is generated packaging.
+
+## Build
+
+```bash
+mvn clean package -Dquickly # fast build, skip tests/checks
+mvn clean install # full build
+mvn clean install -pl core -am # just the core glue
+mvn clean install -pl tooling/camel-kafka-connector-generator-maven-plugin -am
+```
+
+- Build tool is Maven; **do not parallelize** Maven jobs (resource intensive).
+- When changes are confined to a module, build that module (`-pl <module>
+ -am`) rather than the full reactor.
+- After changing the generator/templates/catalog, run the full build so
+ generated `connectors/*`, the catalog, and reference docs are regenerated;
+ commit the regenerated output.
+
+## Testing
+
+```bash
+mvn test # unit tests (core)
+mvn -DskipIntegrationTests=false clean verify package # integration tests
+```
+
+Integration tests require Docker 17.05+ (Testcontainers). Tests can also be
+pointed at external services — see
+`xref:contributor-guide/testing.adoc`
(`docs/.../contributor-guide/testing.adoc`).
+
+## Conventions
+
+Core classes:
+- `Camel<Source|Sink>Connector` / `Camel<Source|Sink>ConnectorConfig`
+- `Camel<Source|Sink>Task` (the Kafka Connect `SourceTask` / `SinkTask`)
+- `CamelKafkaConnectMain` builds the Camel route from configuration
+- SMTs under `org.apache.camel.kafkaconnector.transforms`
+- Tests: `*Test.java` (JUnit 5)
+
+Packages: `org.apache.camel.kafkaconnector[.utils|.transforms|.aggregator]`
+
+Configuration property keys: `camel.<source|sink>.url`,
+`camel.<source|sink>.component`, `camel.<source|sink>.endpoint.*`,
+`camel.<source|sink>.path.*`, `camel.beans.*`, `camel.dataformat.*`,
+`camel.aggregation.*`, `camel.idempotency.*`, `camel.map.headers`,
+`camel.map.properties`, `camel.remove.headers.pattern`,
+`camel.error.handler*`. Every new config constant needs a matching
+`*_CONF` / `*_DOC` / `*_DEFAULT` triple in `CamelConnectorConfig` (or the
+sink/source subclass) and documentation.
+
+Import style: do not use fully qualified class names in Java; add an `import`
+and use the simple name (except when two classes share a simple name).
+
+## Commits
+
+```
+Fix #<ISSUE_NUMBER>: Brief description
+```
+
+Reference the GitHub issue when applicable. Use `chore: ...` for trivial
+quick-fixes and `ci: ...` for CI-only changes.
+
+## Links
+
+- https://camel.apache.org/camel-kafka-connector/
+- https://github.com/apache/camel-kafka-connector
+- https://github.com/apache/camel-kafka-connector/issues
+- https://camel.apache.org/security/ (security reporting)
+- https://kafka.apache.org/documentation/#connect
+- [email protected]
+- https://camel.zulipchat.com/
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000000..7428479ae8
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,38 @@
+# Security Policy
+
+## Supported Versions
+
+Camel Kafka Connector tracks the Apache Camel release train. To see which
+versions are supported please refer to the
+[download page](https://camel.apache.org/download/) and the compatibility
+matrix in the [project
documentation](https://camel.apache.org/camel-kafka-connector/).
+
+## Reporting a Vulnerability
+
+Camel Kafka Connector is an Apache Camel sub-project. For information on how to
+report a new security problem please see
[here](https://camel.apache.org/security/).
+Do not open a public GitHub issue or pull request for an unpublished
+vulnerability — follow the private Apache process and stop.
+
+## Security Model
+
+Before submitting a report, please read the project's
+[Security Model](docs/modules/ROOT/pages/security-model.adoc). It documents who
+is trusted, where the trust boundaries sit, which behaviours count as a Camel
+Kafka Connector vulnerability, and which categories are out of scope:
+
+- A connector configuration is trusted, operator-authored route code — code
+ execution by whoever can submit one (arbitrary `camel.sink.url` /
+ `camel.source.url`, `#class:` beans, SMT class options) is by design.
+- Authentication, exposure and secret storage of the Kafka Connect REST API
+ and config topic are the Kafka Connect runtime's responsibility.
+- Vulnerabilities in the wrapped Camel component, data format, expression
+ language or Kamelet are governed by the
+ [Apache Camel Security
Model](https://camel.apache.org/manual/security-model.html)
+ and triaged by the Camel PMC against `apache/camel` or the Kamelets catalog.
+- DoS through unthrottled routes and third-party transitive CVEs not reachable
+ through Camel Kafka Connector code are out of scope.
+
+Reports outside the documented scope will be closed with a reference to that
+page; reports whose root cause is a wrapped Camel component or Kamelet will be
+redirected to the Apache Camel security process.
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 0f51a56911..798b274c7d 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -13,6 +13,7 @@
*** xref:user-guide/extending-connector/archetype-connector.adoc[Extensible
connector archetype]
***
xref:user-guide/extending-connector/archetype-dataformat-connector.adoc[Extensible
Dataformat connector archetype]
***
xref:user-guide/extending-connector/archetype-apicurio-connector.adoc[Extensible
Apicurio connector archetype]
+* xref:security-model.adoc[Security Model]
* xref:contributor-guide/index.adoc[Contributor guide]
** xref:contributor-guide/testing.adoc[Testing]
** xref:contributor-guide/troubleshooting.adoc[Troubleshooting]
diff --git a/docs/modules/ROOT/pages/security-model.adoc
b/docs/modules/ROOT/pages/security-model.adoc
new file mode 100644
index 0000000000..edf8f07859
--- /dev/null
+++ b/docs/modules/ROOT/pages/security-model.adoc
@@ -0,0 +1,415 @@
+= Security Model
+
+This page documents the Camel Kafka Connector (CKC) security model: who is
+trusted, where the trust boundaries sit, what counts as a CKC vulnerability,
+what is inherited from Apache Camel, and what is expected of the Kafka Connect
+operator. It is the reference used by the Apache Camel PMC when triaging
+security reports against this repository and by the project when deciding
+whether a behaviour should be hardened in CKC, fixed upstream in Camel, or
+addressed by the deployment.
+
+Camel Kafka Connector is *not* a standalone runtime. It is a set of Kafka
+Connect source and sink connectors that package Apache Camel components - via
+the https://camel.apache.org/camel-kamelets/latest/[Camel Kamelets] catalog -
+so they can run inside a Kafka Connect worker without writing code. Almost
+every security-relevant behaviour therefore belongs to one of two other
+layers, and this document's main job is to say which:
+
+* The *Apache Camel security model* -
+ https://camel.apache.org/manual/security-model.html[`security-model.adoc`]
+ in the `apache/camel` repository - governs every wrapped component, data
+ format, expression language and Kamelet. CKC inherits it wholesale.
+* The *Apache Kafka Connect runtime* governs the REST API, connector-config
+ storage, plugin classpath isolation, and worker-to-broker transport. CKC
+ runs inside it and does not re-implement it.
+
+What is left - the thin glue in the `core/` module that turns a connector
+configuration into a Camel route and shuttles records between Kafka and the
+Camel `Exchange` - is the subject of this document.
+
+NOTE: This model is written against camel-kafka-connector 4.21.x (Apache Camel
+4.21.x, Camel Kamelets 4.21.x, Kafka Connect 3.9.x, Java 17). It is versioned
+alongside the project: a report against CKC version _N_ is triaged against the
+model as it stood at _N_. It should be revised on the triggers listed in
+_Conditions that change this model_ below. For instructions on how to report a
+vulnerability, see https://camel.apache.org/security/[Apache Camel Security]
+and the repository `SECURITY.md` file.
+
+== Audience
+
+This document is written for four audiences:
+
+* *Security researchers and CVE reporters* who need to know what the Camel PMC
+ will accept as a CKC vulnerability - as opposed to a Camel-core issue, a
+ Kafka Connect issue, or an operator configuration choice - before submitting
+ a report.
+* *Automated triage tooling* (CVE scanners, AI-assisted security review) that
+ needs an authoritative scope statement to distinguish a real CKC
+ vulnerability from inherited Camel behaviour or an intentional, documented
+ design choice.
+* *Connector and SMT authors* contributing to this repository, who need to
+ know which defaults and patterns are acceptable in the glue layer.
+* *Kafka Connect operators* who deploy these connectors and need to know which
+ hardening responsibilities CKC, Camel and Kafka Connect each delegate to
+ them.
+
+== Trust model
+
+A Camel Kafka Connector runs as a plugin inside a Kafka Connect worker. A
+connector is created by submitting a configuration (a flat map of string
+properties) to the worker, either through the Kafka Connect REST API or
+through a worker properties file. Its trust model reflects that.
+
+=== Roles
+
+[cols="1,1,3"]
+|===
+| Role | Trust level | What this role can do
+
+| CKC contributors (the people writing the `core/` glue, the SMTs, the
+ archetypes and the generated connector modules)
+| Trusted
+| Define how a connector configuration is turned into a Camel route, choose
+ defaults, and publish releases. The project relies on these contributors to
+ ship secure defaults in the glue layer.
+
+| Connector configuration author (whoever submits or edits a connector
+ configuration through the Kafka Connect REST API or worker config)
+| Fully trusted
+| Set `camel.source.url` / `camel.sink.url` to *any* Camel endpoint URI;
+ reference arbitrary beans with `camel.beans.aggregate=#class:fqcn`; pass
+ `#class:` object properties through `camel.component.*` /
+ `camel.sink.endpoint.*` / `camel.source.endpoint.*`; choose any data format
+ for `marshal` / `unmarshal`; choose the error handler and idempotent
+ repository; and configure any Single Message Transform, including ones that
+ load a class named in the config. A connector configuration is route code.
+ Code execution by whoever can author one is *by design* and is not a CKC
+ vulnerability - it is the exact analogue of "a route author is fully
+ trusted" in the Camel security model.
+
+| Kafka Connect operator (whoever runs the worker, secures the REST API,
+ chooses the converters, and decides network exposure)
+| Fully trusted
+| Decide whether the Connect REST API is authenticated and where it listens,
+ pick the key/value/header converters, choose the `config.providers` for
+ secret externalisation, set JVM and OS user, and decide which connector
+ plugins are installed. Operator misconfiguration is not a CKC vulnerability
+ unless a CKC default exposed it.
+
+| Kafka topic producers (sink side) and external systems (source side)
+| Untrusted
+| Place records on the Kafka topics a sink connector consumes, or supply the
+ payloads an external system hands to a source connector's Camel consumer.
+ This is the primary attacker model. CKC's glue must not turn an untrusted
+ record or payload into code execution, endpoint redirection, or control of
+ the Camel route on its own.
+|===
+
+=== Trust boundaries
+
+The fundamental trust boundary in CKC is between *the connector configuration*
+(and the Camel/Kamelet route it deterministically builds) and *the data
+flowing through that route*. Everything in the configuration is authored by a
+trusted operator; everything in a Kafka record body, key or header on the sink
+side, and everything in an external payload on the source side, is untrusted
+data.
+
+CKC's job at this boundary is narrow and specific: the route topology
+(`from`, `toD`, beans, expressions, data formats) is derived *only* from the
+trusted configuration, never from the untrusted data; and untrusted data is
+moved across the Kafka/Camel boundary without being interpreted as a Camel
+control header, an endpoint, or code on CKC's own initiative. What the wrapped
+Camel component then does with that data is governed by the Camel security
+model, not this one.
+
+A second boundary, owned entirely by Kafka Connect, sits in front of CKC: the
+Connect REST API and the connector-config store. Anyone who can write a
+connector configuration is, by the table above, fully trusted - so protecting
+that write path is a precondition for this model, not part of it.
+
+== Vulnerability scope
+
+A report is in scope for CKC when it demonstrates that *the CKC glue layer*,
+in a default or reasonably-expected configuration, lets untrusted record or
+payload data cross the configuration/data trust boundary in a way the model
+says it should not - and the cause is CKC code, not the wrapped Camel
+component, not a Kamelet, and not the Kafka Connect runtime.
+
+=== Security properties and violation severity
+
+The trust-boundary statement commits the CKC glue to a small set of concrete
+properties. The wrapped component's properties (deserialization safety, XXE,
+path traversal, header-injection defence in the component itself, etc.) are
+*inherited from and scored by the Apache Camel security model* and are not
+restated here.
+
+[cols="3,3,1",options="header"]
+|===
+| Property the CKC glue upholds (default or reasonably-expected configuration)
+| What a violation looks like (symptom a reporter or scanner observes)
+| Indicative severity
+
+| Route topology is derived only from the connector configuration, never from
+ record or payload data
+| A crafted Kafka record body/key/header or source payload changes the
+ endpoint of `.toD()`, the bean selected for aggregation, the data format, or
+ the idempotency expression that the configuration did not specify
+| Critical (CVSS 9.0-9.8)
+
+| Untrusted record/exchange data is not promoted into a Camel-internal control
+ header by the CKC mapping itself
+| The Kafka<->Exchange header mapping in `CamelSinkTask` / `CamelSourceTask` /
+ `TaskHelper` injects a `Camel*` dispatch header
(`CamelExecCommandExecutable`,
+ `CamelBeanMethodName`, ...) from untrusted data without the operator opting
+ into that mapping
+| High to Critical (CVSS 7.5-9.1), depending on the reachable component
+
+| Secrets in the connector configuration are not disclosed by CKC's own code
+| CKC's startup logging, an SMT, or the source/sink record path writes a
+ password/token/secret config value verbatim to the worker log or into a
+ produced record
+| Medium to High (CVSS 5.3-8.2), depending on what leaks and where
+
+| The glue adds no untrusted-data deserialization or parsing of its own
+| `CamelSinkTask` / `CamelSourceTask` / a bundled SMT runs `ObjectInputStream`
+ or an external-entity-resolving parser over record data that the operator
+ did not route through a component/data-format that documents it
+| High to Critical, mapped to the Camel deserialization/XXE tiers
+|===
+
+The tiers are *indicative*. The PMC assigns the definitive CVSS vector per
+report, considering the non-default configuration required, the reachable
+component, and the concrete impact. A finding whose only path requires the
+operator to have authored a dangerous configuration is out of scope (see
+below) regardless of tier.
+
+=== In-scope vulnerability classes
+
+==== Untrusted data steering the route topology
+
+Any CKC code path where the body, key, headers or properties of a Kafka
+record (sink) or an external payload (source) - rather than the connector
+configuration - determine where the exchange is sent, which bean or
+aggregation strategy runs, which data format is applied, or which expression
+is evaluated. The route built by `CamelKafkaConnectMain` must be a pure
+function of the configuration.
+
+==== CKC-mapped header injection
+
+The sink path maps Kafka record headers whose key starts with `CamelHeader.`
+into Camel `Exchange` headers (and `CamelProperty.` into exchange properties),
+stripping the prefix; the source path does the reverse. A report is in scope
+if untrusted record/exchange data crosses this mapping and CKC's own code -
+not the wrapped component's `HeaderFilterStrategy` - is what allows a
+Camel-internal dispatch header to be injected in a default configuration
+(`camel.map.headers` / `camel.map.properties` default to `true`). The
+operator-facing mitigation is `camel.remove.headers.pattern`; the question for
+in-scope triage is whether CKC's default mapping is itself the exposure.
+
+==== Information disclosure of configuration secrets by CKC code
+
+CKC code that writes connector-configuration secrets to a log, an event, or a
+produced Kafka record. CKC masks keys flagged sensitive by Camel's
+`SensitiveUtils` in its one startup "initial properties" log line; a path that
+bypasses that masking, or that leaks a secret value through a record or SMT,
+is in scope.
+
+==== Deserialization or external-resource parsing added by the glue
+
+Any `ObjectInputStream`, XML/XSLT/XSD/XPath, or equivalent external-entity- or
+remote-resource-resolving parse performed by `core/` glue or a bundled SMT on
+untrusted record data, where the operator did not select a component or data
+format that documents that behaviour. (Deserialization/XXE *inside a wrapped
+component or data format* is a Camel issue, governed by the Camel model.)
+
+==== Insecure CKC defaults
+
+A default in the glue layer that exposes one of the classes above with no
+configuration - for example, mapping untrusted headers into dispatch headers
+out of the box, or logging configuration verbatim at a default level - is in
+scope independently of the underlying mechanism.
+
+=== Out of scope
+
+The following are *not* CKC vulnerabilities. They are intentional design,
+operator responsibility, Kafka Connect responsibility, or upstream Camel
+matters. Reports in these categories will be closed with a reference to this
+document and, where applicable, redirected.
+
+* *A connector configuration that runs code or reaches any endpoint.* Setting
+ `camel.sink.url=exec:...`, `camel.source.url=file:/etc`, an arbitrary
+ endpoint URI, `camel.beans.aggregate=#class:com.example.Evil`, a `#class:`
+ object property, or an SMT that loads a configured class is configuration
+ authoring, and the configuration author is fully trusted. This is the direct
+ analogue of "a route author writing code that does whatever they want" in
+ the Camel model.
+* *Anything reachable only because the Kafka Connect REST API is
unauthenticated
+ or exposed.* Authentication, authorization, TLS and network placement of the
+ Connect REST API and of the worker are Kafka Connect's responsibility.
Whoever
+ can reach that API is, by definition, a trusted configuration author.
+* *Connector configuration stored or served in clear text.* Kafka Connect
+ persists connector configs (including passwords) in its config topic and
+ serves them through the REST API. Externalising secrets with a
+ `config.providers` / `ConfigProvider` and securing the config topic are
+ operator/Kafka-Connect responsibilities. CKC's only duty here is not to
+ *additionally* leak them (see in-scope above).
+* *A vulnerability in the wrapped Camel component, data format, expression
+ language or Kamelet.* These are governed by the
+ https://camel.apache.org/manual/security-model.html[Apache Camel security
+ model] and triaged by the Camel PMC against `apache/camel` or the Kamelets
+ catalog. A CKC report must show that CKC glue, not the component, is the
+ cause. "Connector X wraps component Y which had CVE-Z" is not, by itself, a
+ CKC finding.
+* *Denial of service via resource exhaustion.* Unbounded aggregation, an
+ oversized record, an unthrottled source, an idempotent repository sized too
+ small - operators apply Camel's aggregation/throttling options, Kafka
+ Connect's `max.poll.records` and converter limits, and JVM heap limits.
+* *Third-party transitive dependency CVEs not reachable through any
+ CKC-exposed code path.* Reported to the upstream project; see `SECURITY.md`.
+* *Self-XSS or issues in a UI built on top of Kafka Connect* (e.g. a connector
+ management console). Not shipped by this project.
+* *Scanner output with no demonstrated trust-boundary breach.* "The glue uses
+ reflection" or "a connector depends on a library with historic CVEs" is not
+ a finding without a PoC showing untrusted record/payload data crossing the
+ boundary through CKC code.
+
+=== Known limitations
+
+These are CKC characteristics that can look like vulnerabilities at first
+glance but are documented design points. They may be tightened over time
+through the normal release and upgrade-note channel.
+
+* *Authoring a connector configuration is equivalent to deploying code.* Kafka
+ Connect's plugin model means a connector *is* code running in the worker
+ JVM; CKC makes that code configuration-driven, but the trust level of
+ whoever submits the configuration is identical to a Camel route author. This
+ is intentional and is why securing the Connect REST API is a precondition,
+ not a CKC feature.
+* *Header mapping is prefix-gated, not `HeaderFilterStrategy`-based.* On the
+ sink side CKC maps only `CamelHeader.` / `CamelProperty.`-prefixed Kafka
+ headers; on the source side it prefixes Camel headers symmetrically. It does
+ not, by itself, apply a Camel `HeaderFilterStrategy`. Stripping unwanted or
+ internal headers from untrusted producers is delegated to the operator via
+ `camel.remove.headers.pattern` and to the wrapped component's own inbound
+ filter. See _Deployment hardening_.
+* *Connectors inherit the security posture and CVE exposure of the wrapped
+ component and Kamelet.* A connector built on a component that defaults to a
+ permissive setting carries that setting. The fix for such a case lands in
+ Apache Camel or the Kamelets catalog and is consumed by CKC on the next
+ dependency bump; it is not separately re-mediated in CKC.
+* *Secrets live in the connector configuration.* CKC masks sensitive keys only
+ in its own startup log line. Everything else about secret handling - the
+ config topic, the REST API, externalisation - is Kafka Connect's model.
+
+== Deployment hardening
+
+The Kafka Connect operator is responsible for the following. None are CKC
+vulnerabilities if skipped; all materially reduce attack surface.
+
+* *Authenticate and isolate the Kafka Connect REST API.* Treat write access to
+ it as equivalent to arbitrary code execution in the worker JVM. Put it
+ behind authentication and on a trusted network only.
+* *Externalise secrets.* Use a Kafka Connect `config.providers` /
+ `ConfigProvider` (file, Vault, environment, cloud secret managers) instead
+ of clear-text passwords in connector configs, and restrict access to the
+ config topic and the REST API.
+* *Strip Camel-internal headers from untrusted producers.* When a sink
+ connector consumes a topic fed by untrusted producers, set
+ `camel.remove.headers.pattern` so that attacker-supplied `CamelHeader.Camel*`
+ headers are not promoted into Camel dispatch headers, and/or set
+ `camel.map.headers=false` / `camel.map.properties=false` when header mapping
+ is not needed.
+* *Do not source dangerous endpoints, beans or expressions from variable
+ configuration.* Treat `camel.sink.url`, `camel.source.url`, `camel.beans.*`,
+ `#class:` properties and SMT class options as trusted code; do not template
+ them from untrusted input in whatever system generates connector configs.
+* *Pin and patch the Camel/Kamelets train.* CKC's component security comes
+ from Apache Camel and the Kamelets catalog. Track Camel advisories at
+ https://camel.apache.org/security/[] and upgrade CKC to pick up fixed
+ component versions.
+* *Constrain resource use.* Apply Camel aggregation/idempotency sizing, Kafka
+ Connect `max.poll.records` / converter limits, and JVM heap limits to bound
+ the effect of large or high-rate records.
+* *Run with least privilege.* Limit the worker OS user's filesystem, network
+ and process privileges; install only the connector plugins actually used -
+ every extra plugin enlarges the worker's attack surface and patch burden.
+
+== Guidance for connector and SMT authors
+
+When contributing to the `core/` glue, a bundled SMT, an archetype, or a
+generated connector module, the following questions decide whether a change is
+in line with this model.
+
+* *Does the change let record or payload data influence the route topology?*
+ The route built in `CamelKafkaConnectMain` must remain a pure function of
+ the connector configuration. Endpoint, bean, data format, aggregation
+ strategy and idempotency expression come from configuration only.
+* *Does the change touch the Kafka<->Exchange header mapping?* Preserve the
+ explicit `CamelHeader.` / `CamelProperty.` prefix gating; do not widen it so
+ that arbitrary untrusted headers become Camel headers by default, and keep
+ `camel.remove.headers.pattern` effective.
+* *Does a new SMT or glue path deserialize or parse record data?* Do not add
+ `ObjectInputStream`, external-entity-resolving XML/XSLT, or equivalent over
+ untrusted record data in the glue. Type conversion must go through Camel's
+ `TypeConverter` (as `CamelTypeConverterTransform` does), and class selection
+ must come from configuration, not from the record.
+* *Does the change log configuration or record content?* Route configuration
+ logging through the existing sensitive-key masking
+ (`SensitiveUtils`-based filtering); never log a raw config map or a record
+ body at a default level.
+* *Does the change rely on a component default?* If a connector's safety
+ depends on a Camel component or Kamelet default, the fix for an unsafe
+ default belongs upstream in Apache Camel or the Kamelets catalog - raise it
+ there, do not paper over it in the glue.
+
+== Reporting a vulnerability
+
+Camel Kafka Connector is an Apache Camel sub-project and uses the standard ASF
+vulnerability reporting process:
+
+* Read https://camel.apache.org/security/[Apache Camel Security].
+* Email mailto:[email protected][[email protected]] with a
+ description, the affected CKC version, the connector(s) involved, and a
+ proof of concept that demonstrates the trust-boundary breach in CKC glue (as
+ opposed to a wrapped Camel component or the Kafka Connect runtime).
+* Do not open a public GitHub issue or pull request, post on a mailing list or
+ social media, or otherwise disclose anything about the potential issue until
+ a coordinated fix is released. Only contact the
+ https://apache.org/security/[Apache Software Foundation Security team] and
+ follow their instructions.
+
+Reports that match the in-scope classes are triaged on the private security
+list, fixed in a coordinated release, and published as a CVE advisory. Reports
+that match the out-of-scope categories are closed with a reference to this
+document; reports whose root cause is a wrapped Camel component or Kamelet are
+redirected to the Apache Camel security process.
+
+== Conditions that change this model
+
+This document should be revised when:
+
+* the connector configuration surface gains a new code-bearing or
+ topology-affecting property, or the header-mapping behaviour changes;
+* a bundled SMT or glue path starts deserializing or parsing record data;
+* CKC stops being a thin Kamelet/Camel packaging and takes on runtime
+ behaviour of its own;
+* the relationship to the Kafka Connect REST API or config store changes
+ (e.g. CKC begins handling secrets itself); or
+* a vulnerability report cannot be cleanly routed to either this model, the
+ Apache Camel security model, or Kafka Connect - which means the boundary
+ here has a gap and the model, not the report, needs the fix.
+
+== Related documents
+
+* https://camel.apache.org/manual/security-model.html[Apache Camel Security
+ Model] - governs every wrapped component, data format, expression language
+ and Kamelet; CKC inherits it.
+* https://camel.apache.org/security/[Apache Camel Security] - the public
+ advisory index and reporting process (shared with CKC).
+* xref:user-guide/basic-configuration.adoc[Basic configuration] - the
+ connector configuration surface this model treats as trusted.
+* xref:user-guide/remove-headers.adoc[Remove Headers] - the
+ `camel.remove.headers.pattern` mitigation referenced above.
+* https://kafka.apache.org/documentation/#connect[Apache Kafka Connect] - the
+ runtime that owns the REST API, config store and plugin isolation.
+* `SECURITY.md` (in the source tree) - the GitHub-rendered security pointer.
