test-fuzz

test-fuzz est une sous-commande Cargo et un ensemble de macros Rust permettant d'automatiser certaines tâches liées au fuzzing avec [afl.rs], notamment :

• la génération d'un corpus de fuzzing
• l'implémentation d'un harnais de fuzzing

test-fuzz accomplit ces tâches (en partie) en utilisant les fonctionnalités de test de Rust. Par exemple, pour générer un corpus de fuzzing, test-fuzz enregistre les arguments d'une cible à chaque appel effectué lors d'une invocation de cargo test. De même, test-fuzz implémente un harnais de fuzzing comme test supplémentaire dans un binaire généré par cargo-test. Cette intégration étroite avec les fonctionnalités de test de Rust est ce qui motive le nom test-fuzz.

Sommaire

1. [Installation]
2. [Overview]
3. [Components]
   • [test_fuzz macro]
   • [test_fuzz_impl macro]
   • [cargo test-fuzz command]
   • [Convenience functions and macros]
4. [test-fuzz package features]
5. [Auto-generated corpus files]
6. [Environment variables]
7. [Limitations]
8. [Tips and tricks]
9. [Semantic versioning policy]
10. [License]

Installation

Installez cargo-test-fuzz et [afl.rs] avec la commande suivante :```sh cargo install cargo-test-fuzz cargo-afl

## Overview

Le fuzzing avec `test-fuzz` se résume essentiellement à trois étapes :\*

1. **Identifier une cible de fuzzing** :
   - Ajoutez les `dependencies` suivantes au fichier `Cargo.toml` de la crate cible :
     ```toml
     serde = "*"
     test-fuzz = "*"
     ```
   - Faites précéder la fonction cible de la macro [`test_fuzz`] :
     ```rust
     #[test_fuzz::test_fuzz]
     fn foo(...) {
         ...
     }
     ```
2. **Générer un corpus** en exécutant `cargo test` :   ```
   cargo test

3. Fuzzez votre cible en exécutant [cargo test-fuzz]: ``` cargo test-fuzz foo

* Une étape préliminaire supplémentaire peut être nécessaire après un redémarrage :```sh cargo afl system-config

Notez que la commande ci-dessus exécute `sudo` en interne. Par conséquent, vous pouvez être invité à saisir votre mot de passe.

## Composants

### Macro `test_fuzz`

Faire précéder une fonction de la macro `test_fuzz` indique que cette fonction est une cible de fuzzing.

Les principaux effets de la macro `test_fuzz` sont :

- Ajouter une instrumentation à la cible pour sérialiser ses arguments et les écrire dans un fichier de corpus à chaque appel de la cible. L'instrumentation est protégée par `#[cfg(test)]` afin que les fichiers de corpus ne soient générés que lors de l'exécution des tests (voir cependant [`enable_in_production`] ci-dessous).
- Ajouter un test qui lit et désérialise les arguments depuis l'entrée standard et applique la cible sur ceux-ci. Le test vérifie une variable d'environnement, définie par [`cargo test-fuzz`], afin qu'il ne bloque pas en tentant de lire l'entrée standard lors d'une invocation normale de `cargo test`. Le test est contenu dans un module pour réduire la probabilité d'une collision de noms. Actuellement, le nom du module est `target_fuzz`, où `target` est le nom de la cible (voir cependant [`rename`] ci-dessous).

#### Arguments

##### `bounds = "where_predicates"`

Imposez `where_predicates` (par exemple, des contraintes de trait) sur la structure utilisée pour sérialiser/désérialiser les arguments. Cela peut être nécessaire, par exemple, si le type d'argument d'une cible est un type associé. Pour un exemple, voir [associated_type.rs] dans ce dépôt.

##### `generic_args = "parameters"`

