Add THREAT_MODEL.md + AGENTS.md/SECURITY.md discoverability chain (draft for PMC review)

[potiuk]

This is a proposal for the Apache Ranger PMC to review — please correct, reject, or discuss as needed. The maintainers are the decision-makers; nothing here is a requirement.

This PR proposes a draft v0 threat model for Apache Ranger, plus the conventional AGENTS.md → SECURITY.md → THREAT_MODEL.md discoverability chain (Ranger currently has no SECURITY.md). Context: the ASF Security team is preparing the project for an automated agentic security scan we're piloting; such scans need the model to be mechanically discoverable, and run far less noisily when a model exists. The Security team reached out separately on the PMC's private list with the program details.

The model is written from Ranger's own public artefacts (README, ranger.apache.org, the FAQ, the public REST API docs, the repo layout) and focuses on the high-value boundaries: the policy decision/distribution path (Admin authors → plugins pull + cache), the Admin REST API, the trust placed in the per-service plugins (PEPs), and Ranger KMS.

Every claim carries a provenance tag:

• (documented) — grounded in a Ranger doc/repo fact; cited inline. (18 claims)
• (inferred) — the Security team's reasoning, not yet confirmed. (47 claims)

Because this is v0 with no maintainer input yet, it's mostly (inferred). Every (inferred) claim has a matching question in §14 "Open questions" (20 questions in 4 waves). The fastest path: walk §14 and reply confirm / correct / strike per line — react, don't compose. We fold your answers in and the (inferred) tags become (maintainer).

A few decisions reshape the whole model — Wave 1 especially: the no-match default (deny vs. fall-through to native ACLs), the transport-security default, and the default admin credential. Those three most determine which reports are real findings vs. by-design.

If the PMC would rather author the model yourselves, close this PR and we'll wait — this is a starting point, not an imposition.

[kumaab]

Thank you @potiuk for preparing this, it's a good starting point for the PMC to own and refine. Please find below answers to the open questions in §14.

Wave 1 — Scope, defaults, and the decisions that reshape everything

1. No-match default: When no Ranger policy matches a request, does the plugin deny, or fall through to the host service's native ACLs? We assume it depends on per-service config; what is the shipped default? (→ §5a, §8 # 2, §11a)
   Answer: When Ranger is enabled as the ACL enforcer, the result is "deny" except for HDFS service where the result falls through to the native ACLs.

2. Transport security default: Is TLS on plugin↔Admin and UI↔Admin required for a supported production deployment, or is plaintext a supported posture? (→ §5a, §9, §13 non-default-build vs VALID)
   Answer: TLS is recommended in production, plaintext HTTP is shipped/supported default.

3. Default admin credential: Does Ranger ship a default admin account/password, and is rotating it a documented operator requirement before exposure? (→ §5a, §10, §11a)
   Answer: Ranger ships seeded accounts (admin, rangerusersync, rangertagsync, keyadmin) as install bootstrap values, but the standard installer requires an explicit, complexity-checked password on fresh install and passwords can be changed any time via the UI/REST. So the seeded password is not a supported production posture.

4. Scope confirmation: Are ranger-examples/ and the install/migration tooling correctly out of model? Any other shipped-but-unsupported code we missed? (→ §2, §3)
   Answer: These are out of model: migration-util & ugsync (filesourceusersynctool,ldapconfigchecktool) modules whereas ranger-examples and ranger-tools are within scope.

5. Caller roles: Is the five-role breakdown in §2 (admin / delegated admin / plugin / end user / identity source) correct and complete? (→ §2, §7)
   Answer: There are additional roles:
   Auditor role: for viewing policies and accessing audits.
   Key Admin role: for KMS service only.
   The (→ §2, §7) section is correct.

Wave 2 — Trust boundaries and authentication
6. Plugin↔Admin auth mechanism: How does a plugin authenticate to Admin to download policy, and how does it verify the policy's origin (Kerberos/SPNEGO? service credentials? signed policy)? (→ §4, §6)
Answer: All plugins and the PDP Service (separate process, not a plugin) support multiple authentication mechanisms (Kerberos, JWT and header-based authentication with trusted proxy) to download policies from Ranger Admin.

7. End-user identity trust: Do we correctly model Ranger as trusting the principal identity asserted by the host service (Kerberos), and not performing user authentication itself? (→ §3, §9)
   Answer: Users logging in to Ranger Admin (to author/manage policies, manage users/roles, view audits) are authenticated by Ranger via one of its supported mechanisms — LDAP, Active Directory, Unix, PAM, Kerberos/SPNEGO, Knox SSO (trusted proxy), header-based, JWT, or the internal DB store.
   At data access time, authentication with Ranger is not required — the end user is authenticated by the host data service (e.g., Kerberos in the cluster), and the embedded plugin (PEP) hands Ranger an already-authenticated principal. Ranger does not authenticate the end-user at access time.

8. Byzantine plugin: Once authenticated, is a plugin fully trusted, with no cross-node integrity claim if its host is compromised? (→ §7)
   Answer: Complete trust of the Ranger plugin is a novel aspect of Ranger's design. It is what keeps the runtime overhead low. Ranger makes no cross-node integrity claim.

