feat(k8saudit): file watching #1167

RichardoC · 2026-01-22T17:14:15Z

What type of PR is this?

/kind feature

Any specific area of the project related to this PR?

/area plugins

What this PR does / why we need it:
Add continuous file watching capability for audit logs using the
tail:// URL scheme. This allows monitoring files for new entries
and handles log rotation via inode detection and file truncation.

Which issue(s) this PR fixes:

Fixes #191

Special notes for your reviewer: Generated with Claude Code. Full transcript attached
claude-log.txt

Add continuous file watching capability for audit logs using the tail:// URL scheme. This allows monitoring files for new entries and handles log rotation via inode detection and file truncation. Closes falcosecurity#191 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

Add documentation for the new tail:// URL scheme and watchPollIntervalMs configuration option. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

poiana · 2026-01-22T17:14:28Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: RichardoC
Once this PR has been reviewed and has the lgtm label, please assign leogr for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

github-actions · 2026-01-22T17:29:26Z

Rules files suggestions

rules

Comparing b4696a614148482909f4e483c2906685abfe2151 with latest tag plugins/k8saudit/v0.16.0

No changes detected

irozzo-1A

Hi @RichardoC, thanks for your contribution. I suggest using file instead of tail to have a more standard URI, and using an event based approach instead of polling.

irozzo-1A · 2026-01-23T15:05:30Z

plugins/k8saudit/pkg/k8saudit/source.go

 		return k.OpenWebServer(u.Host, u.Path, false)
 	case "https":
 		return k.OpenWebServer(u.Host, u.Path, true)
+	case "tail":


Suggested change

case "tail":

case "file":

irozzo-1A · 2026-01-23T15:14:02Z

plugins/k8saudit/README.md

 This plugin supports consuming Kubernetes Audit Events coming from the [Webhook backend](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/#webhook-backend) or from a file. For webhooks, the plugin embeds a web server that listens on a configurable port and accepts POST requests. The posted JSON object comprises one or more events. The web server of the plugin can be configured as part of the plugin's init configuration and open parameters. For files, the plugin expects content to be in [JSONL format](https://jsonlines.org/), where each line represents a JSON object, containing one or more audit events.

-The expected way of using the plugin with Falco is through a Webhook. File reading support can be used with Stratoshark or testing and development.
+The expected way of using the plugin with Falco is through a Webhook. File reading support can be used with Stratoshark or testing and development. The `tail://` scheme enables continuous file watching with log rotation support, useful for reading audit logs written to disk by the API server.


Suggested change

The expected way of using the plugin with Falco is through a Webhook. File reading support can be used with Stratoshark or testing and development. The `tail://` scheme enables continuous file watching with log rotation support, useful for reading audit logs written to disk by the API server.

The expected way of using the plugin with Falco is through a Webhook. File reading support can be used with Stratoshark or testing and development. The `file://` scheme enables continuous file watching with log rotation support, useful for reading audit logs written to disk by the API server.

irozzo-1A · 2026-01-23T15:15:22Z

plugins/k8saudit/README.md

 **Open Parameters**:
 - `http://<host>:<port>/<endpoint>`: Opens an event stream by listening on an HTTP web server
 - `https://<host>:<port>/<endpoint>`: Opens an event stream by listening on an HTTPS web server
+- `tail://<filepath>`: Opens an event stream by continuously watching a file for new audit events, similar to `tail -f`. Handles log rotation (inode changes) and file truncation automatically. Example: `tail:///var/log/kube-apiserver/audit.log`


Suggested change

- `tail://<filepath>`: Opens an event stream by continuously watching a file for new audit events, similar to `tail -f`. Handles log rotation (inode changes) and file truncation automatically. Example: `tail:///var/log/kube-apiserver/audit.log`

- `file://<filepath>`: Opens an event stream by continuously watching a file for new audit events, similar to `tail -f`. Handles log rotation (inode changes) and file truncation automatically. Example: `file:///var/log/kube-apiserver/audit.log`

irozzo-1A · 2026-01-23T15:27:55Z

plugins/k8saudit/pkg/k8saudit/config.go

 	UseAsync            bool   `json:"useAsync"             jsonschema:"title=Use async extraction,description=If true then async extraction optimization is enabled (Default: true),default=true"`
 	MaxEventSize        uint64 `json:"maxEventSize"         jsonschema:"title=Maximum event size,description=Maximum size of single audit event (Default: 262144),default=262144"`
 	WebhookMaxBatchSize uint64 `json:"webhookMaxBatchSize"  jsonschema:"title=Maximum webhook request size,description=Maximum size of incoming webhook POST request bodies (Default: 12582912),default=12582912"`
+	WatchPollIntervalMs uint64 `json:"watchPollIntervalMs"  jsonschema:"title=Watch poll interval,description=Polling interval in milliseconds when watching a file with tail:// scheme (Default: 250),default=250"`


We can avoid this if we use an event based approach e.g. inotify

plugins/k8saudit/pkg/k8saudit/tail/tail_test.go

plugins/k8saudit/pkg/k8saudit/source.go

Co-authored-by: Iacopo Rozzo <iacopo@sysdig.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

RichardoC · 2026-01-26T17:21:55Z

Hi @RichardoC, thanks for your contribution. I suggest using file instead of tail to have a more standard URI, and using an event based approach instead of polling.

Thank you for the thorough review @irozzo-1A , making those changes now

RichardoC · 2026-01-26T17:24:04Z

Claude log for the changes
Uploading claude-log-1.txt…

Replace polling-based file watching with fsnotify for better efficiency. - Use fsnotify to watch parent directory (per maintainer recommendation) - Rename scheme from tail:// to file:// - Remove watchPollIntervalMs config (no longer needed) - Rename test package from tail to filewatch Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

RichardoC · 2026-01-26T17:31:21Z

The cargo install issue in ci seems unrelated to my changes

plugins/k8saudit/go.mod

plugins/k8saudit/pkg/k8saudit/filewatch/filewatch_test.go

Move tests from orphaned filewatch/ package into k8saudit alongside the code they test, and restore truncation detection that was lost in the fsnotify refactor. - Detect file truncation via size check before seeking (copytruncate) - Move filewatch/filewatch_test.go to watch_test.go in k8saudit package - Restore TestOpenFileWatch_HandlesTruncation test - Remove empty filewatch/ directory - Mark fsnotify as direct dependency in go.mod Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

github-actions · 2026-02-05T22:15:45Z

Rules files suggestions

rules

Comparing d55af3c756e061542b4a99366285a3c18c94a2d4 with latest tag plugins/k8saudit/v0.16.0

No changes detected

…tcher - Align scanner buffer with MaxEventSize to avoid silently dropping large events - Log scanner errors instead of swallowing them - Log fsnotify watcher errors instead of discarding them - Add real assertions to watch tests using sentinel-based content verification Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

github-actions · 2026-02-05T22:46:22Z

Rules files suggestions

rules

Comparing 16ded85295827763a0da74e4e7c179c66aa72262 with latest tag plugins/k8saudit/v0.16.0

No changes detected

RichardoC and others added 3 commits January 22, 2026 16:59

docs(k8saudit): document tail:// file watching scheme

b9c7cfd

Add documentation for the new tail:// URL scheme and watchPollIntervalMs configuration option. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

docs(k8saudit): correct documentation for default file read

b4696a6

Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

poiana added kind/feature New feature or request dco-signoff: yes area/plugins labels Jan 22, 2026

poiana requested review from irozzo-1A and leogr January 22, 2026 17:14

poiana added the size/L label Jan 22, 2026

RichardoC changed the title ~~Feature/k8saudit file watching~~ feat(k8saudit): file watching Jan 22, 2026

irozzo-1A reviewed Jan 23, 2026

View reviewed changes

plugins/k8saudit/pkg/k8saudit/source.go Outdated Show resolved Hide resolved

Update plugins/k8saudit/pkg/k8saudit/tail/tail_test.go

2b7e054

Co-authored-by: Iacopo Rozzo <iacopo@sysdig.com> Signed-off-by: Richard Tweed <RichardoC@users.noreply.github.com>

poiana added dco-signoff: no and removed dco-signoff: yes labels Jan 26, 2026

RichardoC force-pushed the feature/k8saudit-file-watching branch from 0613d65 to c12e1e0 Compare January 26, 2026 17:26

poiana added dco-signoff: yes and removed dco-signoff: no labels Jan 26, 2026

leogr reviewed Feb 2, 2026

View reviewed changes

plugins/k8saudit/go.mod Outdated Show resolved Hide resolved

plugins/k8saudit/pkg/k8saudit/filewatch/filewatch_test.go Outdated Show resolved Hide resolved

poiana added size/XL and removed size/L labels Feb 5, 2026

	The expected way of using the plugin with Falco is through a Webhook. File reading support can be used with Stratoshark or testing and development. The `tail://` scheme enables continuous file watching with log rotation support, useful for reading audit logs written to disk by the API server.
	The expected way of using the plugin with Falco is through a Webhook. File reading support can be used with Stratoshark or testing and development. The `file://` scheme enables continuous file watching with log rotation support, useful for reading audit logs written to disk by the API server.

	- `tail://<filepath>`: Opens an event stream by continuously watching a file for new audit events, similar to `tail -f`. Handles log rotation (inode changes) and file truncation automatically. Example: `tail:///var/log/kube-apiserver/audit.log`
	- `file://<filepath>`: Opens an event stream by continuously watching a file for new audit events, similar to `tail -f`. Handles log rotation (inode changes) and file truncation automatically. Example: `file:///var/log/kube-apiserver/audit.log`

feat(k8saudit): file watching #1167

Are you sure you want to change the base?

feat(k8saudit): file watching #1167

Uh oh!

Conversation

RichardoC commented Jan 22, 2026

Uh oh!

poiana commented Jan 22, 2026

Uh oh!

github-actions bot commented Jan 22, 2026

Rules files suggestions

rules

Uh oh!

irozzo-1A left a comment

Choose a reason for hiding this comment

Uh oh!

irozzo-1A Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

irozzo-1A Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

irozzo-1A Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

irozzo-1A Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

RichardoC commented Jan 26, 2026

Uh oh!

RichardoC commented Jan 26, 2026

Uh oh!

RichardoC commented Jan 26, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 5, 2026

Rules files suggestions

rules

Uh oh!

github-actions bot commented Feb 5, 2026

Rules files suggestions

rules

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants