API reference

The version described here is policy.pahlevan.io/v1beta1, which is what the API server stores. v1alpha1 is still served so existing objects and clients keep working, and the API server converts between the two. The v1alpha1 fields with no v1beta1 counterpart are listed, with the reason each one is gone, in IntentionallyDropped in pkg/apis/policy/v1alpha1/conversion.go.

That matters more than it sounds. The previous version of this file was hand-written and described an API that had never existed - learning: instead of learningConfig:, enforcement: instead of enforcementConfig:, plus whole subsystems the CRD has never had. A Kubernetes API server does not reject an unknown field in a custom resource; it prunes it. So anyone who copied from it got a policy that applied cleanly and did a fraction of what they asked for, with no error anywhere.

Fields marked inert are accepted by the API and acted on by nothing. They are listed rather than hidden, because finding one in a cluster and not knowing is worse than being told. pahlevan policy explain -f names every one in a given policy.

PahlevanPolicy

is the Schema for the pahlevanpolicies API

PahlevanPolicySpec

defines the desired state of PahlevanPolicy

LearningConfig

controls the learning phase

EnforcementConfig

controls enforcement behavior

EnforcementException

defines enforcement exceptions. v1alpha1 had both temporary: true and expiresAt, and enforcement applied an expiry only when both were set. So expiresAt on its own was accepted, displayed, and never acted on: an operator who wrote a deadline got a permanent hole in the policy and no warning, which is the worst possible outcome for a field whose entire purpose is to close itself. The expiry is now the only statement of the fact, and an exception is temporary exactly when it has one.

FilePolicy

defines file access policies

ExecutableFilter

defines executable access controls

SyscallPolicy

defines syscall enforcement policies

ProcessFilter

defines process-based filtering

NetworkPolicy

defines network enforcement policies

NetworkRule

defines a network access rule

NetworkPeer

defines network peer specifications

NetworkPort

defines port specifications. The bounds are not decoration. A port is a uint16 on the wire and this field is an int32, so v1alpha1 accepted 0, -1 and 70000 and the translation truncated them into whatever the low sixteen bits happened to be. Port 70000 became port 4464, and the rule looked applied.

IPBlock

defines IP CIDR block

SelfHealingConfig

controls self-healing behavior

ObservabilityConfig

controls observability exports

PahlevanPolicyStatus

defines the observed state of PahlevanPolicy

LearningStatus

provides learning phase status

EnforcementStatus

provides enforcement status. v1alpha1 carried a blockedSyscalls counter that was always zero by construction: syscalls are confined by the generated seccomp profile, whose denials the kernel does not report back to this agent, and the BPF syscall program is observation only. A counter that can only read zero answers "are we blocking anything?" with "no" forever, so it is gone rather than documented again.

AttackSurfaceStatus

provides attack surface analysis

Other types

Reachable from the types above; listed so a new one cannot go undocumented by omission.

• ExpectedBehavior
• ExpectedDestination
• ExpectedFile
• LabelSelector
• LabelSelectorRequirement
• LogOutput
• LoggingConfig
• MetricsConfig
• MetricsExporter
• NamespaceSelector
• PahlevanPolicyList
• PolicyCondition
• TracingConfig
• TracingExporter
• VisualizationConfig
• VisualizationExporter
• WorkloadReference
• WorkloadSelector

Metrics, events and the CLI

The sections below are not generated: they describe surfaces outside the CRD.

Metrics API

Pahlevan exposes Prometheus metrics on port 8080.

Metrics Endpoint

GET /metrics

Available Metrics

Policy Metrics

Learning Metrics

eBPF Metrics

pahlevan_ebpf_handler_errors_total is the one to alert on if you export events. Enforcement happens in the kernel and is unaffected by a handler failure, so the event and denial counters keep climbing normally while an export file, webhook or gRPC subscriber quietly receives nothing.

System Metrics

Metric Labels

Common labels across metrics:

Event stream

Security events leave the agent in four ways, all carrying the same versioned envelope (pahlevan.io/v1alpha1):

Those four carry the envelope, which is the right shape for a collector and the wrong shape for a person. For getting a denial in front of somebody who can act on it there are three more, which send formatted messages rather than JSON:

All three send denials only by default, because an observation stream is not an alert stream and a channel receiving one message per file open gets muted within the hour. --notify-all-events opts in.

All three deduplicate by finding over --notify-dedupe-window (five minutes by default, negative to disable). A finding is the workload, the kind of operation and the subject - deliberately not the pid or the timestamp, which are exactly what make two occurrences of one problem look different. It keys on the owning workload rather than the pod, so a Deployment rolling out does not produce one message per replica for a single misconfiguration.

A template that fails to parse is a startup error naming the mistake, not an error logged once per batch while notifications silently never arrive:

--notify-template-url=https://example.webhook.office.com/... --notify-template='{"text":{{ .Summary | json }}}'

The envelope is defined in pkg/export/event.go and mirrored on the wire by api/v1alpha1/events.proto; the two are asserted to agree in pkg/grpcapi/convert_test.go.

Seeing what a policy does before applying it

pahlevan policy explain -f policy.yaml [--strict]

Translates the policy offline, prints what will be written into the kernel allow-sets, and names every part that will not be enforced - an ingress rule, a CIDR too wide to enumerate, a glob, an inert field. --strict exits non-zero, so a policy that quietly does less than it says can fail a CI gate.

It also rejects a field the CRD does not have, which the API server would otherwise prune without an error.