Connect a self-hosted StackRox and Kubernetes
Requirements sheet for a firewall or network team before connecting a self-hosted StackRox Central and a Kubernetes cluster, with the exact token role, RBAC rules, address and certificate rules, and a troubleshooting table.
Connect a self-hosted StackRox and Kubernetes
Safeguard reaches a self-hosted StackRox Central and a Kubernetes API server from the internet, over HTTPS, using a read-only credential for each. This sheet lists what your network and security teams need to prepare before you connect them. The connect steps themselves are in StackRox and in the Kubernetes card under Integrations › Connectors.
Safeguard makes read calls only. It never changes anything in StackRox or in your cluster.
Safeguard egress addresses
Allow these addresses to reach your StackRox Central and your Kubernetes API server.
| Item | Value |
|---|---|
| Source IP addresses | Ask Safeguard support at hi@safeguard.sh for the current list |
| Protocol and port | HTTPS (TCP) to the port your Central or API server listens on, usually 443 for Central and 6443 for the Kubernetes API server |
If a firewall or security group limits who may connect, add the source addresses above to its allow list. Without this, a connection test fails with a timeout or a "Could not reach" error.
StackRox Central requirements
| Requirement | Detail |
|---|---|
| Address | A public https:// address, with a host name or IP that resolves to a public IP address. Any port is accepted; a path prefix is kept for a Central served behind a reverse proxy. |
| Refused addresses | http://, a private, loopback, link-local or cloud-metadata address, a host that resolves to one, and internal names such as localhost, single-label names and names ending in .local, .internal, .lan, .corp, .intranet or .home.arpa. Safeguard refuses them before it sends anything. |
| Address format | No user name, password or query string in the address. The token has its own field. |
| Certificate | Issued by a public certificate authority, and valid for the host name. Self-signed certificates and certificates from a private certificate authority are refused, and there is no setting to trust your own authority. |
| API token | Generated in Central with the Analyst system role. Analyst reads every resource and changes none. |
| Secured clusters | At least one secured cluster reporting to Central. Without one, Central-level checks still run and the workload checks have nothing to evaluate. |
Create the token in Central under Platform Configuration › Integrations › Authentication Tokens › API Token › Generate token, name it, choose the Analyst role, and copy it when Central shows it. Then connect in Safeguard with the fields Instance URL (your Central address) and API token.
What Safeguard reads from Central
All calls are GET requests with the token in an Authorization: Bearer header.
| Purpose | Central API |
|---|---|
| Token check when connecting | /v1/auth/status |
| Vulnerabilities per workload | /v1/export/vuln-mgmt/workloads |
| Cluster and sensor health | /v1/clusters |
| Open policy violations | /v1/alerts and /v1/alerts/{id} |
| Policy enforcement | /v1/policies and /v1/policies/{id} |
| Notifiers and their health | /v1/notifiers and /v1/integrationhealth/notifiers |
| Compliance scan results | /v2/compliance/integrations, /v2/compliance/scan/configurations and /v2/compliance/scan/stats/profiles |
| Administrator count | /v1/groups and /v1/apitokens |
Kubernetes requirements
| Requirement | Detail |
|---|---|
| API server address | A public https:// address that Safeguard's egress addresses can reach. It follows the same address rules as Central: https only, a public IP, no user name, password, query or fragment. A private API server address is refused. |
| Certificate | Paste the cluster's CA certificate (PEM, or base64 as a kubeconfig carries it) into Cluster CA certificate (PEM). If you leave it empty, the certificate must come from a public certificate authority. TLS verification cannot be turned off. |
| Credential | A ServiceAccount token, entered in Service account token, or a kubeconfig whose current context holds the server, certificate-authority-data and a token. A kubeconfig that uses an exec plugin, an auth provider, a client certificate or file paths is refused. |
| Cluster name | Optional. A label for the connection. |
| Redirects | Not followed. The API server must answer on the address you give. |
Read-only RBAC
Create a ServiceAccount, a ClusterRole that can only get and list, a binding, and a long-lived token. Every rule below is read-only.
apiVersion: v1
kind: ServiceAccount
metadata:
name: safeguard-reader
namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: safeguard-compliance-read
rules:
- apiGroups: ["rbac.authorization.k8s.io"]
resources: ["clusterrolebindings", "clusterroles", "roles", "rolebindings"]
verbs: ["get", "list"]
- apiGroups: [""]
resources: ["namespaces", "pods", "serviceaccounts", "nodes"]
verbs: ["get", "list"]
- apiGroups: ["networking.k8s.io"]
resources: ["networkpolicies"]
verbs: ["get", "list"]
- apiGroups: ["constraints.gatekeeper.sh"]
resources: ["*"]
verbs: ["get", "list"]
- apiGroups: ["kyverno.io"]
resources: ["clusterpolicies", "policies"]
verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: safeguard-compliance-read
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: safeguard-compliance-read
subjects:
- kind: ServiceAccount
name: safeguard-reader
namespace: kube-system
---
apiVersion: v1
kind: Secret
metadata:
name: safeguard-reader-token
namespace: kube-system
annotations:
kubernetes.io/service-account.name: safeguard-reader
type: kubernetes.io/service-account-tokenRead the token and the cluster CA from the Secret once Kubernetes has filled it in:
kubectl -n kube-system get secret safeguard-reader-token -o jsonpath='{.data.token}' | base64 -d
kubectl -n kube-system get secret safeguard-reader-token -o jsonpath='{.data.ca\.crt}' | base64 -dIf you do not run Gatekeeper or Kyverno you can leave out the last two rules. The checks that depend on them then report that the cluster does not serve those APIs.
What Safeguard reads from the cluster
| Purpose | Kubernetes API |
|---|---|
| Cluster administrator bindings, role escalation | clusterrolebindings, clusterroles, roles, rolebindings |
| Namespace pod security labels | namespaces |
| Privileged pods | pods (only the fields judged are kept; no environment values, commands or volumes are stored) |
| Default network policies | networkpolicies |
| Default ServiceAccount token settings | serviceaccounts |
| Managed control plane and node labels | nodes and GET /version |
| Policy engines | Gatekeeper constraints and Kyverno policies |
Troubleshooting
| What you see | Likely cause | What to do |
|---|---|---|
| The address is refused, or the message says it names an internal host or resolves to a private or reserved address | The host is private, an internal name, or its DNS record points to a private IP address | Publish the address on a public IP and a public DNS name, then restrict it to Safeguard's egress addresses |
| Give an https address with no user name, password or query | The address has http://, credentials or a query string | Use https://host[:port] and put the token in its own field |
| Could not reach, with a timeout | A firewall, security group or DNS does not let Safeguard's egress addresses reach the port | Add Safeguard's egress addresses to the allow list, and check the public DNS record resolves from outside your network |
| Could not reach, with a certificate error (StackRox) | The certificate is self-signed, from a private authority, expired or issued for another name | Install a certificate from a public certificate authority for the exact host name |
| Could not reach, with a certificate error (Kubernetes) | The cluster CA is missing or wrong | Paste the cluster CA certificate from the ServiceAccount token Secret |
| HTTP 401 from Central | The token is wrong, expired or revoked | Generate a new token with the Analyst role |
| HTTP 403 from Central, "The credential needs ..." | The token's role cannot read that resource | Generate a token with the Analyst system role |
| The service account token was not accepted (Kubernetes 401) | The token is wrong, or the Secret has no token yet | Read the token again from the Secret and paste it without spaces |
| Grant the read-only ClusterRole ... (Kubernetes 403) | The ClusterRoleBinding is missing, or a rule is missing | Apply the ClusterRole and binding above, then test again |
| The cluster does not serve this API (Kubernetes 404) | The API is not installed, usually Gatekeeper or Kyverno | Install it, or ignore it if you do not use it |
| The list changed while it was read (Kubernetes 410) | The cluster expired a paging token during a large read | Nothing. Safeguard reads it again on the next run. |
| The kubeconfig points at files, uses an exec plugin, or turns off TLS verification | A kubeconfig form Safeguard does not accept | Paste a kubeconfig with certificate-authority-data and a token, or use the token and CA fields |
| StackRox connects but the workload checks are empty | No secured cluster reports to Central, or its sensor is unhealthy | Check the sensor in Central under Platform Configuration › Clusters |
After any change, open the connector's card and choose Test, or Re-check all on the Connectors page.
StackRox
Connect StackRox or Red Hat Advanced Cluster Security so Safeguard can check vulnerability timelines, policy violations, enforcement, notifiers and compliance results.
Identity & SSO connectors
The 53 Identity & SSO connectors Safeguard connects to, how each one connects, and a setup page for each.