Last updated at Tue, 25 Apr 2023 21:32:45 GMT
A Security Automation-Focused API for Forward-Thinking Vulnerability Management
Released in January of 2018, Rapid7 InsightVM’s API version 3—the RESTful API—was a highly anticipated, perhaps somewhat inconspicuous, addition to our vulnerability management solution. Introduced as a successor to previous API versions, the RESTful API was designed for automation-focused security teams.
Let’s look at how (and why) the RESTful API was developed to get a better understanding of how you can use it.
Built to Code
InsightVM’s API v3 was developed in adherence to the Representational State Transfer (REST) architectural style, which defines a set of constraints or rules for creating RESTful web services, including APIs. One of these constraints mandates a client-server architecture. Simply put, the client can send requests to the server, the server will process those requests, then the server will return a successful operation or failure along with a status code (and some additional information) for troubleshooting. These requests, often referred to as API calls, utilize URLs and standard HTTP methods (ex. GET, POST, PUT, DELETE) to interact with data stored on the server. REST architecture dictates that client-server interactions must be stateless, so client data is not retained by the server between requests.
The API accepts and produces messages in JavaScript Object Notation (JSON), a language-independent and compact syntax that is easy to read and write. As a component of yet another REST constraint, it also follows Hypermedia as the Engine of Application State (HATEOAS) principles. The API is hypermedia friendly, meaning the server will return hyperlinks to available resources as part of its responses to the client. This helps decouple the client from the server, because the client doesn’t need to store any information locally, or even have knowledge of the web service prior to interacting with it. The REST client can discover all the resources it needs—dynamically—from the API itself.
An OpenAPI v2 specification file for the API is available to all users. This specification prescribes a machine-readable interface file governing the API’s functionality. This file can be provided to a variety of tools, such as swagger-codegen, to create documentation and even API clients.
Get to the point, already!
I wanted to provide some background on InsightVM’s RESTful API and set the stage for the rest of this blog, but it’s possible that you skipped over the tech jargon, or your eyes glazed over after the second (or third) acronym. That’s fair. One of my favorite questions following a lengthy exposition on technical info—both on the giving or receiving end—is a good old fashioned, “so what?” Trust me, try it out.
So, what does this information mean for me?
I’m glad you asked!
While previous versions of the API were enduring and feature-rich, they had the look and feel of locally executed code. Versions 1.1 and 1.2 were XML over HTTP APIs, and interaction with these services was controlled by Ruby Gems (and a pinch of Python). Client entanglement was a very real thing, locking capabilities behind a gauntlet of additional deployments and configurations. These APIs were thick clients in the age of virtualization: highly capable, but difficult to transition to the web. Such offerings have largely fallen out of favor with the developer community, and demand time and knowledge commitments beyond the means of many security teams.
InsightVM’s RESTful API is a modern web service, composed using a set of industry standards that make it both flexible and approachable for anyone with even a passing interest in harnessing its power. The REST style means that your API calls will be message-based and reliant on HTTP standards. Using JSON means that you can easily read and write those messages, while HATEOAS means that you’ll be working with a web service that is interactive and self-describing. You can wade into the code and learn as you go with a system that provides feedback to keep you pointed in the right direction.
As noted in an earlier post, you can explore API resources directly from your browser with simple URLs, or download a tool such as Postman to write some more advanced requests. The API is fully documented (with example code) directly within your InsightVM console interface and in our help documentation.
So, how can I use it?
Another great question! Let’s take a look at some real-world applications of the API.
Driving Security Automation
The RESTful API was purpose-built to feed automated and repeatable activities, and this is where it excels. It does not facilitate one-time operations (ex. managing web certificate) or bulk data extraction (The Dimensional Data Warehouse Export is better).
Common use cases of InsightVM’s API include:
Automation of console activities
You can create and interact with components of the solution, such as users, assets, reports, and sites in an automated fashion.
For example, a simple URL sent through your browser will return a list of sites and their respective IDs:
https://10.3.71.73:3780/api/3/sites
Plug one of those site IDs into the following URL in Postman to initiate a scan with a ‘POST’ request:
https://10.3.71.73:3780/api/3/sites/52/scans
Write a script to send that request along with a cron job, and you have a scheduled scan. (Quick and easy, right?)
What if we want to find some assets to add to a site prior to scanning? Let’s check the API documentation for some sample code that we can modify. First, we can check the documentation for some info on how we can search for assets:
I want to create a group of assets with a CVSS score greater than 8 that are also assigned (or tagged) to Bob. I don’t want to just list these assets in my browser, though. I want to add them to an asset group so I can then use them as targets in a scan:
Perfect! Over to Postman with the request and the modified JSON:
Bob’s asset group now exists within InsightVM:
...So we can create a new site using that group:
While this was a relatively simple and straightforward set of actions, you may begin to envision a fully automated approach to scanning in the modern network, dynamically generating each and every component of a scan as needed. With many organizations turning to entirely virtual and ephemeral asset deployments—resources created and terminated on demand—we now have a way to align not just scan activities, but scan infrastructure, with those needs.
Data interface between solutions
You can invoke the API to drive a data exchange between InsightVM and other solutions in your toolkit. Integrations of this type may include some of those listed on Rapid7’s Technology Partners page and bespoke workflows created for customers by our Enterprise Security Consulting team. Extract data from the console for sharing, or gather it elsewhere and provide it to InsightVM to establish or add context to your assets.
A very common question that we receive from our customers is, “can we integrate with our CMDB?” The good news is that we can typically jump right past the resounding “YES!” and dive into the details; what would you like to accomplish with this integration? The API can help establish scan targets, tag assets in InsightVM using pre-existing configuration item details (thus applying vital context), and even update your system of record by seeding the database with newly discovered assets. Run your scripts on a schedule and you’ll have an automated workflow that ensures up-to-date visibility across systems.
Custom interfaces
The majority of InsightVM users don’t need access to every piece of the web interface. Using the API, you can create a custom interface that exposes only necessary functions and information to those users, giving them a simpler view or list of actions for their day-to-day work. This can help streamline the user experience according to your organization’s needs and, well, lets you flex those creative muscles.
And in Conclusion...
If you’re interested (and feeling confident), it’s a good time to head over to GitHub and check out some of the Rapid7 information shared there, including the unofficial (but very useful) Python library. Within this repository, you’ll find some helpful instructions and documentation, including some sample code snippets like this, which is pulling a list of assets:
list_assets.py
APIs make the world go round. In the security world, APIs can be used to bridge gaps between individual systems throughout an organization’s ecosystem, helping establish an interconnected and automated program in which data and processes no longer live in independent silos.
A highly capable API is only as valuable as your ability to access and use it efficiently. Our hope is that InsightVM’s RESTful API is not only robust enough to draw you in, but accommodating enough to help you deliver value to your vulnerability management program.
