Last updated at Thu, 16 Jan 2020 14:59:29 GMT

This blog post is part four of our ongoing Automation with InsightAppSec series. Make sure to check out part one, part two, and part three to see everything you can achieve when combining InsightAppSec with automation.

Automation with the InsightAppSec API

As application development continues to trend toward a cycle of rapid releases, developers often find themselves caught in the hectic whirlwind of those releases, expected to swiftly push their code for deployments, and sometimes even straight to production. It’s certainly not ideal, which is why now more than ever, developers are in need of tools that can accompany their development workflows to help ease that process. The Rapid7 InsightAppSec API is one such tool. Released in October 2018, the API provides an easy way to directly interact with InsightAppSec and all the data it houses without having to rely on the user interface.

What does that mean? It means that developer teams can utilize the InsightAppSec API to perform tasks in an automated fashion to further aid in their web application development, maintenance, and dynamic application security testing (DAST). Such tasks can include the creation of new InsightAppSec applications and scan configurations, the launch of scans for these applications, and the retrieval of scan results in order to generate solution-specific outputs and reports. And, because there is no UI component required in these API interactions, each of these steps can become fully automated. The automation of these tasks in the web application life cycle can free up extra time for development and security teams, making it a win-win.

Quickly get started with Python and PowerShell

“What’s an API?”
“How do I start using the API?”
“How do I use this endpoint?”
“What can I accomplish with the API?”

These are all perfectly valid questions when it comes to the InsightAppSec API, so Rapid7 has created an InsightAppSec API Examples project that’s intended to help developers and security professionals alike get started with the API from scratch. The project walks through every step of API interaction, starting with basic API concepts and progressing to focus on application of the InsightAppSec API itself. This allows individuals with varying levels of development and API experience to quickly delve into the InsightAppSec API and its usage. Anybody can get started today.

Within the project, there are two major types of offerings. The first is endpoint examples, which consist of a script containing a single basic API call that’s paired with a step-by-step walkthrough of how to perform that call. This includes the configuration of everything from headers to API keys to URL parameters, and more.

We currently provide examples for both the Python and PowerShell scripting languages, as we have found they are commonly used in conjunction with the InsightAppSec API by the Rapid7 community. These examples are great for getting started and learning exactly what it takes to make an InsightAppSec API call.

There are a few parameters that will be consistently required across all InsightAppSec API requests. First is the URL, which states which endpoint we'll be accessing when making an API call. The base API URL in InsightAppSec can be set
as the following:

region = "us"
api_url = f"https://{region}"

Note the usage of the region parameter. This refers to your InsightAppSec region and will dictate the base URL used for making API calls. In this case we are formatting the base URL to account for this region, and it will read as

Above is a snippet from our general Python guide that walks through the construction of the base API URL.

The second offering within the project is use case-specific code intended to show how to automate—end to end—key functionality to drive simple solutions. Each use case is fully functional and contains a settings file that allows teams to customize the configuration as needed. These use case examples are a great place to start when automating similar functionality within your environment.

One of these use cases is InsightAppSec Reporting. The goal of InsightAppSec Reporting is to generate reports based on scan data retrieved from InsightAppSec, driven by a set of configurations. The user can define as many application/scan config pairings as desired, and upon execution, the script will retrieve data from the latest scan for every given configuration and write three new JSON reports containing a wealth of information. The result is a flexible solution that enables teams to automate report generation and further employ the simple JSON output.

   "XPath Injection": 7,
   "Blind SQL": 4,
   "SQL Injection": 8,
   "OS Commanding": 3,
   "Parameter Fuzzing": 5

Above is an example modules report from InsightAppSec Reporting.

Perhaps most important is that these examples and use cases are intended to demonstrate how to best leverage the InsightAppSec API to achieve the outcomes that matter to you and your environment. You will notice our recommendation of using the search endpoint, as well as ways to do things like pagination and formatting of output. These are all intended to help PowerShell, Python, or users of any other language by adding context and recommendations on how to automate tasks.

The Rapid7 InsightAppSec Examples project is freely available for use today. It offers detailed walkthroughs for individual endpoints for those looking to start with the API from scratch, as well as fully featured, working scripts that fulfill practical use cases for those looking to really harness the capabilities of the API. Want to contribute? We’d love to hear from you and see any additional tips, examples, or other feedback you have regarding the API so we can continue to help others further advance in their usage.

Contributions for this project were made possible by hwilsey-r7, jherlitz-r7, and mhofert-r7.

No an InsightAppSec customer? Start a free 30-day trial today.

Get Started