test-fuzz

test-fuzz é um subcomando do Cargo e uma coleção de macros Rust para automatizar certas tarefas relacionadas a fuzzing com afl.rs, incluindo:

• gerar um corpus de fuzzing
• implementar um harness de fuzzing

test-fuzz realiza essas tarefas (em parte) usando os recursos de teste do Rust. Por exemplo, para gerar um corpus de fuzzing, o test-fuzz registra os argumentos de um alvo cada vez que ele é chamado durante uma invocação de cargo test. Da mesma forma, o test-fuzz implementa um harness de fuzzing como um teste adicional em um binário gerado por cargo-test. Essa integração estreita com os recursos de teste do Rust é o que motiva o nome test-fuzz.

Conteúdo

1. [Instalação]
2. [Visão geral]
3. [Componentes]
   • test_fuzz macro
   • test_fuzz_impl macro
   • [comando cargo test-fuzz]
   • [Funções e macros de conveniência]
4. [Recursos do pacote test-fuzz]
5. [Arquivos de corpus gerados automaticamente]
6. [Variáveis de ambiente]
7. [Limitações]
8. [Dicas e truques]
9. [Política de versionamento semântico]
10. [Licença]

Instalação

Instale o cargo-test-fuzz e o afl.rs com o seguinte comando:```sh cargo install cargo-test-fuzz cargo-afl

## Visão geral

Fuzzing com `test-fuzz` consiste essencialmente em três etapas:\*

1. **Identifique um alvo de fuzzing**:
   - Adicione as seguintes `dependencies` ao arquivo `Cargo.toml` do crate alvo:
     ```toml
     serde = "*"
     test-fuzz = "*"
     ```
   - Preceda a função alvo com a macro [`test_fuzz`]:
     ```rust
     #[test_fuzz::test_fuzz]
     fn foo(...) {
         ...
     }
     ```
2. **Gere um corpus** executando `cargo test`:   ```
   cargo test

3. Faça fuzz do seu alvo executando cargo test-fuzz: ``` cargo test-fuzz foo
   root@kitploit:~

* Uma etapa adicional e preliminar pode ser necessária após uma reinicialização:```sh cargo afl system-config

Note que o comando acima executa `sudo` internamente. Portanto, você pode ser solicitado a inserir sua senha.

## Componentes

### Macro `test_fuzz`

Preceder uma função com a macro `test_fuzz` indica que a função é um alvo de fuzzing.

Os efeitos principais da macro `test_fuzz` são:

- Adiciona instrumentação ao alvo para serializar seus argumentos e escrevê-los em um arquivo de corpus cada vez que o alvo for chamado. A instrumentação é condicionada por `#[cfg(test)]` de modo que os arquivos de corpus são gerados apenas ao executar testes (no entanto, veja [`enable_in_production`] abaixo).
- Adiciona um teste para ler e desserializar argumentos da entrada padrão e aplicar o alvo a eles. O teste verifica uma variável de ambiente, definida por [`cargo test-fuzz`], para que o teste não bloqueie ao tentar ler da entrada padrão durante uma invocação normal de `cargo test`. O teste é encapsulado em um módulo para reduzir a probabilidade de colisão de nomes. Atualmente, o nome do módulo é `target_fuzz`, onde `target` é o nome do alvo (no entanto, veja [`rename`] abaixo).

#### Argumentos

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

Imponha `where_predicates` (por exemplo, limites de trait) na struct usada para serializar/desserializar argumentos. Isso pode ser necessário, por exemplo, se o tipo de argumento de um alvo for um tipo associado. Para um exemplo, veja [associated_type.rs] neste repositório.

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

Use `parameters` como os parâmetros de tipo do alvo ao realizar fuzzing. Exemplo:```rust
#[test_fuzz(generic_args = "String")]
fn foo<T: Clone + Debug + Serialize>(x: &T) {
    ...
}

Nota: Os argumentos do alvo devem ser serializáveis para cada instanciação de seus parâmetros de tipo. Mas os argumentos do alvo são necessários desserializáveis apenas quando o alvo é instanciado com parameters.

impl_generic_args = "parameters"

Use parameters como os parâmetros de tipo Self do alvo ao fazer fuzzing. Exemplo:```rust #[test_fuzz_impl] impl<T: Clone + Debug + Serialize> for Foo { #[test_fuzz(impl_generic_args = "String")] fn bar(&self, x: &T) { ... } }

Nota: os argumentos do alvo devem ser serializáveis para **cada** instanciação de seus parâmetros de tipo `Self`. Porém, os argumentos do alvo só precisam ser desserializáveis quando o `Self` do alvo for instanciado com `parameters`.

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

Ao serializar os argumentos do alvo, converta valores do tipo `X` para o tipo `Y` usando a implementação de `From<X>` em `Y`, ou do tipo `&X` para o tipo `Y` usando a implementação do trait não padrão `test_fuzz::FromRef<X>` em `Y`. Ao desserializar, converta esses valores de volta para o tipo `X` usando a implementação do trait não padrão `test_fuzz::Into<X>` em `Y`.

Ou seja, o uso de `convert = "X, Y"` deve ser acompanhado por determinadas implementações. Se `X` implementa [`Clone`], então `Y` pode implementar o seguinte:```rust
impl From<X> for Y {
    fn from(x: X) -> Self {
        ...
    }
}

Se X não implementar Clone, então Y deve implementar o seguinte:```rust impl test_fuzz::FromRef for Y { fn from_ref(x: &X) -> Self { ... } }

