{"id":29553436,"url":"https://github.com/fededp/container_plugin","last_synced_at":"2025-07-18T06:38:07.058Z","repository":{"id":265282039,"uuid":"878485183","full_name":"FedeDP/container_plugin","owner":"FedeDP","description":"Falco container plugin","archived":false,"fork":false,"pushed_at":"2025-03-17T13:40:51.000Z","size":527,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T14:42:36.372Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FedeDP.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-25T13:33:08.000Z","updated_at":"2025-03-17T13:40:55.000Z","dependencies_parsed_at":"2025-01-16T11:58:22.123Z","dependency_job_id":"ee67593e-64a0-40a0-adb6-4798980e3a99","html_url":"https://github.com/FedeDP/container_plugin","commit_stats":null,"previous_names":["fededp/container_plugin"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/FedeDP/container_plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedeDP%2Fcontainer_plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedeDP%2Fcontainer_plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedeDP%2Fcontainer_plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedeDP%2Fcontainer_plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FedeDP","download_url":"https://codeload.github.com/FedeDP/container_plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedeDP%2Fcontainer_plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265711488,"owners_count":23815546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-18T06:38:06.421Z","updated_at":"2025-07-18T06:38:07.041Z","avatar_url":"https://github.com/FedeDP.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Container metadata enrichment Plugin\n\n## Experimental\n\nConsider this plugin as experimental until it reaches version `1.0.0`. By 'experimental' we mean that, although the plugin is functional and tested, it is currently in active development and may undergo changes in behavior as necessary, without prioritizing backward compatibility.\n\n## Introduction\n\nThe `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](#supported-fields).\n\n### Functionality\n\nThe 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.  \nMoreover, 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 \na single event metadata.\n\n## Capabilities\n\nThe `container` plugin implements the following capabilities:\n\n* `capture listening` -\u003e to attach `container_id` foreign key to all pre-existing threadinfos, once they have been scraped from procfs by sinsp \n* `extraction` -\u003e to extract `container.X` fields\n* `parsing` -\u003e 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\n* `async` -\u003e to generate events with container information and `dump` current plugin cache state when requested\n\nIt requires **3.10.0** plugin API version.\n\n## Architecture\n\n![](./architecture.svg)\n\nThe `container` plugin is split into 2 modules:\n* a [C++ shared object](src) that implements the 3 capabilities and holds the cache map `\u003ccontainer_id,container_info\u003e`\n* a [GO static library](go-worker) (linked inside the C++ shared object) that implements the worker logic to retrieve new containers' metadata leveraging existing SDKs\n\nAs 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. \nWhenever the GO worker finds a new container, it immediately generates an `async` event through the aforementioned callback.\nThe `async` event is then received by the C++ side as part of the `parsing` capability, and it enriches its own internal state cache.\nEvery 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.\nOnce 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.\n\nNote, 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.  \nGiven 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.\n\n### Plugin official name\n\n`container`\n\n### Supported Fields\n\n\u003c!-- README-PLUGIN-FIELDS --\u003e\n| NAME                                | TYPE      | ARG                  | DESCRIPTION                                |\n|-------------------------------------|-----------|----------------------|--------------------------------------------|\n| `container.id`                      | `string`  | None                 | Container ID (first 12B).                  |\n| `container.full_id`                 | `string`  | None                 | Container ID.                              |\n| `container.name`                    | `string`  | None                 | Container name.                            |\n| `container.image`                   | `string`  | None                 | Image name.                                |\n| `container.image.id`                | `string`  | None                 | Image ID.                                  |\n| `container.type`                    | `string`  | None                 | Type.                                      |\n| `container.privileged`              | `bool`    | None                 | Privileged.                                |\n| `container.mounts`                  | `string`  | None                 | Mounts.                                    |\n| `container.mount`                   | `string`  | Idx or Key, Required | Mount.                                     |\n| `container.mount.source`            | `string`  | Idx or Key, Required | Mount Source.                              |\n| `container.mount.dest`              | `string`  | Idx or Key, Required | Mount Destination.                         |\n| `container.mount.mode`              | `string`  | Idx or Key, Required | Mount Mode.                                |\n| `container.mount.rdwr`              | `string`  | Idx or Key, Required | Mount Read/Write.                          |\n| `container.mount.propagation`       | `string`  | Idx or Key, Required | Mount Propagation.                         |\n| `container.image.repository`        | `string`  | None                 | Repository.                                |\n| `container.image.tag`               | `string`  | None                 | Image Tag.                                 |\n| `container.image.digest`            | `string`  | None                 | Registry Digest.                           |\n| `container.healthcheck`             | `string`  | None                 | Health Check.                              |\n| `container.liveness_probe`          | `string`  | None                 | Liveness.                                  |\n| `container.readiness_probe`         | `string`  | None                 | Readiness.                                 |\n| `container.start_ts`                | `abstime` | None                 | Container start.                           |\n| `container.duration`                | `reltime` | None                 | Container duration.                        |\n| `container.ip`                      | `string`  | None                 | Container IP.                              |\n| `container.cni.json`                | `string`  | None                 | Container's / pod's CNI result json.       |\n| `container.host_pid`                | `bool`    | None                 | Host PID Namespace.                        |\n| `container.host_network`            | `bool`    | None                 | Host Network Namespace.                    |\n| `container.host_ipc`                | `bool`    | None                 | Host IPC Namespace.                        |\n| `container.label`                   | `string`  | Key, Required        | Container Label                            |\n| `container.labels`                  | `string`  | None                 | Container Labels                           |\n| `proc.is_container_healthcheck`     | `bool`    | None                 | Process Is Container Healthcheck.          |\n| `proc.is_container_liveness_probe`  | `bool`    | None                 | Process Is Container Liveness.             |\n| `proc.is_container_readiness_probe` | `bool`    | None                 | Process Is Container Readiness.            |\n| `k8s.pod.name`                      | `string`  | None                 | Pod Name                                   |\n| `k8s.ns.name`                       | `string`  | None                 | Namespace Name                             |\n| `k8s.pod.id`                        | `string`  | None                 | Legacy Pod ID                              |\n| `k8s.pod.uid`                       | `string`  | None                 | Pod UID                                    |\n| `k8s.pod.sandbox_id`                | `string`  | None                 | Pod / Sandbox ID (first 12 chars)          |\n| `k8s.pod.full_sandbox_id`           | `string`  | None                 | Pod / Sandbox ID                           |\n| `k8s.pod.label`                     | `string`  | Key, Required        | Pod Label                                  |\n| `k8s.pod.labels`                    | `string`  | None                 | Pod Labels                                 |\n| `k8s.pod.ip`                        | `string`  | None                 | Pod Ip                                     |\n| `k8s.pod.cni.json`                  | `string`  | None                 | Pod CNI result json                        |\n| `k8s.rc.name`                       | `string`  | None                 | [Deprecated] Replication Controller Name   |\n| `k8s.rc.id`                         | `string`  | None                 | [Deprecated] Replication Controller ID     |\n| `k8s.rc.label`                      | `string`  | Key, Required        | [Deprecated] Replication Controller Label  |\n| `k8s.rc.labels`                     | `string`  | None                 | [Deprecated] Replication Controller Labels |\n| `k8s.svc.name`                      | `string`  | None                 | [Deprecated] Service Name                  |\n| `k8s.svc.id`                        | `string`  | None                 | [Deprecated] Service ID                    |\n| `k8s.svc.label`                     | `string`  | Key, Required        | [Deprecated] Service Label                 |\n| `k8s.svc.labels`                    | `string`  | None                 | [Deprecated] Service Labels                |\n| `k8s.ns.id`                         | `string`  | None                 | [Deprecated] Namespace ID                  |\n| `k8s.ns.label`                      | `string`  | Key, Required        | [Deprecated] Namespace Label               |\n| `k8s.ns.labels`                     | `string`  | None                 | [Deprecated] Namespace Labels              |\n| `k8s.rs.name`                       | `string`  | None                 | [Deprecated] Replica Set Name              |\n| `k8s.rs.id`                         | `string`  | None                 | [Deprecated] Replica Set ID                |\n| `k8s.rs.label`                      | `string`  | Key, Required        | [Deprecated] Replica Set Label             |\n| `k8s.rs.labels`                     | `string`  | None                 | [Deprecated] Replica Set Labels            |\n| `k8s.deployment.name`               | `string`  | None                 | [Deprecated] Deployment Name               |\n| `k8s.deployment.id`                 | `string`  | None                 | [Deprecated] Deployment ID                 |\n| `k8s.deployment.label`              | `string`  | Key, Required        | [Deprecated] Deployment Label              |\n| `k8s.deployment.labels`             | `string`  | None                 | [Deprecated] Deployment Labels             |\n \n\u003c!-- /README-PLUGIN-FIELDS --\u003e\n\n## Requirements\n\n* `containerd` \u003e= 1.7 (https://kubernetes.io/docs/tasks/administer-cluster/switch-to-evented-pleg/, https://github.com/containerd/containerd/pull/7073)\n* `cri-o` \u003e= 1.26 (https://kubernetes.io/docs/tasks/administer-cluster/switch-to-evented-pleg/)\n* `podman` \u003e= v4.0.0 (2.0.0 introduced https://github.com/containers/podman/commit/165aef7766953cd0c0589ffa1abc25022a905adb, but the client library requires 4.0.0)\n\n## Usage\n\n### Configuration\n\nHere's an example of configuration of `falco.yaml`:\n\n```yaml\nplugins:\n  - name: container\n    # path to the plugin .so file\n    library_path: libcontainer.so\n    init_config:\n      label_max_len: 100 # (optional, default: 100; container labels larger than this won't be reported)\n      with_size: false # (optional, default: false; whether to enable container size inspection, which is inherently slow)\n      engines:\n        docker:\n          enabled: true\n          sockets: ['/var/run/docker.sock']\n        podman:\n          enabled: true\n          sockets: ['/run/podman/podman.sock', '/run/user/1000/podman/podman.sock']\n        containerd:\n          enabled: true\n          sockets: ['/run/containerd/containerd.sock']\n        cri:\n          enabled: true\n          sockets: ['/run/crio/crio.sock']\n        lxc:\n          enabled: false\n        libvirt_lxc:\n          enabled: false\n        bpm:\n          enabled: false  \n\nload_plugins: [container]\n```\n\nBy default, all engines are enabled on **default sockets**:\n* Docker: `/var/run/docker.sock`\n* Podman: `/run/podman/podman.sock` for root, + `/run/user/$uid/podman/podman.sock` for each user in the system\n* Containerd: [`/run/containerd/containerd.sock`, `/run/k3s/containerd/containerd.sock`, `/run/host-containerd/containerd.sock`]\n* Cri: `/run/crio/crio.sock`\n\n### Rules\n\nThis plugin doesn't provide any custom rule, you can use the default Falco ruleset and add the necessary `container` fields.\nNote: leveraging latest plugin SDK features, the plugin itself will expose certain fields as suggested output fields:\n* `container.id`\n* `container.name`\n\n### Running\n\nThis plugin requires Falco with version \u003e= **0.41.0**.\nThe plugin is bundled within Falco, so you only need to run Falco as you would do normally.\n\n## Local development\n\n### Build and test\n\nBuild the plugin on a fresh `Ubuntu 22.04` machine:\n\n```bash\nsudo apt update -y\nsudo apt install -y cmake build-essential autoconf libtool pkg-config\ngit clone https://github.com/falcosecurity/plugins.git\ncd plugins/container\nmake libcontainer.so\n```\n\nYou can also run `make exe` from withing the `go-worker` folder to build a `worker` executable to test the go-worker implementation.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffededp%2Fcontainer_plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffededp%2Fcontainer_plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffededp%2Fcontainer_plugin/lists"}