Utilisez `parameters` comme paramètres de type de la cible lors du fuzzing. Exemple :```rust
#[test_fuzz(generic_args = "String")]
fn foo<T: Clone + Debug + Serialize>(x: &T) {
    ...
}

Note: Les arguments de la cible doivent être sérialisables pour chaque instanciation de ses paramètres de type. Mais les arguments de la cible ne doivent être désérialisables que lorsque la cible est instanciée avec parameters.

impl_generic_args = "parameters"

Utilisez parameters comme paramètres de type Self de la cible lors du fuzzing. Exemple:```rust #[test_fuzz_impl] impl<T: Clone + Debug + Serialize> for Foo { #[test_fuzz(impl_generic_args = "String")] fn bar(&self, x: &T) { ... } }

Remarque : les arguments de la cible doivent être sérialisables pour **chaque** instanciation de ses paramètres de type `Self`. Mais les arguments de la cible ne doivent être désérialisables que lorsque le `Self` de la cible est instancié avec `parameters`.

##### `convert = "X, Y"`

Lors de la sérialisation des arguments de la cible, convertissez les valeurs de type `X` en type `Y` en utilisant l'implémentation de `From<X>` par `Y`, ou les valeurs de type `&X` en type `Y` en utilisant l'implémentation par `Y` du trait non standard `test_fuzz::FromRef<X>`. Lors de la désérialisation, reconvertissez ces valeurs en type `X` en utilisant l'implémentation par `Y` du trait non standard `test_fuzz::Into<X>`.

Autrement dit, l'utilisation de `convert = "X, Y"` doit être accompagnée de certaines implémentations. Si `X` implémente [`Clone`], alors `Y` peut implémenter ce qui suit :```rust
impl From<X> for Y {
    fn from(x: X) -> Self {
        ...
    }
}

Si X n'implémente pas [Clone], alors Y doit implémenter ce qui suit :```rust impl test_fuzz::FromRef for Y { fn from_ref(x: &X) -> Self { ... } }

De plus, `Y` doit implémenter ce qui suit (que `X` implémente ou non [`Clone`]) :```rust
impl test_fuzz::Into<X> for Y {
    fn into(self) -> X {
        ...
    }
}

La définition de test_fuzz::Into est identique à celle de [std::convert::Into]. La raison d'utiliser un trait non standard est d'éviter les conflits qui pourraient découler d'implémentations fourre-tout des traits standard.

enable_in_production

Générer des fichiers de corpus lorsque les tests ne sont pas exécutés, à condition que la variable d'environnement [TEST_FUZZ_WRITE] soit définie. Par défaut, les fichiers de corpus ne sont générés que lors de l'exécution des tests, que [TEST_FUZZ_WRITE] soit définie ou non. Lorsque vous exécutez une cible depuis l'extérieur de son répertoire de package, définissez [TEST_FUZZ_MANIFEST_PATH] sur le chemin du fichier Cargo.toml du package.

AVERTISSEMENT : Définir enable_in_production pourrait introduire un vecteur de déni de service. Par exemple, définir cette option pour une fonction appelée de nombreuses fois avec des arguments différents pourrait remplir le disque. La vérification de [TEST_FUZZ_WRITE] a pour but d'offrir une certaine protection contre cette possibilité. Néanmoins, examinez attentivement cette option avant de l'utiliser.

execute_with = "function"

Plutôt que d'appeler la cible directement :

• construire une closure de type FnOnce() -> R, où R est le type de retour de la cible, de sorte que l'appel de la closure appelle la cible ;
• appeler function avec la closure.

Appeler la cible de cette manière permet à function de configurer l'environnement de l'appel. Cela peut être utile, par exemple, pour fuzzer [les externalités de Substrate].

no_auto_generate

Ne pas essayer de [générer automatiquement des fichiers de corpus] pour la cible.

only_generic_args

Enregistrer les arguments génériques de la cible lors de l'exécution des tests, mais ne pas générer de fichiers de corpus et ne pas implémenter de harnais de fuzzing. Cela peut être utile lorsque la cible est une fonction générique, mais qu'on ne sait pas quels paramètres de type devraient être utilisés pour le fuzzing.