Troubleshoot: missing SYS_PTRACE capability

Subtrace requires the SYS_PTRACE Linux capability in order to work correctly. Expand the environment you’re using to find the exact change to make.

Docker (docker run)

If you’re using Subtrace in a Docker container via docker run, add --cap-add=SYS_PTRACE when starting your container. For example:

docker run -it --rm --cap-add=SYS_PTRACE debian:12

Docker Compose

Add cap_add: [SYS_PTRACE] to your service in compose.yaml:

services:
  my-app:
    image: ghcr.io/NAMESPACE/IMAGE_NAME:latest
    command: "subtrace run -- ./start.sh"
    cap_add:
      - SYS_PTRACE

Kubernetes (Deployments/Pods)

Add the capability in the container securityContext:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-container
        image: ghcr.io/NAMESPACE/IMAGE_NAME:latest
        securityContext:
          capabilities:
            add:
              - SYS_PTRACE

Amazon ECS (Fargate)

The ECS console UI does not expose linuxParameters.capabilities. Create a new task definition revision and edit the JSON to include SYS_PTRACE:

"linuxParameters": {
  "capabilities": {
    "add": ["SYS_PTRACE"]
  }
},

Flightcontrol

Add the linuxCapabilities section to your flightcontrol.json:

"target": {
  "type": "fargate",
  "linuxCapabilities": {
    "add": ["SYS_PTRACE"]
  }
}