PID Mapper

What It Does

The PID Mapper is the core innovation that enables per-process identity. It runs as a sidecar container with shareProcessNamespace: true, giving it visibility into all processes in the pod. When a new process starts in the agent container (e.g., a CrewAI spawns a researcher subprocess), the PID Mapper:

Detects the new process via /proc filesystem monitoring
Matches the process to a role from the process context ConfigMap
Requests a unique SPIFFE SVID for that specific process
Delivers the SVID so the process gets its own cryptographic identity

How It Works

Agent forks subprocess

The agent container spawns a new subprocess (e.g., researcher at PID 42).

PID Mapper detects new process

The PID Mapper watches /proc and detects the new PID 42. It reads /proc/42/cmdline to identify the process.

Match to process context

The PID is matched against the process-context/researcher.json file to determine the SPIFFE role.

Fetch SVID from SPIRE

PID Mapper calls FetchX509SVID with selectors hexr:role:researcher + k8s:pod-uid:.... SPIRE returns an X.509 SVID for spiffe://.../researcher.

The SVID is registered for PID 42. When the researcher process calls hexr_tool(), Envoy automatically uses this specific SVID for mTLS.

Agent (fork PID 42) → PID Mapper → /proc/42/cmdline → Match role → SPIRE (FetchX509SVID) → SVID registered

Process Context

The PID Mapper reads from a ConfigMap mounted at /hexr/process-contexts/:

{
  "role": "researcher",
  "command_pattern": "python.*researcher",
  "spiffe_suffix": "researcher",
  "allowed_services": ["gcp_bigquery", "aws_s3"],
  "env_markers": {
    "HEXR_ROLE": "researcher"
  }
}

Detection Methods

The PID Mapper uses multiple strategies to match a process to a role:

Priority	Method	How
1	Environment variable	`HEXR_ROLE=researcher` in process env
2	Command pattern	Regex match against `/proc/{pid}/cmdline`
3	Process tree	Parent-child relationship analysis
4	Fallback	Assign `main` role

Why This Matters

Without PID Mapper, all processes in a container share one identity. With it:

Without PID Mapper	With PID Mapper
All processes share one SVID	Each process gets a unique SVID
`hexr_tool()` grants broad access	`hexr_tool()` grants role-specific access
No per-process cost attribution	Per-process LLM cost tracking
One identity in audit logs	Per-process audit trail

PID Mapper requires shareProcessNamespace: true in the pod spec. This is automatically configured by hexr build.

Configuration

The PID Mapper is configured via pod spec, not environment variables:

spec:
  shareProcessNamespace: true
  containers:
    - name: pid-mapper
      image: us-central1-docker.pkg.dev/hexr-cloud-prod/hexr-images/enterprise-pid-mapper:latest
      volumeMounts:
        - name: spire-agent-socket
          mountPath: /run/spire/sockets
        - name: process-contexts
          mountPath: /hexr/process-contexts

Platform Overview

Pod Containers

Cluster Services

Infrastructure

What It Does

How It Works

Process Context

Detection Methods

Why This Matters

Configuration

​What It Does

​How It Works

​Process Context

​Detection Methods

​Why This Matters

​Configuration

What It Does

How It Works

Process Context

Detection Methods

Why This Matters

Configuration