ROX-33217: Instrument inode tracking on directory being created path mkdir by JoukoVirtanen · Pull Request #465 · stackrox/fact

JoukoVirtanen · 2026-04-01T17:54:05Z

Description

Directory creation events need to be handled correctly. When a directory is created in a tracked directory its inode should be added to a hash set in kernel space. In user space an entry needs to be added into a map with the inode as the key and file path as the value.

An alternative approach can be found at #449

Checklist

Investigated and inspected CI test results
Updated documentation accordingly

Automated testing

Added unit tests
Added integration tests
Added regression tests

If any of these don't apply, please comment below.

Testing Performed

Checked metrics

$ grep path_mkdir */metrics 
test_mkdir_ignored/metrics:# HELP stackrox_fact_kernel_path_mkdir_events Events processed by the path_mkdir LSM hook.
test_mkdir_ignored/metrics:# TYPE stackrox_fact_kernel_path_mkdir_events counter
test_mkdir_ignored/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="RingbufferFull"} 0
test_mkdir_ignored/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Added"} 0
test_mkdir_ignored/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Error"} 0
test_mkdir_ignored/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Ignored"} 2
test_mkdir_ignored/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Total"} 3
test_mkdir_nested/metrics:# HELP stackrox_fact_kernel_path_mkdir_events Events processed by the path_mkdir LSM hook.
test_mkdir_nested/metrics:# TYPE stackrox_fact_kernel_path_mkdir_events counter
test_mkdir_nested/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="RingbufferFull"} 0
test_mkdir_nested/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Added"} 0
test_mkdir_nested/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Total"} 3
test_mkdir_nested/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Ignored"} 0
test_mkdir_nested/metrics:stackrox_fact_kernel_path_mkdir_events_total{label="Error"} 0

$ grep d_instantiate */metrics 
test_mkdir_ignored/metrics:# HELP stackrox_fact_kernel_d_instantiate_events Events processed by the d_instantiate LSM hook.
test_mkdir_ignored/metrics:# TYPE stackrox_fact_kernel_d_instantiate_events counter
test_mkdir_ignored/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Error"} 0
test_mkdir_ignored/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Added"} 2
test_mkdir_ignored/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Ignored"} 36
test_mkdir_ignored/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="RingbufferFull"} 0
test_mkdir_ignored/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Total"} 37
test_mkdir_nested/metrics:# HELP stackrox_fact_kernel_d_instantiate_events Events processed by the d_instantiate LSM hook.
test_mkdir_nested/metrics:# TYPE stackrox_fact_kernel_d_instantiate_events counter
test_mkdir_nested/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="RingbufferFull"} 0
test_mkdir_nested/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Added"} 6
test_mkdir_nested/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Error"} 0
test_mkdir_nested/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Total"} 115
test_mkdir_nested/metrics:stackrox_fact_kernel_d_instantiate_events_total{label="Ignored"} 112

JoukoVirtanen · 2026-04-01T23:36:22Z

fact-ebpf/src/bpf/main.c

