The `syscalls` Task

Type: Source
Output: syscall

syscalls is a tracing task that produces syscall events containing process information, function name, and arguments. The data is collected at the sys_enter tracepoint to ensure we have full visibility into all syscalls.

Quick Intro to Capability Sets

During its lifetime, a process holds five capability sets.

Inherited: All capabilities that are allowed to be inherited from a parent process.
Permitted: A set of capabilities that the process may add to effective or inherited.
Effective: All capabilities the process is using at the moment. Capabilities may move a capability from permitted to effective and back as needed.
Bound: Restricts the capabilities a process may receive. Only capabilities in the Bounded set will be allowed in the Permitted and inheritable set. Essentially an upper-bound of capabilities.
Ambient: Capabilities that are preserved across calls to execve by a program that is not privileged. No capability can ever be ambient if it is not both permitted and inheritable.

Tawon conditions can be set for each individual capability and used to filter based on each capability set individually. For example, to target all processes with the CAP_NET_RAW capability in either its effective or ambient capability sets run the command below. This command will also monitor the read and write system calls.

tawonctl d sub -c "process.capeff:CAP_NET_RAW OR process.capamb:CAP_NET_RAW" -t "syscalls|functions:read+write"

Configuration options

functions

functions accepts a subset of linux syscalls defined in the syscalls man page . The keyword "ALL" (case insensitive) can be used to hook all syscalls. This option is not compatible with reading functions from a file; use one or the other to target functions.

For example, to target all processes with permitted capabilities (capprm) that contain "NET" and hook the sendto and recvfrom syscalls

tawonctl d sub -c "process.capprm:~NET~" -t "syscalls|functions:sendto+recvfrom"

