OpenAPI Usage Guide
Each Footprint instance exposes a public API interface, accessible via the standard https://en.wikipedia.org/wiki/OpenAPI_Specification
This guide explains the purpose of the public API, authentication and usage, as well as common caveats.
📑 Table of Contents
📃 Accessing the specification
You can access the specification on your Footprint instance in one of two ways:
1 Access the .yml definition file for ingesting into OpenAPI-compatible tools and generators:
<your-footprint-instance-url>/api/openapi/
2 Access the interactive Swagger UI interface, where you can test-drive the specification live:
<your-footprint-instance-url>/api/openapi/swagger/
We will be using the Swagger UI interface in this guide to present the API usage, but concepts should vbe similar regardless of the client you use.
📡 Making API Calls
This section will present the general concepts you need to understand in order to use the OpenAPI definition.
In these screenshots we are using the demo.codacloud.net Footprint environment. Replace demo.codacloud.net with your own environment where necessary.
🔧 Configuring the schema interface
The Swagger interface might not be configured to make requests on your current instance. In order to make sure you have configured the server variables to match your instance’s URL:
🔒 Authentication
Footprint supports two authentication methods: API keys and JSON Web Tokens. We will explain both authentication methods in this section.
🔑 API Keys
API Keys are generated via the Footprint user interface. In order to generate an API key, you will need to create keys for a certain user.
First, go to Settings → User Management:
And click the Add new user button:
You can also edit any existing user instead of adding a new user
You will be presented with the user add/edit modal. After filling in the fields (required fields are only First Name, Last Name and E-mail) you can click the Generate key button to generate a new API key:
Click the Save button to create the user and activate the API key.
This is the only time you will see the generated API key. Make sure to store it into a safe place, such as a password manager.
In the modal above you can see the Service Account toggle. This will allow the user to authenticate only via the API key, with no interactive login available.
API keys do not require the Service Account toggle to be set in order to be activated.
Be careful when converting your own account to a Service Account - this will lock you out of Footprint interactive access.
You are now ready to use the API key. In order to use it when making requests, you will need to set the FootprintApiKey HTTP header’s value to your key. We will show how to do a basic request using the Swagger OpenAPI client.
Go to the /api/openapi/swagger/ page and click the Authorize button:
You will be presented with a modal which allows you to fill in either API or JWT credentials. Paste your API key in the first field, and click the Authorize button:
You are now ready to perform API requests via your supplied key in the Swagger interface
After each request, Swagger displays the equivalent cURL command which you can paste directly, for example, in a terminal, or convert to your preferred SDK/library format:
The API key string in the images above is for demonstration only - replace it with a valid key when performing requests.
🪙 JSON Web Tokens
In order to authenticate, you will need to obtain an authorization token. You can obtain it by using the /api/auth/token/ endpoint.
First, go to the /api/openapi/swagger/ page, and scroll down to the auth section. Expand the /api/auth/token/ endpoint:
Click the Try it out button to initiate a new request. Fill in your username and password, and hit Execute:
The response body for your request will show up under the Execute button:
As you can see, the response has two tokens:
-
access- this is the access token that you will use to authorize requests. This token is valid only for a short time (e.g. a couple of hours) -
refresh- this is the refresh token that you will use to obtain a newaccesstoken. You can use the/api/auth/token/refresh/endpoint in order to do this.
The final step is configuring the Swagger client to use our access token in order to authenticate requests. For this, scroll at the top of the page, and click the Authorize button:
This will open a modal where you can paste your access token:
Click Authorize. Your requests will now use the authorization token you provided in order to validate the requests.
When using the OpenAPI definition with a generic HTTP client, you will need to authorize your requests by including the Authorization: Bearer <your_access_token_here> HTTP header.
The user account for the API doesn’t need to be anything special - it can be any regular Footprint user.
You can also look at the curl command that Swagger generates after every completed request in order to see exactly how the HTTP request needs to look like.
Now you can start making API requests in Footprint!
🤙 Making a basic request
In order to test our installation, we’ll analyze a simple one - the session request. Scroll down to the common section and expand the /api/common/auth/session/ request.
As you can see, for each request you have a basic description, any required and optional parameters and the possible responses you can have for each request. For most of the request you will also find a generated response with the basic response shape.
You can view more detailed information regarding the response by clicking the Schema tab above the example value:
As you can see, each field has an explanation alongside its data type. Some requests can have more than one response type, as you can see above.
Footprint will always return an application/json response type.
🧠 Specific context
Footprint is a multi-tenant application, and allows users to roam between multiple accounts. In order to see accounts for which your user has access, you can execute the /api/common/auth/session/accounts/ request:
This will return the list of accounts you have access to. In order to select a certain account to use, just input the tenant ID in the FootprintTenantId parameter on the request you want to make.
As you can see in the OpenAPI definition, the FootprintTenantId parameter is just an HTTP header. If you input an invalid ID here, Footprint will fall back on the primary account of your user.
This account has the isPrimaryAccount key set as true in the accounts request.
📃 Paginated queries
Some endpoints provide paginated responses. Most of these endpoints will have a couple of common QUERY parameters:
-
page- the page you want to request -
size- the number of items you want to request
📁 Requesting all available items on paginated queries
Although not recommended, you can obtain all available items on a paginated query in two steps:
-
Run a query with
pageset to 1 andsizeset to 1. Obtain thetotalCountvalue from the paginated response. -
Run the query again with
pageset to 1 andsizeset to thetotalCountvalue you got at step 1. This will give all the available items that match your query.
This is highly discouraged, as it can cause performance issues. It is preferred to use the available selection, sorting and filtering options available in the API to obtain the data you want.
If there is any filter, sorting or selection parameter that you find missing, please contact the CODA Intelligence team and let us know. We are constantly improving the OpenAPI definition.
📚 API Examples
This section contains examples for a couple of commonly used patterns when consuming data from the Footprint application.
These examples assume that you are already logged in to the OpenAPI client and have started and successfully completed a scan using either the frontend interface or the API.
🖥️ Retrieving a device details
When discovering a device, either via an agentless scan or after receiving information from an installed agent, the Footprint interface displays multiple data points:
All these data points can be accessed via the API. First, we will need to request the list of available devices via the /console/elements/devices/ request:
From the response body here, we can see the ID for the server in the above screenshot is 185834. We can now use the various /console/elements/device/* requests to get the sections of information that we need.
For example, we can get the vulnerabilities information by making a request to the /console/elements/device/185834/attackavenues/ request:
In the response body, we can see exactly the entries that we see in the Vulnerabilities tab of the Footprint interface above:
We can also retrieve the list of Associated CVEs by using the /console/elements/device/{deviceId}/vulnerabilities/ endpoint:
Some items in the Footprint interface, such as Vulnerabilties, might have different names in the API (e.g. Attack Avenues).
📊 Retrieving reports
Footprint provides various reports generated from the information we gather from assets you scan. You can also access some of these reports through the API. For example, let’s access the Contextual Risk Report.
Not all reports may be available in the public API - contact the CODA Intelligence team if you require a certain report added to the OpenAPI definition.
First, we want to see if there is an active remediation report generated. In order to check for this, we have to make the /api/console/reporting/contextualRiskReport/status/ request:
We can see in the state field that the report is generated. We can also see when the report has been generated.
In order to see the report, we’re going to need a couple of parameters, as the /api/console/reporting/contextualRiskReport/ API definition shows:
As we can see, we’ll need to decide on a context and a device for which to generate the report. Luckily, we have the associated requests at /api/console/reporting/contextualRiskReport/businessContextsLabels/ and /api/console/reporting/contextualRiskReport/devicesLabels respectively:
After getting the requested information from the above requests, our report query will look like so:
We can now see the Contextual Risk Report for our selected device:
The request details in the OpenAPI schema provide guidance on dependent requests. Although most reports will have just one request, more complex ones will require request orders similar to the above
🔔 Retrieving alerts
The Alerts module integrates all events triggered by the Footprint platform.
-
Alertsare events that the Footprint platform produces through scanning, generating reports and ingesting data.
You can retreive alerts using the following endpoint. Filtering parameters have descriptions associated to them.
You can view field details by expanding values in the Schema field of the Responses section:
📋 Retrieving scan results
Footprint records a separate userInputs entry for each extend scan. You can retrieve the list of scan entries by calling this endpoint:
