The container plugin enhances the Falco syscall source by providing additional information about container resources involved. You can find the comprehensive list of supported fields here.

The plugin itself reimplements all the container-related logic that was already present in libs under the form of a plugin, that can be attached to any source.
Moreover, it aims to fix issues present in the current implementation, trying to be as quick as possible to gather container metadata information, to avoid losing a single event metadata.

The container plugin implements the following capabilities:

• capture listening -> to attach container_id foreign key to all pre-existing threadinfos, once they have been scraped from procfs by sinsp
• extraction -> to extract container.X fields
• parsing -> to parse async and container events (the latter for backward compatibility with existing scap files), and clone/fork/execve events to attach container_id foreign key to any threads
• async -> to generate events with container information and dump current plugin cache state when requested

It requires 3.10.0 plugin API version.

The container plugin is split into 2 modules:

• a C++ shared object that implements the 3 capabilities and holds the cache map <container_id,container_info>
• a GO static library (linked inside the C++ shared object) that implements the worker logic to retrieve new containers' metadata leveraging existing SDKs

As soon as the plugin starts, the go-worker gets started as part of the async capability, passing to it plugin init config and a C++ callback to generate async events. Whenever the GO worker finds a new container, it immediately generates an async event through the aforementioned callback. The async event is then received by the C++ side as part of the parsing capability, and it enriches its own internal state cache. Every time a clone/fork/execve event gets parsed, we attach to its thread table entry the information about the container_id, extracted by looking at the cgroups field, in a foreign key. Once the extraction is requested for a thread, the container_id is then used as key to access our plugin's internal container metadata cache, and the requested infos extracted.

Note, however, that for some container engines, namely {bpm,lxc,libvirt_lcx}, we only support fetching generic info, ie: the container ID and the container type.
Given that there is no "listener" SDK to attach to, for these engines the async event is generated directly by the C++ code, as soon as the container ID is retrieved.

container

• containerd >= 1.7 (https://kubernetes.io/docs/tasks/administer-cluster/switch-to-evented-pleg/, containerd/containerd#7073)
• cri-o >= 1.26 (https://kubernetes.io/docs/tasks/administer-cluster/switch-to-evented-pleg/)
• podman >= v4.0.0 (2.0.0 introduced https://github.com/containers/podman/commit/165aef7766953cd0c0589ffa1abc25022a905adb, but the client library requires 4.0.0)

By default, all engines are enabled on default sockets:

• Docker: [/var/run/docker.sock]
• Podman: [/run/podman/podman.sock for root, + /run/user/$uid/podman/podman.sock for each user in the system]
• Containerd: [/run/host-containerd/containerd.sock]
• Cri: [/run/containerd/containerd.sock, /run/crio/crio.sock, /run/k3s/containerd/containerd.sock, /run/host-containerd/containerd.sock]

Here's an example of configuration of falco.yaml:

plugins:
  - name: container
    # path to the plugin .so file
    library_path: libcontainer.so
    init_config:
      label_max_len: 100 # (optional, default: 100; container labels larger than this won't be reported)
      with_size: false # (optional, default: false; whether to enable container size inspection, which is inherently slow)
      hooks: ['create', 'start'] # (optional, default: 'create'. Some fields might not be available in create hook, but we are guaranteed that it gets triggered before first process gets started)
      engines:
        docker:
          enabled: true
          sockets: ['/var/run/docker.sock']
        podman:
          enabled: true
          sockets: ['/run/podman/podman.sock', '/run/user/1000/podman/podman.sock']
        containerd:
          enabled: true
          sockets: ['/run/containerd/containerd.sock']
        cri:
          enabled: true
          sockets: ['/run/crio/crio.sock']
        lxc:
          enabled: false
        libvirt_lxc:
          enabled: false
        bpm:
          enabled: false  

load_plugins: [container]

This plugin doesn't provide any custom rule, you can use the default Falco ruleset and add the necessary container fields. Note: leveraging latest plugin SDK features, the plugin itself will expose certain fields as suggested output fields:

• container.id
• container.name

This plugin requires Falco with version >= 0.41.0. The plugin is bundled within Falco, so you only need to run Falco as you would do normally.

Build the plugin on a fresh Ubuntu 22.04 machine:

sudo apt update -y
sudo apt install -y cmake build-essential autoconf libtool pkg-config
git clone https://github.com/falcosecurity/plugins.git
cd plugins/container
make libcontainer.so

You can also run make exe from withing the go-worker folder to build a worker executable to test the go-worker implementation.