Além disso, `Y` deve implementar o seguinte (independentemente de `X` implementar [`Clone`]):```rust
impl test_fuzz::Into<X> for Y {
    fn into(self) -> X {
        ...
    }
}

A definição de test_fuzz::Into é idêntica à de std::convert::Into. A razão para usar uma trait não padrão é evitar conflitos que possam surgir de implementações abrangentes de traits padrão.

enable_in_production

Gere arquivos de corpus quando não estiver executando testes, desde que a variável de ambiente TEST_FUZZ_WRITE esteja definida. O padrão é gerar arquivos de corpus apenas durante a execução de testes, independentemente de TEST_FUZZ_WRITE estar definida. Ao executar um alvo fora do diretório do seu pacote, defina TEST_FUZZ_MANIFEST_PATH para o caminho do arquivo Cargo.toml do pacote.

AVISO: Definir enable_in_production pode introduzir um vetor de negação de serviço. Por exemplo, definir essa opção para uma função que é chamada muitas vezes com argumentos diferentes pode encher o disco. A verificação de TEST_FUZZ_WRITE tem a finalidade de fornecer alguma defesa contra essa possibilidade. Ainda assim, considere essa opção com cuidado antes de usá-la.

execute_with = "function"

Em vez de chamar o alvo diretamente:

• construir um closure do tipo FnOnce() -> R, onde R é o tipo de retorno do alvo, de modo que chamar o closure chame o alvo;
• chamar function com o closure.

Chamar o alvo dessa maneira permite que function configure o ambiente da chamada. Isso pode ser útil, por exemplo, para fuzzing de Substrate externalities.

no_auto_generate

Não tente auto-generate corpus files para o alvo.

only_generic_args

Registre os argumentos genéricos do alvo durante a execução de testes, mas não gere arquivos de corpus e não implemente um harness de fuzzing. Isso pode ser útil quando o alvo é uma função genérica, mas não está claro quais parâmetros de tipo devem ser usados para fuzzing.

O fluxo de trabalho pretendido é: habilite only_generic_args, depois execute cargo test seguido por cargo test-fuzz --display generic-args. Um dos argumentos genéricos resultantes pode ser utilizável como parameters de generic_args. Da mesma forma, argumentos genéricos resultantes de cargo test-fuzz --display impl-generic-args podem ser utilizáveis como parameters de impl_generic_args.

Observe, no entanto, que o fato de um alvo ter sido chamado com certos parâmetros durante os testes não implica que os argumentos do alvo sejam serializáveis/desserializáveis quando esses parâmetros são usados. Os resultados de --display generic-args/--display impl-generic-args são meramente sugestivos.

rename = "name"

Trate o alvo como se seu nome fosse name ao adicionar um módulo ao escopo delimitador. A expansão do macro test_fuzz adiciona uma definição de módulo ao escopo delimitador. Por padrão, o módulo é nomeado da seguinte forma:

• Se o alvo não aparecer em um bloco impl, o módulo será nomeado target_fuzz__, onde target é o nome do alvo.
• Se o alvo aparecer em um bloco impl, o módulo será nomeado path_target_fuzz__, onde path é o último segmento do caminho do tipo Self do impl.

Contudo, o uso dessa opção faz com que o módulo seja nomeado, em vez disso, name_fuzz__. Exemplo:```rust #[test_fuzz(rename = "bar")] fn foo() {}

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

#### Atributos de campo do Serde em argumentos de função

A macro `test_fuzz` permite que [atributos de campo do Serde] sejam aplicados a argumentos de função. Isso fornece outra ferramenta para lidar com tipos difíceis.

O exemplo a seguir ilustra isso. As traits `serde::Serialize` e `serde::Deserialize` não podem ser derivadas para `Context` porque ela contém um `Mutex`. No entanto, `Context` implementa `Default`. Assim, aplicar `#[serde(skip)]` ao argumento `Context` faz com que ele seja ignorado durante a serialização e que assuma seu valor padrão durante a desserialização.```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);
}

Note que quando atributos de campo Serde são aplicados a um argumento, a macro test_fuzz não realiza nenhuma outra conversions no argumento.

macro test_fuzz_impl

Sempre que a macro test_fuzz for usada em um bloco impl, o impl deve ser precedido pela macro test_fuzz_impl. Exemplo:```rust #[test_fuzz_impl] impl Foo { #[test_fuzz] fn bar(&self, x: &str) { ... } }

A razão para este requisito é a seguinte. A expansão da macro [`test_fuzz`] adiciona uma definição de módulo ao escopo circundante. No entanto, uma definição de módulo não pode aparecer dentro de um bloco `impl`. Anteceder o `impl` com a macro `test_fuzz_impl` faz com que o módulo seja adicionado fora do bloco `impl`.

Se você vir um erro como o seguinte, provavelmente significa que falta um uso da macro `test_fuzz_impl`:```
error: module is not supported in `trait`s or `impl`s

test_fuzz_impl atualmente não tem opções.

Comando cargo test-fuzz

O comando cargo test-fuzz é usado para interagir com alvos de fuzzing e para manipular seus corpora, crashes, hangs e filas de trabalho. Exemplos de invocações incluem:

1. Listar alvos de fuzzing ``` cargo test-fuzz --list
   root@kitploit:~

2. Exibir o corpus do alvo foo ``` cargo test-fuzz foo --display corpus
   root@kitploit:~

3. Alvo de fuzz foo ``` cargo test-fuzz foo
   root@kitploit:~

4. Reproduzir crashes encontrados para o alvo foo ``` cargo test-fuzz foo --replay crashes
   root@kitploit:~

Uso```

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