GSoC 2026 - Admin API Fuzzer: question about the fuzzing oracle

[TM TALEB]

Hello,

My name is Tarek, a Computer Science student interested in the Admin API Fuzzer project for GSoC 2026.

I have been reading the previous threads on this list, PR #751, the Admin API documentation, and your reply to Laksh where you mentioned that "not every exception is a failure — invalid parameters are supposed to result in an exception during early validation, not later execution."

This brings me to what I think is the core design challenge of this fuzzer: the oracle problem.

For each Admin API call, the fuzzer needs to know what the *expected* behavior is for a given input, in order to correctly classify a response as a real bug or a normal rejection. Without this, the fuzzer would produce too many false positives to be useful.

My question is: is there currently any machine-readable specification of what valid inputs look like for each Admin API method — for example, argument types, allowed characters, length limits — or would that specification need to be built as part of this project, extracted from the existing validation code in admin.py?

Understanding this would help me propose a realistic and precise architecture in my formal proposal.

Thank you for your time.
Tarek

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Sun, Mar 15, 2026 at 06:47:50AM -0700, TM TALEB wrote:
> Hello,

Hello,

> My name is Tarek, a Computer Science student interested in the Admin API
> Fuzzer project for GSoC 2026.
>
> I have been reading the previous threads on this list, PR #751, the Admin
> API documentation, and your reply to Laksh where you mentioned that "not
> every exception is a failure — invalid parameters are supposed to result in
> an exception during early validation, not later execution."
>
> This brings me to what I think is the core design challenge of this fuzzer:
> the oracle problem.
>
> For each Admin API call, the fuzzer needs to know what the *expected*
> behavior is for a given input, in order to correctly classify a response as
> a real bug or a normal rejection. Without this, the fuzzer would produce
> too many false positives to be useful.
>
> My question is: is there currently any machine-readable specification of
> what valid inputs look like for each Admin API method — for example,
> argument types, allowed characters, length limits — or would that
> specification need to be built as part of this project, extracted from the
> existing validation code in admin.py?

This is a very good question!
Unfortunately we don't have machine-readable version of it, but the
human-readable API documentation is at
https://doc.qubes-os.org/en/latest/developer/services/admin-api.html
(you likely found it already)
Some of the fields are defined more precisely, and some less.
Lack of formal API specification leads to issues like this:
https://github.com/QubesOS/qubes-issues/issues/10040
...

So, I guess improving the specification (based on the current
documentation, implementation, and likely a lot of clarification
questions) might be in scope for the project.

> Understanding this would help me propose a realistic and precise
> architecture in my formal proposal.

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmm3fK4ACgkQ24/THMrX
1ywSCgf9HS808TGUHi4oZEcxKJgOoi4+/wjqLNNRKg+IRPjYmCD1j98fCR9kMYcU
qH1W/fXo+13iKI8wBh5mfF4/mZzkCPmtUT6K+Rev9J00bblRWmjTDHJ3wO65/aue
TCQ0Ih2PNwvu2rk4n2dvR/1CxRBfkfvJDCz9t5GrkyjICTI7ADHLf0+S05GqHz45
lOjEghQ7a8no+vsd6a9WdwMD/3UsVYzYp48IKK3ka0Zfpma3GddphWUzNB61N1vy
cG+A4Q5fY2da7lovE8tNrJolIvIJVKtTVRqkA+OJyuvuP+wnxS1M08EvWK8l4VOp
pDjbFs9k2zGTN7o5oGMcThCMaTlKtg==
=nvBB
-----END PGP SIGNATURE-----

[Ben Grande]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Topic of research is how other projects handle this.

`self.arg` and `untrusted_payload` cannot be easily type checked, the
former because it is defined as an object of self in `QubesAbstractAPI`
while it's use is elsewhere, so not passed as a parameter, which means
it is difficult to customize the tipying check. The latter because it is
received in bytes and sometimes some transformation is done instead of
using it raw.

Docstrings is another option, ideally in a format that is already used
by another large, well-recognized project, so we don't roll our own
format.

- --
Best regards,
Benjamin Grande

Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iHUEARYIAB0WIQRklnEdsUUe50UmvUUbcxS/DMyWhwUCabipWwAKCRAbcxS/DMyW
hw8WAP9zQEy185wxWsWSu63b8QLkEebT7ZTcU0puzzFGssIx4wD5AXkn3+eExxOg
kk2n4FOyTUaWYs3vpwGiPlnooPbBjQY=
=NM+a
-----END PGP SIGNATURE-----