Integrating an app

This page shows the fuzzing/ folder an app adds to opt in, who owns each file, and the order to create them. Each file has its own reference page, linked below. The app-boilerplate fuzzing/ folder is the reference to copy and adapt.

The fuzzing subtree

An integrated app owns this subtree at its root:

<app>/fuzzing/
  fuzz-manifest.toml       # what to fuzz: target, seeds, dictionary, coverage
  CMakeLists.txt           # sources, include dirs, compile definitions
  harness/
    fuzz_dispatcher.c      # entry point + adapter to the real dispatcher
  mock/
    mocks.h  / mocks.c     # required fuzz symbols + any app-specific stubs
    scenario_layout.h      # generated; committed with bootstrap values
  invariants/
    fuzz_globals.zon       # generated model; git-ignored, never committed
    zero-symbols.txt       # globals kept out of the prefix
    domain-overrides.txt   # optional per-field value constraints
  macros/                  # optional
    add_macros.txt         # extra -D defines for the fuzz build
    exclude_macros.txt     # -D defines to drop from the fuzz build
  base-corpus.zip          # optional promoted seeds (+ base-corpus.compat-key)

Ownership at a glance

"Owner" is who edits the file: you (the app author) or the tooling (generated, do not hand-edit).

File	Owner	Reference
fuzz-manifest.toml	you	The fuzz manifest
CMakeLists.txt	you	The CMake integration
harness/fuzz_dispatcher.c	you	The harness
mock/mocks.h / mocks.c	you	The mocks
mock/scenario_layout.h	tooling	The mocks
invariants/zero-symbols.txt	you	Tuning invariants
invariants/domain-overrides.txt	you	Tuning invariants
invariants/fuzz_globals.zon	tooling	Tuning invariants
add_macros.txt / exclude_macros.txt	you	Build macros
base-corpus.zip / .compat-key	you	Corpus and compatibility keys

Everything that is not app-specific — crypto, NBGL, OS, and SDK library mocks — comes from the framework through include(${BOLOS_SDK}/fuzzing/cmake/LedgerAppFuzz.cmake). Do not reimplement it in the app.

Integration checklist

1. Copy the boilerplate fuzzing/ folder into your app and delete the parts you do not need.
2. Write the manifest: name the target, list the APDU CLA/INS to seed, and add a dictionary of meaningful byte tokens.
3. Adjust the CMakeLists.txt so it compiles your app sources (minus main()) and points at your include dirs.
4. Fill in the harness: the command table and the adapter to your real dispatcher.
5. Provide the mocks for the required symbols and any app stub the fuzz build needs (for example a PRINTF no-op).
6. Run a first campaign (Running a campaign). The first build bootstraps the generated files; expect low coverage until you tune the next step.
7. Tune the invariants (zero-symbols.txt, domain-overrides.txt) to shorten the prefix and focus the fuzzer.
8. When coverage is good, promote the corpus and wire the app into CI.

File references

• The fuzz manifest
• The CMake integration
• The harness
• The mocks
• Tuning invariants
• Build macros