Manual Task Instrumentation

If you prefer to manually instrument your task definition rather than using serverless-patcher or including the Sysdig Workload Agent in your container image, you can follow these steps.

Secure the Containers with the Workload Agent

Compatible with: Workload Agent version 5.0 and later

To secure your containers with Workload Agent, do the following:

  1. Enable task pid mode at the task level:

    {
   "containerDefinitions": [...],
+  "pidMode": "task"
}

  2. Add the Sysdig sidecar container to your existing containerDefinitions.

    This Sysdig sidecar container initiates the Workload Agent to secure the containers specified in the task.

    1. Give it a name, such as sysdigInstrumentation.

    2. Use the quay.io/sysdig/workload-agent:latest image for this container, and leave the entryPoint and command fields empty.

  3. Provide the sidecar container with the following environment variables:

    • SYSDIG_COLLECTOR, SYSDIG_COLLECTOR_PORT and SYSDIG_ACCESS_KEY

    • SYSDIG_PRIORITY: Specify either availability or security, depending on your use case.

    • SYSDIG_SIDECAR : Set to auto.

    This allows the Workload Agent to reach the Sysdig Collector.

    {
  ...
  "containerDefinitions": [
    ...
+   {
+     "name": "sysdigInstrumentation",
+     "image": "quay.io/sysdig/workload-agent:latest"
+     "environment": [
+       {
+           "name": "SYSDIG_COLLECTOR",
+           "value": "collector.sysdigcloud.com"
+       },
+       {
+           "name": "SYSDIG_COLLECTOR_PORT",
+           "value": "6443"
+       },
+       {
+           "name": "SYSDIG_ACCESS_KEY",
+           "value": "access_key"
+       },
+       {
+           "name": "SYSDIG_PRIORITY",
+           "value": "availability"
+       },
+       {
+           "name": "SYSDIG_SIDECAR",
+           "value": "auto"
+       }
+     ]
+   }
  ]
}

  4. For each container you want to secure, add a volume mount from the sysdigInstrumentation sidecar container to your container.

    This provides the Sysdig’s userspace instrumentation to the container.

    {
  ...
  "containerDefinitions": [
    {
       "name": "my-container-1",
       "image": "myapp:latest",
       "entryPoint": ["my", "original", "entryPoint"],
       ...
+      "volumesFrom": [
+        {
+           "sourceContainer": "sysdigInstrumentation",
+           "readOnly": true
+        }
+      ]
    }
  ]
}

  5. For each container you want to secure, add the SYS_PTRACE Linux capability to enable userspace instrumentation.

    {
  ...
  "containerDefinitions": [
    {
      "name": "my-container-1",
      "image": "myapp:latest",
      "entryPoint": ["my", "original", "entryPoint"],
      ...
      "volumesFrom": [
        {
          "sourceContainer": "sysdigInstrumentation",
          "readOnly": true
        }
      ],
+     "linuxParameters": {
+       "capabilities": {
+         "add": ["SYS_PTRACE"]
+       }
+     }
    }
  ]
}

  6. For each container you want to secure, prepend /opt/draios/bin/instrument to the entryPoint.

    {
  ...
  "containerDefinitions": [
    {
      "name": "my-container-1",
      "image": "myapp:latest",
+     "entryPoint": ["/opt/draios/bin/instrument", "my", "original", "entryPoint"],
      ...
      "volumesFrom": [
        {
          "sourceContainer": "sysdigInstrumentation",
          "readOnly": true
        }
      ],
      "linuxParameters": {
        "capabilities": {
          "add": ["SYS_PTRACE"]
        }
      }
    }
  ]
}

    This enables the Sysdig instrumentation to run in the secured container.

  7. Provide each container you want to secure with the following environment variables:

    • SYSDIG_SIDECAR set to auto
    • SYSDIG_PRIORITY set to either availability or security, depending on your use case.
    {
  ...
  "containerDefinitions": [
    {
      "name": "my-container-1",
      "image": "myapp:latest",
      "entryPoint": ["/opt/draios/bin/instrument", "my", "original", "entryPoint"],
      ...
      "volumesFrom": [
        {
          "sourceContainer": "sysdigInstrumentation",
          "readOnly": true
        }
      ],
      "linuxParameters": {
        "capabilities": {
          "add": ["SYS_PTRACE"]
        }
      },
      "environment": [
        ...
+       {
+         "name": "SYSDIG_SIDECAR",
+         "value": "auto"
+       },
+       {
+         "name": "SYSDIG_PRIORITY",
+         "value": "availability"
+       }
      ]
    }
  ]
}

  8. Save your updated task definition, and then deploy it to your ECS cluster.

Example Instrumentation

The example guides you through manually instrumenting your task definition to deploy the Sysdig Workload Agent in availability mode. While this method demands more manual configuration compared to using serverless-patcher or embedding the Sysdig Workload Agent in your container image, it offers greater control over the instrumentation process.

For the following generic task definition:

{
  "containerDefinitions": [
    {
      "name": "my-container-1",
      "image": "myapp:latest",
      "entryPoint": ["my", "original", "entryPoint"],
      "command": ["my", "original", "command"],
      "environment": [
        {
          "name": "my-envar",
          "value": "my-value"
        }
      ]
    }
  ]
}

The instrumented version is:

