Add a draft security threat model (THREAT_MODEL.md) + SECURITY.md + discoverability wiring - #1224
Open
potiuk wants to merge 2 commits into
Open
Add a draft security threat model (THREAT_MODEL.md) + SECURITY.md + discoverability wiring#1224potiuk wants to merge 2 commits into
potiuk wants to merge 2 commits into
Conversation
…iscoverability wiring Generated-by: Claude Code
necouchman
reviewed
Jul 24, 2026
necouchman
left a comment
necouchman
left a comment
Contributor
There was a problem hiding this comment.
Okay, several comments from me - apologies in advance if any of these are nonsensical.
necouchman
reviewed
Jul 24, 2026
necouchman
left a comment
necouchman
left a comment
Contributor
There was a problem hiding this comment.
Okay, several comments from me - apologies in advance if any of these are nonsensical.
necouchman reviewed the draft on 2026-07-24 (26 inline comments), with one note from corentin-soriano. Nine were confirmations; the rest corrected or extended the draft, so the body is rewritten where it was wrong and re-tagged (inferred) -> (maintainer) where it was confirmed. The §4 data-flow diagram was materially wrong. As drawn it implied the remote server speaks the Guacamole protocol directly to the browser. It does not: every byte in both directions passes through the web app, which terminates the browser tunnel, holds the TCP connection to guacd, and relays between them. Redrawn, with the return path spelled out and the REST API's role noted. Other corrections: - guacd persists nothing outside memory. Boundary 4 attributed credential storage to "guacd/web app"; all authentication, authorization, connection documentation, credential storage and lookup are the web application's, which then hands parameters to guacd for the life of the connection. - guacd imposes no restriction on which valid connection parameters a caller may use. Reaching guacd therefore grants any capability the remote protocol supports - file transfer, clipboard, printing, drive redirection - not merely session access. Restricting those is the web app's job (§9). - Exposure is about any untrusted network, not "the Internet". Any user or system that should not have proxy access to the remote systems counts. - The trust-boundary precondition was incomplete. It covered unauthenticated and authenticated-but-unprivileged input, but not an authenticated *and authorized* user exceeding what that authorization meant to permit - e.g. transferring files when file transfer was configured off. Connection parameters are themselves a security guard (§4, §8.2). - libguac, guacamole-common and guacamole-common-js are consumed as libraries by third parties, and guacd is supported as a generic Guacamole-protocol proxy for custom front-ends. §2 said "not an in-process library" without qualification; it now covers that second audience. - The Guacamole protocol is text-based but also carries binary payloads such as images and audio. - Kubernetes was missing from the per-plugin ingress table (§6). - TLS termination: stated directly that failure to terminate TLS is the operator's responsibility and such a report is DOWNSTREAM, not a vulnerability. - §5a renamed from "Build-time" to "Deployment" - every knob in it is a deployment concern, not a compile-time one. - Version mismatch between web app and guacd IS supported, with feature negotiation; the correction is that no safety guarantee comes with it. Rulings recorded as the PMC's: - I14: cleartext webapp<->guacd on a trusted segment is OUT-OF-MODEL. It is the deliberate default and most deployments co-locate guacd with the web app. The two "pending the I14 ruling" placeholders are resolved. - I18: there is no mutual authentication native to the web app <-> guacd link; it can be built with SSH/SSL tunnelling, which is out of model. - I17: no resource guarantees; monitoring and throttling are the operator's. Still open: the document-ownership/venue question, which necouchman is happy with but defers to @mike-jumper, and with it the §15 sidecar. Generated-by: Claude Opus 5 (1M context)
Member
Author
|
@necouchman thanks — this was a genuinely useful review, and several of your points corrected the draft rather than just confirming it. All folded in as of The §4 diagram was wrong and you were right to call it out. As drawn it implied the remote server speaks the Guacamole protocol straight to the browser. Redrawn so every byte in both directions passes through the web app, with the return path ( Other corrections:
Rulings recorded as the PMC's: I14 cleartext Left open: the document-ownership/venue question, since you're content with the proposal but defer to @mike-jumper — and the §15 sidecar with it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is a proposal for the Guacamole PMC to review — please correct, reject, or discuss as needed. The PMC owns the document; nothing here is a requirement.
This adds a draft umbrella
THREAT_MODEL.mdfor the Apache Guacamole family, aSECURITY.md(the code repos don't currently carry one — the security policy lives only at guacamole.apache.org/security), and anAGENTS.mdwiringAGENTS.md -> SECURITY.md -> THREAT_MODEL.mdso an automated scanner can mechanically discover it. Path 3 as agreed on the list (we draft the v0, the PMC reviews). It lands on apache/guacamole-client as the canonical home; guacamole-server and guacamole-website get small pointer PRs to it once you're happy with the shape.Generated from Guacamole's public artefacts (the security page, docs, advisory history) via the
threat-model-producerrubric. Provenance-tagged throughout; every (inferred) claim routes to a numbered §14 question (15 of them).The model's spine is the guacd(C) / client(Java) / website(static) split:
Two calls we'd especially value your confirmation on (both in §14 wave 1): (1) guacd is not an auth boundary and must be kept off untrusted networks — a report against an exposed
:4822is a misconfiguration, not an in-model bug; (2) the plaintext/unauthenticated webapp↔guacd default (guacd-ssloff on a trusted segment) as the supported production posture.What's most useful: walk the §14 questions and confirm / correct / strike each — a one-liner each is enough. This PR only adds files; it edits no existing content.
Context: the ASF Security team is preparing projects for an automated agentic security scan we're piloting; discoverability is the one hard prerequisite.