Documentation
¶
Overview ¶
Package hostpolicy decides which hosted VCS instances a controller is allowed to send credentials to.
Pipelines-as-Code derives the API host it talks to from data that originates, directly or indirectly, from a webhook payload. Without a check, whoever can reach the controller endpoint could make it send its Git provider credentials to a host they control. This package is the single gate that prevents it.
The policy lives in the controller ConfigMap and works in two states:
- Administrator configured: the list is authoritative for every host, public ones included. The controller never writes to the ConfigMap, and an administrator can express "this controller must never talk to a public SaaS instance". Administrators own the settings.TrustedProviderHostnamesKey value exclusively.
- Controller managed: the controller has no configured policy. The public SaaS hostnames stay trusted, any other host is refused, and each request the provider itself authenticated appends its host to the keys.AutoTrustedProviderHostnames annotation (trust on first use), so that a default install needs no configuration and a controller serving several instances learns all of them.
A non-empty administrator allowlist selects administrator configured mode. An empty allowlist selects controller managed mode. Keeping the two lists under separate keys gives each value a single owner and avoids inferring ownership by comparing their contents.
Trust on first use appends rather than replaces, so a controller serving several instances, or several providers, learns all of them instead of being pinned to whichever one happened to send the first webhook.
The policy only covers hosts the controller did not choose. A caller that picked the host itself, from its own configuration rather than from a payload or a Repository CR, installs its client through github.Provider.UsePreauthenticatedClient and never reaches this package: the end to end harness is the one caller that does.
Index ¶
- func ControllerConfigMap(run *params.Run) string
- func InvalidAllowlistError(namespace, configMapName string, err error) error
- func NotTrustedError(namespace, configMapName, host string, reason int) error
- func TrustOnFirstUse(ctx context.Context, run *params.Run, rawHost string) (string, error)
- func Trusted(ctx context.Context, run *params.Run, rawHost string) (string, error)
- func TrustedURL(ctx context.Context, run *params.Run, rawURL string) (string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ControllerConfigMap ¶
ControllerConfigMap returns the ConfigMap holding this controller policy. Each controller has its own, so a second controller can never widen the policy of the first one.
func InvalidAllowlistError ¶
InvalidAllowlistError is returned when the configured allowlist cannot be parsed.
func NotTrustedError ¶
NotTrustedError explains, with a ready to run command, how to trust a host.
func TrustOnFirstUse ¶
TrustOnFirstUse validates rawHost against the policy and, while the policy is controller managed, appends rawHost to the controller-owned annotation.
Only call it once the provider itself has authenticated the request with a credential the controller owns, for instance after verifying a webhook signature against the GitHub App webhook secret: rawHost joins the policy from that point on. Anything else must use Trusted.
func Trusted ¶
Trusted validates rawHost against the allowlist and returns its normalised hostname.
It never writes, so it is the function to use on every path that the provider has not authenticated, and on every path authenticated by a secret a tenant controls, such as a per Repository webhook secret: letting those record a host would hand any namespace user a write primitive on the controller wide policy.
func TrustedURL ¶
TrustedURL validates the host component of rawURL against the allowlist and returns the URL rebuilt on the canonical hostname, keeping the path and query.
GitHub derives its API endpoint from a bare hostname, but GitLab, Gitea and Bitbucket Data Center are routinely served under a path prefix (https://example.com/gitlab), which rebuilding a URL from the hostname alone would silently drop. Those providers keep their own URL and use this function as their gate.
The returned URL always carries the hostname the allowlist actually approved, never the one the caller passed in: the two can differ, and a caller dialling the raw value would defeat the check. See the vcshost package documentation.
Types ¶
This section is empty.
Source Files