Skip to content

docs(security): point endpoint + credential docs at the real controls (#299, #251) - #333

Merged
thc1006 merged 1 commit into
mainfrom
docs/remotecontrol-security-doc-accuracy
Jul 31, 2026
Merged

docs(security): point endpoint + credential docs at the real controls (#299, #251)#333
thc1006 merged 1 commit into
mainfrom
docs/remotecontrol-security-doc-accuracy

Conversation

@thc1006

@thc1006 thc1006 commented Jul 31, 2026

Copy link
Copy Markdown
Owner

What

Two documentation-accuracy fixes surfaced while verifying the acceptance criteria of #299 and #251. No behavior change — comment + field-godoc only (plus the CRD regeneration the godoc triggers).

#299 (任意 endpoint SSRF) — acceptance #4

The remoteControl.endpoint field godoc documented only the shape validation (host:port, DNS-1123, CEL) and never pointed at the control that actually bounds which host the operator will dial. Added a note that confining the destination is an admin egress concern, naming the two enforced controls:

  • --remote-control-allowed-endpoint-hosts app-layer allow-list (empty = any, backward compatible)
  • the egress NetworkPolicy at config/network-policy/allow-egress-traffic.yaml

The godoc flows into all four CRD copies via controller-gen (config/crd/bases, bundle/manifests, dist/chart/templates/crd, nephio/packages).

This closes the last open acceptance item for #299 (the allow-list, plaintext-relay gate, and egress policy already shipped in #300/#317/#324). #299 is closeable after this merges.

#251 (remoteControl.tls confused deputy)

The resolveRemoteControlTLS SECURITY comment called itself "a partial mitigation, not an authorization boundary" and pointed only at a hypothetical future SubjectAccessReview. That is now stale and understates what shipped: the opt-in credentialRefPolicy ValidatingAdmissionPolicy (ADR-0009) IS the enforced boundary — it makes the apiserver require the CR's writer to hold get on the referenced Secret (authorizer…namespace(request.namespace).name(…secretName).check('get')).

Rewrote the comment to name that policy as the real boundary, while staying honest that it is opt-in and enable: false by default, so the two in-resolver gates (reject API-credential Secret types; require an owner opt-in label) remain a partial mitigation out of the box.

#251 stays OPEN — remaining work: an automated envtest exercising a restricted (secrets-get-less) user against the live policy, and the decision on whether to flip the default posture. This PR only corrects the misleading comment.

Verification

  • go build ./... + go vet ./api/... ./internal/controller/... clean
  • make manifests bundle nephio-sync — all four CRD copies regenerated consistently (+6 lines each)
  • Every factual claim in the new docs checked against the actual code: flag name + empty=permit-all (pkg/netutil/allowlist.go:50), NetworkPolicy path exists, and the VAP CEL scopes get to the referenced Secret (dist/chart/templates/admission/credential-ref-policy.yaml:37-40)

Two documentation-accuracy fixes surfaced while verifying the #299/#251
acceptance criteria; no behavior change.

#299 (endpoint SSRF), acceptance #4 — the remoteControl.endpoint field
godoc described only shape validation and never pointed at the control
that actually bounds where the operator will dial. Add a note that
confining the destination is an admin egress concern: the
--remote-control-allowed-endpoint-hosts allow-list (empty = any,
backward compatible) plus the egress NetworkPolicy. Flows into all four
CRD copies via controller-gen.

#251 (remoteControl.tls confused deputy) — the resolveRemoteControlTLS
comment claimed to be "a partial mitigation, not an authorization
boundary" and pointed only at a hypothetical future SubjectAccessReview.
That is now stale and understates what shipped: the credentialRefPolicy
ValidatingAdmissionPolicy (ADR-0009) IS the enforced boundary, requiring
the CR's writer to hold `get` on the referenced Secret. Rewrite the
comment to name it, while staying honest that the policy is opt-in and
OFF by default, so the two in-resolver gates remain a partial mitigation
out of the box. #251 stays open (automated restricted-user envtest and
the default-posture decision are still outstanding).
@thc1006
thc1006 merged commit 419caa9 into main Jul 31, 2026
6 checks passed
@thc1006
thc1006 deleted the docs/remotecontrol-security-doc-accuracy branch July 31, 2026 07:08
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.

1 participant