Allow actors to opt-in/out of Linux capabilities

[juli4n]

The set of capabilities we grant to actor sandboxes are hardcoded today. There should be a way for actors to specify which capabilities to add / drop, similar to securityContext.capabilities in k8s Pod's.

It would be nice to have a way to define this in the ActorTemplate container. We could follow a similar patter as k8s where users can specify capabilities to add / drop, from the default set of capabilities from the sandbox class (i.e gvisor, cloud-hypervisor).

[nmn3m]

Hi! I'd like to take this one on, if it's free.

I had a look around first. The hardcoded list is in buildActorOCISpec in cmd/atelet/oci.go, and as far as I can tell it's the only spot where capabilities get set. Both gvisor and microvm just pass it along unchanged, so I don't think ateom needs touching at all ,it's really just about getting the field down there from the template.

What I'd do:
Add a securityContext.capabilities block with add/drop to Container in actortemplate_types.go, then thread it through ateletpb.Container → workload_spec.go → prepareOCIDirectory → buildActorOCISpec. Final set is default + add − drop, with drop: ["ALL"] working like it does in k8s. Pause container keeps the defaults. Tests in oci_test.go and workload_spec_test.go.

I'd put it under securityContext rather than a plain capabilities field, just so there's room for things like runAsUser later without changing shape again.

Two things I'd like your call on:

1. Should defaults be per sandbox class in this PR, or later? Right now one list covers both. I noticed the comment in ensureKataCompatibleSpec about atelet eventually emitting runtime-appropriate specs, doing per-class defaults properly probably means moving them into SandboxConfigSpec, which feels like its own change. My instinct is to do add/drop first and leave that as a follow-up, but I'm happy either way.
2. Should there be a limit on what add allows? As proposed, nothing stops CAP_SYS_ADMIN. That might be fine since the sandbox is the real boundary ,just want to check that's deliberate before I build it that way.

[mtaufen]

Overall this sounds good to me, though I have a few questions:

• On order of operations: I think we want default - drop + add?
• Could we drop all capabilities by default for the pause container?
• Would it make sense to always drop all by default, and require explicit specification in ActorTemplate, given the generally higher security risk with agents?

There are also a number of recent conversations revisiting #44 to unlock additional scalability, which may have implications for this (but not a blocker IMO).

[BenTheElder]

Should defaults be per sandbox class in this PR, or later? Right now one list covers both. I noticed the comment in ensureKataCompatibleSpec about atelet eventually emitting runtime-appropriate specs, doing per-class defaults properly probably means moving them into SandboxConfigSpec, which feels like its own change. My instinct is to do add/drop first and leave that as a follow-up, but I'm happy either way.

I do not think they should be per sandboxclass, they're per actortemplate, with a default. The kata bit is internal. Where possible the runtimes are compatible.

I also think we need to nail down the correct defaults. E.G. should they match k8s/docker or be more restrictive. The latter is probably not necessary since we have the sandbox, and not matching might be surprising for existing container images.

[AiWatson343]

This is a great idea. Making actor sandbox capabilities configurable through the ActorTemplate would provide more flexibility while keeping the sandbox class as the source of default security policies. A model similar to Kubernetes securityContext.capabilities makes sense — allowing users to explicitly add or drop capabilities while inheriting a safe baseline from the underlying runtime (gVisor, Cloud Hypervisor, etc.).

It would also improve portability and governance by making capability requirements visible as part of the actor definition instead of being hidden in hardcoded sandbox logic. We should consider validation rules to prevent actors from requesting unsafe capabilities and ensure the sandbox runtime enforces the final effective capability set. This could be a strong step toward a more dynamic and secure actor execution model.

[BenTheElder]

Noureldin (@nmn3m) if you'd like to work on this, please do, if not we have a few people that expressed interest in other forums (slack etc). thanks!

[AiWatson343]

This idea is about making security privileges for sandboxed AI actors configurable at the ActorTemplate level instead of being buried inside sandbox code. It is essentially bringing a Kubernetes-style security model into an actor execution platform.

Below is a detailed breakdown.

---

Configurable Actor Sandbox Capabilities Through ActorTemplate

1. Current Problem

In many actor systems, the sandbox controls what an actor can do:

Access files

Use networking

Spawn processes

Access hardware

Use system APIs

Perform privileged operations

Today, these permissions are often hardcoded inside the sandbox implementation.

Example:

ActorTemplate
|
v
Sandbox Manager
|
v
Hardcoded Security Policy
|
v
Runtime (gVisor / Cloud Hypervisor)

The problem:

Every actor gets the same security profile.

Changing permissions requires modifying sandbox code.

Developers cannot see required privileges from the actor definition.

Governance teams cannot easily audit actor behavior.

Different runtimes may require different security assumptions.

---

2. Proposed Architecture

Move capability declarations into the ActorTemplate.

New model:

ActorTemplate
|
|-- Metadata
|
|-- Runtime Requirements
|
|-- Capabilities
|
|-- Add
|
|-- Drop
|
|-- Limits
|
|-- Policies
|
v
Sandbox Controller
|
v
Security Policy Engine
|
v
Runtime Adapter
|
+--> gVisor
|
+--> Cloud Hypervisor
|
+--> Firecracker
|
+--> WASM Runtime

The ActorTemplate becomes the declarative security contract.

---

3. Kubernetes SecurityContext Model Inspiration

Kubernetes already uses this concept.

Example Kubernetes:

securityContext:
capabilities:
add:
- NET_BIND_SERVICE
drop:
- ALL

Meaning:

Remove everything dangerous.

Add only explicitly required privileges.

The actor system could use something similar:

actorTemplate:
name: network-monitor-agent

