Add draft project security threat-model document

[potiuk]

Summary

This PR adds an initial draft of a project-level security
threat-model document (draft-THREAT-MODEL.md) so that automated
security scanners running against this repository have a
maintainer-facing reference for which classes of findings are
in-scope vs. out-of-scope for the project.

The document follows the rubric format used by several other ASF
projects piloting improved security-model discoverability for
agentic scanners. Every claim carries a provenance tag:

• (documented) — paraphrased from public artefacts (this repo or
  the project website), cited inline.
• (inferred) — synthesised from code structure or domain
  knowledge; the PMC has not confirmed.
• (maintainer) — confirmed by a CloudStack PMC member in response
  to this draft. (Zero in this initial draft.)

Draft stats:

• ~88 documented claims
• ~64 inferred claims (each maps to a §14 question)
• 38 open questions for maintainers in §14

§14 is the highest-leverage section: answering each question
either promotes one (inferred) tag to (maintainer) or corrects
the underlying claim.

Why "draft-" prefix?

The file is named draft-THREAT-MODEL.md rather than
SECURITY-THREAT-MODEL.md because this is a proposal for the
PMC to review — please correct, reject, or discuss as needed.
Once the PMC ratifies (or substantially edits) the content, the
file can be renamed in a follow-up PR and a discoverability
scaffold (AGENTS.md → SECURITY.md → the model) added so
scanners can mechanically follow the chain.

What this is, and what it is not

This is not a security audit. It is a working triage document
— the reference a triager holds against an inbound report to
decide whether the report is about a CloudStack vulnerability or
about caller misuse / operator misconfiguration / an out-of-scope
concern.

The draft was generated by an automated agentic security scan
being piloted by the ASF Security team; the discoverability work
is independent of any specific scan run.

How to review

1. §14 first. Each answer either confirms one (inferred) tag or
   replaces the inferred claim with the correct one.
2. After that, please skim §3 (out-of-scope) and §13 (triage
   dispositions) — those govern how a vulnerability report would
   be triaged.

Reply edits / corrections inline on the PR, or to the original
security@apache.org thread, whichever fits the PMC's workflow.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 18.76%. Comparing base (7308dad) to head (dcc71cd).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #13293      +/-   ##
============================================
+ Coverage     18.10%   18.76%   +0.65%     
- Complexity    16752    17974    +1222     
============================================
  Files          6037     6160     +123     
  Lines        542796   552571    +9775     
  Branches      66456    67346     +890     
============================================
+ Hits          98291   103705    +5414     
- Misses       433460   437459    +3999     
- Partials      11045    11407     +362     

