Does Edgescan Enforce Pagination & Rate-Limiting on The API?

All versions of the Edgescan API enforce pagination and rate-limiting in all requests. These must be taken into when creating your API interactions.

Version Number: v1.0.0

Published Date: 17 Dec 2024

____________________________________________________________________________

This guide assumes you have created an authentication token and can make authenticated requests to the API.

Overview

The edgescan API provides index endpoints for each of the main resources in the portal:

• Assets
• Hosts
• Vulnerabilities
• Definitions
• Users (note this requires super-user privileges)

Each of these endpoints supports a rich and intuitive query language, which is explained below.

Making Requests

Index endpoints are of the form:

GET /api/v1/[resource-name-plural].json?[query-string]

If no query string is supplied, then all resources will be returned.

Adding query strings allows you to filter the returned resources. For example, the below request returns all open vulnerabilities, ordered by the date they were opened.

GET /api/v1/vulnerabilities.json?c[status]=open&s[date_opened]=desc

The Easy Way to Build Queries

The user frontend provides an easy way to generate queries for the assets, hosts, vulnerabilities and users endpoints. Simply navigate to the list page and use the filter functionality to generate your desired query. 

As filters are added, the equivalent query string is appended to the url in the search bar. This query string can be copy-pasted over to an API request by clicking on the Copy as API url button, as highlighted below.

Filtering Results

The results of an index endpoint can be filtered by specifying one or more conditions. A condition is a query fragment that specifies a field name, an operator, and a value to compare against. Here's an example condition:

c[date_opened_after]=25-06-19

• The 'c' indicates that we are specifying a condition
• The field here is date_opened. Any field on a resource can be used to filter against, and each resource has different fields
• The operator is after. Operators are added to the field name, separated by an underscore
• The value is 25-06-13. This is a date field and we are comparing against a string representation of a date

Let's look at another example:

c[status]=open

• The field here is status
• The operator is equals. This is the default when no operator is specified
• The value is open

When multiple conditions are specified, only resources that satisfy all conditions will be returned. This query combines the two previous conditions:

GET /api/v1/vulnerabilities.json?c[status]=open
    &s[date_opened_after]=25-06-19

This will return all open vulnerabilities that we opened after 25th June 2019.

Available Operators

Note: some operators support aliases to provide better semantics for some queries.

 

Operator	Description	Supported Field Types
equal	Field is exactly equal to value. This is the default operator if none is given	Numbers, Strings
not_equal	Field is not equal to the value	Numbers, Strings
is_null, never	Field does not have a value	All
is_not_null	Field has a value	All
less_than, before	Field is less than the value	Numbers, Dates
greater_than, more_than, after	Field is greater than the value	Numbers, Dates
like	Field contains the value as a substring	Strings
not_like	Field does not contain the value as a substring	Strings
in	Field is contained within the value array	Numbers, Strings

Array Operators

Operators like 'in' allow an array of possible values to be specified. Array values are passed as a comma-separated list. For example, to query for all vulnerabilities on two particular assets, we use the in operator like so.

GET /api/v1/vulnerabilities.json?c[asset_id_in]=61,62

The in operator can also be used to filter string fields:

GET /api/v1/vulnerabilities.json?c[status_in]=open,risk_accepted

Tag operators also accept array values, and are described in the next section.

Filtering by Tags

Assets in edgescan support tagging, and these tags can be used in queries. The following operators are available:

Operator	Description
tagged_with_any	returns assets that have at least one of the given tags
tagged_with_all	returns assets that have all of the given tags
not_tagged_with	returns assets that have none of the given tags
not_tagged	returns assets that have no tags at all (any value is ignored for this comparison)

These operators can be used to query for hosts or vulnerabilities by applying them to the asset field. For example, this request retrieves all vulnerabilities whose asset is tagged with 'business-critical' or 'infrastructure'

GET /api/v1/vulnerabilities.json?c[asset_tagged_any]=business-
    critical,infrastructure

The tag operators can also be used when filtering assets. For example, to get all assets that are not tagged 'business-critical':

GET /api/v1/assets.json?c[not_tagged_with]=business-critical

