Audit integration into Node-agent #648

slashben · 2025-09-15T14:52:57Z

This pull request introduces a major new feature: integration of the Linux Audit subsystem into the Kubescape node-agent, alongside supporting documentation, code changes, and dependency updates. The audit subsystem provides kernel-level event filtering and real-time audit event streaming, operating independently from the existing eBPF-based runtime detection. The implementation includes new architecture, configuration, event processing, and testing strategies.

Linux Audit Subsystem Integration

Added a comprehensive design overview (AUDIT_DESIGN_OVERVIEW.md) detailing the architecture, rule processing pipeline, event flow, security, testing, and future enhancements for Linux Audit subsystem integration.
Implemented a new interface AuditManagerClient in pkg/auditmanager/audit_manager_interface.go, supporting real audit event management and a mock manager for disabled/testing states.
Integrated the audit manager into cmd/main.go: creates and starts the audit manager with dedicated configuration and exporters, supports independent operation from runtime detection, and ensures proper lifecycle management. [1] [2] [3] [4]

Testing & Documentation

Added a detailed testing guide (README_AUDIT_TESTING.md) covering unit, integration, and end-to-end tests, troubleshooting, configuration examples, and validation steps for the audit subsystem.

Dependency Updates

Updated go.mod to add dependencies for the audit subsystem and testing, including github.com/elastic/go-libaudit/v2 for kernel audit integration and github.com/golang/mock for mocking. [1] [2] [3]

github-actions · 2025-09-15T15:08:52Z

Summary:

License scan: success
Credentials scan: failure
Vulnerabilities scan: failure
Unit test: success
Go linting: failure

Signed-off-by: Ben <[email protected]>

Signed-off-by: Matthias Bertschy <[email protected]>

pkg/auditmanager/v1/audit_manager.go