Flag	Coverage Δ
uitests	3.53% <ø> (+0.01%)	⬆️
unittests	19.96% <ø> (+0.68%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[yadvr]

There's a lot of details in the draft that needs a better set of eyes, so assigning @DaanHoogland @vishesh92 who're also PMC leads on the work.

[potiuk]

Thanks @DaanHoogland @yadvr @vishesh92 — agreed, let's make this (apache/cloudstack) the canonical project-level threat model and have the client/tooling repos inherit from it rather than each carrying a full copy.

Concretely, mirroring what we've done for other multi-repo PMCs:

• apache/cloudstack/THREAT_MODEL.md is the single source of truth for the project-wide model: scope, trust boundaries, the management-server adversary model, in/out-of-scope classes, known non-findings, and triage dispositions.
• The satellite repos (cloudstack-go, -cloudmonkey, -terraform-provider, -kubernetes-provider) get a short discoverability pointer — AGENTS.md → SECURITY.md → this model — plus, only where it adds something, a thin repo-specific addendum (e.g. the Go SDK's own input-trust surface) that references the parent instead of duplicating it.

So let's converge here first. None of the satellite PRs are merged, so re-pointing them to reference this model once its shape is settled is cheap — I'll repurpose those into pointer PRs (or close + reopen) once you're happy with the parent.

On "the fields we need": that's exactly the §14 "Open questions" section — each is a proposed answer for you to confirm, correct, or strike, grouped into waves so you can take a few at a time. Drop answers inline or here and I'll fold them in and promote the provenance tags. Happy to adjust the section set if CloudStack's shape calls for it.

[potiuk]

Thanks @DaanHoogland and @vishesh92 — pushed a revision folding the review in:

• Global-setting names corrected to the real ones (enforce.post.requests.and.timestamps, proxy.header.verify / proxy.header.names / proxy.cidr, ca.framework.cert.management.custom.san, user.password.encoders.order + .exclude with their defaults) and struck the non-existent ones I'd guessed (api.signature.version, auth.password.algorithm, hash.user.password, post.requests.and.timestamps.enforced, the forward-header variants).
• ca.plugin.root.auth.strictness: documented as default-true on new setups, false only on pre-Aug-2017 upgrades (PR CLOUDSTACK-9993: Securing Agents Communications #2239).
• Mgmt server modeled as single-instance or clustered; cloudstack-agent per hypervisor host (dropped the wrong Hyper-V-as-agent label); system VMs at the agent trust tier.
• Download links documented as unauthenticated UUID symlinks via Apache httpd, removed after a period (timed availability = the mitigation) — BY-DESIGN.
• noVNC noted as a vendored fork of novnc/novnc with CloudStack changes.

Two things I captured in-model as PMC follow-ups rather than acting on: the download-token timed-removal behavior ("make sure/test this"), and the absence of a vendored-dependency update procedure. The remaining §14 questions are the open ones for the PMC to walk. WDYT?

[potiuk]

Thanks @DaanHoogland and @vishesh92 — all 17 threads are folded in; resolving them now. What changed / was confirmed:

• Config-setting names corrected (vishesh92): proxy.header.verify / proxy.header.names / proxy.cidr, enforce.post.requests.and.timestamps, user.password.encoders.order (+.exclude), ca.framework.cert.management.custom.san, and ca.plugin.root.auth.strictness (default true for new setups; false only on pre-Aug-2017 upgrade). Dropped api.signature.version (not in code).
• Secondary-storage download links (§6/§11a): UUID-named symlinks, no auth on the link, removed after a window → BY-DESIGN (timed-availability mitigation); a non-removed or guessable link is VALID-HARDENING. Noted your "re-test in code" point + Daan's "why didn't static analysis catch this" as a scan-agent note.
• noVNC (§3/§11a): vendored fork, bugs go upstream; recorded there's no automated dependency-update procedure today and the PMC would like one.
• Deployment shape: single management-server or clustered — both supported (your wording).
• §14 Q1–Q7 + Q12 now resolved/struck per your confirmations.

Two items are PMC follow-ups, not model changes: (a) re-test/confirm the download-link TTL in code, (b) establish a dependency-update procedure for noVNC. The model is the PMC's to merge whenever — thanks for the thorough review.

[vishesh92]

This sound right.
IMO, the only scenario where it would be a cloudstack problem will be if cloudstack is setting wrong/bad settings while launching the guest VM or some other action which results in the corresponding issues with hypervisor. In this scenario, CloudStack needs to ensure it's using correct/secure settings for the hypervisor.
@DaanHoogland What do you think?

[vishesh92]

@DaanHoogland do you think we need to include simulator & tools/appliance?

[DaanHoogland]

I think we need to exclude them and make that explicit. Later we might want to create tooling with the express purpose of checking security but let’s leave oit out of scope for now.

[vishesh92]

IMO, this is a deployment choice. The correct global settings for this are:
enable.user.2fa - default is false. Determines whether two factor authentication is enabled or not. This can also be configured at domain level.
mandate.user.2fa - default is false. Determines whether to make the two factor authentication mandatory or not. This setting is applicable only when enable.user.2fa is true. This can also be configured at domain level.

[vishesh92]

The default should be 0 (disabled). But I need to confirm this.
@DaanHoogland any idea about this?

[DaanHoogland]

yes, it is set to 0 and only in test configurations it is set to 8096.

[potiuk]

Thanks @vishesh92 — this is exactly the input the §14 questions were after; folding all of it in. How each lands:

• Root admin (L959) — confirmed trusted operator with direct access anyway → stays out of the adversary model (§7); promoting (inferred) → (maintainer).
• userdata (L970) — confirmed: the end user customizing their own guest OS → tenant-controlled data inside their own boundary, not a CloudStack-side injection surface (§6/§9).
• Hypervisor settings (L965) — narrowing the in-model case to "CloudStack applies a wrong/insecure setting when launching/managing the guest" (a CloudStack responsibility); the hypervisor's own hardening stays out. Left flagged for @DaanHoogland.
• proxy.header.verify (L984) — corrected: default false; only when the remote address is in proxy.cidr does CloudStack read proxy.header.names. Fixing §5a/§6.
• 2FA (L989) — confirmed deployment choice: enable.user.2fa (default false) + mandate.user.2fa (default false), domain-configurable → "2FA not enforced" is operator config, not a flaw (§10/§11a), with those exact knob names.
• Password hashing (L1000) — the clincher for the §11a non-finding: default encode set excludes MD5,LDAP,PLAINTEXT (effective PBKDF2,SHA256SALT,SAML2), so md5/plaintext hashing of new passwords in a default install is out of model. I'll cite the exact default-vs-excluded set.

Two still on @DaanHoogland: L976 (whether simulator + tools/appliance are in scope — I'd lean out, dev/test paths) and L1007 (the default-0/disabled confirm).

I'll push the updated model with the confirmed items folded in. Thanks again — this is the review that makes it usable for triage.