Add the SYS_PTRACE Linux Kernel Capability
Learn how to add the SYS_PTRACE Linux kernel capability when deploying your stub images

Overview

To optimize and secure your application, RapidFort must be able to trace the runtime behavior and generate a runtime profile while the stub image is deployed and running. Tracing the runtime behavior of the stub image has additional requirements. In particular, the SYS_PTRACE Linux kernel capability must be added.
Review: A stub image is the original image built with additional dependencies necessary for RapidFort to trace the runtime behavior and generate the runtime profile.
In this guide, we will learn how to add SYS_PTRACE when deploying the stub image.
For more information on SYS_PTRACE, please view the capabilities(7) Linux manual page.
During initialization, the stub image will try to detect if SYS_PTRACE has been added. If SYS_PTRACE has not been added, then the stub image will fail to run.

Add SYS_PTRACE

Docker

Add --cap-add=SYS_PTRACE to the docker run command.
1
docker run --cap-add=SYS_PTRACE <flags> <stub image>
Copied!
For example:
1
docker run --cap-add=SYS_PTRACE -p9999:80 --name=nginx-rf-test docker.io/library/nginx:latest-rfstub
Copied!
For more information, please view the Docker run reference.

Docker-Compose

Add a section called cap_add and a SYS_PTRACE list item to the Compose yaml file.
1
cap_add:
2
- SYS_PTRACE
Copied!
For more information, please view the Docker-Compose specification.

Kubernetes

Add a securityContext section to the Kubernetes manifest file.
1
securityContext:
2
capabilities:
3
add: ["SYS_PTRACE"]
4
allowPrivilegeEscalation: true
5
readOnlyRootFilesystem: false
Copied!
allowPrivilegeEscalation and readOnlyRootFilesystem are not directly related to adding SYS_PTRACE, but these are required for RapidFort to trace the runtime behavior of the stub image and must also be specified in the securityContext when deploying the stub image.
For more information, please view the Kubernetes documentation.

AWS Fargate

Add a "capabilities" section to the "linuxParameters" section in the AWS Fargate task definition.
1
"linuxParameters": {
2
"capabilities": {
3
"add": [
4
"SYS_PTRACE"
5
]
6
}
7
}
Copied!

Next Steps

Verify that Profiling Information is Propagated to RapidFort

Adding SYS_PTRACE is one requirement for profiling your stub image. You will need to verify that the stub image is able to send profiling information to RapidFort.

Run Coverage Tests for the Application

While your stub image is deployed, run coverage tests to exercise the functionalities of the application. The goal is to ensure that all required files and dependencies are detected while the runtime behavior of the stub image is being traced. This reduces the risk that required files will be removed during the hardening process.
Use it or lose it! If a file is not detected as being used during runtime tracing, then it may be removed during the hardening process.

Harden the Stub Image

Congratulations! Your stub image is now ready to be hardened. Run rfharden <stub_image> to optimize and secure your image.
Adding SYS_PTRACE is not required when running the hardened image (unless this is required by your application). RapidFort does not leave any runtime tracing dependencies in the hardened image.