+	containerID, err := am.processTreeManager.GetContainerIDForPid(event.PID)
+	if err != nil {
+		logger.L().Debug("failed to get container ID from process tree manager",
+			helpers.Int("pid", int(event.PID)),


To fix the incorrect integer conversion, we should ensure that when converting uint32(pid) (parsed from untrusted string input) to int (for logging), an explicit upper bound check for math.MaxInt32 is present. If the value exceeds math.MaxInt32, it should either be capped/truncated, or a fallback value used. This prevents potentially negative or unexpected values from being logged.
Specifically, in file pkg/auditmanager/v1/audit_manager.go, in the method enrichWithKubernetesContext, just before logging with helpers.Int("pid", int(event.PID)), we should check if event.PID (which is of type uint32) is <= math.MaxInt32 before casting. If not, log or handle the fact appropriately (e.g., log max value, or add a warning).
To implement the fix, we need to import "math", and replace the single call helpers.Int("pid", int(event.PID)) with something like:

helpers.Int("pid", safePidToInt(event.PID))

and define a helper function safePidToInt(pid uint32) int that performs the bound check.

pkg/auditmanager/v1/audit_manager.go

+	if event.PID == 0 || containerID == "" {
+		logger.L().Debug("skipping Kubernetes enrichment",
+			helpers.String("reason", "no PID or no container ID"),
+			helpers.Int("pid", int(event.PID)),


To fix the issue, we need to ensure that before converting a uint32 PID (from parsed input) to int, we check that its value does not exceed the maximum value for int (i.e., math.MaxInt32), and ideally is not negative (which can't occur for uint32, but input may wrap around if unchecked). We should update the code at line 1170 to check if event.PID is less than or equal to math.MaxInt32 before performing the cast, and use a safe default (such as -1) if it's not in range. This requires importing the math package if it is not already imported. The same check should be performed anywhere the conversion from uint32 (from parsed data) to int is made. In this file, the conversion of interest is on line 1170. The rest of the code shown already parses the PID from a string as a uint32, which is correct.

github-actions · 2025-10-01T12:19:04Z

Summary:

License scan: success
Credentials scan: failure
Vulnerabilities scan: failure
Unit test: success
Go linting: failure

matthyx

can you check the few comments?
I've also rebased on main and fixed the tests...

matthyx · 2025-10-01T08:11:22Z

cmd/main.go

+	err = auditManager.Start(ctx)
+	if err != nil {
+		logger.L().Ctx(ctx).Error("error starting the audit manager", helpers.Error(err))
+		// For POC, we'll continue even if audit manager fails to start


can you add a FIXME at the beginning of this comment to fix it later

matthyx · 2025-10-01T12:10:11Z

pkg/exporters/alert_manager.go

+			"description": fmt.Sprintf("Audit event of type '%s' detected", auditEvent.Type.String()),
+		},
+		Alert: models.Alert{
+			GeneratorURL: strfmt.URI("https://armosec.github.io/kubecop/alertviewer/"),


matthyx · 2025-10-01T12:28:50Z

pkg/exporters/auditbeat_exporter.go

+
+// AuditbeatEvent represents a metricbeat-compatible event structure
+// This mimics the mb.Event structure from metricbeat
+type AuditbeatEvent struct {


is it OK to exclude with json:"-"?

matthyx · 2025-10-02T09:52:21Z

pkg/auditmanager/v1/audit_manager.go

+	if exit, err := strconv.ParseInt(data["exit"], 10, 32); err == nil {
+		event.Exit = int32(exit)
+	} else {
+		event.Exit = -1 // FIXME: in case of non-numeric exit codes, such as "EACCES" or "EPERM" should we map them to numeric values?


@slashben check, this is important

slashben requested a review from matthyx September 15, 2025 14:52

matthyx added this to KS PRs tracking Sep 16, 2025

matthyx moved this to WIP in KS PRs tracking Sep 16, 2025

slashben marked this pull request as ready for review September 29, 2025 20:54

slashben and others added 15 commits October 1, 2025 12:48

Initial test version

7ca8c7e

Signed-off-by: Ben <[email protected]>

Implementing a robust event pipe

8491637

Signed-off-by: Ben <[email protected]>

Version working

2b9f509

Signed-off-by: Ben <[email protected]>

Loading all rules

aadecc9

Signed-off-by: Ben <[email protected]>

Redesigned rule loading

3647794

Signed-off-by: Ben <[email protected]>

Fixed keys and tags

bd67c17

Signed-off-by: Ben <[email protected]>

Kubernetes enrichment - not working completely

d053868

Signed-off-by: Ben <[email protected]>

Auditbeat exporter

17dbebb

Signed-off-by: Ben <[email protected]>

Updating user-guid to include helm

ec7767b

Signed-off-by: Ben <[email protected]>

Fix in example config

4968636

Signed-off-by: Ben <[email protected]>

Fixing success and actor fields (+uid)

74cdc8d

Signed-off-by: Ben <[email protected]>

Re-enabling cloud metadata

6ed2115

Signed-off-by: Ben <[email protected]>

refactor: restructure audit detection configuration and fix test

e6cee79

Signed-off-by: Matthias Bertschy <[email protected]>

fix: update audit rule keys to use plural form and fix tests

0cf34a0

Signed-off-by: Matthias Bertschy <[email protected]>

fix tests

8d3f908

Signed-off-by: Matthias Bertschy <[email protected]>

matthyx force-pushed the feature/linux-audit branch from d690cb5 to 8d3f908 Compare October 1, 2025 12:01

github-advanced-security bot found potential problems Oct 1, 2025

View reviewed changes

matthyx reviewed Oct 1, 2025

View reviewed changes

matthyx reviewed Oct 2, 2025

View reviewed changes

@@ -20,6 +20,7 @@
             	"github.com/kubescape/go-logger"
             	"github.com/kubescape/go-logger/helpers"
             	"github.com/kubescape/node-agent/pkg/auditmanager"
+            	"math"
             	"github.com/kubescape/node-agent/pkg/auditmanager/crd"
             	"github.com/kubescape/node-agent/pkg/config"
             	"github.com/kubescape/node-agent/pkg/exporters"
@@ -1158,7 +1159,7 @@
             	containerID, err := am.processTreeManager.GetContainerIDForPid(event.PID)
             	if err != nil {
             		logger.L().Debug("failed to get container ID from process tree manager",
-            			helpers.Int("pid", int(event.PID)),
+            			helpers.Int("pid", safePidToInt(event.PID)),
             			helpers.Error(err))
             		return
             	}

@@ -9,6 +9,7 @@
             	"strings"
             	"sync"
             	"time"
+            	"math"
             	"github.com/elastic/go-libaudit/v2"
             	"github.com/elastic/go-libaudit/v2/auparse"
@@ -1167,7 +1168,12 @@
             	if event.PID == 0 || containerID == "" {
             		logger.L().Debug("skipping Kubernetes enrichment",
             			helpers.String("reason", "no PID or no container ID"),
-            			helpers.Int("pid", int(event.PID)),
+            			helpers.Int("pid", func() int {
+            				if event.PID <= math.MaxInt32 {
+            					return int(event.PID)
+            				}
+            				return -1
+            			}()),
             			helpers.String("containerID", containerID))
             		return
             	}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Audit integration into Node-agent #648

Audit integration into Node-agent #648

Uh oh!

slashben commented Sep 15, 2025

Uh oh!

github-actions bot commented Sep 15, 2025

Uh oh!

Check failure

Copilot Autofix

Check failure

Copilot Autofix

github-actions bot commented Oct 1, 2025

Uh oh!

matthyx left a comment

Uh oh!

matthyx Oct 1, 2025

Uh oh!

matthyx Oct 1, 2025

Uh oh!

matthyx Oct 1, 2025

Uh oh!

matthyx Oct 2, 2025

Uh oh!

Uh oh!

Audit integration into Node-agent #648

Are you sure you want to change the base?

Audit integration into Node-agent #648

Uh oh!

Conversation

slashben commented Sep 15, 2025

Uh oh!

github-actions bot commented Sep 15, 2025

Uh oh!

Check failure

Uh oh!

Copilot Autofix

Check failure

Uh oh!

Copilot Autofix

github-actions bot commented Oct 1, 2025

Uh oh!

matthyx left a comment

Choose a reason for hiding this comment

Uh oh!

matthyx Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

matthyx Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

matthyx Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

matthyx Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!