Skip to content

Add threat model + security-model discoverability (AGENTS.md → SECURITY.md → THREAT_MODEL.md)#3148

Open
potiuk wants to merge 2 commits into
apache:masterfrom
potiuk:asf-security/threat-model-2026-06-02
Open

Add threat model + security-model discoverability (AGENTS.md → SECURITY.md → THREAT_MODEL.md)#3148
potiuk wants to merge 2 commits into
apache:masterfrom
potiuk:asf-security/threat-model-2026-06-02

Conversation

@potiuk

@potiuk potiuk commented Jun 1, 2026

Copy link
Copy Markdown
Member

Add a threat model + security-model discoverability for Apache Helix

This PR adds an initial threat model for apache/helix and wires up the
standard discoverability chain so automated security tooling can mechanically
find it:

  • THREAT_MODEL.md — a v1 draft threat model authored by the ASF Security
    Team for the Helix PMC to review.
  • SECURITY.md — points reporters at the threat model + the ASF security
    reporting process.
  • AGENTS.md — a Security section linking SECURITY.md → THREAT_MODEL.md
    so an automated reviewer can follow the chain.

Please read this as a proposal to react to, not a finished document

Following up on the mailing-list thread (thanks @junkaixue for the go-ahead to
draft one): this is a first draft built from public artefacts only — the
README and the repository structure. Almost every security claim is tagged
*(inferred)* and has a matching open question in §14. The PMC is the
decision-maker; please correct, reject, or refine any of it.

The highest-value things to confirm or correct (all in §14):

  1. helix-rest auth posture (Q5) — the crux. What is the default auth on
    the admin REST API? Can a default deployment accept unauthenticated
    cluster-mutating requests, or is auth required / is it bound to an internal
    interface? Any built-in authz on who can administer which clusters?
  2. ZooKeeper trust (Q6) — is "secure the ensemble (ACLs / auth / network
    isolation)" an operator responsibility, and does Helix set ACLs on the
    znodes it creates? The metadata store is the real control plane.
  3. Trust framing (Q1, Q2) — that Helix coordinates operator-owned
    resources (not a security boundary for them), and the operator + in-domain
    components (Controller / Participant / Spectator) are trusted.
  4. gateway / agent surfaces (Q8) and recurring non-findings (Q18a).

The point of the model is to let a triager (or an automated scan) classify an
inbound finding as valid / out-of-model / disclaimed-by-design and cite a
section — and to cut false-positive noise (the §11a known-non-findings list
especially).

This is part of an automated agentic security-scan pilot the ASF Security team
is running; a discoverable threat model lets the scan focus on real issues and
suppress the by-design ones.

…TY.md → THREAT_MODEL.md)

Generated-by: Claude Code
Comment thread THREAT_MODEL.md Outdated
@potiuk

potiuk commented Jun 4, 2026

Copy link
Copy Markdown
Member Author

Thanks @junkaixue — pushed a revision folding your answers in as maintainer-confirmed: helix-rest is a skeleton with operator-implemented auth (default = no auth); ZooKeeper is a separate service (not Helix's responsibility) and Helix sets no ACLs on the ZNodes it creates, with ZK access going through the ZK client's own authz; gateway/agent are pluggable (user supplies the impl); controllers run independent of user data; and Helix-UI findings are out of model (deprecated). Two narrower items left as §14 questions we never asked: the TLS default for the helix-rest listener / ZK client connection (transport, not authz), and whether helix-lock adds any surface beyond the ZK control plane. WDYT?

@potiuk

potiuk commented Jun 5, 2026

Copy link
Copy Markdown
Member Author

Thanks @junkaixue — your confirmations are folded in as (maintainer): helix-core roles run independent of user data (Q1/Q2); helix-rest ships as a skeleton, operator implements auth, default no-auth — the primary network trust boundary (Q5); ZK-gated znode access (Q6/Q7); gateway/agent pluggable (Q8). Resolving — the model is the PMC's to merge whenever. Thanks for the review.

@junkaixue

junkaixue commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Thank you for the help! Looks good to me!

@potiuk

Comment thread THREAT_MODEL.md
confirmed by the Helix PMC (Junkai Xue, 2026-06-04) and folded above as
*(maintainer)*. The remaining open items are narrower:

1. **(Q7a)** TLS posture: is TLS available/default for the helix-rest listen

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By default is not enabled for transport-encryption. Since this product was infra product assuming staying with in firewall. No remote call should be peforming.

Comment thread THREAT_MODEL.md
interface, and for the ZooKeeper client connection? (The PMC confirmed ZK
access goes through the ZK client's own authz, but the transport-encryption
default for each channel is not yet stated.) *(inferred)*
2. **(Q-lock)** Confirm `helix-lock` (ZK-backed distributed locks) carries no

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants