chore: add draft threat model

[oscerd]

What this is

A threat model for Karavan, at docs/threat-model.md.

It is deliberately not an audit, a pentest report, or a findings list. It describes the
implicit contract between Karavan and the people who deploy it: what Karavan assumes, what
it guarantees given those assumptions, what it leaves to the operator, and which misuses
look reasonable but aren't. The audience is two-sided — an operator deciding how to deploy
Karavan, and a triager who has to classify an inbound vulnerability report or a scanner hit
and cite a section to justify the call.

Why

Karavan has no SECURITY.md, and no entry in the ASF security site's
project-coordinates.json.
The Apache Camel security model
scopes itself to apache/camel artifacts and explicitly notes that sibling subprojects
"have their own security surfaces" — Karavan isn't named. So today there is nothing a
triager can cite when a report or an automated scan lands.

The model inherits Camel's role vocabulary (route author / operator / external message
sender) rather than inventing a parallel one. Appendix A back-maps all eleven of that
document's statements to sections here.

Status: reviewed

@mgubaidullin answered waves 1–3 below. Every hypothesis in the first draft is now
confirmed, corrected, or superseded:

57 (documented) · 40 (maintainer) · 0 (inferred) — down from 28 inferred.

Only Q13 and Q14 remain open, and both are about the document rather than about
Karavan (see Still open at the bottom).

The claim the document turns on — confirmed

The trust boundary is HTTP authentication, and nothing after it. A Karavan account is
Camel's "route author", which that model declares fully trusted. Docker mode bind-mounts
/var/run/docker.sock; Kubernetes mode grants verbs: ["*"] plus pods/exec; a project's
docker-compose.yaml reaches MountType.valueOf(...) and /bin/sh -c; and
configuration/build.sh is a user-editable file executed at mode 0755.

Q2 confirmed this. So "an authenticated user achieves RCE" is OUT-OF-MODEL: adversary-not-in-scope, and §4.11a carries it as a suppression entry alongside the
docker.sock mount, the wildcard RBAC, and the application.properties credentials that
every secret scanner flags.

Three answers changed the model rather than confirming it

Q11 corrected the draft. I proposed that the non-invalidating
/platform/internal/sources/{projectId}/{filename} route was an oversight. It isn't — it's
by design. §4.8 property 9 now scopes the single-use guarantee to the whole-project route
only, and a report that the per-file route reuses a session is BY-DESIGN.

Q5 was confirmed but not promised. The negative side-effect inventory (no signal
handlers, no child processes, no host path reads, no extra listeners) is accurate — but
"that is just how it is today and we do not have any plans to change that" is a description,
not an invariant. §4.5 now says so explicitly and asks readers to re-verify on a §4.12
trigger, rather than treating it as a guarantee a future release will keep.

Q1 settled the insecure default. platform.password is an install-time convenience set
via Kubernetes secret or Docker env var and changed afterwards through the UI, so a report
against the shipped default is OUT-OF-MODEL: non-default-build.

Q9 rebound the whole document

"Already fixed" turned out to mean three controls that landed after the 4.22.0 tag:

Control	Commit	Where it lands
CsrfFilter — synchronizer-token check on X-CSRF-Token, constant-time, logout deliberately not exempt	d211d71f	§4.8 property 13
PathUtils — project id / file name validation on the /ui/file write paths	5e425249	§4.8 property 14
karavan.deployment.allowed-kinds + pod-spec restrictions, namespace pinned	d211d71f	§4.5a, §4.9

So the model is now bound to main at 677a293a, not to 4.22.0, and says so in the
header: a report filed against 4.22.0 or earlier is triaged against a model in which those
three do not exist. CSRF moved out of the §4.9 "false friends" table and into §4.8 as a
claimed property.

Two things I want to flag rather than bury:

• The Kubernetes resource validation is written up as defence in depth, explicitly not a
  boundary. It covers startDeployment only — not runBuildProject's pod fragment, not
  configuration/build.sh, and nothing on the Docker path, where a compose file still
  controls bind mounts and the shell command. §4.9 says that plainly so nobody later reads
  it as a sandbox, and §4.11a routes "it can be bypassed via the builder pod" to
  OUT-OF-MODEL rather than to a control bypass.
• application.properties sets deployment.allowed-kinds, but KubernetesService injects
  karavan.deployment.allowed-kinds. The names don't match, so the properties entry
  doesn't bind and the code falls back to its DEFAULT_ALLOWED_DEPLOYMENT_KINDS constant.
  Same value today, so no behaviour change — but editing the properties file to widen the
  list silently does nothing. Not a threat-model matter and not fixed here; worth a separate
  one-line change.

Still open

Q13 — where does this live? Should Karavan get a SECURITY.md pointing at
security@apache.org and at this file, and be added to the ASF security site's
project-coordinates.json so the Camel security page links it as a subproject?

Q14 — who owns revisions, and does the model ship with releases? Proposed: Karavan
committers own it, it updates in the same PR as any change tripping a §4.12 trigger, and it
is tagged per release. This revision already spans two versions — which is exactly the drift
the tagging policy would prevent.

Notes

• Appendix B is a resolution log: every ruling, what it changed, and where it landed — so a
  disputed disposition can be traced to the answer behind it rather than to prose.
• Doc-only. No code changes in this PR.
• Rubric: https://gist.github.com/potiuk/da14a826283038ddfe38cc9fe6310573

🤖 Generated with Claude Code

[oscerd]

@mgubaidullin have a look at the questions so we could complete the model.

[mgubaidullin]

Q1: Correct. The default password is a starting point set during installation (via Kubernetes secrets or Docker env vars) and operators are expected to change it through the UI; it is an out-of-scope dev/install convenience, not a supported production posture.

Q2 — Confirm. Yes, any authenticated user is fully trusted.

Q3 — Confirm. Yes, the connected Git repository and image registry are considered fully trusted inputs.

Q4 — Confirm. It is just forward-looking scaffolding for future features.

Q5 - Correct. That is just how it is today and we do not have any plans to change that.

Q6 - Confirmed. Reports against insecure defaults are OUT-OF-MODEL (operator responsibility).

Q7 (Resource Limits): Confirmed. DoS and resource exhaustion are OUT-OF-MODEL.

Q8 (Public Endpoints): Confirmed. Pre-login disclosure of Keycloak/SSO configs is BY-DESIGN.

Q9 - Already fixed

Q10 (VS Code): Confirmed. Malicious workspaces/repos are OUT-OF-MODEL (trusted input).

Q11 (API Sessions): Corrected. The non-invalidating route is BY-DESIGN (not an oversight).

Q12 (Logs): Confirmed. Lack of strict audit trails is BY-DESIGN (it's just telemetry).