You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .agents/sow/current/SOW-0027-20260629-netdata-vendor-memory-safety-update.md
+77-13Lines changed: 77 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
Status: in-progress
6
6
7
-
Sub-state: preflight found one Netdata-only vendored-source Sonar cleanup that must be backported to `plugin-ipc` before copying source into Netdata.
7
+
Sub-state: Netdata vendoring exposed a missing public L3 cache enumeration API required by the eBPF cgroup consumer; implementation is paused for a user design decision.
8
8
9
9
## Requirements
10
10
@@ -37,6 +37,7 @@ Inferences:
37
37
Unknowns:
38
38
39
39
- Whether the next pushed source commit will keep GitHub and Codacy checks green; this must be checked before copying into Netdata.
40
+
- Whether the L3 cache public API should grow a borrowed scan/enumeration operation, an allocated snapshot-copy operation, or a different integration path for consumers that need to process every cached cgroup item.
None currently blocking. The target checkout is `~/src/netdata-ktsaou.git`; branch/PR handling will be determined after local validation so unrelated local files are not staged.
159
+
- 2026-07-01: Netdata vendoring blocks on an L3 cache API decision. The new guarded cache contract supports borrowed lookup by key, but Netdata's eBPF cgroup integration needs to enumerate all cached cgroup items after each refresh.
159
160
160
161
## Implications And Decisions
161
162
@@ -199,16 +200,75 @@ None currently blocking. The target checkout is `~/src/netdata-ktsaou.git`; bran
199
200
-`git diff --check`: passed.
200
201
-`bash .agents/sow/audit.sh`: passed.
201
202
- Note: the unqualified `ctest` in the user-local PATH failed because its Python `cmake` module was unavailable, so validation used `/usr/bin/ctest`.
203
+
- Committed and pushed source backport as `bb7a73e0e2b871352eeb3c4403afbd69649a351d`.
204
+
- Source post-push preflight for `bb7a73e0e2b871352eeb3c4403afbd69649a351d`:
205
+
- GitHub Actions/check-runs: all completed successfully; Valgrind was skipped by workflow policy.
206
+
- Current-commit GitHub code-scanning analyses: zero results for CodeQL C/C++ POSIX, CodeQL C/C++ Windows, CodeQL Go POSIX, CodeQL Go Windows, CodeQL Rust, Semgrep, gosec, OSV, and Codacy local.
207
+
- GitHub open code-scanning alerts: only stale Semgrep alert `7750` remains on old commit `b4dfe405e1f99be417c21a9c0478aba2f64facaa`; not present in the current commit analyses.
208
+
- GitHub Dependabot open alerts: none.
209
+
- GitHub secret-scanning open alerts: none.
210
+
- Codacy Cloud analyzed `bb7a73e0e2b871352eeb3c4403afbd69649a351d`; repository problems were empty and coverage was 90%.
211
+
- Codacy Cloud issues remain the 23 previously accepted Go standard-library dependency findings at `src/go/go.mod:3`, tied to the required `go 1.26.0` compatibility.
212
+
- Pre-vendor decision after source post-push preflight: proceed to Netdata vendoring from `bb7a73e0e2b871352eeb3c4403afbd69649a351d`.
213
+
- Netdata vendoring from `bb7a73e0e2b871352eeb3c4403afbd69649a351d` exposed a compile blocker in `src/collectors/ebpf.plugin/ebpf_cgroup.c`:
214
+
- Netdata still reads removed public cache fields: `ebpf_cgroup_cache.item_count`, `ebpf_cgroup_cache.generation`, `ebpf_cgroup_cache.systemd_enabled`, and `ebpf_cgroup_cache.items`.
215
+
- Source evidence: `src/libnetdata/netipc/include/netipc/netipc_service.h` exposes `nipc_cgroups_cache_status()`, `nipc_cgroups_cache_read_lock()`, `nipc_cgroups_cache_get()`, `nipc_cgroups_cache_item_dup()`, and `nipc_cgroups_cache_item_free()`, but no public enumeration operation.
216
+
- Source implementation evidence: `src/libnetdata/netipc/src/service/netipc_service_cgroups_cache_common.c` keeps `snapshot->views` and `snapshot->item_count` internally, so read-guarded enumeration can be implemented without exposing mutable snapshot internals.
217
+
- Netdata consumer evidence: `src/collectors/ebpf.plugin/ebpf_cgroup.c` counts enabled items and rebuilds eBPF cgroup targets by iterating every cached item. Key-based lookup alone cannot express this workflow.
218
+
- Implementation paused before changing source API or Netdata consumer code because the correct public API shape is a design decision.
219
+
- Follow-up risk review found that `ebpf.plugin` does not appear to be an L3 hot-lookup consumer:
220
+
- One cgroup integration thread calls `ebpf_parse_cgroup_netipc_data()` periodically.
221
+
- Other eBPF module threads consume the derived `ebpf_cgroup_pids` table protected by `mutex_cgroup_shm`; they do not look up items in the NetIPC L3 cache.
222
+
- The direct L2 snapshot API already supports `fetch -> iterate response view -> process`, using `nipc_client_call_cgroups_snapshot()` and `nipc_cgroups_resp_item()`.
223
+
- Risks of replacing L3 with direct L2 in `ebpf.plugin` are manageable if implementation preserves existing failure semantics: on failed fetch, return before touching `ebpf_cgroup_pids`; on successful fetch, use borrowed response views only before the next typed call or client close; keep the 5000 ms call timeout and abort path; preserve empty-snapshot behavior.
224
+
- Accepted plan: do not add a new L3 enumeration API for this vendoring fix; adapt `ebpf.plugin` to use a plain `nipc_client_ctx_t` and direct L2 snapshot fetch/process.
225
+
- User decision: switch `ebpf.plugin` to direct L2 snapshot fetch/process for this vendoring fix. Do not add a new L3 enumeration API in `plugin-ipc`.
226
+
- Implemented the Netdata-side consumer adaptation in `src/collectors/ebpf.plugin/ebpf_cgroup.c`:
227
+
- replaced the local `nipc_cgroups_cache_t` instance with a plain `nipc_client_ctx_t`;
228
+
- replaced `nipc_cgroups_cache_refresh()` and direct cache field reads with `nipc_client_refresh()`, `nipc_client_call_cgroups_snapshot_timeout()`, and `nipc_cgroups_resp_item()`;
229
+
- preserved existing failure behavior by returning before modifying `ebpf_cgroup_pids` on fetch or item-decode failure;
230
+
- preserved the 5000 ms timeout, shutdown abort path, empty-snapshot preservation behavior, and `mutex_cgroup_shm` publication boundary.
- Stale L3 field/type scan in `src/collectors/ebpf.plugin/ebpf_cgroup.c`: no `nipc_cgroups_cache`, `ebpf_cgroup_cache.*`, or removed cache-field usage remained.
234
+
- Fresh CMake build target `ebpf.plugin`: passed.
235
+
- Fresh CMake build targets `apps-lookup-netipc-lock-test`, `apps-cgroups-lookup-client-abort-test`, and `cgroup-lookup-netipc-test`: passed.
236
+
- Direct test binary runs for those three targets: passed.
237
+
-`/usr/bin/ctest --test-dir <fresh-build> -N`: zero registered tests in this temporary build, so the linked binaries were run directly.
238
+
- Netdata branch, commit, and PR:
239
+
- branch: `netipc-vendor-bb7a73e`;
240
+
- commit: `705d587ec2` (`Update vendored NetIPC to bb7a73e`);
- PR `netdata/netdata#22936` later reported CI/scanner failures against commit `705d587ec2`:
244
+
- GitHub Actions Go toolchain jobs failed in the `go fix ./...` step because Go 1.26 rewrote `src/go/pkg/netipc/service/raw/cache_test.go`.
245
+
- Codacy Cloud reported three new issues: one Cppcheck unread variable in `src/libnetdata/netipc/src/transport/windows/netipc_win_shm.c`, and two Flawfinder `umask()` findings in `src/libnetdata/netipc/src/transport/posix/netipc_uds_lifecycle.c`.
246
+
- SonarCloud reported `strlen()` safety findings in `src/libnetdata/netipc/src/service/netipc_service_cgroups_cache_common.c`, one `strlen()` finding in Netdata-only `src/collectors/ebpf.plugin/ebpf_cgroup.c`, one `umask()` security finding, and a duplicated-lines quality-gate failure.
247
+
- Source-side fixes prepared before re-vendoring:
248
+
- applied the Go 1.26 `go fix` rewrite in `src/go/pkg/netipc/service/raw/cache_test.go`;
249
+
- removed the duplicated Unix-only cache fallback/control test because `src/go/pkg/netipc/service/raw/cache_common_test.go` already covers the same behavior on all platforms;
250
+
- replaced scanner-flagged `strlen()` use in `src/libnetdata/netipc/src/service/netipc_service_cgroups_cache_common.c` with local NUL-terminated string length walking;
251
+
- added Flawfinder and Sonar suppressions to the intentional `umask()` hardening calls that bind UDS sockets as `0600` without a post-bind permission window;
252
+
- removed post-spin `observed = true` assignments in the Windows SHM receive loop that were no longer read after the loop branch exits.
253
+
- Source-side validation for the CI/scanner repair:
254
+
-`go fmt ./pkg/netipc/service/raw && go fix ./pkg/netipc/service/raw && go test -count=1 ./pkg/netipc/service/raw`: passed.
255
+
-`go test -count=1 ./pkg/netipc/...`: passed.
256
+
-`flawfinder --minlevel=5 --error-level=5 src/libnetdata/netipc/src/transport/posix/netipc_uds_lifecycle.c`: passed with zero hits; two intentional `umask()` hits were suppressed.
257
+
-`cppcheck --enable=style --inline-suppr --quiet --suppress=missingIncludeSystem src/libnetdata/netipc/src/transport/windows/netipc_win_shm.c`: no unread-variable finding remained; only const-style suggestions were reported.
- Source preflight completed before Netdata vendoring: CI/checks, GitHub code scanning, Dependabot, secret scanning, and Codacy Cloud were checked for `fe4e31633b5372b3c93e21f9e37b38f2407aaed1`.
268
+
- Source post-backport preflight completed before Netdata vendoring: CI/checks, GitHub code scanning, Dependabot, secret scanning, and Codacy Cloud were checked for `bb7a73e0e2b871352eeb3c4403afbd69649a351d`.
209
269
- Two-way gap analysis completed before vendoring and recorded in the 2026-07-01 execution log.
210
270
- Valid Netdata-only vendored-source drift was backported to `plugin-ipc` before any Netdata copy.
211
-
- Netdata vendoring, Netdata validation, Netdata commit, and post-vendor evidence are not started yet.
271
+
- Netdata vendoring is implemented in the target checkout and the eBPF L2 adaptation builds; the first PR commit exposed CI/scanner findings that are being fixed source-first before re-vendoring.
212
272
213
273
Tests or equivalent validation:
214
274
@@ -218,11 +278,14 @@ Tests or equivalent validation:
218
278
- source same-pattern numeric lowercase `ull` search, no matches;
219
279
-`git diff --check`;
220
280
- SOW audit.
221
-
- GitHub/Codacy validation for the new source backport commit is pending until the commit is pushed.
281
+
- GitHub/Codacy validation for the new source backport commit passed as recorded above.
282
+
- Source-side CI/scanner repair validation passed locally as recorded in the 2026-07-01 execution log. Remote source CI/scanner validation is pending until the repair commit is pushed.
222
283
223
284
Real-use evidence:
224
285
225
-
- Not started for Netdata; vendor copy has not been modified yet.
286
+
- Netdata compile evidence exists from the fresh temporary CMake build:
287
+
- vendored NetIPC C target `netipc` built successfully;
288
+
-`ebpf.plugin` built successfully after switching the consumer to L2.
226
289
227
290
Reviewer findings:
228
291
@@ -231,6 +294,7 @@ Reviewer findings:
231
294
Same-failure scan:
232
295
233
296
- Source same-pattern scan for lowercase numeric `ull` suffixes in `src/libnetdata/netipc` returned no matches.
297
+
- Netdata eBPF same-failure scan found no remaining removed L3 cache field/type usage in `src/collectors/ebpf.plugin/ebpf_cgroup.c`.
234
298
235
299
Sensitive data gate:
236
300
@@ -243,39 +307,39 @@ Artifact maintenance gate:
243
307
- Specs: no update needed until implementation changes behavior.
244
308
- End-user/operator docs: no update needed until implementation changes behavior.
245
309
- End-user/operator skills: no update needed until implementation changes behavior.
246
-
- SOW lifecycle: created as open in `.agents/sow/pending/`.
310
+
- SOW lifecycle: moved from pending to current before source backport and Netdata vendoring; remains in progress until Netdata commit, post-vendor checks, and final review are complete.
247
311
248
312
Specs update:
249
313
250
-
-Not started.
314
+
-No source spec update was needed for the Netdata-side L2 switch; it uses the existing cgroups-snapshot client API.
251
315
252
316
Project skills update:
253
317
254
-
-Not started.
318
+
-Already updated earlier in this SOW family with the mandatory vendoring preflight and two-way gap analysis workflow; no additional skill change needed for the eBPF L2 consumer adaptation.
255
319
256
320
End-user/operator docs update:
257
321
258
-
-Not started.
322
+
-No end-user/operator docs update needed; the Netdata eBPF plugin behavior and configuration stay the same.
259
323
260
324
End-user/operator skills update:
261
325
262
-
-Not started.
326
+
-No end-user/operator skill update needed.
263
327
264
328
Lessons:
265
329
266
-
-None yet.
330
+
-Not every consumer that iterates cgroups needs the NetIPC L3 cache. If the consumer is a single periodic importer that publishes its own protected derived table, direct L2 fetch/process can be simpler and avoids exposing an unnecessary cache enumeration API.
267
331
268
332
Follow-up mapping:
269
333
270
334
- This SOW tracks the SOW-0026 Netdata vendor propagation item.
271
335
272
336
## Outcome
273
337
274
-
Pending.
338
+
In progress. Source backport and pre-vendor checks are complete, Netdata vendoring is copied, and the eBPF consumer now builds against the vendored opaque NetIPC cache API by using direct L2 snapshot access. Draft PR `netdata/netdata#22936` is open; its first commit exposed Go fix, Codacy, and Sonar findings that are being repaired source-first before re-vendoring. Post-vendor CI/scanner checks and final SOW closure are not complete yet.
275
339
276
340
## Lessons Extracted
277
341
278
-
Pending.
342
+
- Avoid adding a public L3 enumeration API only to satisfy a single-threaded periodic importer; first check whether the consumer is actually a hot multi-threaded lookup user or just a fetch/process pipeline.
0 commit comments