Note: when filtering assets by tags only the operator should be given, the field should be omitted.

Filtering by Booleans

Boolean queries treat the following values as true:

• "true"
• "t"
• true JSON literal (if using post endpoint, see below)

All other values are considered false.

Filtering by Date

The values for date filtering supports a wide variety of formats. There are too many to list exhaustively, so some examples are given below. Special attention should be given to cases where the difference between American and International date formats is ambiguous.

 

Format	Formatted Date Value	Parsed Value
DD-MM-YYYY	05-02-2020	5th February 2020
YY-MM-YY	19-05-20	20th May 2019
DD-MMM-YY	27-Feb-19	27th February 2019

 

Date fields also support specifying the time of day, by joining T[format] on to the date formats above:

 

Format	Formatted Date and Time Value	Parsed Value
HH:MM:SS	05-02-2020T20:18:01	5th February 2020 at 20:18:01
HH:MM:SS(+/-)ZZZZ	19-05-20T05:30:00-0800	20th May 2019 at 5:30 Pacific Standard Time
HH:MM(AM/PM)	27-Feb-19T05:30PM	27th February at 17:30

 

Please note the following when using date filters:

• If no time is provided, the time will default to 00:00
• If no timezone is provided, the timezone defaults to UTC
• The equals/not-equals comparison should be avoided with date fields. The comparison includes time and therefore it's unlikely that two values will coincide exactly

Sorting and Pagination

Results can be sorted by a field by adding the following query fragment:

s[field]=asc|desc

For example, to sort all assets by name in descending order:

GET /api/v1/assets.json?s[name]=desc

Pagination can be performed by specifying an 'l' (limit) and 'o' (offset) parameter:

GET /api/v1/assets.json?l=50&o=50

Exporting

All of the index endpoints support exports in the following formats:

• XLSX
• CSV
• JSON

Export endpoints are of the form:

GET /api/v1/[resource-name-plural]/export.[format]?[query-string]

Note: the export endpoints support exactly the same query functionality as index endpoints. Pagination parameters are ignored in imports.

Exporting using POST Request with Polling

When exporting a large amount of data, or querying with a long query string (2048 characters or more), it is advisable to request the export via POST and a polling methodology. 

 

The endpoint which triggers the generation of an export is of the form:

POST /api/v1/[resource-name-plural]/export.json

The request body should be a JSON representation which includes the format of the desired export and the query parameters. It also supports an additional parameter which when provided, will send the export to your email address, aliieviating you of the need to manually poll and download. 

 

The following request exports  critical- and high-risk vulnerabilities on business critical assets:

POST /api/v1/vulnerabilities/export.json
Body {
    export: {
        format: "csv",
        send_via_email: <true/false>,
    },
    c: {
        asset_tagged_any: "business-critical",
        risk_more_than: 3
    }
}

This request triggers the export process, it returns a JSON representation of the export with a UUID. If you wish to download the export grammatically, you'll need to poll the export using the UUID and then request to download the export via the download endpoint.

 

The following request poll's the status of the export.

GET /api/v1/exports/<uuid>.json

This will return a JSON representation with the status, percent complete and format of the export. It will also return a download URL when the export is ready to be downloaded:

{
  uuid: <uuid>,
  format: "csv",
  status: <"initializing"/"generating"/"error"/"finished">,
  percent_complete: 50,
  download_url: "https://live.edgescan.com/api/v1/exports/<uuid>/download.csv
}

The following request will download the export, providing it is ready for download. You must supply the correct format with the request: 

GET /api/v1/exports/<uuid>/download.csv

Querying using POST Request

In rare cases, query strings can exceed the maximum length of a URL (2048 characters). All index endpoints support a POST endpoint that accepts the query as a body parameter. These endpoints are of the form:

POST /api/v1/[resource-name-plural]/query.json

The request body should be a json representation of the query string. The following request returns the first 50 critical- and high-risk vulnerabilities on business critical assets, sorted newest to oldest:

POST /api/v1/vulnerabilities/query.json
Body {
    c: {
        asset_tagged_any: "business-critical",
        risk_more_than: 3
    },
    s: {
        date_opened: "desc"
    },
    l: 50,
    o: 0
}