stan: Haskell STatic ANalyser

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Stan is a Haskell STatic ANalysis CLI tool. See README.md for more details.


[Skip to Readme]

Properties

Versions 0.0.0.0, 0.0.0.0, 0.0.1.0, 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.1.0, 0.1.2.0, 0.1.2.1
Change log CHANGELOG.md
Dependencies array (>=0.5 && <0.6), base (>=4.13 && <4.15), base64 (>=0.4.1 && <0.5), blaze-html (>=0.9.1 && <0.10), bytestring (>=0.10 && <0.11), clay (>=0.13 && <0.14), colourista (>=0.1.0.0 && <0.2), containers (>=0.6 && <0.7), cryptohash-sha1 (>=0.11 && <0.12), dir-traverse (>=0.2.2.2 && <0.3), directory (>=1.3 && <1.4), extensions (>=0.0.0.1 && <0.1), filepath (>=1.4 && <1.5), ghc (>=8.8 && <8.11), ghc-boot-th (>=8.8 && <8.11), gitrev (>=1.3.1 && <1.4), optparse-applicative (>=0.15 && <0.16), pretty-simple (>=3.2 && <3.3), relude (>=0.7.0.0 && <0.8), slist (>=0.1 && <0.2), stan, text (>=1.2 && <1.3), tomland (>=1.3.0.0 && <1.4), trial (>=0.0.0.0 && <0.1), trial-optparse-applicative (>=0.0.0.0 && <0.1), trial-tomland (>=0.0.0.0 && <0.1), unordered-containers (>=0.2 && <0.3) [details]
License MPL-2.0
Copyright 2020 Kowainik
Author Veronika Romashkina, Dmitrii Kovanikov
Maintainer Kowainik <xrom.xkov@gmail.com>
Category Static Analysis
Home page https://github.com/kowainik/stan
Bug tracker https://github.com/kowainik/stan/issues
Source repo head: git clone https://github.com/kowainik/stan.git
Uploaded by vrom911 at 2020-06-21T17:23:54Z

Modules

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for stan-0.0.0.0

[back to package description]

Stan

Stan Logo

GitHub CI Hackage MPL-2.0 license

Stan is a Haskell STatic ANalysis tool.

⚠️ Note: Stan is in the beta phase. The API is the subject to be changed if required by our needs ⚠️

Table of Contents

What this tool is about

[Back to the Table of Contents] ↑

Stan is a command-line tool for analysing Haskell projects and outputting discovered vulnerabilities in a helpful way with possible solutions for detected problems. Stan is searching for not only performance or error-prone code pieces, but it also can help with establishing and applying best-practices from the whole Haskell ecosystem.

Although Haskell is a statically typed language, not all properties can be encoded in types. Even though GHC is quite a powerful compiler, it tries to be library-agnostic and provide only language-specific suggestions, while Stan uses the knowledge about the current state of the ecosystem and commonly used libraries.

You will find Stan helpful if you enjoy writing in Haskell, but want more guarantees from your code, not provided by the Haskell type system or GHC.

Goals

[Back to the Table of Contents] ↑

Stan design and implementation is driven by the following goals:

Features

[Back to the Table of Contents] ↑

Stan is a configurable CLI tool. Besides the main feature of analysing Haskell projects statically, Stan has a list of features that make it unique, easy to use and flexible to configure:

You can see an example of Stan HTML report hosted online here:

The below example of the terminal output gives you the understanding of what sorts of analysis you can expect from Stan:

Stan terminal example

How it works

[Back to the Table of Contents] ↑

Stan analysis is based on the HIE files — compile-time information about Haskell source code gathered and recorded by GHC. The HIE files contain the Haskell AST, detailed information about each identifier and types of all expressions and sub-expressions. GHC does a huge amount of work when compiling the Haskell projects, and Stan takes advantage of this feature to avoid duplicating the work and focus more on the unique features.

To analyse HIE files easily, we developed an eDSL for defining AST and Type patterns based on the final taggless approach. Stan algorithm traverses HIE AST for each HIE file in the project, and matches every AST node with the given pattern to find potential vulnerabilities in the code.

Each Stan analysis check is represented by the inspection with the unique ID. Each inspection has a name, description, severity, list of categories, pattern for matching relevant parts of source code and possible solutions to the problem.

When an inspection is casted on the project, it produces zero or more observations — vulnerabilities in the specific parts of the code. You can think of an observation as a pair of an inspection and a piece of source code where this inspection was triggered. Each observation is assigned an unique stable ID depending on the source location, so you can refer to them later or ignore.

You can disable inspections or enable them only in particular modules using check — rules for controlling which inspections to run and where. Each check has a type (include or exclude), filter (by inspection id, category, severity, etc.) and scope (file, directory, everything). Checks can be specified using either TOML of CLI interfaces. By default, Stan analyses all source files using all implemented inspections.

If you want to understand Stan terminology better, refer to the glossary:

Installation instructions

[Back to the Table of Contents] ↑

Stan takes advantage of the GHC API to provide its analysis. Because of this, Stan and the analysed project need to be built with the same GHC version (for more details see #178). That is why the easiest and most robust way to install Stan is to build it from sources on your machine.

Note: Stan is compatible with the GHC versions ⩾ 8.8

Using Cabal

[Back to the Table of Contents] ↑

Below are the steps to install Stan using the Cabal build tool.

You need to have Cabal ⩾ 2.4

First, you need to clone the repository:

$ git clone https://github.com/kowainik/stan.git
$ cd stan

Then, you need to build it using Cabal:

$ cabal v2-build exe:stan

Finally, you can copy the resulting executable under the desired location (that should be under the PATH environment variable), like so:

$ cp dist-newstyle/build/x86_64-linux/ghc-8.8.3/stan-0.0.0.0/x/stan/build/stan/stan ~/.local/bin/stan

The path to the executable will be outputted as the last line of the previous command.

Using Stack

[Back to the Table of Contents] ↑

Below are the steps to install Stan using the Stack build tool.

You need to have Stack ⩾ 2.1.3

First, you need to clone the repository.

$ git clone https://github.com/kowainik/stan.git
$ cd stan

Then, you need to build it using Stack:

$ stack build

Finally, you can copy the resulting executable under the desired location (that should be under the PATH environment variable), like so:

$ cp "$(stack path --local-install-root)/bin/stan" ~/.local/bin/stan

Usage instructions

[Back to the Table of Contents] ↑

Stan works with the HIE files to analyse Haskell projects. Therefore, Stan requires users to generate HIE files in advance. Fortunately, it is straightforward to satisfy this necessity. To produce HIE files, add the following GHC options in your project's .cabal file to each stanza you want to analyse:

    ghc-options:       -fwrite-ide-info
                       -hiedir=.hie

Recommendation: you can use the common stanzas feature to write the above options only once and enable them in each stanza easily.

Note: here we recommend generating the HIE files into .hie/ folder. As it is the recommendation only, you can specify your own folder as well. But then you will need to run stan using the --hiedir option with the specified path to your hie folder.

After creating HIE files, you can just run Stan on the project:

$ stan

to see all found vulnerabilities in your terminal.

If you want to see a more detailed information in a more structured way, you can generate an HTML report (to the stan.html file) using the following command:

$ stan report

Stan strives to implement the convenient interface, so you can use the tool without configuring a lot in advance. However, the tool also provides various ways to set it up in the way to be the most efficient with your particular use case.

General configuration info

[Back to the Table of Contents] ↑

Stan's work can be configured from the multiple sources (in increasing order of priority):

  1. Default settings (hard-coded in the library — includes no custom settings)
  2. Environment variables
  3. TOML file configuration
  4. CLI arguments

Stan runtime settings have many parts, and each of them can come from different configuration sources. If some option is specified through multiple sources, the most prioritized one will be used. In addition, Stan helps to understand its own configuration, so it outputs detailed information about each part of the config, what configuration settings were used and how they were set.

Configuration explanation

TOML configurations

[Back to the Table of Contents] ↑

Stan supports TOML runtime configuration in order to customize the work of the tool based on the user's individual requirements. You can use the TOML configuration to disable some inspections, enable them only in particular Haskell modules, ignore some observations or completely remove some files from the analysis.

See Haddock documentation for explanation of how the TOML configuration works and examples of the different use cases.

In case you have a number of TOML files locally, the following rules describe how Stan decides which TOML configuration file to use:

Command-line Interface

[Back to the Table of Contents] ↑

This section describes what is possible to achieve with the Stan CLI. If you have already installed the analyser, you can use

$ stan --help

to get the short information of all possible commands and options in your terminal.

Main command

[Back to the Table of Contents] ↑

The main command is the one that actually would analyse the Haskell codebase. There are plenty of configurations and options you can tune for each run (similarly to the TOML configurations):

More precisely the commands and options are described in here:

stan
    [REPORT]
    [   CHECKs {[TYPE option] [FILTER option] [SCOPE option]}
      | REMOVEs {SCOPE option}
      | IGNOREs {ID option}
    ]
    [--hiedir=DIR_PATH]
    [--cabal-file-path=FILE_PATHs]
    [--config-file=FILE_PATH]
    [--no-default]
    [-s|--short]
    [--hide-solution]
    [-h|--help]
    [-v|--version]

Description:
  CHECKs           Command to Specify the list of checks
  REMOVEs          Command to Specify scope to be removed
  IGNOREs          Command to Specify the list of what needs to be ignored
  REPORT           Command to generate an HTML Report
  --hiedir=DIR_PATH        Relative path to the directory with HIE
                           files (default: .hie)
  --cabal-file-path=FILE_PATHs
                           Relative path to the .cabal file (can specify many of this option)
  --config-file=FILE_PATH  Relative path to the .toml configurations file
  --no-default             Ignore local .stan.toml configuration file
  -s,--short               Hide verbose output information for observations
  --hide-solution          Hide verbose solution information for observations
  -h,--help                Show this help text
  -v,--version             Show Stan's version

Sub-commands options:


  TYPE:
    --include                Include check
    --exclude                Exclude check
  FILTER:
    --id=INSPECTION_ID       Inspection ID to be used
    --severity=SEVERITY      Inspection Severity to exclude or include
    --category=CATEGORY      Inspection Category to exclude or include
    --filter-all             Exclude or include ALL inspections
  SCOPE:
    --file=FILE_PATH         File to exclude or include
    --directory=DIRECTORY_PATH
                           Directory to exclude or include
    --scope-all              Apply check to all files

For example, if you want to run Stan analysis only on a single file, you can use the following command:

$ stan check --exclude --filter-all --scope-all \
       check --include --filter-all --file=src/Stan/Example.hs

Inspections

[Back to the Table of Contents] ↑

You can find the list of all available inspections with description and additional information on our dedicated wiki page. However, with the tool you can get this information easily by using the inspection command. Optionally, you can see details of a particular inspection by typing the corresponding inspection ID alongside. You can see more robust description of the command here:

inspection – Show all Inspections

Usage:
  stan inspection [INSPECTION_ID]

Available options:
  INSPECTION_ID            Show specific Inspection information
  -h,--help                Show this help text

Converting between TOML and CLI configurations

[Back to the Table of Contents] ↑

It is usually convenient to have a proper configuration file that suits your project, which you can reuse each run of the Stan.

But sometimes you need to quickly run the tool with the same settings on another machine where having such files is not possible. Or you want to send the reproducible command, that anyone could execute and get the identical results. For these purposes, we have a special command that allows you to do so:

toml-to-cli – Convert TOML configuration file into stan CLI command

Usage:
    stan toml-to-cli [--config-file=FILE_PATH]

Available options:
  --config-file=FILE_PATH  Relative path to the .toml configurations file
  -h,--help                Show this help text

And for convenience you are able to use the reversed command –– cli-to-toml.

cli-to-toml – Convert CLI arguments into stan TOML configuration

Usage:
    stan cli-to-toml
      [--config-file=FILE_PATH]
      [   CHECKs {[TYPE option] [FILTER option] [SCOPE option]}
        | REMOVEs {SCOPE option}
        | IGNOREs {ID option}
      ]

Roadmap

[Back to the Table of Contents] ↑

Our plan for the nearest future:

We have much more ideas to work on. See more detailed plan in the dedicated GitHub Project page.

[Back to the Table of Contents] ↑