astreviewer 0.2.0
astreviewer is a command-line integrator for tools like Application Security Testing tools (AST)
Requires Python: >=3.6
Keywords: ast integration middleware scm security appsec github fortify

# ASTReviewer

**ASTReviewer** is a command-line integrator between _Application Security Testing tools_ (_AST_)
and _Source Control Management systems_ (SCM), _CI platforms_, _Ticket Systems_, etc.
Its main goal is to publish _AST_ findings (issues) as reviews in _SCM_ changes (or _PR_ reviews).

The base use case is running ASTs on build pipelines, making available their scan results 
in the developer's tool of choice with instructions on how to mitigate the issues.
To accomplish that, **ASTReviewer** retrieves data from _ASTs_, parses, processes, modifies them, and
publishes the results to the chosen destination, usually the code review tool.

**Simple Scenario example**: 

The team's _SCM_ is _Github_. The engineers make use of _Pull Requests_ (_PR_) for code
reviewing and triggering their build and test pipelines.
As part of the CI, they also run security scans using couple of tools.
As the PR is their tool for reviewing code and discussing issues, they want reviews from the _ASTs_ showing issues and mitigation as they would have from a peer.

The security tools can be, for example, a [SAST](https://en.wikipedia.org/wiki/Static_application_security_testing) tool such
[Fortify Source Code Analyzer](https://www.microfocus.com/en-us/support/Fortify%20Static%20Code%20Analyzer) and an 
[SCA](https://en.wikipedia.org/wiki/Software_Composition_Analysis) tool like 
[Nexus Lifecycle](https://www.sonatype.com/products/open-source-security-dependency-management).

When a developer creates a PR with a new feature, this will trigger the CI pipeline that will perform the build and test of the code with different tools. At some point, the pipeline will run the two security tools. The team will also configure **ASTReviewer** with its proper modules for each one of the tools.

For each one of the _ASTs_, **ASTReviewer** will retrieve both the scan results related to the _PR_ 
as the ones from its destination branch. It then compares both results.
If new issues exist in the _PR_ scan that are not present in the destination branch scan, it creates a 
_review_ for the _PR_. After that, for each one of the new issues, it will add a comment under that _review_.

While processing the issues, **ASTReviewer** can retrieve information from other sources (_Knowledge Bases_) and add them to the review or comments. A good example is adding links to security training, ASVS requirements, OWASP Cheat Sheet pages, etc, related to the specific issue.

![Basic ASTReviewer flow](doc/astreviewer_basic_flow.png)

Depending on the tools and user configuration, the review can contain details such as specific location in the code where the issue was found, snippets of the code, images, etc. **ASTReviewer** uses templates to determine the format of the reviews and comments.

![Github PR review example](doc/github_pr_review_example.png)


**ASTReviewer** is written in Python and is highly modular and extensible. Supporting a new AST, or SCM, or even 
parsing data from another format or location (Key vault for example), it's a matter of writing a small 
Python file (module) and reference it in the configuration file.



## Getting started

For instructions on setting up different production environments see: [Installing into Production](docs/install_production.md)

For development, the easiest way to get up and running is by creating a Python virtual environment and install the dependencies and the `astreviewer` package on it.

First step is to clone the repository:

```bash
$ git clone ssh://<youruser>@git.it.volvo.net:29418/Astreviewer astreviewer
```

Setting up the environment:

```bash
$ cd astreviewer
$ python3 -m venv env
$ . .env/bin/activate
(env) $ pip install -U pip
(env) $ pip install -e .
```

This will install only dependencies for a production environment.
Package management is done in the `requirements` directory and is explained in [Package Management](doc/astreviewer_pkg_mgt.md).

For installing useful tools for testing and development do:

```bash
(env) $ cd requirements
(env) $ make install_dev
```

## Testing

The tool is developed utilizing [TDD](https://en.wikipedia.org/wiki/Test-driven_development). Said so, both _Acceptance Tests_ and _Unit tests_ are provided and contributors are required to provide both.
Clean code is expected, including the test code.

Tests are implemented and run with [Pytest](https://docs.pytest.org/).
To test the application, run from the project root directory:

```bash
(env) $ pytest
```

If you want to run only the unit tests:

```bash
(env) $ pytest astreviewer
```

If you want to run only the acceptance ones:

```bash
(env) $ pytest tests
```

## Currently Supported Tools

- **AST**
  - **SAST**
    - Microfocus Fortify Scan Central 
  - **SCA**
    - Nexus IQ Server
- **SCM**
  - Github

## Contributing

[See contribution guide](CONTRIBUTING.md)