README
¶
KubeGauge Agent
In-cluster security posture agent for KubeGauge: scans your
Kubernetes cluster read-only, through the API server, and pushes the compliance report to the
KubeGauge API. One agent per cluster, installed with a single helm install.
Push-only (Phase 4, M1): the agent makes outbound requests only — it pushes scan reports to the KubeGauge API and polls it for on-demand scan commands. It serves no API and has no Service: the old in-cluster HTTP endpoint is gone, and the only listener left is
GET /healthzon 8787 for kubelet probes. That port is bound on0.0.0.0, so other pods can reach it like any pod port; from v0.16.0 the chart ships an opt-in NetworkPolicy (networkPolicy.enabled=true) that denies all ingress to the agent. What leaves your cluster is documented in docs/what-leaves-your-cluster.md and formalized by schema/agent-report.v1.schema.json, generated from the code.
Install
helm install kubegauge-agent oci://ghcr.io/kubegauge/charts/kubegauge-agent \
--namespace kubegauge --create-namespace \
--set clusterName=<name> --set ingestUrl=https://<api> --set apiKey=<kga_...>
See charts/kubegauge-agent for all values (RBAC surface, trivy,
resources).
What the agent can read
A list-only ClusterRole over the resource types needed by the checks — pods, workloads
(Deployments/StatefulSets/DaemonSets), ServiceAccounts, Services, Namespaces, Nodes,
ResourceQuotas/LimitRanges, NetworkPolicies, Ingresses, RBAC objects, validating webhooks —
plus get for kube-system/kubeadm-config only. The agent never writes to the cluster.
From v0.16.0, Secrets are not readable by the agent at all: the
ClusterRole grants nothing on them, because RBAC cannot express "list metadata only" and a token
that can list Secrets cluster-wide is a credential oracle no matter how careful the code is
(TestClusterRoleGrantsNoSecretAccess, TestSnapshotNeverListsSecrets). v0.15.0 and earlier —
the versions published today — still grant list on secrets cluster-wide; they keep only
name/namespace/type and never send it, but the grant is real. See
docs/what-leaves-your-cluster.md for what that means for you.
ConfigMaps are read for their KEY NAMES only — the input to KG-SE-003's credential heuristic —
and values never survive collection (TestConfigMapValuesNeverLeaveSnapshot). See
the chart README for the trade v0.16.0 makes in
KG-RB-004.
Development
make agent-dev # kind cluster + build + deploy pushing to the host API (requires KG_API_KEY)
make agent-logs # follow agent logs
go test ./... # unit tests (no cluster required)
License
Apache-2.0
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
genschema
command
cmd/genschema writes the wire contract artifacts: schema/agent-report.v1.schema.json (generated from internal/wire's structs) and schema/check-ids.json (sorted ids of every implemented check, vendored by the platform to guard catalog coverage).
|
cmd/genschema writes the wire contract artifacts: schema/agent-report.v1.schema.json (generated from internal/wire's structs) and schema/check-ids.json (sorted ids of every implemented check, vendored by the platform to guard catalog coverage). |
|
kubegauge-agent
command
Package main implements kubegauge-agent: a push-only outbound agent — scan on a timer, POST the AgentReport to the KubeGauge API, poll for on-demand scan commands.
|
Package main implements kubegauge-agent: a push-only outbound agent — scan on a timer, POST the AgentReport to the KubeGauge API, poll for on-demand scan commands. |
|
internal
|
|
|
checks
backupdr.go implements KG-DR-001 (Backup & Disaster Recovery): whether the cluster runs a recognized backup/DR solution as a Deployment.
|
backupdr.go implements KG-DR-001 (Backup & Disaster Recovery): whether the cluster runs a recognized backup/DR solution as a Deployment. |
|
kube
client.go builds the in-cluster Kubernetes clientset for the KubeGauge agent.
|
client.go builds the in-cluster Kubernetes clientset for the KubeGauge agent. |
|
netpoleval
Package netpoleval implements the M5 NetworkPolicy semantics engine (PLAN-FASE-2.md §8): given the cluster's NetworkPolicies and Namespaces, it answers "is flow A→B on port/protocol allowed or denied, and which policy is responsible?" following upstream semantics (https://kubernetes.io/docs/concepts/services-networking/network-policies/):
|
Package netpoleval implements the M5 NetworkPolicy semantics engine (PLAN-FASE-2.md §8): given the cluster's NetworkPolicies and Namespaces, it answers "is flow A→B on port/protocol allowed or denied, and which policy is responsible?" following upstream semantics (https://kubernetes.io/docs/concepts/services-networking/network-policies/): |
|
push
Package push implements the agent's outbound loop: scan → gzip POST /v1/ingest, plus the ~30s GET /v1/agent/commands poll (heartbeat + on-demand scans).
|
Package push implements the agent's outbound loop: scan → gzip POST /v1/ingest, plus the ~30s GET /v1/agent/commands poll (heartbeat + on-demand scans). |
|
report
cluster.go implements the distribution heuristic (B5) used when building wire.KubernetesInfo.
|
cluster.go implements the distribution heuristic (B5) used when building wire.KubernetesInfo. |
|
snapshot
imagevulns.go defines the image-vulnerability enrichment types carried by a Snapshot.
|
imagevulns.go defines the image-vulnerability enrichment types carried by a Snapshot. |
|
trivy
cache.go is the trivy result cache: parsed ImageScanResults stored per image key (digest when known, ref otherwise) under --trivy-cache-dir, so repeat scans skip the (slow) trivy exec while the 24h TTL keeps results fresher than the daily CVE DB updates.
|
cache.go is the trivy result cache: parsed ImageScanResults stored per image key (digest when known, ref otherwise) under --trivy-cache-dir, so repeat scans skip the (slow) trivy exec while the 24h TTL keeps results fresher than the daily CVE DB updates. |
|
wire
gen.go generates the versioned JSON Schema for AgentReport from the Go structs — the single source of truth for what leaves the cluster.
|
gen.go generates the versioned JSON Schema for AgentReport from the Go structs — the single source of truth for what leaves the cluster. |