Identity and security

Active contributors: jrajahalme, christarazi, joestringer, gandro, aanm

Purpose

The identity model is what makes Cilium policy meaningful at scale: workloads carry an identity derived from labels, and policy is expressed identity-to-identity rather than IP-to-IP. This page collects the user-facing security capabilities that build on top of identities.

For the implementation of identity allocation see systems/identity-allocation.md. For policy syntax see features/network-policy.md.

Capabilities

• Identity-aware L3/L4 policy — every CNP/CCNP rule names label sets, not IPs.
• Identity-aware L7 policy — HTTP, gRPC, Kafka, DNS rules combine identity with application-level matchers.
• FQDN policy — toFQDNs rules let policy reference DNS names (api.example.com, *.s3.amazonaws.com).
• CIDR policy — toCIDR, toCIDRSet rules for non-K8s endpoints (databases, SaaS APIs, legacy).
• Mutual authentication — peer-to-peer authentication using SPIFFE identities derived from Cilium identity (pkg/auth/).
• Encryption — node-to-node WireGuard / IPSec (encryption.md).
• TLS interception via Envoy — for L7 policy and SDS-managed certs.
• Reserved entities — match world, cluster, kube-apiserver, host, remote-node, init directly in policy.

Identity catalog

graph LR
    Pod[Pod with labels]
    Hash[Label hash]
    CRD[CiliumIdentity CRD]
    NumID[NumericIdentity]
    IPCache[ipcache map]
    Policy[policy map]

    Pod --> Hash
    Hash --> CRD
    CRD --> NumID
    NumID --> IPCache
    NumID --> Policy

Every label set produces a stable 24-bit numeric identity. Reserved identities (world, host, ...) occupy small numbers; CIDR-based identities for external IPs use a higher range; pod identities fill the remaining space.

CIDRGroups

CiliumCIDRGroup (CRD pkg/k8s/apis/cilium.io/v2/types_cidr_group.go) is a reusable named CIDR set. Policies can reference a CIDRGroup by name instead of repeating CIDR lists. The agent compiles each CIDRGroup into a synthetic identity that flows into the ipcache for matching IPs.

Mutual authentication (pkg/auth/)

When a policy carries authentication.mode: required, traffic between peers is gated on a successful identity-based handshake:

1. The source agent derives a SPIFFE ID from the source endpoint's identity labels.
2. Agents on both sides exchange certificates and verify peer identity.
3. Once verified, the agent programs an "auth ok" entry into the policy map; subsequent packets pass through.
4. Auth state has a TTL and is renewed in the background.

The trust anchor is the agent itself — there is no per-pod sidecar. Operators integrate with external CAs through the auth.identityIssuer configuration.

Audit mode

Policies can be tested in audit mode (AuditMode: true on a CNP or via Helm). Drops are recorded as AUDIT verdicts in Hubble flows but the packet is forwarded as if allowed. This lets operators dry-run new policies before enforcing them.

Threat model considerations

• The agent runs as CAP_SYS_ADMIN in the host network namespace; it is the trust boundary on each node.
• Policy consistency depends on every node receiving identity updates promptly; the operator is the authority for identity GC.
• Cluster Mesh extends the identity space across clusters; policy referencing remote labels relies on the kvstore being healthy.
• Supply-chain integrity: the project publishes SBOMs and signs container images (see Documentation/configuration/sbom.rst).

Key source files

File	Purpose
pkg/identity/numericidentity.go	NumericIdentity.
pkg/identity/reserved.go	Reserved identities.
pkg/policy/api/rule.go	Policy schema (where identity selectors are evaluated).
pkg/auth/manager.go	Mutual auth.
pkg/k8s/apis/cilium.io/v2/types_cidr_group.go	CIDRGroup CRD.
pkg/fqdn/dnsproxy/proxy.go	FQDN policy.

See security.md for the operational security model.