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 20.40%. Comparing base (7308dad) to head (0a0e38a).
⚠️ Report is 66 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #13293      +/-   ##
============================================
+ Coverage     18.10%   20.40%   +2.29%     
- Complexity    16752    18789    +2037     
============================================
  Files          6037     5757     -280     
  Lines        542796   520921   -21875     
  Branches      66456    60823    -5633     
============================================
+ Hits          98291   106300    +8009     
+ Misses       433460   403044   -30416     
- Partials      11045    11577     +532     

Flag	Coverage Δ
uitests	?
unittests	20.40% <ø> (+1.13%)	⬆️

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 vishesh92 — folded your three follow-ups in (draft-THREAT-MODEL.md):

• Q15 (file ownership): recorded as root:cloud, mode 0640 (rw for owner, r for the cloud group) for the four sensitive artifacts. Resolved.
• Q24 (same-IP host): captured that re-adding a host with the same IP updates the existing record rather than creating a spoofed peer, and is gated by root-admin access + the keys/certs needed to reach the management server (with Don't allow adding of existing host to another zone, pod or cluster #13182 refining it) — so not an unauthenticated identity-spoof path. Resolved.
• Q29 (data-at-rest): marked confirmed by both of you (delegated to the storage layer / hypervisor).

That clears the items that were still pending a second confirmation. The one remaining open ask on your side is Q37 — whenever convenient, 3-5 recurring "not a vuln" patterns from your inbound security@ triage would make §11a (the scanner's suppression list) much stronger; no rush.

Unrelated to this PR: the red CI check is a component/integration test (test_mm_*_limits), not anything this docs-only change touches.

[shwstppr]

@vishesh92 can you please have a look if you've further feedback on this?

@weizhouapache can we include this in 4.23.0 milestone?

[potiuk]

Thanks @shwstppr. From the ASF Security side this one is through pre-flight:
the model has folded in all of @DaanHoogland's and @vishesh92's review, and
the discovery chain (AGENTS.md -> SECURITY.md -> THREAT_MODEL.md) resolves. The
only outstanding item is optional — a few recurring "not a vuln" patterns from
your security@ triage to strengthen the §11a suppression list (Q37), a
nice-to-have rather than a blocker.

One note for the milestone question: the red check is the test_mm_*_limits
component/integration test, which this docs-only PR doesn't touch — it's
unrelated to these changes, so it shouldn't gate the merge.

No changes requested on our end; happy to see it land in 4.23.0. Once it merges
we're ready on our side.

[DaanHoogland]

@vishesh92, cc @shwstppr. Ready for merge (and the new flow of sec issues?)

[potiuk]

Thanks DaanHoogland — nothing outstanding on our side, so this is ready to merge whenever you and vishesh92 are happy. All of your and Vishesh's review is folded in, the AGENTS.md → SECURITY.md → THREAT_MODEL.md chain resolves, and the one open item (Q37 — a few recurring "not a vuln" patterns from your security@ triage for the §11a suppression list) is an optional nice-to-have, not a blocker. The red check is the test_mm_*_limits integration test, unrelated to this docs-only PR.

On "the new flow of sec issues" — assuming you mean what happens once this lands: merging completes pre-flight, so CloudStack enters the scan queue at its criticality rank. When the scan runs, the findings come back to your three designated recipients (dahn@, rohit@, vishesh@) verbatim, for the PMC to triage against this very threat model — the §13 disposition table is what turns each finding into VALID / hardening / out-of-model. That's the "new flow." If you meant something else, let me know and I'll point you at the right place.

[shwstppr]

@DaanHoogland Tbh, at this point I'm not sure how this is to be reviewed or if it is ready for merge.
Maybe the contributors who volunteered to be maintainer should have a closer look. Just running Copilot review would not be enough in my opinion.

I see some issues around - API considered JSON only; in my reading I didn't see it establishes a difference between runtime configs - ConfigKey vs server.properties, hidden configs, etc. Some of the statements about CloudStack internals and worflows were not completely correct in my understanding.

PS: My nudge on the PR was purely to have the process moving.

[potiuk]

@shwstppr fair question — this one reviews differently from a code PR. A few notes to unstick it:

• It's docs-only: a single THREAT_MODEL.md plus the AGENTS.md → SECURITY.md wiring. No code path to review, and the red CI is CloudStack's normal code/integration checks, which don't apply to a docs change — safe to ignore here.
• It's a v0 draft to react to, not a finished document. Every inferred claim is tagged and collected into open questions at the end (§14) — so "reviewing" it is really answering those (confirm / correct / strike) and fixing anything factually wrong for CloudStack. Vishesh already did a solid pass on the global-setting names; that's exactly the shape of review that helps.
• Copilot / automated review won't say anything useful about a prose threat model — agreed.
• Merging is the ratification: once it's in, the model is the CloudStack PMC's document, owned and refined in place. It doesn't have to be perfect at merge — just correct enough that the PMC is comfortable it represents the project.

Happy to jump on any specific §14 question if that helps reviewers move.

— Jarek

[DaanHoogland]

@shwstppr , at only @vishesh92 , me and now you have reviewed. I would be very happy if we have more involvement, but on the other hand nothing here cannot be adjusted later.

[vishesh92]

It looks good to me. The only thing left is Q37 which is to add more patterns based on the existing security issues to use here.

[shwstppr]

Looks good for start. We can refine this as we proceed.
Some suggestions from @DaanHoogland can be applied if no objections.

[Copilot]

Pull request overview

Adds a project-level draft security threat-model document intended to help maintainers and automated security scanners quickly triage findings as in-scope vs out-of-scope for apache/cloudstack.

Changes:

• Introduces draft-THREAT-MODEL.md describing scope, trust boundaries, adversary model, claimed/non-claimed properties, and triage dispositions.
• Captures configuration-sensitive security posture details (e.g., Root CA strictness, proxy header verification, integration port exposure).
• Includes a maintainer Q&A / resolution section intended to ratify or correct inferred claims.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[DaanHoogland]

I don’t see how this is still valid, we can add maintainers but in my view the statsu already was “reviewed”/“approved”, and not “draft". guess it slipped through the cracks.

[DaanHoogland]

@potiuk , can you advice?

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.

[vishesh92]

lgtm. There might be some issues but let's get it merged and we can revisit once we have some output.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 6 comments.