Last updated at Fri, 30 Aug 2024 19:22:03 GMT

With 2017 firmly in the rear-view mirror, we peer forward into 2018 and thanks to genre-bending vulnerabilities like Meltdown and Spectre the future would seem a bit blurry. Louis Pasteur is attributed with the quote: “Chance favors the prepared mind.” Pasteur’s work precedes information security as we know it today by a century, but as an an individual responsible for a great deal of prevention, we could learn a thing or two from his stance. In complex times such as these, it can be useful to take an inventory of your kit. I’m pleased to share a new addition to your kit as part of InsightVM: a modern, RESTful API.

Now, unless you had been paying close attention to InsightVM release notes, you just might’ve missed the announcement:

With our collective attention being split between the holiday season, Meltdown/Spectre unfurling, and the fog of getting back into gear for a new year, the release of a modern, fully-documented and supported RESTful API for our vulnerability management solution just might have fallen outside your field of vision. If you fall in this camp, read on for an introduction to your new powers.

An API for the rest of us

If you are familiar with InsightVM and Nexpose, you may have heard of API v1.1 and v1.2. Both are XML over HTTP APIs and are commonly accessed via either Ruby Gem or Python client. While these APIs have served security teams admirably for nearly 15 years, no single approach can withstand the march of time. As software developers and automation-hungry security teams have evolved their kit, RESTful APIs have become modus operandi for command and control of software.

With the January 10th, 2018 release of InsightVM and Nexpose, you’ll find the Security Console includes an exhaustively instrumented RESTful API that also happens to be comprehensively documented and supported.

The RESTful API has been created from the ground up. It was designed to be:

  • Easy to pick up and learn: Fully documented, including code samples, and helpful responses and errors for those that like to learn by doing.
  • Focused on automation: Exposes common activities for repeatability
  • Integrated into your kit: With an OpenAPI v2 specification, use the API client you wish.

While contemplating the contents of this blog post, one of my colleagues at Rapid7, Patrick Noyes, reached out and shared his experience with the API. Rather than death by bullet points, instead I’ll share his first experience working with the new API.

Controlling your risk and security program is hard; controlling your InsightVM Security Console should not be. Pat’s experience took him from zero knowledge of the API to action in less than 10 minutes.

“Upon updating my Console I couldn’t wait to get my hands on it and it couldn’t have been easier due to the new API Documentation built into the Console.”

The RESTful API is available to all customers of InsightVM and Nexpose with no additional cost or commitment.


“The documentation is comprehensive, has a built-in search and looks really easy to use. Let’s start with lightly kicking the tires on this thing. Let’s see what sort of asset information I can get using the Assets resource.”


“The documentation shows the full resource using my server’s URL, response or request samples, and the query parameters. Let’s hit the server to see the API in action.“


“Just a simple call to Assets provides a great way to explore the API. That was a quick and easy test, but what if I want to use the API for some automation? Let’s kick off a scan!”


“I can jump to the Scan and Site Scans resource section of the API Documentation, and I’ll want to make a POST request since I want to tell InsightVM to do something. I’ve already got POSTMAN, so I’ll use that.”


“I sent a POST request to the resource instance specified, replacing the ID with the siteid of my target site, and just like that a scan kicked off.”


“With no dependencies to be installed and full API documentation getting started was pretty easy. If I want to use a language of my choosing, I can use the OpenAPI (also known as Swagger 2) specification with tools such as swagger-codegen to generate an API client.”

Frequently asked questions

  • Can I still use the XML-based APIs?
    Yes, APIv1.1 and APIv1.2 will remain fully supported as they are today. If they are deprecated, we will be sure to give you plenty of notice per Rapid7 end of life policy.
  • Is there a client I can use that is provided by Rapid7?
    You can use the OpenAPI v2 Swagger specification along with swagger-codegen to generate a client in the language of your choosing (there are over 15 at the time of this post).
  • Are there examples?
    Yes! Examples are included directly in the API documentation.

What’s in your kit?

With a comprehensive, modern and easy-to-learn API we know you’ll be able to automate and orchestrate tasks like tagging, asset creation and scanning, but we’re really excited to learn about what will come out of the Rapid7 community. How are you planning on incorporating this into your kit?