Wassail

wassail (WebAssembly static analyzer and inspection library) is a toolkit to perform both lightweight and heavyweight static analysis of WebAssembly modules.

• Web version
• Installation
• Usage
• Contributing

Web version

Parts of Wassail can be run in your web browser here.

Installation

0. Install opam

1. Run opam install core_unix

2. Run opam install .

Then you should be able to run the wassail command. You can also simply run dune exec -- wassail if you don't want to install it.

Usage

Wassail can perform a number of tasks on WebAssembly modules, both in their textual representation (.wat files) or in their binary representation (.wasm)

Listing imports

$ dune exec -- wassail imports ./benchmarks/benchmarksgame/fasta.wat
0       proc_exit       i32 ->
1       fd_close        i32 -> i32
2       fd_seek         i32, i64, i32, i32 -> i32
3       fd_write        i32, i32, i32, i32 -> i32
4       fd_fdstat_get   i32, i32 -> i32

Listing exports

$ dune exec -- wassail exports ./benchmarks/benchmarksgame/fasta.wat
5       _start   ->

Listing section sizes

Section sizes are reported in bytes.

$ dune exec -- wassail sizes ./benchmarks/benchmarksgame/fankuchredux.wat
23      type
42      import
12      func
0       table
9       memory
14      global
25      export
0       start
0       elem
882     code
0       data

Generating Call Graphs

To generate the call graph for a module foo.dot:

$ wassail callgraph benchmarks/benchmarksgame/fankuchredux.wat foo.dot

Output graph:

Generating Control-Flow Graphs

You can either generate a single CFG, for example to generate the CFG of function 4 from benchmark fankuchredux.wat into foo.dot:

$ wassail cfg benchmarks/benchmarksgame/fankuchredux.wat 4 foo.dot

Or you can generate all CFGs in a given directory:

$ wassail cfgs foo.wat out/

Example output:

Other entry points

$ dune exec -- wassail help
Static analysis of WebAssembly

  wassail SUBCOMMAND

=== subcommands ===

  callgraph                  . Generate the call graph for the module from file
                               [in], outputs as DOT to file [out]
  callgraph-adjlist          . Generate the call graph for the module from file
                               [in], outputs in a textual representation to file
                               [out]
  cdg                        . Produce a CDG for a given function
  cfg                        . Generate a DOT file representing the CFG of
                               function [fidx] from the wasm file [in], in file
                               [out]
  cfg-adjlist                . Generate the CFG of function [fidx] from the wasm
                               file [in], in two text files: [out].adjlist and
                               [out].nodes
  cfgs                       . Generate DOT files representing the CFG of each
                               function defined in the wasm file [in], and
                               outputs them in the directory [out_dir]
  count                      . Count instructions in a file
  count-in-slice             . Count the number of instructions in a slice for a
                               specific slicing criterion
  dependencies               . Produce a PDG for a given function
  dump                       . Outputs the entire WebAssembly file without
                               modification
  evaluate-slicing           . Evaluate the slicer on a a benchmark
  exports                    . List functions exported by a WebAssembly module
  find-criterion             . Find the slicing criterion in a program. Prints
                               the address the string ORBS.
  find-indirect-calls        . Find call_indirect instructions and shows the
                               function in which they appear as well as their
                               label
  function-body              . Returns the body of a given function
  function-instruction-labels
                             . Returns the labels of instructions of a given
                               function
  functions                  . Returns the indices of functions of a WebAssembly
                               modules, along with their name if they have one
  gen-slice-specific         . Generate a slice for a specific slicing criterion
  generate                   . Generate a WebAssembly module from a single
                               function
  icfg                       . Generate a DOT file representing an
                               interprocedural CFG (ICFG), starting at function
                               [fidx] from the wasm file [in]
  imports                    . List functions imported by a WebAssembly module
  instructions               . List instructions used by a WebAssembly module,
                               and how many time each instruction appears
  load                       . Load a module and quits
  mem-exports                . Outputs the number of memories exported by this
                               module
  mem-imports                . Outputs the number of memories exported by this
                               module
  postdom                    . Visualize the post-dominator tree of a function
  reduced-callgraph          . Generate the call graph for the module from file
                               [in], only considering functions reachable from
                               [fidx], outputs as DOT to file [out]
  schedule                   . Generate the analysis schedule for the module
                               from file [in]
  sizes                      . Output the size (in bytes) of each section of a
                               WebAssembly module
  slice                      . Produce an executable program after slicing the
                               given function at the given slicing criterion
  spec-inference             . Annotate the CFG with the inferred variables
  spec-inference-inter       . Annotate the ICFG with the inferred variables
  taint-cfg                  . Generate a DOT file representing the
                               taint-annotated CFG of function [fid] from the
                               wasm file [in], in file [out]
  taint-from-exported-to-imported
                             . Detects unsafe flows from exported functions to
                               imported functions
  taint-from-sources-to-sinks
                             . Detects unsafe flows from a list of sources to a
                               list of defined sinks
  taint-inter                . Performs summary-based interprocedural taint
                               analysis of a set of functions in file [file].
                               [funs] is a list of comma-separated function ids,
                               e.g., to analyze function 1, then analyze both
                               function 2 and 3 as part of the same fixpoint
                               computation, [funs] is 1 2,3. The full schedule
                               for any file can be computed using the `schedule`
                               target.
  taint-inter-classical      . Perform classical interprocedural taint analysis
                               from a given entry point
  taint-intra                . Just like `intra`, but only performs the taint
                               analysis
  taintcall-cfg              . Performs a inter-procedural taintcall analysis
                               and displays the results for the given CFGs
  version                    . print version information
  help                       . explain a given subcommand (perhaps recursively)

Contributing

Contributions are welcome! Wassail is licensed under the conditions of the GPLv3.0 license with a non-commercial usage clause.

Running the tests

$ make test

Using the web interface

You can access the web interface here, or compile it for yourself as follows:

$ opam install js_of_ocaml js_of_ocaml-ppx
$ make js
$ open js/index.html

References

The following publications use Wassail:

• Compositional Information Flow Analysis for WebAssembly Programs, SCAM 2020. (presentation video).
• Wassail: A WebAssembly Static Analysis Library, ProWeb 2021.
• Static Stack-Preserving Intra-Procedural Slicing of WebAssembly Binaries, ICSE 2022.
• Dynamic Slicing of WebAssembly Binaries, ICSME 2023.
• An Empirical Evaluation of Static, Dynamic, and Hybrid Slicing of WebAssembly Binaries, Journal of Systems and Software, 2025.

The following presentations might be useful as extra documentation:

• Building Static Analyses for WebAssembly Binaries with Wassail, PAW 2022.
• Wassail: A WebAssembly Static Analysis Library, ProWeb 2021.