sandbox:
capabilities:

  drop:
    - ALL

  add:
    - NETWORK_INSPECT
    - DNS_QUERY

  filesystem:
    read:
      - /model
    write:
      - /tmp

  network:
    outbound:
      allowed: true

---

4. Capability Types

Capabilities could be divided into categories.

A. Compute Capabilities

Controls resource access.

Examples:

CPU_LIMIT
GPU_ACCESS
TPU_ACCESS
MEMORY_HIGH_PRIORITY

Example:

AI training actor:

capabilities:
add:
- GPU_ACCESS

---

B. Network Capabilities

Controls communication.

Examples:

NETWORK_ACCESS
NETWORK_INSPECT
INBOUND_PORT_BIND
SERVICE_DISCOVERY

Example:

API actor:

capabilities:
add:
- NETWORK_ACCESS

---

C. Storage Capabilities

Controls data access.

Examples:

READ_DATASET
WRITE_CHECKPOINT
TEMP_STORAGE
SECRET_ACCESS

Example:

Research actor:

capabilities:
add:
- READ_DATASET
- WRITE_CHECKPOINT

---

D. System Capabilities

Most restricted.

Examples:

PROCESS_CREATE
DEVICE_ACCESS
KERNEL_EXTENSION
HOST_FILESYSTEM

These should normally be blocked.

---

5. Security Policy Flow

The final permission should not come directly from the user.

A secure model:

Requested Capabilities
|
v
ActorTemplate
|
v
Policy Validator
|
v
Security Baseline
|
v
Runtime Enforcement
|
v
Sandbox

The effective capability set:

Effective Capabilities =
(User Request)
+
(Runtime Allowed)

(Security Deny Rules)

---

6. Example

Actor Request

actor:
name: medical-ai-agent

sandbox:
capabilities:

add:
- GPU_ACCESS
- DATABASE_READ

drop:
- NETWORK_ACCESS

---

Sandbox Default Policy

Default:

Allowed:
CPU
MEMORY
TEMP_STORAGE

Denied:
HOST_FILESYSTEM
KERNEL_ACCESS
PRIVILEGED_NETWORK

---

Policy Engine Result

Approved:

GPU_ACCESS
DATABASE_READ
CPU
MEMORY
TEMP_STORAGE

Rejected:

HOST_FILESYSTEM
KERNEL_ACCESS

---

7. Validation Rules

The system needs capability governance.

Rule 1 — Dangerous Capabilities Require Approval

Example:

add:

• HOST_FILESYSTEM

Result:

DENIED

Reason:
Capability requires elevated trust level.

---

Rule 2 — Capability Dependencies

Example:

A GPU capability requires:

GPU_ACCESS
requires:
DEVICE_ACCESS

The validator automatically checks:

GPU_ACCESS
|
+--> DEVICE_ACCESS allowed?

---

Rule 3 — Runtime Compatibility

Different runtimes support different capabilities.

Example:

gVisor:

GPU ❌
Kernel modules ❌
Network isolation ✅

Cloud Hypervisor:

GPU passthrough ✅
Strong VM isolation ✅

Validation:

Actor Capability Request
|
v
Runtime Capability Matrix

---

8. Actor Capability Manifest

Each actor could publish a security manifest.

Example:

Actor:
Autonomous Research Agent

Requires:

✓ Read scientific datasets
✓ GPU acceleration
✓ Internet API access

Does NOT require:

✗ Host access
✗ Kernel privileges
✗ Device control

This improves:

Auditing

Compliance

Security reviews

Deployment automation

---

9. Governance Benefits

Security Teams

Can answer:

"What permissions does this AI agent have?"

without reading code.

---

Platform Operators

Can enforce:

"Production actors cannot request privileged capabilities."

---

Developers

Can define requirements once:

ActorTemplate
|
|
Deploy Anywhere

---

10. Runtime Enforcement

The sandbox must enforce the final result.

Example:

Actor requests:

NETWORK_ACCESS

Policy says:

DENY

Runtime receives:

network=false

Even if the actor tries:

socket.connect()

Result:

Permission denied

---

11. Possible API Design

ActorTemplate CRD Example

apiVersion: actors.io/v1

kind: ActorTemplate

metadata:
name: ai-research-agent

spec:

runtime:
type: gvisor

security:

capabilities:

 baseline:
   inherit: true

 add:
   - GPU_ACCESS
   - DATA_READ

 drop:
   - NETWORK_ACCESS

isolation:
filesystem: restricted
process: isolated

---

12. Advanced Future Features

Capability Profiles

Instead of individual permissions:

profiles:

research-agent:
GPU
DATA_READ
INTERNET_API

web-agent:
NETWORK
BROWSER

secure-agent:
NO_NETWORK
NO_FILESYSTEM

---

Dynamic Capability Escalation

Temporary permission:

Example:

AI agent needs a database for 5 minutes.

Request:
DATABASE_READ

Approval:
Granted

Expiration:
300 seconds

---

Zero Trust Actor Model

Every actor starts with:

Capability Set = Empty

Then explicitly receives:

Minimum Required Permissions

This follows:

Zero Trust Architecture

Least privilege security

Defense in depth

---

13. Strategic Impact

This change would make the actor platform closer to:

Kubernetes security model

Cloud-native workload identity

Zero-trust AI execution

Secure autonomous agent infrastructure

It enables:

✅ Multi-tenant AI workloads
✅ Enterprise governance
✅ Safer autonomous agents
✅ Easier compliance audits
✅ Portable actor deployments
✅ Runtime independence

---

Summary

The core idea:

Move sandbox permissions from hidden implementation details into a declarative ActorTemplate security contract.

The sandbox remains the authority for default security, but actors can request controlled capabilities through a validated policy layer.

The result is a more flexible, portable, and secure architecture for running autonomous actors at scale.