How to get started with the API?

Hello all,

I am just recently exploring the InsightVM API in order to more effectively evaluate my company’s data. I would like to be able to pull out data, specifically vulnerability exception and asset data, and use Power BI or other means of analysis. Does anyone have any suggestions for doing this? I have been using postman but am very new to API usage and keep getting 500 error statuses.

Thanks in advance!

https://help.rapid7.com/insightvm/en-us/api/index.html

for use with PowerBI I’d suggest setting up a DataWarehouse
https://docs.rapid7.com/nexpose/configuring-data-warehousing-settings/
then pointing PowerBI to that

3 Likes

Postman is a great tool for getting started with API’s, so you’re on the right track there :+1:

I also echo Brandon’s suggestion to setup the data warehouse, since that can make it easy to export all your data and pull it into another tool like PowerBI.

And if you’re still wanting to use the API, I’ll share some info that can be helpful starting off. I might eventually turn this into a separate guide for other folks here on the forum, so I welcome any comments/suggestions on what did or didn’t work for you along the way.


Using the API Documentation

One of the best ways to get started with the API is to login to the InsightVM console, and then at the top right, click Help > API Documentation. It might take a bit to load, but this is the most up-to-date version of the API documentation, and it has some helpful stuff built into it that I’ll touch on down below.

Once you’re looking at the API documentation, the first thing you want to do is figure out what you’re looking to accomplish. That will tell you which API endpoint you want to call.

For instance, you said you’re interested in pulling vulnerability exception data. To see the exception-related endpoints that are available, you can click the “Vulnerability Exception” option on the left side of the API docs menu. This will display a list of those endpoints, each of which you can click on to see more details.

Endpoints

The first endpoint under Vulnerability Exception could be helpful in your case. It’s a “GET” endpoint that will return info on all vulnerability exceptions. If you click that endpoint, you’ll see more details about it, along with a section at the top that shows /api/3/vulnerability_exceptions. If you click that text, a dropdown will appear that contains the exact URL you can use to call that endpoint. This includes your console’s address and port, which are used to build the endpoint URL. It makes it really easy to ensure the URL for your API call is correct and doesn’t have any typos.

Postman

If you copy the aforementioned URL, you can head over to Postman and paste it in the “Enter request URL” text box. There should also be a dropdown menu directly to the left of that text box where you’ll see options like “GET”, “POST”, “PUT”, etc. In this case, you’ll want to select “GET”, because this is a GET endpoint where we’re retrieving data, as per the API documentation.

Next, there should be an “Authorization” tab below that where you can select “Basic Auth” from the “Type” dropdown. This allows you to input a username and password for authentication purposes. These credentials must belong to a valid account that has access to the InsightVM console. I believe some teams use a service account for this and apply specific permissions to restrict the usage of the API (@brandon_mcclure I’d be interested in hearing if your team does this). Postman may also have some guidance on secure usage/storage of your credentials here.

Once that’s done, you can also go to the “Body” tab in Postman and select “None”, since we’re not actually sending any data to this endpoint. We’re only retrieving exception data, after all.

With all of that, you should be able to hit the blue “Send” button to send the request and hit that endpoint to retrieve exception data. If your request succeeds, you should see output down below that contains the data you requested - in this case, details about your vulnerability exceptions, in all their glory.


Troubleshooting

I know you also mentioned that you’re seeing 500 errors, so there are a couple things you can do to troubleshoot.

  1. Check the accompanying error message. Does it say anything in particular about the endpoint? The authorization? That’ll give you a good starting point.

  2. If the error message tells you to “see the log file”, you can often check nsc.log on your console to see additional info to aid in troubleshooting. If you don’t see anything there, you can also check access.log. We’ve got some more info here on how to access these files.

I hope that helps as far as getting started with the API and understanding how to use the documentation. It can take some getting used to, but it’s ultimately pretty powerful for collecting data and integrating with your other tools.

1 Like

For any APIs, I usually start with Postman to validate authentication part, check the API capabilities following the documentation. When I see that I understand how the API of a given solution works, I jump to Python scripting using the requests module :slight_smile: You might find some ready-to-use libraries, but depending on the situation, it might be “easier” to create your own functions according to your use cases, this is why I like to start from scratch.

1 Like