linux-kernel - Re: [PATCH v2 RFC 5/7] kfuzztest: add ReST documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAG_fn=VBbSqb07-pbbEw7F=SP5_t74Re7ki0+ZS=mBm2S9BehA@mail.gmail.com>
Date: Thu, 4 Sep 2025 10:53:32 +0200
From: Alexander Potapenko <glider@...gle.com>
To: Ethan Graham <ethan.w.s.graham@...il.com>
Cc: ethangraham@...gle.com, andreyknvl@...il.com, brendan.higgins@...ux.dev, 
	davidgow@...gle.com, dvyukov@...gle.com, jannh@...gle.com, elver@...gle.com, 
	rmoar@...gle.com, shuah@...nel.org, tarasmadan@...gle.com, 
	kasan-dev@...glegroups.com, kunit-dev@...glegroups.com, 
	linux-kernel@...r.kernel.org, linux-mm@...ck.org, dhowells@...hat.com, 
	lukas@...ner.de, ignat@...udflare.com, herbert@...dor.apana.org.au, 
	davem@...emloft.net, linux-crypto@...r.kernel.org
Subject: Re: [PATCH v2 RFC 5/7] kfuzztest: add ReST documentation

On Mon, Sep 1, 2025 at 6:43 PM Ethan Graham <ethan.w.s.graham@...il.com> wrote:
>
> From: Ethan Graham <ethangraham@...gle.com>
>
> Add Documentation/dev-tools/kfuzztest.rst and reference it in the
> dev-tools index.
>
> Signed-off-by: Ethan Graham <ethangraham@...gle.com>
Acked-by: Alexander Potapenko <glider@...gle.com>

Some nits below.

> +Macros ``FUZZ_TEST``, `KFUZZTEST_EXPECT_*`` and ``KFUZZTEST_ANNOTATE_*`` embed

Nit: missing second backtick before KFUZZTEST_EXPECT_


> +Input Format
> +============
> +
> +KFuzzTest targets receive their inputs from userspace via a write to a dedicated
> +debugfs ``/sys/kernel/debug/kfuzztest/<test-name>/input``.

Nit: "debugfs file"?

> +- Padding and Poisoning: The space between the end of one region's data and the
> +  beginning of the next must be sufficient for padding. In KASAN builds,
> +  KFuzzTest poisons this unused padding, allowing for precise detection of
> +  out-of-bounds memory accesses between adjacent buffers. This padding should
> +  be at least ``KFUZZTEST_POISON_SIZE`` bytes as defined in
> +  `include/linux/kfuzztest.h``.

Nit: missing leading backtick.

> +
> +KFuzzTest Bridge Tool
> +=====================
> +
> +The kfuzztest-bridge program is a userspace utility that encodes a random byte

Nit: do we need backticks around kfuzztest-bridge?

> +This tool is intended to be simple, both in usage and implementation. Its
> +structure and DSL are sufficient for simpler use-cases. For more advanced
> +coverage-guided fuzzing it is recommended to use syzkaller which implements
> +deeper support for KFuzzTest targets.

Nit: please add a link to syzkaller.

> +
> +The textual format is a human-readable representation of the region-based binary
> +format used by KFuzzTest. It is described by the following grammar:
> +
> +.. code-block:: text
> +
> +       schema     ::= region ( ";" region )* [";"]
> +       region     ::= identifier "{" type+ "}"

Don't types need to be separated with spaces?

> +       type       ::= primitive | pointer | array | length | string
> +       primitive  ::= "u8" | "u16" | "u32" | "u64"
> +       pointer    ::= "ptr" "[" identifier "]"
> +       array      ::= "arr" "[" primitive "," integer "]"
> +       length     ::= "len" "[" identifier "," primitive "]"
> +       string     ::= "str" "[" integer "]"
> +       identifier ::= [a-zA-Z_][a-zA-Z1-9_]*
> +       integer    ::= [0-9]+
> +
> +Pointers must reference a named region. To fuzz a raw buffer, the buffer must be

Maybe insert a paragraph break between these two sentences?

> +.. code-block:: text
> +
> +       my_struct { ptr[buf] len[buf, u64] }; buf { arr[u8, n] };
> +
> +Where ``n`` is some integer value defining the size of the byte array inside of

s/Where/, where/ ?