apache/knox.master, cross-read against the 1.6.0 User's Guide. A report against Knox version N should be triaged against the model as it stood at N, not at HEAD. Attach this model to a release tag once ratified.| Tag | Meaning |
|---|---|
| (documented) | Stated in Knox‘s own docs (project site, User’s Guide). Cited inline. |
| (maintainer) | Stated by a Knox maintainer in response to this process. |
| (inferred) | Reasoned from architecture, domain knowledge, or absence of a doc statement — not yet confirmed. Has a matching §14 open question. |
~17 documented / ~39 maintainer / ~11 inferred (after the 2026-07-09 PMC review). The Wave 1–3 core answers — deployment shape, adversary boundary, the keystone identity-assertion property, backend-hop TLS expectations, the HeaderPreAuth disposition, the per-surface trust table and resource line, the bearer-token/backend-hop false friends, and the reverse-proxy responsibility split — are now (maintainer). Still (inferred) and awaiting confirmation: Q7, Q8, Q9–Q13, Q17, Q21–Q22, Q28, Q29 (data-flow/reachability preconditions, remaining environment/host-side-effect inventory, self-signed / -persist-master stances, secondary adversary capabilities, the known-non-findings suppression set, and cross-topology isolation).
Apache Knox is an application gateway / reverse proxy that provides perimeter security for the REST APIs and web UIs of Apache Hadoop-ecosystem (and other) services (documented — project homepage). A single Knox instance sits at the network edge in front of a cluster, terminates client TLS, authenticates the caller through a configurable provider chain (LDAP/AD via Shiro, Kerberos via HadoopAuth, SAML/OIDC/CAS via pac4j, header pre-auth, SSO cookie, JWT), authorizes the request against service-level ACLs, rewrites URLs to hide internal topology, and dispatches the request to the appropriate backend service while asserting the caller‘s identity to that backend *(documented — User’s Guide)*. It also issues SSO tokens (KnoxSSO) and bearer tokens (KnoxToken) and manages secrets in a master-secret-protected credential store / alias service (documented — User's Guide). Knox's whole purpose is to be a trust boundary: untrusted HTTP clients on one side, trusted cluster services on the other.
Primary intended use (documented — homepage / User's Guide):
Deployment context (maintainer, 2026-07-09 — L. McCay confirmed Q1): a long-running network daemon (Jetty-based server), deployed at the cluster edge, operated by a cluster administrator. It is not an in-process library and not a CLI-first tool (though a Knox CLI exists for admin/keystore operations).
Caller roles. A gateway has no single “caller”; the role splits three ways:
Component-family table (maintainer, 2026-07-09 — L. McCay confirmed Q2):
| Family | Representative entry point | Touches outside process? | In model? |
|---|---|---|---|
| Request pipeline (routing, filter chain) | inbound HTTP/WS on the gateway port | network | in |
| Authentication provider chain | Shiro/LDAP, HadoopAuth/Kerberos, pac4j SAML/OIDC, HeaderPreAuth, SSOCookie, JWT filters | network (to IdP), filesystem | in |
| Authorization (AclsAuthz) | topology ACL evaluation | — | in |
| Rewrite / URL translation | per-service rewrite rules | — | in |
| Dispatch / proxy | backend HTTP(S) client, identity assertion | network (to backend) | in |
| KnoxSSO / KnoxToken services | /knoxsso, /knoxtoken endpoints | filesystem (keys), network | in |
| Credential / alias / keystore service | master secret, __gateway-credentials.jceks, per-topology stores | filesystem | in (operator boundary — see §3) |
| Admin API + Knox CLI | /admin, bin/knoxcli.sh | filesystem | in (operator-authenticated) |
| Topology / provider descriptors | XML in conf/topologies/ | filesystem | operator input, trusted — §3/§6 |
| Sample topologies, demo LDAP, examples | sandbox.xml, demo ApacheDS, gateway samples | filesystem, network | OUT — §3 |
sandbox topology, gateway sample apps, and self-signed test certificate are explicitly for evaluation, not production. Findings that only manifest with the demo LDAP running, the sample topology deployed, or the self-signed cert in use are OUT-OF-MODEL: unsupported-component (maintainer, 2026-07-09 — L. McCay confirmed Q5; the User's Guide markets these as getting-started aids, documented).doAs).The trust boundary is the gateway itself. North of Knox: untrusted HTTP/WS clients. South of Knox: trusted backend services. Knox‘s job is to be the gate where an untrusted request is authenticated, authorized, and — only then — re-emitted as a trusted request *(documented — homepage: “perimeter security”; User’s Guide)*.
Request data flow (per request) (inferred → Q8):
doAs/proxy-user header, SPNEGO). This is a trust-elevation point: after this step the request carries Knox-minted identity that the backend trusts.Reachability preconditions (the triager's first test) (inferred → Q8):
OUT-OF-MODEL: trusted-input (§6).data/security/ and conf/.data/security/keystores/). Knox assumes only the operator (and the Knox process user) can read the master secret file, the credential stores, and the identity keystore. -persist-master explicitly trades a prompt for on-disk storage and “requires careful file permission management” (documented).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. Specific open item flagged by the PMC (2026-07-09 — L. McCay): verify whether the webshell terminal service spawns any process — if it does, the “spawns nothing beyond the JVM” assumption needs qualification and the webshell surface warrants its own trust-boundary note.Unlike a library with compile flags, Knox's security envelope is set almost entirely by operator topology/gateway configuration, not build flags. The model describes a correctly configured production gateway; several knobs, at their sample/default values, void §8 properties. For each, the PMC must rule whether the less-secure value is a supported posture (report ⇒ VALID) or a dev-convenience the operator must flip (report ⇒ OUT-OF-MODEL: non-default-build). All rulings below are proposed, pending §14.
| Knob / mode | Less-secure setting | Proposed maintainer stance |
|---|---|---|
Demo LDAP + sandbox topology | shipped, trivially bypassable creds | dev-only; production must replace (maintainer — confirmed Q5) |
| Self-signed identity certificate | 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 | OUT-OF-MODEL — operator responsibility (maintainer, 2026-07-09 — L. McCay, Q14): the operator must avoid this or implicitly accepts the risk. Report ⇒ OUT-OF-MODEL: non-default-build. Hardening (VALID-HARDENING): Knox should default the trust gate so operators must explicitly accept the ungated risk. |
Anonymous / Anonymous auth provider or no authz provider in a topology | request passes unauthenticated/unauthorized | operator-chosen posture for public / self-authenticating services; report ⇒ OUT-OF-MODEL unless a different topology's protection leaks (maintainer, 2026-07-09 — L. McCay confirmed Q15: this is used for public/self-authenticating services and is OUT-OF-MODEL) |
| TLS protocol/cipher and hostname-verification settings on the backend dispatch hop | plaintext or unverified backend connection | operator-configured; a plaintext/unverified default hop is a §11 misuse, not a Knox guarantee (maintainer, 2026-07-09 — L. McCay confirmed Q16; TLS to backend is required to protect SPNEGO tokens) |
-persist-master | master secret stored on disk | supported with correct file perms (documented) (→ Q17) |
| Token TTL / renewal / server-managed token state | long-lived or non-revocable KnoxTokens | supported range TBD (→ Q18) |
Knox's inputs split cleanly into untrusted network input (the client) and trusted operator input (the descriptors and secrets).
Per-surface trust table (maintainer, 2026-07-09 — L. McCay confirmed Q19: the table stands, unless noted):
| Surface | Parameter | Attacker-controllable? | Operator/Knox must enforce |
|---|---|---|---|
| Any gateway route | request line / path | yes | rewrite must not allow path-traversal into other topologies/services |
| Any gateway route | request headers | yes | identity headers (SM_USER, X-Forwarded-*, forwarded-identity) must NOT be trusted unless a preauth trust gate is configured |
| Any gateway route | request body / WS frames | yes | streamed to backend; size/timeout limits are operator/Jetty config |
| Auth providers | credentials (LDAP bind, SPNEGO, OIDC code, JWT) | yes | validate signature/binding against the trusted IdP; no bypass |
/knoxtoken, /knoxsso | token/cookie presented by client | yes | verify signature + expiry + (if applicable) server-side revocation |
| Dispatch | backend hostname/port | no — from topology | rewrite/service defs come from trusted operator config |
Topology descriptors (conf/topologies/*.xml) | provider chain, ACLs, service URLs | no — trusted operator | authored by admin; not attacker input |
Provider config / descriptors (__gateway.xml, shared provider configs) | all fields | no — trusted operator | — |
| Master secret / credential store / keystore | secrets, aliases | no — operator, FS-protected | OS file permissions |
| Admin API / Knox CLI | topology CRUD, alias ops | operator-authenticated | admin authz; not an anonymous surface |
Key line: client-supplied identity headers and tokens are the crown-jewel untrusted inputs. The single most consequential Knox failure class is a client getting Knox to assert an identity (or authorization) it did not legitimately earn.
Size/shape/rate: Knox streams request/response bodies and WebSocket frames; body size, connection, and timeout limits are Jetty/topology configuration rather than a Knox-guaranteed bound (maintainer, 2026-07-09 — L. McCay confirmed Q20).
Primary adversary — the untrusted perimeter client (inferred → Q21). An anonymous or partially-authenticated HTTP/WebSocket peer that can reach the gateway listen port. Capabilities:
Secondary adversary — an authenticated-but-limited client (inferred → Q22): a client with valid credentials for some topology/service who tries to reach a service/topology they are not authorized for (authorization bypass, cross-topology confusion, rewrite escape).
Attacker goals in scope: authentication bypass; identity/assertion forgery (impersonate another user to the backend); authorization bypass; token forgery/ replay; disclosure of a secret from the credential store over the network; topology/internal-address disclosure defeating the concealment goal; SSRF via the proxy; crashing/hanging the gateway from unauthenticated input.
Explicitly out of the adversary model (maintainer, 2026-07-09 — L. McCay confirmed Q3/Q4):
data/security/ (that's the operator boundary).(No Byzantine-participant / consensus actor applies — Knox is a proxy, not a replicated consensus system. Clustered Knox instances share config and secret and are mutually trusting, not adversarial to each other → Q11.)
Each: property (+conditions) · violation symptom · severity · provenance.
Resource properties: Knox makes no strong quantitative resource guarantee against unauthenticated load beyond what Jetty/topology limits provide; slow-loris / large-body / many-connection pressure is bounded by operator config, not a Knox invariant (maintainer, 2026-07-09 — L. McCay confirmed Q19/Q20). Confirmed resource line: “an unauthenticated request that hangs or crashes the gateway process is a bug; merely consuming proportionate resources under load is not.” (maintainer, 2026-07-09 — L. McCay)
False friends — call these out explicitly:
HeaderPreAuth (SM_USER etc.) looks like it authenticates the user, but it only trusts a header — it is secure only when paired with an mTLS/IP trust gate that proves the header came from a trusted SSO front-end. Without that gate any client sets the header and impersonates anyone. This is the most dangerous Knox false friend. Disposition (maintainer, 2026-07-09 — L. McCay, Q14): an ungated HeaderPreAuth is OUT-OF-MODEL: non-default-build — the operator must avoid it or implicitly accepts the risk; it is not reported as a Knox VALID bug. The paired hardening ask is that Knox default the gate so the operator has to explicitly accept the ungated posture (VALID-HARDENING).Well-known attack classes Knox as a reverse proxy is exposed to and the operator must weigh (maintainer, 2026-07-09 — L. McCay answered Q27): HTTP request smuggling / desync between Knox and backend; SSRF via rewrite/dispatch if client input reaches the backend target; open-redirect via the SSO originalUrl/return-URL parameter; XXE if any provider parses attacker-supplied XML (e.g. SAML responses); host-header / X-Forwarded-* trust confusion; WebSocket origin/authorization gaps; cookie scope/Secure/HttpOnly handling for KnoxSSO.
Responsibility split (maintainer, 2026-07-09 — L. McCay): all of these protections are ultimately the operator's responsibility, but Knox provides the mechanisms to configure them:
WebAppSecProvider can be configured for XSRF, CORS, CSP, and related cross-site protections.These mechanisms must be tuned to the deployment's specific expectations (allowed hosts, ports, domains). A report that a protection is available but unconfigured is therefore OUT-OF-MODEL (operator responsibility); a report that a configured WebAppSecProvider / whitelist can be bypassed is VALID.
For a gateway, “downstream user” = the cluster operator/deployer. To keep §5–§8 valid, the operator must:
-persist-master as security-sensitive (documented).sandbox topology, and the self-signed cert; install a real IdP and a CA-issued identity keystore (documented as getting-started aids → Q5/Q13).HeaderPreAuth without a trust gate (mTLS/IP allow-list proving the header source) — an ungated deployment is the operator's risk to accept, not a Knox bug (maintainer, 2026-07-09 — L. McCay, Q14).WebAppSecProvider and the SSRF/open-redirect regexp whitelists (XSRF/CORS/CSP; allowed hosts/ports/domains) for the deployment — Knox provides these mechanisms but the operator must turn them on and tune them (maintainer, 2026-07-09 — L. McCay, Q27).HeaderPreAuth and trusting SM_USER/custom identity headers directly from clients. Looks like SSO integration; is actually anonymous impersonation. Fix: require mTLS/IP trust gate. Per Q14 this is the operator's risk to accept (OUT-OF-MODEL), with a standing hardening ask that Knox default the gate to force explicit acceptance (maintainer, 2026-07-09 — L. McCay).Populated with the shapes a scanner/AI is likely to raise against Knox; each is safe given the model and the PMC should confirm/extend (all inferred → Q28):
SM_USER header” flagged as auth bypass — not a finding when the topology pairs HeaderPreAuth with an mTLS/IP trust gate (§6 header row, §9 false friend). An ungated HeaderPreAuth is OUT-OF-MODEL: non-default-build (operator responsibility per Q14), not a Knox VALID bug — though a proposal to harden the default gate is welcome (maintainer, 2026-07-09 — L. McCay, Q14).OUT-OF-MODEL: trusted-input. VALID only if client bytes reach the destination selection.OUT-OF-MODEL: unsupported-component / non-default-build.-persist-master, .jceks)” — by design under the operator FS-trust boundary (§5) ⇒ BY-DESIGN / operator responsibility, not a network-reachable disclosure.OUT-OF-MODEL: unsupported-component.VALID if it defeats the §8(6) concealment property with real internal addresses; generic stack traces are VALID-HARDENING at most.HeaderPreAuth by default).| Disposition | Meaning | Licensed by |
|---|---|---|
VALID | Untrusted client bypasses authn/authz, forges an identity assertion or token, discloses a secret over the network, or crashes/hangs the gateway from unauthenticated input. | §8, §6, §7 |
VALID-HARDENING | No §8 property broken, but Knox elects to make a §11 misuse harder (e.g. safer default, extra warning, tighter header handling). Usually no CVE. | §11 |
OUT-OF-MODEL: trusted-input | Requires attacker control of topology/provider config, a dispatch target from config, or another §6-trusted parameter. | §6 |
OUT-OF-MODEL: adversary-not-in-scope | Requires operator, backend, IdP, local-FS, or around-the-gateway capability. | §7 |
OUT-OF-MODEL: unsupported-component | Lands in demo LDAP, sample topologies, gateway samples, or self-signed test cert. | §3 |
OUT-OF-MODEL: non-default-build | Only manifests under a discouraged §5a configuration the operator is documented to change. | §5a |
BY-DESIGN: property-disclaimed | Concerns a §9 disclaimed property (backend authz, WAF inspection, bearer-token replay within TTL, operator secret-at-rest). | §9 |
KNOWN-NON-FINDING | Matches a §11a recurring false positive. | §11a |
MODEL-GAP | Routes to none of the above. | triggers §12 |
Each states a proposed answer to confirm/correct, and the section it lands in. Grouped in waves. Larry McCay (PMC chair) answered Wave 1–3 core + meta on 2026-07-09; those answers are recorded here and folded into the sections above.
Wave 1 — scope, deployment, adversary (unblocks everything) — ANSWERED 2026-07-09:
sandbox/sample topologies, and gateway samples are dev/eval only; findings requiring them are out of model.doAs.Wave 2 — the keystone properties & false friends — ANSWERED 2026-07-09:
HeaderPreAuth is a misconfiguration the operator must avoid or implicitly accepts; a report is OUT-OF-MODEL: non-default-build, not a Knox VALID bug. Paired hardening ask: Knox should default the trust gate so operators must explicitly accept the ungated risk (VALID-HARDENING). (This corrects the v0 proposal of “VALID whenever ungated”.)Wave 3 — inputs, resources, isolation, false-positive suppression:
WebAppSecProvider (configurable for XSRF/CORS/CSP) and regexp-based whitelists (SSRF / open-redirect). They must be tuned to the deployment’s hosts/ports/domains.VALID only if it breaks §8(1/2).-persist-master stances, and secondary adversary-capability details as stated inline.Wave 4 — meta / ownership — ANSWERED 2026-07-09:
SECURITY.md and the project site.docs/ in-repo, versioned with releases; a §12 change class triggers a revision.Not produced in v0. Once §14 wave 1–2 answers land, emit a threat-model.yaml sidecar (entry surfaces → trust level from §6; component families in/out from §2/§3; §5a config knobs; §8 properties with severity+symptom; §9 disclaimed + false friends; §11a non-findings; §13 dispositions) for automated/Glasswing triage.
Not applicable. Knox publishes no project-specific SECURITY.md (repo 404) and no dedicated security page; security.apache.org/projects/ lists Knox only with the generic Apache Security Team contact. There is therefore no prior maintainer-authored security-policy artifact to back-map or superset. If the PMC adopts this model (Q-meta-A), this section becomes the seed for a new SECURITY.md.