The SAW scripting language.
siddharthist Update llvm-pretty and llvm-pretty-bc-parser submodules (#333)
* Update llvm-pretty and llvm-pretty-bc-parser submodules

* Update crucible submodule to track llvm-pretty* changes

* Changes for updated Crucible submodule

- TimeoutResult from symbolic simulator
- New X86_FP80 type

* Update llvm-verifier submodule to account for llvm-pretty* changes
Latest commit bbbb4ad Dec 15, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
deps Update llvm-pretty and llvm-pretty-bc-parser submodules (#333) Dec 15, 2018
doc Add integration tests for new global handling Oct 8, 2018
examples Rewrite aes.saw proof to avoid using bogus rule ecEq_refl. Dec 6, 2018
intTests Update some integration tests to use cryptol-specs Oct 16, 2018
saw Further excision of fixed ABC dependencies Jun 12, 2018
src/SAWScript Update llvm-pretty and llvm-pretty-bc-parser submodules (#333) Dec 15, 2018
.gitignore add .class to gitignore Jul 23, 2018
.gitmodules Add submodule for cryptol-specs Oct 16, 2018
.travis.yml Re-enable Linux/GHC-8.2.2 on Travis Sep 6, 2018
CHANGES.md Remove TODO from change log Apr 13, 2016
LICENSE Change license to BSD3 Apr 12, 2016
Makefile Add Makefile with Emacs TAGS target. Jun 24, 2016
README.md readme: note zlib C header dependency Aug 16, 2018
Setup.hs Changes missed in previous Setup commit. Sep 5, 2018
build.sh Yet another submodule attempt Jul 18, 2018
cabal.project add crux to project Sep 27, 2018
cabal.project.GHC-8.4.3.freeze Rename Cabal freeze file Sep 6, 2018
gen-doc A small script to make it easier to generate docs with new-haddock Apr 17, 2018
jenkins-junit-munge.xsl Move top-level files into SAWScript in anticipation of repo split. Apr 16, 2015
saw-script.cabal Update llvm-pretty and llvm-pretty-bc-parser submodules (#333) Dec 15, 2018
saw-script.el Merge pull request #297 from siddharthist/el-comments Aug 21, 2018
stack.ghc-8.2.yaml Set `allow-newer` to true for GHC 8.2 Stack Dec 13, 2018
stack.ghc-8.4.yaml Update dependency versions. Sep 26, 2018
stage.sh Include Cryptol in release tarballs again Mar 14, 2018

README.md

Build Status

SAWScript

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.

Documentation

The SAWScript tutorial gives an introduction to using the SAWScript interpreter.

Precompiled Binaries

Precompiled SAWScript binaries for a variety of platforms are available on the releases page.

Getting Z3

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 (or z3.exe on Windows) is on your PATH.

Manual Installation

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 ncurses on most platforms. On Fedora, it is part of the ncurses-compat-libs package. You will also need the C headers for zlib.

  • Ensure that you have the programs javac and z3 on your PATH. Z3 binaries are available at https://github.com/Z3Prover/z3/releases

  • Setup a stack.yaml for your OS and preferred GHC.

    Choose one of the Stack YAML config files and link it to stack.yaml:

    ln -s stack.<ghc version and os>.yaml stack.yaml
    

    The stack-<ghc version>-unix.yaml files 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_YAML env var also overrides the stack.yaml file, if any, and so is useful for testing a alternative build without permanently changing your default. You can even define STACK_YAML only 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

    ./build.sh
    

    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

    stack install
    

    which installs into

    stack path --local-bin-path
    

    which is $HOME/.local/bin by default.

  • 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 clang. However, 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 version of 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.

Related Packages

Many dependencies are automatically downloaded into deps/ when you build using build.sh; see Manual Installation above. Key automatically downloaded dependencies include:

For SAW developers

Presently, the 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 saw-script target:

$ 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 saw-script 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 src/.dir-locals.el:

((haskell-mode
  (intero-targets "saw-script:lib")))

Acknowledgements

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.