Integrate Security Checks with RIPS CLI

Today, fully automated application security testing is an important part within every secure development life cycle. RIPS leading code analysis solution for the detection of security issues comes with an extensive API that can be used to automate its analysis features. Based on our RESTful API, we built a command line interface (CLI) tool.

In this blog post we will demonstrate how to use the RIPS CLI tool to automatically scan a project for security vulnerabilities. This enables you to integrate RIPS into basically any system as a security gate that automatically warns you when new security bugs were introduced.

Getting started

Installation

The installation of rips-cli is described in detail in our documentation. You can download the PHAR build of our CLI tool into your bin directory and make it executable with the following commands:

12

sudo wget https://github.com/rips/rips-cli/releases/download/1.1.1/rips-cli.phar -O /usr/bin/rips-cli
sudo chmod 755 /usr/bin/rips-cli

The only requirements to run rips-cli are the PHP command line interface and the Zip extension to start scans.

Authentication

The CLI tool needs a valid RIPS user account to login. To avoid having to enter your credentials on every command you can store them in a configuration file. To do this execute the login command as follows. It will ask for the API URL (defaults to our SaaS version), your user name, and your password. If you are using the On-Premises version you have to change the API URL (for example, use http://127.0.0.1:8080 if you execute rips-cli on the RIPS server).

1

rips-cli rips:login

Application

Every scan is part of an application. At this point you can either create a new application or use an existing application.

You can create a new, empty application through rips-cli itself with the command rips:application:create. The command expects a name that can be specified through --name or -N. If the parameter is not specified there is a fall-back in place that will ask for a name. If the command is successful it prints out the ID of the application. We will need the ID to start a scan in the next chapter.

1

rips-cli rips:application:create --name test

This command results in a message like Success: Application "test" (20985) was created at 2018-02-27T10:32:24+0000 where test is the name of the application and 20985 is its ID.

If you want to use an existing application instead or if you do not remember the ID, you can list your existing applications through rips-cli as well.

1

rips-cli rips:list -t applications

Integration

Integrating rips-cli into your CI process is easy! With only a single command you can:

1. Create an archive with your code from a file path
2. Send the archive to your RIPS account
3. Start a new scan
4. Wait for the scan to finish if at least one threshold is specified
5. Compare the number of found issues to thresholds

For example, you can scan the current directory (--path .) with the following command. Make sure to replace the application ID with your own.

1

rips-cli rips:scan:start --application 20985 --path . --threshold 0

The scan is added to the application we have created in the previous chapter and if one or more issues are found the scan fails.

Threshold

The most essential difference between a normal scan and a CI scan are thresholds that define when a scan should be considered successful or when it should be considered failed. Thresholds are separated into 5 categories based on the issue severity: low, medium, high, critical, and sum. The last category contains the total sum of all issues and is used by default if no category is specified.

You can set thresholds with the option --threshold or -t. For example, the options -t high:0 -t critical:0 -t sum:10 check if the scan has more than 0 high or critical issues, or more than 10 issues in total. It only counts issues that have a review other than not exploitable, not an issue, and duplicate.

The exit code of the command is based on the threshold comparison. If the actual number of issues is below or equal the threshold the command exits with the success code 0. If at least one threshold is exceeded the command exits with the error code 2 instead. All common CI platforms, for example GitLab CI or Drone CI, use the exit code of executed programs automatically to determine if the test succeeded or failed.

The recommended approach for thresholds is to allow no medium, high, or critical issues at all (-t medium:0 -t high:0 -t critical:0). If such an issue is found it should either be fixed or reviewed directly by the developers.

Advanced

Once the basic setup is done you might want to fine-tune your analysis settings for improved results. RIPS unique code analysis is able to simulate the exact PHP environment to disregard issues that are not relevant, for example vulnerabilities that only affect very old PHP installations. To do this create the file env.yml in your project directory and include it with the parameter --env-file or -F.

env.yml

123456789

php:
    majorVersion: "7"
    minorVersion: "0"
    releaseVersion: "0"
    magicQuotesGpc: false
    registerGlobals: false
    allowUrlFopen: true
    allowUrlInclude: false
    filterDefault: "unsafe_raw"

Another common desire is to exclude certain directories or files, for example cache directories. To do this specify regular expressions with the option --exclude-path or -E. The regular expressions are compared to the full path of every file and if one expression matches the file is not added to the archive. The slash character (/) is used as separator, so it is important to escape the slash with a backslash character.

For example, the option -E '^include\/config\.php$' excludes only the file include/config.php whereas -E '\.git' excludes any file in a .git directory.

Summary

In this blog post we got a glimpse of rips-cli for the easy integration of security testing into third-party tools. We learned how to start security scans and to set thresholds for security warnings. But there are many more options and commands. RIPS CLI can also be used to clean up old scans, review multiple issues at once, and many more tasks. For a full list of commands please refer to the documentation. In the documentation you can also find examples how to easily integrate rips-cli into popular CI tools, such as GitLab CI, Drone CI, or Travis CI. In an upfollowing post we will demonstrate how to create own commands for absolute flexibility.