Add transparent actor egress policy and credential injection

[EItanya]

Description

Substrate should support transparent egress policy for actors. This should let operators define which external destinations an actor can reach without requiring actor code changes or proxy environment variables.

The policy model should be actor-aware rather than only pod-aware. Actors are dynamically started, restored, suspended, and reused across workers, so egress policy needs to follow actor and template identity through that lifecycle.

Credential handling is a large motivation. Today, if an actor needs to call an external service, credentials generally need to be made available inside the actor runtime. That increases the blast radius if the actor is compromised or prompt-injected, because the actor can potentially exfiltrate credentials or use them against unintended destinations.

Substrate should instead support destination-scoped credential injection. The runtime should be able to attach a configured credential only when the actor is calling an explicitly allowed destination. The actor should not need direct access to the raw credential by default.

Goals

• Default-deny actor egress.
• Allow egress by host and port.
• Apply policy without actor application changes.
• Support destination-scoped credential injection for allowed destinations.
• Keep raw credentials out of the actor environment when possible.
• Support plaintext HTTP policy.
• Support HTTPS passthrough and HTTPS inspection modes.
• Clean up policy state when actors suspend, fail, or move workers.
• Expose effective policy status for debugging.
• Emit audit-relevant allow and deny decisions.

Non-Goals

• Do not require actor applications to set proxy environment variables.
• Do not require actor application code changes.

HTTPS Inspection and MITM

HTTPS policy has two useful modes:

• Passthrough: allow or deny TLS connections based on connection metadata such as hostname and port, without decrypting application traffic.
• Inspection: terminate actor-side TLS, inspect or modify the HTTP request, then establish upstream TLS to the destination.

Credential injection for HTTPS generally requires inspection. If the runtime needs to add an authorization header or similar request credential, it must be able to see and modify the HTTP request before it is sent upstream.

Inspection requires the actor to trust a Substrate-managed certificate authority. That trust can be prepared before golden snapshot creation or provided through a runtime trust bundle. This should be explicit in the policy mode because some workloads will not support inspection:

• Certificate-pinned clients may fail.
• Workloads with private trust stores may need extra integration.
• Some users may prefer passthrough mode for destinations where inspection is not required.

Example Capability Sketch

This is intentionally illustrative rather than a final API.

egress:
  defaultAction: Deny
  rules:
  - to:
      host: api.example.com
      ports: [443]
    mode: Inspect
    credential:
      header:
        name: Authorization
        valueFrom:
          secretKeyRef:
            name: api-example-credentials
            key: bearer-token
  - to:
      host: docs.example.com
      ports: [443]
    mode: Passthrough

Open Questions

• Should the initial policy be namespace-scoped only?
• Should policy attach directly to actor templates, select actor templates, or both?
• What should the default be when no policy selects a template?
• Should multiple selected policies merge, or should that be rejected?
• What are the minimum useful policy modes for v1?
• How should policy changes apply to already-running actors?
• How should certificate trust be distributed for HTTPS inspection?
• What status fields are needed to make debugging effective policy easy?

[EItanya]

The following are 2 basic shapes I've been milling about, but treat these as the start of a discussion rather than my final thoughts

Option 1: Inline Policy On ActorTemplate

Policy lives directly on the actor template.

apiVersion: ate.dev/v1alpha1
kind: ActorTemplate
metadata:
  name: browser-agent
spec:
  egress:
    defaultAction: Deny
    rules:
    - to:
        host: api.example.com
        ports: [443]
      mode: Inspect
      credential:
        header:
          name: Authorization
          valueFrom:
            secretKeyRef:
              name: api-example-credentials
              key: bearer-token

Benefits:

• Simple to understand.
• Policy versions with the actor template.
• Easy to show effective policy on the template.

Tradeoffs:

• Harder to reuse across templates.
• Couples application authorship and security policy ownership.
• Policy updates require editing workload templates.

Option 2: External ActorEgressPolicy Selecting Templates

Policy is a separate resource that selects actor templates by labels.

apiVersion: ate.dev/v1alpha1
kind: ActorEgressPolicy
metadata:
  name: research-agent-egress
spec:
  selector:
    matchLabels:
      app.kubernetes.io/part-of: research-agents
  defaultAction: Deny
  rules:
  - to:
      host: api.example.com
      ports: [443]
    mode: Inspect
    credential:
      header:
        name: Authorization
        valueFrom:
          secretKeyRef:
            name: api-example-credentials
            key: bearer-token

Benefits:

• Separates workload definition from security and network policy.
• Reusable across many actor templates.
• Easier for platform teams to manage broad policy.
• Allows namespace, team, or workload-class defaults.

Tradeoffs:

• Needs deterministic merge behavior if multiple policies select one template.
• Requires status or tooling to explain the final effective policy.
• Label changes can alter policy attachment, intentionally or accidentally.

[mtaufen]

Agree we need a policy design and I potentially like the idea of including credential injection.

+1 to supporting L7 policy.

Do we want this to have any relationship w/ K8s NetworkPolicy? Since the workers are K8s Pods I expect people to also use K8s NP as a coarse grained control.

Another topic for debate: Should this be a standard that lets you bring your own proxy, or should substrate implement a built-in proxy and policy engine for this?

[bowei]

My mental model is:

• K8s NP is used to broadly lock things down and apply at the level of Workers. It's going to be hard to make current K8s NP work well in their present form with Actor dynamism given the propagation latency -- but this could be something that is improved, but the current state of the art is not there yet.
• Substrate L7 policy takes precedence over K8s NP but only via a small, proscribed policy-enforced allowed path. The thought that comes to mind would be similar to how K8s meshes work (for better or worse).

[EItanya]

Another topic for debate: Should this be a standard that lets you bring your own proxy, or should substrate implement a built-in proxy and policy engine for this?

My take here is that in the long run we’ll probably need the former, but shipping with a “batteries included” option is also probably a good idea for getting started/simplicity

[thockin]

Notes as I read thru this one:

Does this policy apply to a single actor or to all actors in a "namespace" (which is a concept we don't have yet) or to all actors of a template?

Does this cover all TCP/UDP/... or only HTTP?

If policy applies to FQDNs, do you trust the host header or do you intercept DNS for resolution?

(edit: I see you asked these questions too :)

Regarding policies on ActorTemplates - what is the use-case? I am not saying it doesn't exist, but let's root our discussion in the concrete as much as we can.

I am assuming that you intend this ONLY to be egress policy (as in "egress from the cluster") and not general "east-west" policy? Kubernetes NetPol tries to do both and does neither very well.

I think we should start with user-stories. What are the things we need to be able to express? I think it's safe to assume some notion of "namespace".

• As a substrate admin, I want to set a default-deny policy for the whole substrate
• As a substrate admin, I want to set a default policy for a single namespace or set of namespaces
• As an agent developer, I want to set a default policy for all actors from my template
• As a namespace user, I want to set a default policy for all actors in a namespace
• As a namespace user, I want to set a specific policy on a single actor

I am sure there are more and with more nuance. Which are the most important and where is the best places to express them?