{
  "containerDefinitions": [
    {
      "name": "my-container-1",
      "image": "myapp:latest",
+     "entryPoint": ["/opt/draios/bin/instrument", "my", "original", "entryPoint"],
      "command": ["my", "original", "command"]
      "environment": [
        {
          "name": "my-envar",
          "value": "my-value"
        },
+       {
+         "name": "SYSDIG_SIDECAR",
+         "value": "auto",
+       },
+       {
+         "name": "SYSDIG_PRIORITY",
+         "value": "availability",
+       }
      ],
+     "linuxParameters": {
+       "capabilities": {
+         "add": ["SYS_PTRACE"]
+       }
+     },
+     "volumesFrom": [
+       {
+         "sourceContainer": "sysdigInstrumentation",
+         "readOnly": true
+       }
+     ]
    },
+   {
+     "name": "sysdigInstrumentation",
+     "image": "quay.io/sysdig/workload-agent:latest"
+     "environment": [
+       {
+           "name": "SYSDIG_COLLECTOR",
+           "value": "collector.sysdigcloud.com"
+       },
+       {
+           "name": "SYSDIG_COLLECTOR_PORT",
+           "value": "6443"
+       },
+       {
+           "name": "SYSDIG_ACCESS_KEY",
+           "value": "0123456789abcdef"
+       },
+       {
+           "name": "SYSDIG_PRIORITY",
+           "value": "availability"
+       },
+       {
+           "name": "SYSDIG_SIDECAR",
+           "value": "auto"
+       }
+     ]
+   }
+ ],
+ "pidMode": "task"
}

Upgrade Workload Agent v4.x to 5.0

Given a generic task definition secured by the Workload Agent 4.x as the following:

{
   "containerDefinitions": [
      {
         "name": "my-container-1",
         "image": "myapp:latest",
         "entryPoint": ["/opt/draios/bin/instrument", "my", "original", "entryPoint"],
         "command": ["my", "original", "command"]
         "environment": [
            {
               "name": "my-envar",
               "value": "my-value"
            },
            {
               "name": "SYSDIG_COLLECTOR",
               "value": "collector.sysdig.com",
            },
            {
               "name": "SYSDIG_COLLECTOR_PORT",
               "value": "6443",
            },
            {
                "name": "SYSDIG_ACCESS_KEY",
                "value": "0123456789abcdef"
            }
         ],
         "linuxParameters": {
            "capabilities": {
               "add": ["SYS_PTRACE"]
            }
         },
         "volumesFrom": [
            {
               "sourceContainer": "sysdigInstrumentation",
               "readOnly": true
            }
         ]
      },
      {
        "name": "sysdigInstrumentation",
        "image": "quay.io/sysdig/workload-agent:4.3.2"
      }
   ]
}

  1. Turn on the task pid mode at the task level:

    {
   "containerDefinitions": [...],
+  "pidMode": "task"
}

  2. Update the Workload Agent image to v5.0.0:

    {
   "containerDefinitions": [
       ...,
       {
           "name": "sysdigInstrumentation",
+          "image": "quay.io/sysdig/workload-agent:5.0.0"
       }
   ],
   "pidMode": "task"
}

  3. Provide the following environment variables to the Sysdig sidecar container:

    • SYSDIG_COLLECTOR, SYSDIG_COLLECTOR_PORT and SYSDIG_ACCESS_KEY

    • SYSDIG_PRIORITY : Specify either availability or security, depending on your use case.

    • SYSDIG_SIDECAR: Set to to auto.

      {
   "containerDefinitions": [
      ...,
      {
         "name": "sysdigInstrumentation",
         "image": "quay.io/sysdig/workload-agent:5.0.0"
+        "environment": [
+           {
+              "name": "SYSDIG_COLLECTOR",
+              "value": "collector.sysdig.com",
+           },
+           {
+              "name": "SYSDIG_COLLECTOR_PORT",
+              "value": "6443",
+           },
+           {
+              "name": "SYSDIG_ACCESS_KEY",
+              "value": "0123456789abcdef",
+           },
+           {
+              "name": "SYSDIG_PRIORITY",
+              "value": "availability"
+           },
+           {
+              "name": "SYSDIG_SIDECAR",
+              "value": "auto"
+           }
+        ],
      }
   ]
}

  4. Add the environment variable, SYSDIG_SIDECAR="auto", to the secured container:

    {
   "containerDefinitions": [
      {
         "name": "my-container-1",
         "image": "myapp:latest",
         "entryPoint": ["/opt/draios/bin/instrument", "my", "original", "entryPoint"],
         "command": ["my", "original", "command"]
         "environment": [
            ...,
+           {
+              "name": "SYSDIG_SIDECAR",
+              "value": "auto",
+           }
         ],
         "linuxParameters": {
            "capabilities": {
               "add": ["SYS_PTRACE"]
            }
         },
         "volumesFrom": [
            {
               "sourceContainer": "sysdigInstrumentation",
               "readOnly": true
            }
         ]
      },
      {
         "name": "sysdigInstrumentation",
         "image": "quay.io/sysdig/workload-agent:5.0.0"
         "environment": [
            {
               "name": "SYSDIG_COLLECTOR",
               "value": "collector.sysdig.com",
            },
            {
               "name": "SYSDIG_COLLECTOR_PORT",
               "value": "6443",
            },
            {
               "name": "SYSDIG_ACCESS_KEY",
               "value": "0123456789abcdef",
            },
            {
               "name": "SYSDIG_PRIORITY",
               "value": "availability"
            },
            {
               "name": "SYSDIG_SIDECAR",
               "value": "auto"
            }
         ],
      }
   ]
}

Next Steps

After the deployment is completed, security-related events will be visible in the Sysdig Secure Events feed.

Optionally, you can perform advanced Configuration steps.