This repository contains the code for SAWScript, the scripting language that forms the primary user interface to the Software Analysis Workbench (SAW). It provides the ability to reason about formal models describing the denotation of programs written in languages such as C, Java, and Cryptol.
The SAWScript tutorial gives an introduction to using the SAWScript interpreter.
Precompiled SAWScript binaries for a variety of platforms are available on the releases page.
SAW can use many theorem provers, but because of its use of Cryptol it always needs to have Microsoft Research's Z3 SMT solver installed. You can download Z3 binaries for a variety of platforms from their releases page.
SAW generally requires the most recent version of Z3, which at the time of writing this file is 4.5.0.
After installation, make sure that
z3.exe on Windows)
is on your PATH.
To build SAWScript and related utilities (CSS, LSS, JSS) from source:
Ensure that you have the Stack program on your
PATH. If you don't already have Stack, then
cabal install stack, or download a precompiled binary from https://github.com/commercialhaskell/stack/releases.
Ensure that you have the C libraries and header files for
terminfo, which generally comes as part of
ncurseson most platforms. On Fedora, it is part of the
ncurses-compat-libspackage. You will also need the C headers for
Ensure that you have the programs
PATH. Z3 binaries are available at https://github.com/Z3Prover/z3/releases
stack.yamlfor your OS and preferred GHC.
Choose one of the Stack YAML config files and link it to
ln -s stack.<ghc version and os>.yaml stack.yaml
stack-<ghc version>-unix.yamlfiles are for both Linux and OS X.
(Alternatively, you can
export STACK_YAML=stack.<ghc version and os>.yaml
instead of creating a symlink.
Developers: defining a
STACK_YAMLenv var also overrides the
stack.yamlfile, if any, and so is useful for testing a alternative build without permanently changing your default. You can even define
STACK_YAMLonly for the current command: e.g.
STACK_YAML=stack.<ghc version and os>.yaml stack build
will build SAWScript using the given Stack YAML.)
Build SAWScript by running
The SAWScript executables will be created in
echo `stack path --local-install-root`/bin
a path under the SAWScript repo. You can install SAWScript into a more predictable location by running
which installs into
stack path --local-bin-path
Optionally, run ./stage.sh to create a binary tarball.
Notes on LLVM
SAW can analyze LLVM programs (usually derived from C, but potentially
for other languages). The only tool strictly required for this is a
compiler that can generate LLVM bitcode, such as
having the full LLVM tool suite available can be useful. We have tested
SAW with LLVM and
clang versions from 3.5 to 4.0, as well as the
clang bundled with Apple Xcode. We welcome bug reports on
any failure to parse bitcode from LLVM versions in that range.
Note that successful parsing doesn't necessarily mean that verification
will be possible for all language constructs. There are various
instructions that are not supported during verification. However,
any failure during
llvm_load_module should be considered a bug.
Many dependencies are automatically downloaded into
deps/ when you
Manual Installation above. Key automatically
downloaded dependencies include:
deps/cryptol-verifier/: Cryptol Symbolic Simulator (CSS)
deps/jvm-verifier/: Java Symbolic Simulator (JSS)
deps/llvm-verifier/: LLVM Symbolic Simulator (LSS)
deps/saw-core/: SAWCore intermediate language, used by CSS, JSS, LSS and SAWScript
deps/abcBridge/: Haskell bindings for ABC
For SAW developers
saw-script main executable cannot be loaded into GHCi due to a
linker issue. However, the rest of the library can be manipulated in GHCi, with
a little convincing.
If you are using
cabal to build, select the
$ cabal new-repl saw-script
If you are using
stack to build, select the
saw-script library target:
$ stack repl saw-script:lib
In order to use interactive tools like
intero, you need to configure them with
this target. You can configure
intero-mode in Emacs to use the
library target by setting the variable
intero-targets to the string
"saw-script:lib". To make this setting persistent for all files in this
project, place the following snippet in the file
((haskell-mode (intero-targets "saw-script:lib")))
Much of the work on SAW has been funded by, and lots of design input was provided by the team at the NSA's Trusted Systems Research Group, including Brad Martin, Frank Taylor and Sean Weaver.
Portions of SAW are also based upon work supported by the Office of Naval Research under Contract No. N68335-17-C-0452. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Office of Naval Research.