Add draft project security threat-model document by potiuk · Pull Request #1293 · apache/knox

potiuk · 2026-07-02T18:41:02Z

What

Adds a v0 THREAT_MODEL.md for Apache Knox, plus the discoverability wiring (SECURITY.md and AGENTS.md), drafted by the ASF Security team for the Knox PMC to review, adjust, and own.

This is path 3 of the Frontier Model Preparation pre-flight — the Knox PMC (Larry McCay, chair) asked on 2026-07-02 for a v0 draft to react to. The document follows the Security team's threat-model rubric: it describes the assumptions Knox makes about its environment and callers, the security properties it upholds and the ones it explicitly disclaims, the operator's responsibilities, and a triage-disposition table for routing a security report.

THREAT_MODEL.md — the v0 draft (provenance-tagged (documented)/(maintainer)/(inferred); §14 collects the open questions for the PMC, prioritized in waves).
SECURITY.md — a reporting policy (Knox had none) that links the threat model.
AGENTS.md — points to SECURITY.md → THREAT_MODEL.md so the model is mechanically discoverable.

For the PMC — highest-leverage open questions

§14 Q14 — is ungated HeaderPreAuth (trusting an identity header without an mTLS/IP gate) a supported posture, or a misconfiguration the operator must avoid?
§14 Q24 — ratify "faithful identity assertion" (a client cannot make Knox assert a principal it did not authenticate) as the keystone property.
§14 Q3 / Q4 — confirm the operator, the federated IdP, and the backend services are out of the adversary model.

The (inferred) claims are the ones needing PMC confirmation; promoting them to (maintainer) as you answer §14 is the fastest path to a ratified model.

🤖 Generated with Claude Code