To target a process named ‘curl’ and hook all syscalls`

tawonctl d sub -c "process.name:curl" -t "syscalls|functions:ALL"

You can also use the '@' symbol to read functions from a relative file

tawonctl directive sub -t "syscalls|functions:@/tmp/mysyscalls.txt"

And a - can be used to read from stdin.

echo "send_msg+recv_msg+read+write+open" | tawonctl directive sub -t "syscalls|functions:@-"

capabilities

capabilities accepts a small subset of linux capabilities defined in the capabilities man page. This will hook syscall functions associated with that capability. As there is no official documentation of which capabilities are associated with which functions, the functions we hook here are based on research, testing, and the capabilities man pages.

For example, to target all processes with the CAP_NET_RAW capability and hook all syscalls associated with CAP_NET_RAW

tawonctl d sub -c "process.capprm:CAP_NET_RAW" -t "syscalls|capabilities:CAP_NET_RAW"

The currently supported Linux Capabilities.

Capability

Functions

CAP_NET_RAW

socket, sendto, recvfrom, recvmsg, bind, setsockopt, ioctl

CAP_NET_ADMIN

bind, connect, listen, accept, setsockopt, getsockopt, getsockname, getpeername, ioctl, recvfrom

CAP_IPC_LOCK

munlock, mlockall, munlockall, shmget, shmat, shmdt, shmctl, msgget, msgsnd, msgrcv, msgctl, semget, semop, semctl

CAP_SYS_PTRACE

ptrace, process_vm_readv, process_vm_writev, kcmp, get_robust_list, set_robust_list

compact

default false By default compact mode is disabled. Compact mode generates syscall events that do not include the arguments.

For example, to Target all processes with the CAP_NET_RAW capability and hook all syscalls associated with CAP_NET_RAW and generate compact output

tawonctl d sub -c "process.capprm:CAP_NET_RAW" -t "syscalls|capabilities:CAP_NET_RAW;compact:true"

meta

default "" Meta allows you configure exactly what metadata (process, container, and pod info) will be published with the payload message. See Configuring the meta Field for more information.

For example:

meta: process.name+pod.min

demo

demo runs a demo in the background that simulates a set of syscalls that can be used to demonstrate that the task is working and in a good condition.

Supported simulations

Simulation

Functions

cap_chown

chown

cap_ipc_lock

mlockall, mlock

cap_kill

kill

cap_net_raw

socket, setsockopt, bind

cap_setuid

setuid, setreuid

cap_sys_chroot

chroot, setns

cap_sys_ptrace

ptrace

all

Runs all simulations above

demiInterval: demoInterval accepts an integer that dictates the amount of time the task will sleep between simulations. (defaults to 10 seconds)

Sample Command Lines

The example below targets pods with the CAP_NET_RAW capability in the default namespace that have the label 'prod'. It will hook all syscalls associated with the CAP_NET_RAW capability (see above for full list of functions)

tawonctl d sub -c "process.capprm:CAP_NET_RAW AND pod.namespace:default AND pod.label:prod" -t "syscalls|capabilities:CAP_NET_RAW"

Similarly, the example below targets pods with the CAP_NET_RAW capability in the default namespace that have the label 'prod'. However, this command will only hook the sendto and recvfrom syscalls.

tawonctl d sub -c "process.capprm:CAP_NET_RAW AND pod.namespace:default AND pod.label:prod" -t "syscalls|functions:sendto+recvfrom"

Note that it’s not necessary to have CAP_NET_RAW in both the condition and the syscall options. You can filter for pods that have that capability and hook whichever functions you want. The CAP_NET_RAW in the syscall configuration is just shorthand for a hardcoded set of functions

The example below shows how to run syscalls with a cap_chown demo in the background. Note that we still need to have a condition, in this case process.name, as tasks won’t run without at least one condition, but any condition will do here.

tawonctl d sub -c "process.name:*"  -t "syscalls|functions:chown;demo:cap_chown"

Conditions

syscalls requires one of the following Conditions to be defined:

process.pid: Filtering syscalls to collect by Process PID.
process.name: Filtering syscalls to collect by Process Name.
process.cmd: Filtering syscalls to collect by Process Command.
process.exe: Filtering syscalls to collect by Process Executable.
process.capinh: Filtering syscalls to collect by Process' Inherited capabilities.
process.capprm: Filtering syscalls to collect by Process' Permitted capabilities.
process.capeff: Filtering syscalls to collect by Process' Effective capabilities.
process.capbnd: Filtering syscalls to collect by Process' Bound capabilities.
process.capamb: Filtering syscalls to collect by Process' Ambient capabilities.
container.id: Filtering syscalls to collect by Container ID/UID.
container.name: Filtering syscalls to collect by Container Name.
container.label: Filtering syscalls to collect by Container Label value or key=value.
pod.id: Filtering syscalls to collect by Pod ID/UID.
pod.name: Filtering syscalls to collect by Pod Name.
pod.namespace: Filtering syscalls to collect by Pod K8s Namespace.
pod.label: Filtering syscalls to collect by Pod Label value or key=value.

syscalls will not produce data without a Condition.

Output

syscall: map Holds the syscalls output.
syscall.args: map Holds the syscall argument names and values.
syscall.args.name: string Holds the name of the syscall argument.
syscall.args.value: string Holds the name of the syscall argument.
syscall.function: string|uint64 Holds the valueof the syscall argument.
syscall.process: map Holds the Process information.
syscall.process.pid: uint32 Process PID.
syscall.process.ppid: uint32 Process Parent PID.
syscall.process.name: string Process name.
syscall.process.cmd: string Command line string.
syscall.process.exe: string Executable name.
syscall.process.ns: string Namespace in the format of {device ID}-{inode number}.
syscall.process.startedAt: string Time the process started.
syscall.process.container: map Container information for process (if it is a container).
syscall.process.container.ID: string ID of Container.
syscall.process.container.Name: string Name of Container.

Sample output.

  "data": [
    {
      "data": {
        "args": [
          {
            "name": "fd",
            "value": 1
          },
          {
            "name": "buf",
            "value": "+"
          },
          {
            "name": "count",
            "value": 1
          }
        ],
        "function": "write",
        "process": {
          "cmd": "/app/simulator -sims webfetch -loop",
          "container": {
            "id": "780f159f59c75b09da4103566b39d3ea3793beb20a11d0e8e1056637036472fe",
            "name": "/minikube"
          },
          "exe": "/app/simulator",
          "name": "simulator",
          "ns": "4-4026533309",
          "pid": 1644020,
          "ppid": 1643994,
          "startedAt": "2023-12-11T21:04:00Z"
        }
      },
      "type": "syscalls"
    }
  ],
  "src": {
    "directiveID": "clroeh9eo0msn9golhkg",
    "hostname": "8e77aad68513",
    "instanceID": "clroefpeo0msnck6dus0",
    "name": "syscalls",
    "tawonID": "cfr7vtqm49rliqd1vs0g"
  },
  "timestamp": "2023-12-11T22:03:59.277299703Z"
}