docs: describe how the preStop exec cache and network event dedup affect the runtime rules

Open Beginner friendly
  • Is something wrong?
#1,093 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
documentation

Research direction

Read the existing dedup and configuration notes under docs/, then check pkg/rulemanager/cel/libraries/containerprofile/exec.go and pkg/dedupcache/keys.go for the stated behavior. Add documentation covering the preStop trigger, five-minute window, affected CEL functions, event keys and TTLs, and what deduplicated events skip. Done when rule authors can find both behaviors and their runtime effects in the docs.

Written by the indexing model from the issue text.

Description

Description

Two behaviours of the rule engine aren't documented, and both change which events the runtime rules see. They're intended, but someone writing or tuning rules has no way to know about them except by reading the code.

  1. preStop exec cache. isExecInPodSpec (pkg/rulemanager/cel/libraries/containerprofile/exec.go) marks a container's preStop hook as triggered when an executed path appears in its lifecycle.preStop.exec.command. While it's marked, which lasts DefaultPreStopCacheTTL (5 minutes), was_executed treats every exec in that container as expected. With a common hook like ["/bin/sh", "-c", "sleep 5"], this window starts whenever /bin/sh runs, not only when the pod terminates. That's worth stating next to the rules that use ap.was_executed / cp.was_executed.
  2. Network event dedup. ComputeNetworkKey(mntns, pid, dstAddr, dstPort, proto) (pkg/dedupcache/keys.go) has no packet direction, and network events dedup for 5s. So within that window, a second event with the same process, remote address, port and protocol is dropped before the rule manager, profile learning and malware scan see it.

Proposal

Add a short section, for example in docs/ next to the existing dedup and configuration notes, that explains:

  • the preStop exec window: what triggers it, how long it lasts, and which CEL functions it affects;
  • the dedup keys and TTLs per event type, and what a deduplicated event skips.

I'm happy to write the doc PR if that sounds useful, and to adjust it to how you'd like these described.

Dominant language
Go
Stars
39
Forks
42
Avg merge
1d 18h
Merged PRs (30d)
40

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from kubescape/node-agent

All issues in kubescape/node-agent

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.