Adds a v0 THREAT_MODEL.md for Apache Knox drafted by the ASF Security team for the Knox PMC to review, adjust, and own (path 3 of the Frontier Model Preparation pre-flight, per the Knox PMC's 2026-07-02 go-ahead), plus the discoverability wiring: AGENTS.md -> SECURITY.md -> THREAT_MODEL.md. Generated-by: Claude (Opus 4.8, 1M context)

github-actions · 2026-07-02T19:04:58Z

Test Results

32 tests 32 ✅ 3s ⏱️
1 suites 0 💤
1 files 0 ❌

Results for commit 7f2caa4.

♻️ This comment has been updated with latest results.

…nore apache-rat 0.13 (this repo's version) does not recognise the short SPDX identifier, so it flagged THREAT_MODEL.md / SECURITY.md / AGENTS.md. Switching to the full AL-2.0 header (HTML comment) makes them pass the license check on every RAT version, so the .ratignore exemption is no longer needed. Generated-by: Claude Code

potiuk · 2026-07-04T13:36:07Z

Quick note on the CI: the red was apache-rat flagging the three added .md files. I've just pushed a commit adding the full Apache License v2.0 header (as an HTML comment) to each, which resolves it under this repo's current apache-rat 0.13 — so the PR should go green as-is.

One alternative worth flagging: apache-rat-plugin.version here is pinned to 0.13 (~2015). Newer RAT (0.16.1) recognises the SPDX identifier and has a decade of format/bugfix improvements. If the PMC prefers, I'm happy to swap the header commit for a one-line bump of that property (0.13 → 0.16.1) instead — whichever you'd rather carry. Just say the word and I'll include it here.

No strong preference from our side; the header fix already gets you green, so the bump is purely optional cleanup.

lmccay · 2026-07-09T22:11:42Z

Quick note on the CI: the red was apache-rat flagging the three added .md files. I've just pushed a commit adding the full Apache License v2.0 header (as an HTML comment) to each, which resolves it under this repo's current apache-rat 0.13 — so the PR should go green as-is.

One alternative worth flagging: apache-rat-plugin.version here is pinned to 0.13 (~2015). Newer RAT (0.16.1) recognises the SPDX identifier and has a decade of format/bugfix improvements. If the PMC prefers, I'm happy to swap the header commit for a one-line bump of that property (0.13 → 0.16.1) instead — whichever you'd rather carry. Just say the word and I'll include it here.

No strong preference from our side; the header fix already gets you green, so the bump is purely optional cleanup.

@potiuk - thanks for the offer. We can bump that separately.
I have a couple comments in-flight in this PR, I'll continue it for the review and likely just make the changes myself.

lmccay

Provided comments

lmccay · 2026-07-02T20:06:16Z

+  proxy-user / identity-assertion mechanism assumes the backend will accept a
+  Knox-asserted principal. This means **anything that lets a client control the
+  asserted identity is an authentication bypass against every backend.**
+- **Network segmentation** *(inferred → Q6)*: Knox assumes clients cannot reach


Network segmentation is one possibiliity. The other is that traffic that CAN authenticate via Kerberos directly to the backend servers are indeed allowed and without explicit proxyuser config making the clients trusted proxies they may not assert the identity of another user via doAs.

lmccay · 2026-07-02T20:08:41Z

+  `conf/` and `data/security/`; writes audit + service logs; may spawn nothing
+  beyond the JVM. This "no-surprise" inventory is almost entirely inferred and is
+  a high-priority confirmation target.
+


Let's verify whether the webshell terminal spawns any process.

lmccay · 2026-07-02T20:13:04Z

+| Knob / mode | Less-secure setting | Proposed maintainer stance |
+| --- | --- | --- |
+| Demo LDAP + `sandbox` topology | shipped, trivially bypassable creds | dev-only; production must replace *(→ Q5)* |
+| Self-signed identity keystore | default if operator provides none | dev-only; production installs a CA cert *(→ Q13)* |


This should be 'identity certificate' as the keystore has separate considerations.

lmccay · 2026-07-02T20:14:35Z

+| Demo LDAP + `sandbox` topology | shipped, trivially bypassable creds | dev-only; production must replace *(→ Q5)* |
+| Self-signed identity keystore | default if operator provides none | dev-only; production installs a CA cert *(→ Q13)* |
+| `HeaderPreAuth` without an IP/mTLS trust check | trusts `SM_USER`/custom identity header from any client | **VALID if reachable** — a preauth header trusted without a gating check is a classic Knox misconfig-to-CVE path *(→ Q14)* |
+| Anonymous / `Anonymous` auth provider or no authz provider in a topology | request passes unauthenticated/unauthorized | operator-chosen posture for public services; report ⇒ OUT-OF-MODEL unless a *different* topology's protection leaks *(→ Q15)* |


This is used for public or self-authenticating services and is indeed OUT-OF-MODEL

lmccay · 2026-07-09T22:22:45Z

+**Wave 1 — scope, deployment, adversary (unblocks everything):**
+
+- **Q1 (§2):** Deployment shape is "a long-running Jetty-based edge daemon,
+  administrator-operated; not an in-process library." Correct?


lmccay · 2026-07-09T22:32:38Z

+
+- **Q19/Q20 (§6/§8):** Confirm the per-surface trust table, and state the
+  resource line. Proposed: "unauthenticated hang/crash = bug; proportionate load
+  = not."


lmccay · 2026-07-09T22:32:57Z

+  resource line. Proposed: "unauthenticated hang/crash = bug; proportionate load
+  = not."
+- **Q26 (§9):** Confirm Knox perimeter authz does not replace backend/Ranger
+  authz.


lmccay · 2026-07-09T22:38:01Z

+  authz.
+- **Q27 (§9):** For the reverse-proxy attack classes (request smuggling, SSRF,
+  SSO open-redirect, SAML XXE, host-header/XFF confusion, WebSocket origin),
+  which does Knox take responsibility for vs leave to the operator?


All protections are the responsibility of the operator though Knox provides various ways for them to add ptotections. For things like XSRF, we have the WebAppSecProvider that can be configured for XSRF, CSS, CORS, etc. We also have various regexp based whitelists to protect against SSRF and open-redirect. These protections must be properly tuned for the deployment specific expectations with regard to hosts, ports, domains, etc.

lmccay · 2026-07-09T22:39:53Z

+- **Q-meta-A:** Knox has **no** project-specific `SECURITY.md` or website security
+  page (only the generic `security@apache.org` entry on
+  security.apache.org/projects). Should this model become the canonical Knox
+  security document, linked from a new `SECURITY.md` and the project site?


lmccay · 2026-07-09T22:40:33Z

+  security.apache.org/projects). Should this model become the canonical Knox
+  security document, linked from a new `SECURITY.md` and the project site?
+- **Q-meta-B:** Where should the ratified model live (`docs/` in-repo, versioned
+  with releases) and what change class triggers a revision (per §12)?


smolnar82 requested review from lmccay, moresandeep, pzampino and smolnar82 July 3, 2026 19:03

lmccay requested changes Jul 9, 2026

View reviewed changes

Uh oh!

Conversation

potiuk commented Jul 2, 2026

What

For the PMC — highest-leverage open questions

Uh oh!

github-actions Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

potiuk commented Jul 4, 2026

Uh oh!

lmccay commented Jul 9, 2026

Uh oh!

lmccay left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Jul 2, 2026 •

edited

Loading