test-fuzz

test-fuzz è un sottocomando di Cargo e una raccolta di macro Rust per automatizzare alcune attività relative al fuzzing con afl.rs, tra cui:

• generazione di un corpus di fuzzing
• implementazione di un harness di fuzzing

test-fuzz realizza queste attività (in parte) utilizzando le strutture di test di Rust. Ad esempio, per generare un corpus di fuzzing, test-fuzz registra gli argomenti di un target ogni volta che viene chiamato durante un'invocazione di cargo test. Analogamente, test-fuzz implementa un harness di fuzzing come test aggiuntivo in un binario generato da cargo-test. Questa stretta integrazione con le strutture di test di Rust è ciò che motiva il nome test-fuzz.

Contenuti

1. [Installazione]
2. [Panoramica]
3. [Componenti]
   • test_fuzz macro
   • test_fuzz_impl macro
   • [cargo test-fuzz comando]
   • [Funzioni e macro di convenienza]
4. [Funzionalità del pacchetto test-fuzz]
5. [File di corpus generati automaticamente]
6. [Variabili d'ambiente]
7. [Limitazioni]
8. [Suggerimenti e trucchi]
9. [Politica di versionamento semantico]
10. [Licenza]

Installazione

Installa cargo-test-fuzz e afl.rs con il seguente comando:```sh cargo install cargo-test-fuzz cargo-afl

## Panoramica

Il fuzzing con `test-fuzz` consiste essenzialmente in tre passaggi:\*

1. **Identificare un target di fuzzing**:
   - Aggiungere le seguenti `dependencies` al file `Cargo.toml` della crate target:
     ```toml
     serde = "*"
     test-fuzz = "*"
     ```
   - Anteporre alla funzione target la macro [`test_fuzz`]:
     ```rust
     #[test_fuzz::test_fuzz]
     fn foo(...) {
         ...
     }
     ```
2. **Generare un corpus** eseguendo `cargo test`:   ```
   cargo test

3. Effettua il fuzzing del tuo target eseguendo cargo test-fuzz: ``` cargo test-fuzz foo
   root@kitploit:~

* Potrebbe essere necessario un ulteriore passaggio preliminare dopo un riavvio:```sh cargo afl system-config

Si noti che il comando precedente esegue `sudo` internamente. Pertanto, potrebbe esserti richiesto di inserire la password.

## Componenti

### Macro `test_fuzz`

Anteporre la macro `test_fuzz` a una funzione indica che la funzione è un fuzz target.

Gli effetti principali della macro `test_fuzz` sono:

- Aggiunge strumentazione al target per serializzare i suoi argomenti e scriverli in un file di corpus ogni volta che il target viene chiamato. La strumentazione è protetta da `#[cfg(test)]`, così che i file di corpus vengano generati solo durante l'esecuzione dei test (vedi comunque [`enable_in_production`] di seguito).
- Aggiunge un test che legge e deserializza gli argomenti dallo standard input e applica il target agli stessi. Il test controlla una variabile d'ambiente, impostata da [`cargo test-fuzz`], in modo che il test non si blocchi tentando di leggere dallo standard input durante una normale invocazione di `cargo test`. Il test è racchiuso in un modulo per ridurre la probabilità di una collisione di nomi. Attualmente, il nome del modulo è `target_fuzz`, dove `target` è il nome del target (vedi comunque [`rename`] di seguito).

#### Argomenti

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

Impone `where_predicates` (ad esempio, trait bounds) sulla struct usata per serializzare/deserializzare gli argomenti. Questo può essere necessario, ad esempio, se il tipo di un argomento del target è un tipo associato. Per un esempio, vedere [associated_type.rs] in questo repository.

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

Usa `parameters` come parametri di tipo del target durante il fuzzing. Esempio:```rust
#[test_fuzz(generic_args = "String")]
fn foo<T: Clone + Debug + Serialize>(x: &T) {
    ...
}

Nota: gli argomenti del target devono essere serializzabili per ogni istanziazione dei suoi parametri di tipo. Ma gli argomenti del target devono essere deserializzabili solo quando il target è istanziato con parameters.

impl_generic_args = "parameters"

Usa parameters come parametri di tipo Self del target durante il fuzzing. Esempio:```rust #[test_fuzz_impl] impl<T: Clone + Debug + Serialize> for Foo { #[test_fuzz(impl_generic_args = "String")] fn bar(&self, x: &T) { ... } }

Nota: gli argomenti del target devono essere serializzabili per **ogni** istanziazione dei parametri di tipo `Self`. Ma gli argomenti del target devono essere deserializzabili solo quando il `Self` del target è istanziato con `parameters`.

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

Quando si serializzano gli argomenti del target, convertire i valori di tipo `X` in tipo `Y` usando l'implementazione di `From<X>` per `Y`, oppure quelli di tipo `&X` in tipo `Y` usando l'implementazione del trait non standard `test_fuzz::FromRef<X>` per `Y`. Quando si deserializzano, riconvertire quei valori al tipo `X` usando l'implementazione del trait non standard `test_fuzz::Into<X>` per `Y`.

Cioè, l'uso di `convert = "X, Y"` deve essere accompagnato da determinate implementazioni. Se `X` implementa [`Clone`], allora `Y` può implementare quanto segue:```rust
impl From<X> for Y {
    fn from(x: X) -> Self {
        ...
    }
}

Se X non implementa Clone, allora Y deve implementare quanto segue:```rust impl test_fuzz::FromRef for Y { fn from_ref(x: &X) -> Self { ... } }

Inoltre, `Y` deve implementare quanto segue (indipendentemente dal fatto che `X` implementi [`Clone`]):```rust
impl test_fuzz::Into<X> for Y {
    fn into(self) -> X {
        ...
    }
}

The definition of test_fuzz::Into is identical to that of std::convert::Into. The reason for using a non-standard trait is to avoid conflicts that could arise from blanket implementations of standard traits.

enable_in_production

Generate corpus files when not running tests, provided the environment variable TEST_FUZZ_WRITE is set. The default is to generate corpus files only when running tests, regardless of whether TEST_FUZZ_WRITE is set. When running a target from outside its package directory, set TEST_FUZZ_MANIFEST_PATH to the path of the package's Cargo.toml file.

WARNING: Setting enable_in_production could introduce a denial-of-service vector. For example, setting this option for a function that is called many times with different arguments could fill up the disk. The check of TEST_FUZZ_WRITE is meant to provide some defense against this possibility. Nonetheless, consider this option carefully before using it.

execute_with = "function"

Rather than call the target directly:

• construct a closure of type FnOnce() -> R, where R is the target's return type, so that calling the closure calls the target;
• call function with the closure.

Calling the target in this way allows function to set up the call's environment. This can be useful, e.g., for fuzzing Substrate externalities.

no_auto_generate

Do not try to auto-generate corpus files for the target.

only_generic_args

Record the target's generic args when running tests, but do not generate corpus files and do not implement a fuzzing harness. This can be useful when the target is a generic function, but it is unclear what type parameters should be used for fuzzing.

The intended workflow is: enable only_generic_args, then run cargo test followed by cargo test-fuzz --display generic-args. One of the resulting generic args might be usable as generic_args's parameters. Similarly, generic args resulting from cargo test-fuzz --display impl-generic-args might be usable as impl_generic_args's parameters.

Note, however, that just because a target was called with certain parameters during tests, it does not imply the target's arguments are serializable/deserializable when those parameters are used. The results of --display generic-args/--display impl-generic-args are merely suggestive.

rename = "name"

Treat the target as though its name is name when adding a module to the enclosing scope. Expansion of the test_fuzz macro adds a module definition to the enclosing scope. By default, the module is named as follows:

• If the target does not appear in an impl block, the module is named target_fuzz__, where target is the name of the target.
• If the target appears in an impl block, the module is named path_target_fuzz__, where path is the last segment of the impl's Self type path.

However, use of this option causes the module to instead be named name_fuzz__. Example:```rust #[test_fuzz(rename = "bar")] fn foo() {}

// Without the use of rename, a name collision and compile error would result. mod foo_fuzz__ {}

#### Attributi di campo Serde sugli argomenti di funzione

La macro `test_fuzz` consente di applicare [Serde field attributes] agli argomenti di funzione. Questo fornisce un altro strumento per gestire tipi difficili.

Di seguito è riportato un esempio. I trait `serde::Serialize` e `serde::Deserialize` non possono essere derivati per `Context` perché contiene un `Mutex`. Tuttavia, `Context` implementa `Default`. Quindi applicare `#[serde(skip)]` all'argomento `Context` fa sì che venga saltato durante la serializzazione e che assuma il suo valore predefinito durante la deserializzazione.```rust
use std::sync::Mutex;

// Traits `serde::Serialize` and `serde::Deserialize` cannot be derived for `Context` because it
// contains a `Mutex`.
#[derive(Default)]
struct Context {
    lock: Mutex<()>,
}

impl Clone for Context {
    fn clone(&self) -> Self {
        Self {
            lock: Mutex::new(()),
        }
    }
}

#[test_fuzz::test_fuzz]
fn target(#[serde(skip)] context: Context, x: i32) {
    assert!(x >= 0);
}

Nota che quando gli attributi di campo Serde vengono applicati a un argomento, la macro test_fuzz non esegue altre [conversioni] sull'argomento.

Macro test_fuzz_impl

Ogni volta che la macro test_fuzz viene usata in un blocco impl, il blocco impl deve essere preceduto dalla macro test_fuzz_impl. Esempio:```rust #[test_fuzz_impl] impl Foo { #[test_fuzz] fn bar(&self, x: &str) { ... } }

Il motivo di questo requisito è il seguente. L'espansione della macro [`test_fuzz`] aggiunge una definizione di modulo all'ambito circostante. Tuttavia, una definizione di modulo non può apparire all'interno di un blocco `impl`. Anteporre la macro `test_fuzz_impl` all'`impl` fa sì che il modulo venga aggiunto all'esterno del blocco `impl`.

Se vedi un errore come il seguente, probabilmente significa che manca un uso della macro `test_fuzz_impl`:```
error: module is not supported in `trait`s or `impl`s

test_fuzz_impl attualmente non ha opzioni.

Comando cargo test-fuzz

Il comando cargo test-fuzz viene utilizzato per interagire con i fuzz target e per manipolare i relativi corpora, crash, hang e code di lavoro. Esempi di invocazioni includono:

1. Elenca i fuzz target ``` cargo test-fuzz --list
   root@kitploit:~

2. Mostra il corpus del target foo ``` cargo test-fuzz foo --display corpus
   root@kitploit:~

3. Esegui il fuzz sul target foo ``` cargo test-fuzz foo
   root@kitploit:~

4. Riproduci i crash trovati per il target foo ``` cargo test-fuzz foo --replay crashes
   root@kitploit:~

Utilizzo```

Usage: cargo test-fuzz [OPTIONS] [TARGETNAME] [-- ...]

Arguments: [TARGETNAME] String that fuzz target's name must contain [ARGS]... Arguments for the fuzzer

Options: --backtrace Display backtraces --consolidate Move one target's crashes, hangs, and work queue to its corpus; to consolidate all targets, use --consolidate-all --coverage Generate coverage for corpus, crashes, hangs, or work queue. Note that generating coverage for instrumented fuzz targets is not supported. --cpus Fuzz using at most cpus; default is all but one --display Display corpus, crashes, generic args, impl generic args, hangs, or work queue. By default, an uninstrumented fuzz target is used. To display with instrumentation, append -instrumented to , e.g., --display corpus-instrumented. --exact Target name is an exact name rather than a substring --exit-code Exit with 0 if the time limit was reached, 1 for other programmatic aborts, and 2 if an error occurred; implies --no-ui, does not imply --run-until-crash or --max-total-time --features Space or comma separated list of features to activate --list List fuzz targets --manifest-path Path to Cargo.toml --max-total-time Fuzz at most of time (equivalent to -- -V ) --no-default-features Do not activate the default feature --no-run Compile, but don't fuzz --no-ui Disable user interface -p, --package Package containing fuzz target --persistent Enable persistent mode fuzzing --pretty Pretty-print debug output when generating coverage, displaying, or replaying --release Build in release mode --replay Replay corpus, crashes, hangs, or work queue. By default, an uninstrumented fuzz target is used. To replay with instrumentation, append -instrumented to , e.g., --replay corpus-instrumented. --reset Clear fuzzing data for one target, but leave corpus intact; to reset all targets, use --reset-all --resume Resume target's last fuzzing session --run-until-crash Stop fuzzing once a crash is found --slice If there are not sufficiently many cpus to fuzz all targets simultaneously, fuzz them in intervals of [default: 1200] --test Integration test containing fuzz target --timeout Number of seconds to consider a hang when fuzzing or replaying (equivalent to -- -t <TIMEOUT * 1000> when fuzzing) --verbose Show build output when generating coverage, displaying, or replaying -h, --help Print help -V, --version Print version