Scanner permissions and data 
¶
This page lists everything the AI Hypervisor scanner is allowed to do in your cluster, what it sends to Wallarm, how long Wallarm keeps it, and how to remove the scanner completely. It applies to the aih-scanner Helm chart 3.0.0 and later.
Profiles¶
The chart value profile selects a preset of capabilities. Any single capability can be overridden with capabilities.<name>: true|false.
| Profile | What it is for | Writes to the cluster |
|---|---|---|
monitor (default) |
Observation only. The scanner inspects pods in namespaces you labelled higgs.scan=enabled yourself. |
Nothing outside its own namespace. No webhook, no proxy, no enforcement, no DNS observation. |
enforce |
Adds blocking: the proxy, the admission webhook, kernel enforcement, and the console's Monitor, Enforce, Adopt and Revert actions. | Namespace labels, workload restarts on Adopt, quarantine labels and NetworkPolicies, the proxy's CA Secret, Kubernetes Events. |
full |
Everything in enforce, plus Shadow AI, PodSecurity changes on onboarded namespaces and in-process agents. The 2.x behaviour. |
As enforce, plus PodSecurity labels. |
If you upgrade from 2.x and want the 2.x behaviour, set profile: full. A 2.x value you set explicitly (proxy.enabled, webhook.enabled, coreDNS.enableLogPlugin, upgrader.enabled, agents.enabled) still takes precedence over the profile.
When the scanner is not allowed to do something, it does not try. The console then disables the action and shows the kubectl command that does it by hand. The Enforcement page shows how many active block rules are not applied.
Capabilities¶
| Capability | What it enables | monitor |
enforce |
full |
|---|---|---|---|---|
capture |
eBPF capture, TLS uprobes, package and model scans, all read-only. | on | on | on |
inventory |
Read-only cluster inventory: nodes, services, workloads, ingresses, NetworkPolicies, CRDs, ClusterRole names. | on | on | on |
shadowAI |
DNS observation (packet capture of UDP/53), CoreDNS and ingress-controller log reads, the passive MCP server fingerprint, and connection-based LLM egress. | – | – | on |
coreDNSPatch |
A post-install job adds the log plugin to kube-system/coredns. |
– | – | – (opt-in) |
onboard |
The console's Monitor, Enforce and Revert actions label namespaces. | – | on | on |
adopt |
The console's Adopt action rolling-restarts workloads. | – | on | on |
podSecurity |
Sets PodSecurity privileged on onboarded namespaces. The previous values are saved in the namespace annotation higgs.io/psa-before and restored on Revert. |
– | – | on |
enforce |
Kernel enforcement, block rules and quarantine. | – | on | on |
proxy |
The egress proxy and its CA Secret. | – | on | on |
webhook |
The admission webhook. It is installed only together with the proxy or the agents. | – | on | on |
agents |
In-process agents for Python and Node.js. | – | – | on |
selfUpgrade |
The in-cluster upgrader updates the scanner image. | – | – | – (opt-in) |
Kubernetes RBAC¶
Each capability has its own ClusterRole and binding, named <release>-<capability> and labelled higgs.wallarm.com/capability. To list the capabilities an install has, run kubectl get clusterrole -l higgs.wallarm.com/capability.
| ClusterRole | Rules |
|---|---|
capture |
pods, namespaces, services, nodes: get, list, watch. pods/status: get. |
inventory |
serviceaccounts, persistentvolumes: get, list. Deployments, StatefulSets, DaemonSets: get, list. Ingress classes, Ingresses, NetworkPolicies: get, list. CRDs: get, list. ClusterRoles: list. |
shadow-ai |
pods/log: get. |
onboard |
namespaces: patch. |
adopt |
Deployments, StatefulSets, DaemonSets: get, list, patch. ReplicaSets: get. |
enforce |
pods: patch (quarantine label). NetworkPolicies: get, list, create, update, delete (only aih-quarantine-<id>, deleted when the quarantine is lifted). Events: create, patch. |
proxy |
Secrets: get, update, patch on the CA Secret by name, and create. A ValidatingAdmissionPolicy admits only an Opaque Secret with the CA name. |
A monitor install binds only capture and inventory, which contain no write verb. It never reads ConfigMaps, and it reads no Secret outside its own namespace. In its own namespace the scanner has two Roles, both limited to one object by name:
-
<release>-key-delivery:getandupdateon the Secret<release>-delivered-key, where a rotated scanner key is stored. -
<release>-self-terminate:getanddeleteon its own DaemonSet, used when you remove the scanner from the console.
With proxy, it also manages its own CA Secret by name (see the proxy row above).
Node privileges¶
The scanner runs as a DaemonSet with hostPID and hostNetwork.
| Privilege | Profile | Why |
|---|---|---|
SYS_PTRACE, SYS_ADMIN |
all | Reading /proc/<pid>/root of target containers, loading eBPF programs. |
NET_ADMIN |
enforce, full, or with shadowAI |
tc filters and sockops for kernel enforcement, and the DNS packet capture. |
allowPrivilegeEscalation: true, AppArmor Unconfined |
enforce, full |
Writing pinned eBPF objects to /sys/fs/bpf. In monitor the scanner runs with false and RuntimeDefault. |
/proc, /var/log, /sys/kernel/btf, /sys/fs/cgroup, the containerd socket (all read-only) |
all | Process, cgroup and container metadata for capture. |
/sys/kernel/debug (read-write) |
all | kprobe and uprobe attachment on kernels without a perf kprobe PMU. |
/sys/fs/bpf (read-write) |
enforce, full |
Pinned enforcement maps, so a restart keeps enforcing. |
/run/higgs (host path) |
with agents |
The socket that in-process agents use. Otherwise a per-pod emptyDir. |
In monitor (no enforce), a short-lived init container named kernel-lane-cleanup runs before the scanner starts. It holds NET_ADMIN and a writable /sys/fs/bpf for a few seconds, removes any enforcement objects an earlier version left on the node (tc filters named session_block, pins under /sys/fs/bpf/higgs), and exits.
tolerations defaults to tolerating every taint, so that no node goes unobserved. priorityClassName defaults to system-node-critical. You can change both values.
The scanner's HTTP port (config.port, default 19090) listens on 127.0.0.1 only. The exception is when in-process agents with the Python agent are enabled. Then it also listens on the node address, and every post must carry its namespace's ingest token, which the webhook injects into the pod.
Data sent to Wallarm¶
The scanner sends data only to your tenant (config.backendUrl). Every request is signed with the scanner key.
| Data | Source | Content |
|---|---|---|
| Package and model inventory | Scans of labelled pods | Packages and versions, model files and their format, MCP server definitions. File contents are not sent. |
| AI traffic | Capture of labelled pods (eBPF, and the proxy in enforce and full) |
One record per request: source and destination application, host, path, status, timings, token counts, the caller identity (JWT subject or a derived anonymous key), personal-data classes found, and the request and response body. Bodies have personal data masked (for example j***@example.com) and are cut to 2,048 characters. |
| Cluster inventory | inventory |
Node, service, workload, ingress and NetworkPolicy names and labels; cluster provider and region. No Secrets or ConfigMaps. |
DNS lookups (shadowAI only) |
Packet capture of UDP/53 on the node | Only queries for known AI-provider domains: the domain, the source pod and namespace, and a count. Other lookups are dropped on the node. |
Ingress traffic (shadowAI only) |
Ingress-controller logs | Requests whose host matches a known AI provider: host, source and count. |
| Scanner health | The scanner itself | Version, capabilities, memory and CPU, and the counts of what it observed. |
Wallarm keeps this data for your tenant's retention period. If a retention period is set for your tenant, sessions, events and scan inventory are kept for that many days, personal-data records for twice that, findings for four times that, and block lists for that many days. Without a retention period, data is kept until you delete it. To delete everything about one cluster or device, use Forget environment… on its card in Debugger.
In-process agents and signals¶
In-process agents run only with the agents capability. For Node.js, the scanner attaches to an already running process only when it has positive evidence that the process is the V8 runtime. It never signals other processes. Attaching to running processes is off by default (agents.nodeLiveAttach, agents.pythonLiveAttach); new pods get the agent through the webhook instead.
Uninstall¶
With Helm, run helm uninstall <release> -n higgs-system. A pre-delete hook removes the enforcement objects (pins under /sys/fs/bpf/higgs and tc filters named session_block) from every node, along with the proxy's iptables rules.
Argo CD does not run Helm pre-delete hooks when it removes an application. Nothing is left enforcing either way:
-
Since chart 3.0.0, the kernel enforcement programs stop dropping traffic within two minutes of the scanner being gone, whether it was uninstalled, crashed or OOM-killed.
-
With
monitor, thekernel-lane-cleanupinit container removes earlier versions' objects on every start.
To remove the remaining pins by hand on a node, run rm -r /sys/fs/bpf/higgs there.