StackRox Collector: the node agent that gathers runtime data

An agent on every node under a performance budget

Collector is the StackRox component responsible for gathering runtime data, and the project states the design constraint up front: it is an agent that runs on every node under strict performance limitations. That single sentence explains the shape of the repository. A component scheduled onto every machine in a cluster cannot be casually heavy, so the top level is dominated by build plumbing rather than by feature code: CMakeLists.txt, CMakePresets.json, vcpkg.json, vcpkg-configuration.json, a Makefile that reads nproc, and .clang-format and .clangd for the C++ sources. The code is C++, the license is Apache-2.0, the default branch is master, and the last recorded push to it is dated 2026-09-28. Nothing here suggests a side project; the work is current and the repository is not archived.

Kernel modules or eBPF probes, with one default

Collection happens in one of two ways. The project gathers data via kernel modules or via eBPF probes, and eBPF is the default collection mode nowadays, as the README puts it. So there is a legacy path and a current path, and the current one won by default rather than by removal. What the published documentation does not say is how a deployment picks a mode: no flag, no configuration key and no environment variable appears for it in the README, and the five docs files are only named, not quoted. The configuration surface is said to live in docs/references.md, which is described as the full list of configuration options for the project. Anyone rolling this out should read that file before assuming eBPF is the only supported path, and before assuming kernel modules are still wired up.

Falco libraries arrive through a custom fork

The eBPF side is not built against upstream Falco. To implement the probes, the project leverages the Falco libraries through a custom fork, stackrox/falcosecurity-libs, and the README links that fork directly. The top level of the tree carries a falcosecurity-libs entry next to .gitmodules, which is how a forked dependency is wired into a checkout, so the fork is part of the build rather than an optional extra. Two consequences follow. Building from source resolves the fork during checkout, and tracking changes in the probe machinery means following StackRox's copy rather than the original project, whose own release cycle will not line up with the collector's. docs/how-to-start.md is the file named for building and troubleshooting the project from scratch, and it is the right starting point for that first build.

Every top-level make target delegates into collector/

The top-level Makefile is a dispatcher rather than a build script. It sets NPROCS from nproc, defaults BUILD_BUILDER_IMAGE to false, exports COLLECTOR_VERSION from COLLECTOR_TAG, includes Makefile-constants.mk, and then forwards to subdirectories. The three everyday targets are one line each:

make -C collector collector
make -C collector connscrape
make -C collector unittest

Each forwards to the same named target inside collector/, so the real rules sit one directory down. connscrape is exposed at the top level without any note about what it collects, which makes it the least explained entry point in the file. Integration work is delegated the same way: integration-tests-report runs make -C integration-tests report, ci-integration-tests runs make -C integration-tests ci-integration-tests, and ci-all-tests depends on both ci-benchmarks and ci-integration-tests. Reading this file is the fastest way to learn the project's own vocabulary.

Two runtime images built from one Dockerfile each

Runtime images come out of docker buildx. The image target builds the component, runs make -C collector txt-files, then builds collector/container/Dockerfile into the collector repository on quay.io, tagged with COLLECTOR_TAG:

image: collector
	make -C collector txt-files
	docker buildx build --load --platform ${PLATFORM} \
		--build-arg COLLECTOR_VERSION="$(COLLECTOR_TAG)" \
		-f collector/container/Dockerfile \
		-t quay.io/stackrox-io/collector:$(COLLECTOR_TAG) \
		$(COLLECTOR_BUILD_CONTEXT)

A parallel image-dev target produces the same tag from collector/container/dev.Dockerfile instead. Both depend on a builder image: with BUILD_BUILDER_IMAGE left at false the Makefile pulls the collector-builder image for the requested platform, and setting it to anything else builds builder/Dockerfile locally. Platform, tag and build context are variables, not literals, so a cluster-specific image comes from overriding them rather than from editing the file.

The newest tag is v3.4.1 from 2021 while branches track 3.2x

Two release systems disagree about how recent this project is, and the difference is large. The GitHub releases stop at v3.4.1, published 2021-10-07, preceded by v3.3.0 on 2021-08-31 and v3.2.2 on 2021-08-30. The README table, by contrast, tracks master next to release-3.24, release-3.23 and release-3.22, pairs every branch with an upstream main.yml workflow and a downstream konflux.yml workflow, and maps those branches onto stackrox release-4.10, release-4.9 and release-4.8. The branch table is the live release channel; the tags are history. Anyone pinning a version by tag would pin a 2021 artifact, while code that ships today sits on branches named for the 3.2x line, and a 2026-09-28 push to master says the branch itself is still moving.

Five documentation files and a tree full of build config

The README is a table of contents, not a manual. It points to docs/how-to-start.md for building and troubleshooting from scratch, docs/design-overview.md for how the collector fits into the wider platform, docs/troubleshooting.md for common startup errors and ways of identifying and fixing them, docs/release.md with tips for the release process, and docs/references.md as the full list of configuration options. The rest of the top level describes the kind of project this is: .adr/ for architecture decision records, .tekton/ for pipelines, ansible/ and utilities/ for deployment helpers, githooks/ for local commit hooks, .pre-commit-config.yaml and .flake8 for Python tooling, .syft.yaml for software bill of materials, and rpms.in.yaml with rpms.lock.yaml and rpms.rhel.repo for RPM packaging. A C++ project shipping RPMs, Tekton pipelines and Ansible roles has an operations surface far larger than a three line summary suggests.

Editorial conclusion

StackRox Collector is an actively worked on, Apache-2.0 C++ component whose real behaviour lives in docs/ and collector/ rather than in its short README. It suits a team already running the StackRox Kubernetes Security Platform and prepared to read docs/references.md for the configuration surface. It does not suit someone looking for a quick install, because no install command is published and the newest GitHub tag, v3.4.1 from 2021-10-07, is far behind the release-3.24 and release-3.22 branches that ship today. Before adopting it, confirm which branch your platform version expects, how the Falco fork is pinned, and what the configuration options actually default to.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes