Write Cve Rule

Writing a CVEhound detection rule

A rule is one file in cvehound/cve/CVE-YYYY-NNNNN.cocci (or .grep). That is the entire change. Do not add, edit, or parametrize tests — tests/conftest.py discovers every rule and generates the whole suite from the file's metadata headers.

Syntax questions go to docs/COCCINELLE_CHEATSHEET.md. Everything below is workflow and the things about this repository that will otherwise trip you up.

1. Gather the inputs

You cannot start without these:

• CVE ID
• the mainline fix commit hash
• the commit that introduced the bug, if it is known
• the affected file paths, relative to the kernel root

git -C tests/linux show <fix_commit>          # the diff is the specification
git -C tests/linux log -1 --format=%H <fix_commit>

Look for a Fixes: trailer in the fix commit message — that is usually the introducing commit. If there is none and you can only guess, you will use Detect-To: instead.

2. Decide what to match

Read the diff and take the first branch that applies:

Match the invariant, not the era. The rule runs on every commit in Fixes..Fix and on old stable branches — the code's exact shape drifts across that range, and a pattern that transcribes today's spelling (the precise condition, per-era disjunction branches) silently misses the eras nobody transcribed. Prefer a stable anchor that existed the whole time (the call or computation that is the bug — that line gets the star) plus a @fixed@ helper matching what the fix added, with the error rule depends on !fixed. cvehound/cve/CVE-2017-1000112.cocci is the worked example; docs/WRITING_RULES.md → "Rule 7: Match the invariant, not the era" has the full treatment and the loosening toolbox.

Then read three existing rules of the same shape before writing yours — they are the real house style, and they encode workarounds no prose captures:

cd cvehound/cve
grep -l "memset" *.cocci              # initialization bugs
grep -l "copy_to_user" *.cocci        # information leaks
grep -l "when != if" *.cocci          # missing checks
grep -l 'depends on' *.cocci          # inter-rule dependencies
grep -l 'depends on .*&&' *.cocci     # conjunctions: several conditions must hold

3. Write it

Start from contrib/blank.cocci. The skeleton:

/// Files: <paths from kernel root, space-separated, one line>
/// Fix: <full hash of the fixing commit>
/// Fixes: <full hash of the introducing commit>   // or Detect-To: <hash>

@err@
@@

vulnerable_function(...)
{
	...
*	<the line that identifies the vulnerability>
	...
}

A rule is match rules only. The report is the *: on a match spatch prints a unified diff of the starred lines, and CVEhound reads that. No output means no detection. There is no script rule and no position/@p for reporting — the rules must run under a spatch built without Python. (A position used as a match constraint is still fair game; see cvehound/cve/CVE-2020-27777.cocci.)

Non-negotiables:

• Anchor the pattern in a named function. A bare return -1; or kfree(x); with no enclosing context is the single largest source of false positives here.
• Never declare a virtual rule. CVEhound passes no -D, so a rule gated on one is dropped before translation and reports nothing, silently. To turn a rule off, comment it out and say why.
• * is not decoration. It switches the patch into match mode, which flips the default quantification of un-annotated ... from forall to exists. Adding or removing it changes what matches. Every rule stars a line, so that flip is always in force: never write exists in a rule header — it is a no-op. To make one ellipsis hold on all paths (a when != guard otherwise only constrains a single witness path), annotate that ellipsis with when forall.
• Star the deciding rule only, and only its identifying line. A starred rule prints whenever it matches, whatever the other rules did — so a * on a helper (classically a @fix@ rule that recognises the fix) reports on fixed trees, and starring several lines across ... reports a partial match.
• Star a line spatch can delete — in every version of the range. A star on a lone } is silently dropped (the branch matches and reports nothing); a star on a token an older version builds via a macro aborts spatch with "try to delete an expanded token".
• Independent sites are separate starred rules (OR); a conjunction needs depends on. Chain the rules so the last one depends on all the others — @err_c depends on err_a && err_b@ — and star only that last rule. See cvehound/cve/CVE-2021-3347.cocci and cvehound/cve/CVE-2021-3609.cocci for the AND, cvehound/cve/CVE-2016-5195.cocci for the OR.
• Filter by function with the pattern, not after the fact. "Only in foo()" is written by anchoring inside the definition — foo(...) { ... when any <pattern> ... when any }, with \(foo1\|foo2\) for several. Never wrap a statement body in <+... ...+>: same meaning, orders of magnitude slower. See cvehound/cve/CVE-2021-28971.cocci, cvehound/cve/CVE-2017-1000112.cocci.
• The rule's literal tokens decide how much of the tree spatch parses. A name left literal where a metavariable would do, or more than five rules that star something in one file, and spatch stops skipping files it cannot match. validate-rule.sh measures it; docs/WRITING_RULES.md → "Rule 8: Keep the grep query selective" explains it.

docs/WRITING_RULES.md → "Rule 2: Star discipline" has the full treatment of the star rules — the corpus exceptions, the failure symptoms, and the measured costs.

When the rule is a judgement call, prefer a false positive — a missed CVE is worse than a noisy one.