docs: add STYLE_GUIDE.md for rules doc comments (closes #150) by koiakoia · Pull Request #364 · falcosecurity/rules

koiakoia · 2026-04-29T16:42:57Z

Closes #150.

As discussed in the issue, this introduces a STYLE_GUIDE.md covering rule documentation conventions:

Doc comments vs section comments (blank-line rule per @leogr's February 2026 proposal)
First-sentence-as-summary convention for doc comments
Override examples in tuning macros (user_*, allowed_*) — concrete append: true snippets
Source attribution for list-derived data (commands, vendor URLs)
"Explain or delete" convention for commented-out items

Each section pairs a GOOD example with a BAD example so the convention is unambiguous on review. The examples are drawn from actual items in falco_rules.yaml rather than invented syntax.

Also:

Added a short pointer in CONTRIBUTING.md near the top (just after the license note) so contributors find the style guide without hunting for it
Added STYLE_GUIDE.md to mkdocs.yml so it renders in the docs site

These conventions emerged from running ~77 custom rules in production on OKD, so I expect the maintainers will have refinements based on a wider rule corpus. Happy to iterate on structure, examples, or scope during review.

/cc @leogr @LucaGuerra @Issif

poiana · 2026-04-29T16:43:07Z

Welcome @koiakoia! It looks like this is your first PR to falcosecurity/rules 🎉

@leogr

Implements the convention discussed in falcosecurity#150 (doc comments vs section comments, override examples in tuning macros, source attribution for list-derived data, "explain or delete" for commented-out items). Builds on @leogr's Go-Doc-inspired proposal from Feb 2026, fleshed out with GOOD/BAD examples drawn from running ~77 custom rules in production on OKD. Closes falcosecurity#150 Signed-off-by: koiakoia <jimhaistlinux@gmail.com>

koiakoia · 2026-04-29T16:48:10Z

Missed DCO on the initial push — force-pushed af134ef with proper Signed-off-by trailer. Label flipped green. Will run pre-commit install first next time.

leogr · 2026-04-30T08:52:59Z

cc @falcosecurity/core-maintainers

leogr · 2026-05-19T12:15:30Z

/assign

ekoops · 2026-05-19T12:47:51Z

+**Required in every tuning macro doc comment:**
+
+1. What the macro does (one sentence).
+2. How to override it — include a concrete `append: true` snippet.


Actually, append: true has been deprecated in favor of override: {replace|append}. Could you please adjust this section? append: true is also used in other sections, so it would be great if you can fix it also there.

ekoops · 2026-05-19T12:54:21Z

Shouldn't this be inside docs/ for mkdocs to find it? 🤔

ekoops · 2026-05-19T12:58:18Z

+# To restrict SSH to known management hosts:
+#
+#   - macro: allowed_ssh_hosts
+#     condition: (evt.hostname in (bastion.example.com, mgmt.example.com))


Mmm this example uses evt.hostname, that is the name of the host running Falco, not the destination host. This means that this macro doesn't provide the described behaviour.

@ekoops

- Replace deprecated `append: true` with `override: append` throughout the examples and Quick Reference, per @ekoops review feedback. Add a note that `override: replace` is the swap-default counterpart. - Rewrite the `allowed_*` style example: the previous version used `evt.hostname`, which is the Falco runner's own hostname (not the destination), so the macro could never restrict SSH peers as described. Renamed to `allowed_ssh_initiators` and switched the condition to `proc.name`, with a callout that `fd.rip` is the right field for peer-IP allowlists. Reviewer thread: https://github.com/falcosecurity/rules/pull/<TBD> Signed-off-by: koiakoia <jimhaistlinux@gmail.com>

poiana · 2026-05-19T13:06:52Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: koiakoia
Once this PR has been reviewed and has the lgtm label, please ask for approval from ekoops. 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

@ekoops

Per review feedback from @ekoops: the top-level STYLE_GUIDE.md isn't found by mkdocs since the project's docs_dir defaults to docs/. Moving the file into docs/ aligns with mkdocs convention and matches the existing docs/images/ placement. The mkdocs.yml nav entry `Style Guide: STYLE_GUIDE.md` already resolves to docs/STYLE_GUIDE.md under docs_dir, so no nav rewrite is needed; added a clarifying comment. Signed-off-by: koiakoia <jimhaistlinux@gmail.com>

koiakoia · 2026-05-19T13:09:22Z

@ekoops thank you for the careful review — both points well-taken. Pushed two commits:

be40a7e — review feedback: override syntax + correct SSH allowlist example

Replaced append: true with override: append throughout (Section 3 examples, Section 5 commented-out template, and the Quick Reference table). Added a note that override: replace is the swap-default counterpart so operators see both forms.
Rewrote the allowed_* style example. You are correct that evt.hostname is the Falco runner's own hostname, so the original macro could never restrict SSH peers as described. Renamed the macro to allowed_ssh_initiators and changed the condition to proc.name in (ansible-playbook, scp, rsync) — a tuning shape that matches what existing Falco rules actually use. Also called out fd.rip in the common-override-fields note for the peer-IP allowlist variant in case operators reach for that.

79f6c33 — Move STYLE_GUIDE.md into docs/ for mkdocs discovery

Good catch — mkdocs's default docs_dir is docs/, so the top-level file would not have been picked up. The existing mkdocs.yml nav entry Style Guide: STYLE_GUIDE.md resolves to docs/STYLE_GUIDE.md under that default, so the move suffices without rewriting the nav. Added a small comment in mkdocs.yml so the path resolution is obvious to future readers.

Happy to make further changes if you spot anything else.

leogr · 2026-05-20T08:46:47Z


+For comment and documentation conventions within rule files (doc comments,
+section comments, tuning-macro override examples, and list provenance), see
+**[STYLE_GUIDE.md](STYLE_GUIDE.md)**.


Suggested change

**[STYLE_GUIDE.md](STYLE_GUIDE.md)**.

**[STYLE_GUIDE.md](docs/STYLE_GUIDE.md)**.

Since the file lives under docs/ now, this link needs the prefix, otherwise it 404s from CONTRIBUTING.md 🙏

leogr · 2026-05-20T08:46:47Z

+**Required in every tuning macro doc comment:**
+
+1. What the macro does (one sentence).
+2. How to override it — include a concrete `override: append` snippet.


Suggested change

2. How to override it — include a concrete `override: append` snippet.

2. How to override it — include a concrete `override:` block snippet (e.g. `condition: append`).

Same syntax point as the inline comments below 🙏

leogr · 2026-05-20T08:46:47Z

+#     override: append
+#
+# Use `override: replace` to swap the default condition entirely instead of
+# extending it. Common override fields: proc.name, proc.exepath,
+# container.image.repository.


Suggested change

# override: append

#

# Use `override: replace` to swap the default condition entirely instead of

# extending it. Common override fields: proc.name, proc.exepath,

# container.image.repository.

# override:

# condition: append

#

# Use `condition: replace` (instead of `append`) to swap the default condition

# entirely. Common override fields: proc.name, proc.exepath,

# container.image.repository.

override is a block in the canonical syntax (the value selects per-field append/replace). For a macro it is condition: append; for a list, items: append. See 👉 https://falco.org/docs/concepts/rules/overriding/

I verified with falco -V on 0.43.0: the single-value form (override: append) loads but produces schema warnings, so I would rather we teach the right shape from day one 🙏

leogr · 2026-05-20T08:46:47Z

+#     override: append
+#
+# Use `override: replace` to swap the default condition entirely instead of
+# extending it. Common override fields: proc.name, proc.exepath, fd.rip
+# (for peer-IP allowlists). See also: macro never_true for the placeholder
+# pattern.


Suggested change

# override: append

#

# Use `override: replace` to swap the default condition entirely instead of

# extending it. Common override fields: proc.name, proc.exepath, fd.rip

# (for peer-IP allowlists). See also: macro never_true for the placeholder

# pattern.

# override:

# condition: append

#

# Use `condition: replace` (instead of `append`) to swap the default condition

# entirely. Common override fields: proc.name, proc.exepath, fd.rip

# (for peer-IP allowlists). See also: macro never_true for the placeholder

# pattern.

Same here 🙏

leogr · 2026-05-20T08:46:47Z

+#
+#   - macro: possibly_node_in_container
+#     condition: (proc.pname=node and proc.aname[3]=docker-containe)
+#     override: replace   # swap the default never_true guard entirely


Suggested change

# override: replace # swap the default never_true guard entirely

# override:

# condition: replace # swap the default never_true guard entirely

Same here 🙏

leogr · 2026-05-20T08:46:48Z

+|-----------|------------|
+| Comment immediately precedes an item (no blank line) | Doc comment — documents that item |
+| Comment has a blank line before it AND below it | Section comment — labels a group |
+| Tuning macro (`user_*`, `allowed_*`) | Doc comment must include override snippet with `override: append` (or `override: replace`) |


Suggested change

| Tuning macro (`user_*`, `allowed_*`) | Doc comment must include override snippet with `override: append` (or `override: replace`) |

| Tuning macro (`user_*`, `allowed_*`) | Doc comment must include override snippet using an `override:` block (e.g. `condition: append` or `condition: replace`) |

Same syntax fix as above 🙏

leogr · 2026-05-20T08:46:48Z

+This guide covers **comment conventions only**. For rule expression style,
+output format, tag requirements, and maturity-level criteria, see the
+[Falco Rules Style Guide](https://falco.org/docs/rules/style-guide/) and
+[CONTRIBUTING.md](CONTRIBUTING.md).


Suggested change

[CONTRIBUTING.md](CONTRIBUTING.md).

[CONTRIBUTING.md](../CONTRIBUTING.md).

CONTRIBUTING.md is at the repo root, so from here it needs ../. Otherwise the relative link breaks 🙏

github-project-automation Bot added this to Falco Roadmap Apr 29, 2026

poiana requested review from Issif, LucaGuerra and leogr April 29, 2026 16:43

github-project-automation Bot moved this to Todo in Falco Roadmap Apr 29, 2026

poiana added the dco-signoff: no label Apr 29, 2026

poiana added the size/XL label Apr 29, 2026

koiakoia force-pushed the style-guide-rules-doc-comments branch from 5d52b47 to af134ef Compare April 29, 2026 16:47

poiana added dco-signoff: yes and removed dco-signoff: no labels Apr 29, 2026

poiana assigned leogr May 19, 2026

ekoops requested changes May 19, 2026

View reviewed changes

poiana assigned ekoops May 19, 2026

github-project-automation Bot moved this from Todo to In progress in Falco Roadmap May 19, 2026

leogr reviewed May 20, 2026

View reviewed changes

leogr requested a review from ekoops May 20, 2026 08:52

	[STYLE_GUIDE.md](STYLE_GUIDE.md).
	[STYLE_GUIDE.md](docs/STYLE_GUIDE.md).

	2. How to override it — include a concrete `override: append` snippet.
	2. How to override it — include a concrete `override:` block snippet (e.g. `condition: append`).

	# override: replace # swap the default never_true guard entirely
	# override:
	# condition: replace # swap the default never_true guard entirely

	\| Tuning macro (`user_`, `allowed_`) \| Doc comment must include override snippet with `override: append` (or `override: replace`) \|
	\| Tuning macro (`user_`, `allowed_`) \| Doc comment must include override snippet using an `override:` block (e.g. `condition: append` or `condition: replace`) \|

	[CONTRIBUTING.md](CONTRIBUTING.md).
	[CONTRIBUTING.md](../CONTRIBUTING.md).

Conversation

koiakoia commented Apr 29, 2026

Uh oh!

poiana commented Apr 29, 2026

Uh oh!

koiakoia commented Apr 29, 2026

Uh oh!

leogr commented Apr 30, 2026

Uh oh!

leogr commented May 19, 2026

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!

poiana commented May 19, 2026

Uh oh!

koiakoia commented May 19, 2026

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants