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:
The only requirements to run
rips-cli are the PHP command line interface and the Zip extension to start scans.
Please note that this blog post assumes that you are using RIPS 2. If you are using a different version of RIPS make sure to download a compatible version.
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).
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
The command expects a name that can be specified through
-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.
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.
rips-cli into your CI process is easy! With only a single command you can:
- Create an archive with your code from a file path
- Send the archive to your RIPS account
- Start a new scan
- Wait for the scan to finish if at least one threshold is specified
- 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.
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.
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:
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
-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 an issue, and
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
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.
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
Another common desire is to exclude certain directories or files, for example cache directories. To do this specify regular expressions with the option
-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
-E '\.git' excludes any file in a
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.