fuzzing.md - mozsearch

(mozilla-projects-nss-runbooks-fuzzing)=

# Fuzzing NSS

NSS uses [libFuzzer](https://llvm.org/docs/LibFuzzer.html) to fuzz-test its

parsing and protocol code. The fuzz targets live under `fuzz/targets/` and

cover ASN.1/DER decoding, certificate-DN parsing, TLS/DTLS client and server

handshakes, PKCS #7/#8/#12, S/MIME, and ECH configuration decoding.

Every target is compiled into its own binary (e.g. `nssfuzz-tls-client`) and

run with AddressSanitizer and UndefinedBehaviorSanitizer enabled by default.

## Building the fuzz targets

The fuzz build requires **clang**.

```bash

# Build all fuzz targets (with ASan + UBSan + libFuzzer).

./build.sh --fuzz

# Optionally skip the test suite to speed up the build.

./build.sh --fuzz --disable-tests

```

The build system also accepts two specialised fuzz modes:

`--fuzz=oss`

: Used by OSS-Fuzz. Skips ASan/UBSan (the OSS-Fuzz build infrastructure

  supplies its own sanitizer flags) and adds `-Dfuzz_oss=1`.

`--fuzz=tls`

: Enables *Totally Lacking Security* mode (see [below][totally lacking security (tls) mode]).

After a successful build the fuzz binaries are placed in

`../dist/Debug/bin/`. Each binary is named `nssfuzz-<target>`, for

example `nssfuzz-tls-client` or `nssfuzz-asn1`.

The exact compiler and sanitizer flags are configured in `coreconf/fuzz.sh`.

## Totally Lacking Security (TLS) mode

`--fuzz=tls` builds NSS in the special 'Totally Lacking Security' mode that mocks out various cryptographic checks. This mode was originally designed for the running the TLS-specific fuzz targets, hence the name, but it's been extended to handle other fuzzers where cryptographic checks get in the way of fuzzing (e.g. PKCS #7).

Fuzzers can be registered to use this mode by adding a file named `<target>-no_fuzzer_mode.options` in the `fuzz/options/` directory.

## Running a fuzz target locally

The fuzz targets use the standard [libFuzzer interface](https://llvm.org/docs/LibFuzzer.html).

```bash

# Run with an existing corpus directory.

../dist/Debug/bin/nssfuzz-tls-client fuzz/corpus/tls-client/

# Useful libFuzzer flags:

#   -max_total_time=300   Stop after 300 seconds.

#   -fork=30 Run 30 parallel instances

#   -runs=0               Just verify the corpus (no new mutations).

```

To reproduce a crash from a test case file:

```bash

../dist/Debug/bin/nssfuzz-tls-client path/to/crash-input

```

## Corpus management

Using a good corpus is essential for effective fuzzing. A corpus is a set of test inputs that the fuzzer uses as a starting point. A good corpus should be diverse and cover a wide range of code paths.

### Downloading the public OSS-Fuzz corpus

OSS-Fuzz publishes public corpora for every target. You can download them

directly:

```bash

target=tls-client

mkdir -p fuzz/corpus/$target && cd fuzz/corpus/$target

curl -O "https://storage.googleapis.com/nss-backup.clusterfuzz-external.appspot.com/corpus/libFuzzer/nss_${target}/public.zip"

unzip public.zip && rm public.zip

cd -

```

Replace `tls-client` with the name of the target you want.

### Extracting corpus from existing tests (Frida)

NSS ships a [Frida](https://frida.re/)-based tool that intercepts NSS API

calls during test execution and saves the inputs as corpus files. This is a

great way to bootstrap a corpus from the existing test suite.

The tooling lives in `fuzz/config/frida_corpus/`:

- `hooks.js` -- Frida script that attaches interceptors to NSS functions

  (e.g. `SEC_ASN1DecodeItem_Util`, `ssl_DefRecv`, etc.) and sends the

  captured data back to the Python harness.

- `cli.py` -- Python harness that spawns a program under Frida, receives

  intercepted data, and writes corpus files to disk.

## Continuous fuzzing (OSS-Fuzz)

All NSS fuzz targets run continuously on [OSS-Fuzz](https://oss-fuzz.com/).

The project configuration lives at

[google/oss-fuzz: projects/nss/project.yaml](https://github.com/google/oss-fuzz/blob/master/projects/nss/project.yaml).

Useful dashboards:

- [OSS-Fuzz introspector for NSS](https://introspector.oss-fuzz.com/project-profile?project=nss)

  -- code coverage and fuzz introspector reports.

- [ClusterFuzz dashboard](https://oss-fuzz.com/) -- requires access; shows

  crash reports, corpus statistics, and coverage.

## Fuzzing on Taskcluster (CI)

NSS fuzzing tasks run on Taskcluster as part of the CI pipeline. The entry

point is `automation/taskcluster/scripts/fuzz.sh` and the jobs are registered in

`taskcluster/kinds/fuzz/kind.yml`, which:

1. Fetches the pre-built fuzz binaries.

2. Downloads the public OSS-Fuzz corpus for the target.

3. Reads libFuzzer options from `fuzz/options/<target>.options`.

4. Runs `nssfuzz-<target>` against the corpus.

You can trigger fuzzing tasks on try by pushing to the NSS try repository.

Results are visible on [Treeherder](https://treeherder.mozilla.org/jobs?repo=nss-try).

### Mozilla internal services

Two services maintained in [MozillaSecurity/orion](https://github.com/MozillaSecurity/orion)

support NSS fuzzing:

- [nss-coverage](https://github.com/MozillaSecurity/orion/tree/master/services/nss-coverage)

  -- collects code coverage information from fuzzing runs. Reports are

  published at <https://fuzzmanager.fuzzing.mozilla.org/covmanager/reports/>.

- [nss-corpus-update](https://github.com/MozillaSecurity/orion/tree/master/services/nss-corpus-update)

  -- mirrors the public OSS-Fuzz corpora and populates the private corpus

  bucket with new test cases.

## Adding a new fuzz target

Fuzz target source files go in `fuzz/targets/`. When adding a new target,

keep the following in mind:

1. **Create an \`\`.options\`\` file** at `fuzz/options/<target>.options`. Other

   tooling (CI, OSS-Fuzz) depends on its existence. At minimum it should

   set `max_len` and `len_control`:

   ```ini

   [libfuzzer]

   len_control = 100

   max_len = 16777215

```

2. **Register the target** in `fuzz/targets/targets.gyp` and

   `fuzz/fuzz.gyp` so the build system picks it up.

3. **Schedule CI runs** by adding the corresponding fuzzing tasks in the

   Taskcluster task graph configuration at

   `taskcluster/kinds/fuzz/kind.yml`.

4. **(Optional but recommended) Add suitable Frida hooks** in `fuzz/config/frida_corpus/hooks.js`

   and `fuzz/config/frida_corpus/cli.py` to automatically extract corpus

   inputs from existing tests.

Source code

Revision control

Copy as Markdown

Other Tools