9. Fail mode on total evaluation failure: If a plugin can neither evaluate fresh nor cached policy, does it deny, or defer to the host service? (→ §5, §8 # 2)
   Answer: Plugin does "deny" if it can neither evaluate fresh nor cached policy, exception is HDFS plugin where result can fall through to native ACL.

10. REST endpoint auth matrix: Which /service/... and /public/v2/api/... endpoints are reachable unauthenticated vs. require admin vs. require a plugin identity? (→ §6, §8 # 3)
    Answer: Ranger Admin endpoints fall into three buckets.
    (1) Truly public: login page/static assets, /service/actuator/health, and /service/metrics/** — no identity required.
    (2) Plugin/PEP identity: the policy/tag/role/user/GDS download endpoints and the grant/revoke endpoints (security="none" at Spring, but authenticated at the app layer by service client-cert or, in Kerberos, SPNEGO — with the secure/...download variants requiring an authenticated user in the service's policy.download.auth.users list).
    (3) Authenticated admin/user: everything else (policy/service/user/role/zone/audit CRUD, plugin info, KMS keys) requires an authenticated session plus @PreAuthorize RBAC, with writes blocked for read-only Auditor roles.

Wave 3 — Properties, resources, and KMS
11. Authorization-bypass severity: Confirm a policy-evaluation/matching bug that grants denied access is CVE-class VALID. (→ §8 # 1, §13)
Answer: If no policy exists or a specific policy exists to deny and a grant has been done then it's a CVE-class VALID finding.

12. Resource bound / DoS line: Is super-linear policy-evaluation cost (in policy count or resource-string length) a bug? Is a hang inside the host service a security issue? Or is no resource guarantee made? (→ §8 # 6)
    Answer: (→ §8 # 6) is correct: "Policy evaluation is bounded and thread-safe."
    "Is super-linear evaluation cost in policy size or resource-string length a bug?" - No, it's not a bug.
    "Is a hang inside the host service a security issue" - Yes, could be.
    "Is no resource guarantee made?" - needs further discussion, this can be ratified later maybe.

13. KMS authorization: Confirm Ranger KMS releases key material only per key-access policy, and that unauthorized key retrieval is VALID/CVE-class. (→ §8 # 5)
    Answer: Key is the resource in a KMS policy. Unauthorized key retrieval is CVE class VALID.

14. Audit integrity: Is a forgeable/suppressible audit record (by a non-admin) a security finding, or is audit best-effort? (→ §8 # 4, §9)
    Answer: Yes, it's a security finding if a non-admin user is able to tamper audit records.

15. Stale-policy window as disclaimed: Confirm that the revocation-propagation delay (pull interval + cache) is by-design, not a bug. (→ §9 false friends, §11a)
    Answer: Yes, revocation propagation delay is by design.

Wave 4 — Misuse, non-findings, and ownership
16. Tagsync/usersync trust: Confirm policy is only as trustworthy as the tag/identity source, and injection upstream of Ranger is out of the model (trusted-input). (→ §6, §9, §11)
Answer: True

17. Resource canonicalization: Is mismatch between host-service resource naming and policy-engine matching (path normalization, case, wildcards) a known bypass class you actively defend, or a shared responsibility with the host service? (→ §9, §11)
    Answer: Resource names should map correctly in the Ranger policies with respect to resources in the service, so that's a shared responsibility.

18. Known non-findings: What do scanners/researchers most often report against Ranger that you consider a non-finding, and why? (→ §11a — needs maintainer history)
    Answer: The list of known non-findings (§11a) look good - this is a good starting point and can evolve with time, one correction - admin password is mandated at installation - insecure default password is not supported posture.

19. Side channels / co-tenancy: Confirm timing/side-channel adversaries against the policy engine and KMS are out of scope. (→ §7)
    Answer: It is out of scope.

20. Document ownership & coexistence: Since Ranger has no SECURITY.md, should this become the canonical security model linked from the project site, and who on the PMC owns its revision? (→ §1; meta)
    Answer: Yes, this model can become the canonical security model. I'm willing to volunteer.

[potiuk]

Thanks @kumaab — these answers are exactly what turns a v0 draft into a real model. I've folded all 20 into the model and pushed an update to this PR:

• Promoted the confirmed claims to (maintainer, 2026-06-12) and rewrote §14 as the resolved record.
• Applied the substantive corrections: no-match default = deny (except HDFS native-ACL fallthrough); ranger-examples + ranger-tools are now IN scope; plaintext HTTP recorded as the supported default; the seeded-but-mandated admin password (so a "default password" finding is not waved off); added the Auditor and Key Admin roles; and the Byzantine-plugin full-trust, KMS, audit-integrity, stale-policy, and side-channel dispositions.
• Left the one item you deferred (whether no resource guarantee is made, §8 Ranger 0.5 #6) flagged as still-open.

Please give it a final read — if it looks right, this is ready for the PMC to merge and own. Thanks again for volunteering to steward it.

[kumaab]

Thank you @potiuk, I've added few updates. LGTM.