+  struct inode* parent_inode_ptr = BPF_CORE_READ(parent_dentry, d_inode);
+  inode_key_t parent_inode = inode_to_key(parent_inode_ptr);
+
+  if (should_track_mkdir(parent_inode, path) != PARENT_MONITORED) {


I originally had

if (should_track_mkdir(parent_inode, path) == NOT_MONITORED) {

However, test_nonrecursive_wildcard::test_wildcard.py failed with that change. The reason was that was the inodes of all directories created in that test were tracked and subsequently all files in those directories were tracked regardless if they matched the wildcard pattern or not.

Molter73 · 2026-04-02T17:00:49Z

fact-ebpf/src/bpf/main.c

 #define FMODE_PWRITE ((fmode_t)(1 << 4))
 #define FMODE_CREATED ((fmode_t)(1 << 20))

+// File type constants from linux/stat.h


Could we add a permalink to the definition?

Molter73 · 2026-04-02T17:07:18Z

fact-ebpf/src/bpf/main.c

+  umode_t mode = BPF_CORE_READ(inode, i_mode);
+  if (!S_ISDIR(mode)) {
+    bpf_map_delete_elem(&mkdir_context, &pid_tgid);
+    m->d_instantiate.ignored++;
+    return 0;
+  }


We should check if m->d_instantiate.ignored actually increases, I have a feeling this condition should never be met.

m->d_instantiate.ignored increases, but I don't know if it is due to this or other locations with m->d_instantiate.ignored++;.

Molter73 · 2026-04-02T17:09:03Z

fact-ebpf/src/bpf/main.c

+
+  m->d_instantiate.total++;
+
+  if (inode == NULL) {


We should check if inode can actually be null, if so, we probably still want to try and cleanup the mkdir_context map entry.

There is now cleanup even when the inode is null.

Molter73 · 2026-04-02T17:13:17Z

fact-ebpf/src/bpf/events.h

+  }
+
+  // d_instantiate doesn't support bpf_d_path, so we use false and rely on the stashed path from path_mkdir
+  __submit_event(event, m, FILE_ACTIVITY_CREATION, filename, inode, parent_inode, false);


Calling __submit_event will cause a full event to be filled in, including process information. However, mkdir is mostly needed for inode tracking and probably not interesting enough to send an event over gRPC, so we might want to look into having an abbreviated version that will just submit a FILE_ACTIVITY_MKDIR event that will be processed by HostScanner and dropped after adding to the userspace map.

Molter73 · 2026-04-02T17:15:02Z

fact-ebpf/src/bpf/maps.h

+struct {
+  __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
+  __type(key, __u32);
+  __type(value, struct mkdir_context_t);
+  __uint(max_entries, 1);
+} mkdir_context_heap SEC(".maps");
+
+__always_inline static struct mkdir_context_t* get_mkdir_context() {
+  unsigned int zero = 0;
+  return bpf_map_lookup_elem(&mkdir_context_heap, &zero);
+}


This seems to be unused.

This is used. get_mkdir_context is used at https://github.com/stackrox/fact/pull/465/changes#diff-ffd13aea0af666b10cf909b17d6e19eb4c0855151d6cf2cbf6567a941c21b068R264

You are right, but now I'm wondering why we are not just getting an entry from mkdir_context directly and filling that in, instead of getting an entry from mkdir_context_heap and then copying it over.

There's a few things you could try for when the entry doesn't actually exist.

If you drop BPF_F_NO_PREALLOC from mkdir_context, I'm fairly certain you should always get a value back.

You can try using bpf_map_lookup_elem and if it fails, create a new entry passing value as NULL.

If that doesn't work, you can just pass a pointer to a default value from a const global, which will end up in .rodata section.

Molter73 · 2026-04-02T17:19:47Z

fact/src/metrics/kernel_metrics.rs

I think you also need to add your metrics here:

fact/fact-ebpf/src/lib.rs

Lines 123 to 127 in eb0b3a9

m.file_open = m.file_open.accumulate(&other.file_open);

m.path_unlink = m.path_unlink.accumulate(&other.path_unlink);

m.path_chmod = m.path_chmod.accumulate(&other.path_chmod);

m.path_chown = m.path_chown.accumulate(&other.path_chown);

m.path_rename = m.path_rename.accumulate(&other.path_rename);

I will look into improving how we handle these, it is getting very repetitive and having it scattered among multiple files is very error prone.

Molter73 · 2026-04-02T17:21:24Z

tests/test_path_mkdir.py

+    os.mkdir(level1)
+    os.mkdir(level2)
+    os.mkdir(level3)


[nit] We can probably just use os.makedirs on level3.

Molter73 · 2026-04-02T17:22:53Z

tests/test_path_mkdir.py

+from event import Event, EventType, Process
+
+
+def test_mkdir_nested(monitored_dir, server):


Maybe we can parametrize the final directory with UTF-8 characters?

Molter73 · 2026-04-06T15:05:08Z

fact-ebpf/src/bpf/maps.h

+struct {
+  __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
+  __type(key, __u32);
+  __type(value, struct mkdir_context_t);
+  __uint(max_entries, 1);
+} mkdir_context_heap SEC(".maps");
+
+__always_inline static struct mkdir_context_t* get_mkdir_context() {
+  unsigned int zero = 0;
+  return bpf_map_lookup_elem(&mkdir_context_heap, &zero);
+}


You are right, but now I'm wondering why we are not just getting an entry from mkdir_context directly and filling that in, instead of getting an entry from mkdir_context_heap and then copying it over.

There's a few things you could try for when the entry doesn't actually exist.

If you drop BPF_F_NO_PREALLOC from mkdir_context, I'm fairly certain you should always get a value back.

You can try using bpf_map_lookup_elem and if it fails, create a new entry passing value as NULL.

If that doesn't work, you can just pass a pointer to a default value from a const global, which will end up in .rodata section.

fact/src/event/mod.rs

Co-authored-by: Mauro Ezequiel Moltrasio <mmoltras@redhat.com>

JoukoVirtanen added 4 commits March 31, 2026 15:32

X-Smart-Branch-Parent: main

6e63d30

Added integration tests

0682fb2

Instrument inode tracking on directory being created

7aecaa4

Only tracking directories if the parent is monitored

e01ccb1

JoukoVirtanen marked this pull request as ready for review April 1, 2026 23:30

JoukoVirtanen requested a review from a team as a code owner April 1, 2026 23:30

JoukoVirtanen commented Apr 1, 2026

View reviewed changes

JoukoVirtanen mentioned this pull request Apr 1, 2026

WIP ROX-33217: Instrument inode tracking on directory being created #449

Draft

5 tasks

Removed some comments

9a7a03e

Molter73 reviewed Apr 2, 2026

View reviewed changes

JoukoVirtanen added 7 commits April 2, 2026 10:43

Combined two uses of BPF_CORE_READ

ab17d26

Added DIR_ACTIVITY_CREATION

3aa4998

Added permalink to linux/stat.h

5288866

Removing map entry in case of early return in lsm/d_instantiate

99ee8cb

Using os.makedirs instead of os.mkdir three times

be580e1

Accumulate m.path_mkdir and m.d_instantiate

2974373

Checking pid_tgid earlier so if inode is null we still cleanup

b0ef4fe

Molter73 reviewed Apr 6, 2026

View reviewed changes

JoukoVirtanen force-pushed the jv-ROX-33217-instrument-inode-tracking-on-directory-being-created-path_mkdir branch from 4a6a257 to b0ef4fe Compare April 6, 2026 15:39

JoukoVirtanen and others added 6 commits April 6, 2026 17:09

Not using BPF_F_NO_PREALLOC

a295468

Switched from BPF_MAP_TYPE_HASH to BPF_MAP_TYPE_LRU_HASH

5f882ba

Apply suggestion from @Molter73

349a4e2

Co-authored-by: Mauro Ezequiel Moltrasio <mmoltras@redhat.com>

Parameterized test

be4d39d

Fixed verifier issue. Not sending directory creation events

e93080b

make format

60b3962

	m.file_open = m.file_open.accumulate(&other.file_open);
	m.path_unlink = m.path_unlink.accumulate(&other.path_unlink);
	m.path_chmod = m.path_chmod.accumulate(&other.path_chmod);
	m.path_chown = m.path_chown.accumulate(&other.path_chown);
	m.path_rename = m.path_rename.accumulate(&other.path_rename);

		from event import Event, EventType, Process


		def test_mkdir_nested(monitored_dir, server):

Conversation

JoukoVirtanen commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Testing Performed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JoukoVirtanen commented Apr 1, 2026 •

edited

Loading