Datagrid API Version 3 - Reference

© Copyright 2015-2016 Datagrid Systems, Inc.

Intro

This document describes the Datagrid API, version 3, available to Datagrid service subscribers.

Basics

The Datagrid API is built on HTTP. The API is RESTful and it:

  • Uses predictable, resource-oriented URLs
  • Uses the built-in HTTP capabilities for authentication and passing parameters
  • Responds with standard HTTP response codes to indicate errors
  • Returns data in JSON format

You can use the Linux wget or curl utilities, or your favorite HTTP/REST library available for your programming language, to make HTTP calls to Datagrid. In addition, you can use the Datagrid command line tool, dgri-query, to experiment with various options.

To give you an idea of how to use the API and make it easy to try, we have annotated our documentation with curl sample commands that can use to try out the API capabilities.

Base URL

https://api.datagridsys.com/api/v3

Authentication

When you sign up for an account with us, you are given an API username and password. You authenticate to the Datagrid API by providing your API username and password in the request.

NOTE: When you sign up, you may receive telemetry user name and password; these credentials are different and will not work with the API. Use the API username and password for submitting API requests.

This API is intended for use by a machine (programmatic) client and only over HTTPS protocol. Authentication to the API occurs via HTTP Basic Auth mechanism. Here is how you use basic HTTP auth with curl:

curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg'

CAUTION! Keep you API password secret

Date and Time Format

Datagrid returns data in JSON format for all API calls. As JSON does not have a built-in date type, we pass dates, times and timestamps as strings encoded according to ISO 8601 format (RFC3339), limited to the UTC timezone which is indicated by a ‘Z’ at the timezone identifier. Examples:

2015-06-17T03:05:23.1234Z
2015-06-17T03:05Z
2015-06-17

This format has the following advantages:

  • it is easy for humans to read, while also being easy to parse in most programming languages
  • it conveniently allows comparing dates and timestamps as strings

Note that all dates and times are in the UTC time zone (aka GMT), so that confusion about time zones of different datacenters and locations can be avoided. You can convert the UTC time to the local time of your choosing.

Inputs to a Request

Path

The path is given on the HTTP request line. It identifies the target object. For objects within containers that are themselves accessible objects, the path will usually be of the form path-to-container/object-name, where path-to-container is the path used to access the container object (possibly with more than one level of nesting, if there are containers within containers). Trailing '/' in the path is not allowed.

Paths are relative to the [Base URL]. For example the systems path is accessible as:

curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' https://api.datagridsys.com/api/v3/systems

Parameters

Parameters are specified on the HTTP request line, as a suffix of the path, in the form ?p1=v1&p2=v2&.... Request parameters modify the behavior of the request and can affect:

  • format of returned data
  • the portion of data returned from a large object (e.g, starting point and number of elements from an array)
  • for complex objects, whether some detail data is to be included or omitted (filter)

The Datagrid API parameters that work on all requests that return data are:

Parameter Description
format compact or pretty. Modifies JSON whitespace formatting.
compact means no whitespace.
pretty means use whitespace indent to highlight object nesting and newlines between object elements. Default: pretty
limit for container objects that are lists, specify the maximum number of items to include in the response. If no limit is specified, server will attempt to return the entire list - or reply with failure status if the size of the reply would exceed what the server can support.
view bool, count, summary, normal, extended, full.
bool returns only whether there are any matching objects (0: no, non-zero: yes)
count returns only the number of matching objects, without any object data/lists
summary returns only the most important elements of the data, omitting most data from complex objects
normal returns most frequently needed data, omitting only exotic fields and very large items or items that are slow to obtain
extended, returns most data only except details that may be very large in size or slow to access (e.g., nested lists of objects).
'full' returns all data in the object to be returned, including any nested object lists.
For container objects, the default is summary. For single objects, the default is normal. For some simpler objects, 'summary' and 'normal' may be the same; for objects containing only a few small-sized elements, the summary, normal, extended and full view options may produce the same output, which is the full object's contents.
Note that containers may have max limit of entries returned; an error will be returned if there are too many objects. The limits may vary by view type (e.g., summary may allow 10,000 objects while full may be limited to 100); some views may not be allowed for containers (typically, extended and full views are not be supported for containers)
action For API actions that cannot be naturally represented as REST, endpoints use the POST HTTP request and the action parameter (e.g., resolve).

NOTE: Other parameters may be defined for requests on specific objects.

Request Data (Payload)

Payload can be sent only with PUT and POST requests. It provides the data to use to create or update the target object, or provide data to an action.

The payload data is to be provided as a JSON-encoded document. The JSON data is plain-text (unicode) character data, encoded into a byte stream with UTF-8. All JSON object names (that is, the left-hand side of the "key":value construct) are limited to the 7-bit ASCII character set.

When sending requests with payload, the API client should use Content-type: application/json HTTP header. Note that using Content-type: application/json;charset=utf-8 is also allowed, although the application/json definition says charset= suffixes are not defined. Other encodings should not be used as they are not standard JSON.

Output from a Request

When the server returns data, the replies always have a Content-type: application/json header, indicating that the response data is JSON encoded.

Status Codes

Datagrid returns standard HTTP response codes.

Code Description
200 Everything worked as expected; there is JSON data available in the response
204 Everything worked as expected and there is no response data
400 Bad Request - syntax error or other problem with the request (often missing a required field or incorrect parameter name or value). Retrying with the same parameters will not help.
401 Unauthorized - No valid API key provided. Retry should include authentication data as described above.
402 Request Failed - The request parameters were valid but the request failed.
404 Not Found - The requested item doesn’t exist
500, 503 Server Errors - something is wrong on Datagrid’s end
502, 504 Gateway Errors - something is wrong with the network configuration, likely with any proxies or gateways (including the Datagrid Anonimizing Gateway if you use it)

In addition to the error code, Datagrid returns more information about the specific failure reason and, in most cases, the specific parameter which caused the error.

The 400 status code replies return the following JSON-encoded data:

{ "status" : "code", "message" : "text", "data" : {values} }

Where:

  • code - a short token string, e.g., invalid_value, report_limit, etc. The code is intended for a programmatic client, if needed to differentiate between errors.
  • text - a human readable error message, which is selected from a fixed list of messages. It may contain placeholders for variable data, in the form {key} or it may have placeholder data included in the message. The first form allows for easier localization of the error messages by client software using the Datagrid API
  • values - a JSON object containing values for the placeholders in the text parameter, in the form {key1:value1,key2:value2}

Datagrid API Objects

The Datagrid service provides the following objects through its API:

Object Description
system A host within subscriber's account. A system is a reporting unit; it may be a physical server, a VM, a container, etc. Systems are identified by a system_id which is unique within the subscriber's account
config A configuration, separate from any particular system. In many environments, systems are cloned from the same image, resulting the the same configuration, at least initially. Configuration are identified by a config_id; a configuration typically represents a particular set of installed packages, with specific versions. When a system's configuration is changed - e.g., by installing or upgrading a package - the system's configuration ID changes
package A package installed on a system. Packages may be of different types (e.g., rpm, deb, etc.); they are identified by a name, vendor, version and release
vuln A vulnerability that affects one or more packages. Vulnerabilities are identified by a vuln_id which is typically a CVE number, as defined by the NIST NVD common vulnerabilities and exploits database
repo A package repository configured on a system and used to obtain new packages and updates of already installed packages.

API Reference

Request Summary

Request Description
GET systems List of systems in the accout, possibly filtered to those matching specified criteria (using system and/or either repo or vuln filters).
POST systems?action=resolve Return system ID based on system’s id block (as provided in telemetry data)
GET systems/<system_id> Get information about a system (e.g., server, VM or container, etc.)
GET systems/<system_id>/packages Get system’s list of installed packages
GET systems/<system_id>/vulns Get system’s list of vulnerabilities and affected packages. May be filtered by vuln filters (e.g., severity, attack vector, etc.)
GET systems/<system_id>/history Get system’s history of configurations
GET systems/<system_id>/repos Get system’s list of configured package repositories (Note: filter by repo type, url, etc., is currently not supported for this request)
GET configs/<config_id> Get information about a configuration using the config_id typically provided in systems info, incl. config history
GET configs/<config_id>/packages Get list of installed packages in a given configuration
GET configs/<config_id>/vulns Get list of vulnerabilities and affected packages in a configuration. May be filtered by vuln filters (e.g., severity, attack vector, etc.)
GET vulns Get list of unique vulnerabilities affecting all or some of the systems. Filter criteria using the system and/or vuln filters may be specified
GET vulns/<vuln_id> Get generic information on a given vulnerability by vuln_id (such as `CVE-2015-1234), nor related to a specific system

Notation Convention

In data structure descriptions below: for objects that have multiple views, elements that appear only in more detailed views have a parenthesised marker prepended to the description, as follows:

  • no marker - appears in all views
  • (n) - appears in normal, extended and full views, but not in summary view
  • (e) - appears in extended and full views, but not in summary or normal
  • (f) - appears only in full view

The marker is not part of the name, nor it will appear in data returned by an API request.

Request Details

GET systems

List of all systems, as an array of system objects, possibly filtered by one or more filters.

The objects in the list are returned only in summary or normal view, selected with ?view= parameter sent with the request. If no view is given, default is view=summary.

If no filters are specified, all systems belonging to the subscriber’s account are returned. The following filters and filter type combinations are permitted on this endpoint:

  • system filter (see definition below) AND/OR

  • exactly one of the vuln or repo filters

Essentially, this means that a system filter can always be specified; either vuln or repo filters can also be specified - but fields from vulnerability and repo filters cannot be combined in the same request.

The response data structure is a list of system objects, each containing some or all of the following fields:

Field Description
"id" The system ID (object name, relative to /systems). For example, i-1324abcd or 25077f36-6329-47eb-b76d-db96f5597e2d
"hostname" The system’s hostname, as a fully qualified domain name of the system (to the extent that it can be determined from the system itself, the value returned here cannot be relied upon as a valid DNS name by which the system can be addressed)
"parent_id" (n) The system ID of this system's parent system (object name, relative to /systems). If not provided, there is no parent. For systems that are containers (e.g., docker), the parent system is the host; parent ID is not provided for any other systems.
"ip_addr" [] (n) A list of system's IP addresses at the time when the most recent event (signal or configuration) was received. The first address listed is the one most likely to be ‘outward facing’ - the source address of the route with shortest prefix (typically, this will be the default route, with prefix length of 0). The IP addresses are represented in string form and include both IPv4 and IPv6 addresses
"config_id" (n) The config ID identifying the current configuration on the system (object name, relative to /configs/)
"match": { (n) Filter match metrics (only if a filter is specified in the request). It is included only if per-system metrics related to a query are available (omitted otherwise)
    "count" Number of elements that match the filter (e.g., vulnerabilities or repos). An integer
    "max_severity" The highest severity of all matching vulnerabilities, 0.0..10.0 (string)
    }

Example requests:

curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems?view=normal'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems?system.ip_addr=172.17.36.12&view=normal'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems?system.hostname=*.app1.foo.com'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems?system.config_start=min:2016-01-01&system.hostname=*.app1.example.com&view=normal

Example response (partial):

[
   {
     "config_id": "ubuntu-12.04-d879",
     "config_start": "2016-01-14T00:08:45.555035Z",
     "hostname": "www1.app1.example.com",
     "id": "i-f7847c7e",
     "ip_addr": [
        "172.31.37.74"
     ]
   },
   {
    "config_id": "ubuntu-14.04-137d",
    "config_start": "2016-01-17T02:20:19.607685Z",
    "hostname": "www2.app1.example.com",
    "id": "i-0e6c378f",
...
]

Example requests with vulnerability filter:

curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems?vuln.id=CVE-2014-0160,CVE-2014-6271&limit=10'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems?system.hostname=*.app1.example.com&vuln.severity=min:7&view=normal'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems?vuln.changed=min:2016-04-01'

Example response with vulnerability match metrics (partial):

[
   {
     "config_id": "ubuntu-12.04-d879",
     "config_start": "2016-01-14T00:08:45.555035Z",
     "hostname": "www1.app1.example.com",
     "id": "i-f7847c7e",
     "ip_addr": [
        "172.31.37.74"
     ],
     "match": {
        "count": 45,
        "max_severity": "10.0"
     }
   },
   {
    "config_id": "ubuntu-14.04-137d",
    "config_start": "2016-01-17T02:20:19.607685Z",
    "hostname": "www2.app1.example.com",
    "id": "i-0e6c378f",
...
]

POST systems?action=resolve

The resolve request is intended to determine the system ID of a system from unique identifying information known by the system itself, so as to allow a client running on that system (or an administrative tool capable of running commands on systems under its control, such as ansible, chef, etc.) to find the ID of the system and be able to make requests for information about it.

The identifying information is the same as what is sent to the telemetry ‘feed’ API entry point (the path through which new systems get registered and become "known" and available in the systems container described here). POST to this API will not actually create the new system record, if it did not exist previously. The data returned by POST is in the same format as for GET for systems/<system_id> (or return not found).

Request data format (for POST) is the contents of the id block from the telemetry data (see /tmp/dgri_collect.json shadow file that the Datagrid ansible client leaves on the system for examples)

Note: In most cases, system IDs are best found by running the GET systems query. The resolve request is used primarily to programmatically stitch other tools, such as deployment and monitoring, to the Datagrid API

GET systems/<system_id>

Return detailed information about the specific system identified by <system_id>. The system ID can be obtained through the GET systems or POST systems?action=resolve API request.

Upon successful retrieval, the response data structure contains some or all of the following fields (level of detail depends on the requested view):

Field Description
"id" The system ID (object name, relative to /systems/), the same as the one requested in the URL path
"hostname" System’s hostname, as the fully qualified domain name of the system (to the extent that it can be determined from the system itself; the value returned here does not necessarily allow reaching the system, depending on the DNS settings in the system's environment)"
"parent_id" (n) The system ID of this system's parent system (object name, relative to /systems). If not provided, there is no parent. For systems that are containers (e.g., docker), the parent system is the host; parent ID is not provided for any other systems.
"ip_addr" [] (n)List of IP addresses at the time when the most recent event was collected (signal or configuration). The first address listed is the one most likely to be ‘outward facing’ - the source address of the route with shortest prefix (typically, this will be the default route, with prefix length of 0)
"created" (e) Timestamp when this system record was created
"last_signal" (e) Timestamp when the last signal about this system was received
"n_signals" (e) Number of signals received about this system (including config, ping, etc.)
"config_id" (n) Config ID of the current configuration of this system (object name, relative to /configs/)
"config_start" (e) Timestamp when the current configuration was first reported for this system
"os" { Operating system information about this system
    "name" (n) OS name suitable for display, such as CentOS 7.2
    "type" (e) OS type, such as linux or windows (currently, only linux is supported)
    "distro" (e) OS distribution name, such as centos, ubuntu, rhel, etc.
    "version" (e) OS distribution version, such as 7.2
    "arch" (n) OS architecture, such as x86 or x86-64
    "edition" (e) OS edition, if defined (e.g., server, desktop, home, pro, etc.). Omitted if not applicable.
    "cpe" (e) Canonical CPE name for the OS (see Common Platform Enumeration specs at mitre.org)
    }
"vuln" { (e) Vulnerability metrics about this system
    "count" Number of identified vulnerabilities affecting this system
    "max_severity" The highest severity level of all vulnerabilities affecting this system
    "fix_max_severity" The highest severity level of all vulnerabilities that will remain if all available updates that resolve vulnerabilities are applied to the system (i.e., max. level for which fixes are not available)
    "last_eval" Timestamp of the last time vulnerabilities were evaluated for this system
    }
"packages" [ (f) List of packages installed on this system
    ... See /systems/<system_id>/packages for package fields and their descriptions
    ]
"vulns" [ (f) List of known vulnerabilities affecting this system and packages that cause them
    ... See /systems/<system_id>/vulns for vulnerability fields and their descriptions
    ]
"history" [ (f) List of configuration history entries
    ... See /systems/<system_id>/history for history fields and their descriptions
    ]
"repos" [ (f) List of configured package repositories on this system
    ... See /systems/<system_id>/repos for repository fields and their descriptions
    ]

GET systems/<system_id>/packages

Return information about packages installed on the system.

Note: This request is equivalent to getting the list of packages from the corresponding configuration object (/configs/<config_id>/packages using <config_id> equal to the config.id returned by /systems/<system_id>)

The response data structure is a list of package objects, each containing some or all of the following fields:

Field Description
"type" Type of package, such as rpm, deb
"name" Name of the package. Note that the package name may not be unique - there may be an openssl OS package as well as an openssl perl package. The type, vendor, version and release fields provide further disambiguation
"version" (n) Package version number, such as 1.2.3. For most Linux OS packages, this is the upstream version
"release" (n) Package release number, within the upstream version. For most Linux OS packages, this is the packager/OS distro vendor build within a given upstream version. May be omitted if the package does not have a release defined (e.g., authored by the distro vendor and not having an upstream source)
"epoch" (n) Package version epoch. Assumed zero or not applicable if omitted. Even though the epoch is a number, this field is provided as a string, for consistency with the rest of the package fields
"vendor" (e) Name of the package vendor, as retrieved from the package information (frequently not very meaningful, esp. for OS packages). May be omitted if not available
"arch" (e) Package architecture, such as x86 or none. May be omitted if the package (or the package type) does not have an architecture
"src_diff" { (e) : Source package information, such as name or version, that may be different from the installed (binary) package’s information. This sub-structure is omitted if all the fields match of if source/binary differences don’t apply. This information is useful primarily when tracking down the source code for the package
    "name" Name of the source package, if different from the name of the installed package
    "version" Version of the source package, if different from the version of the installed package
    "release" Release of the source package, if different from the release of the installed package
    "epoch" Epoch of the source packag,e if different from the epoch of the installed package"
    }

Note: the elements in this list don’t have an ‘id’ field as there is single field that is a unique identifier of a package (multiple versions of the same package may be installed - primarily in kernels and libraries).

GET systems/<system_id>/vulns

Return information about identified vulnerabilities affecting the system.

Note: this request is equivalent to getting the list of vulnerabilities from the corresponding configuration object (/configs/<config_id>/vulns using <config_id> equal to the config.id returned by /systems/<system_id>)

If no filters are specified, all vulnerabilities affecting the system are returned. Vulnerability filters can be specified in order to limit the returned list (similar to querying systems for vulnerabilities further limited to this specific system)

The response data structure is a list of vulnerability description objects, each containing some or all of the following fields:

Field Description
"id" Vulnerability primary ID, such as CVE-2015-1234
"severity" Severity level of the vulnerability, from 0.0 (least severe) to 10.0 (most severe). String
"confidence" Confidence score for this identified vulnerability, representing how precisely the installed package was matched to known vulnerability data, as well as the level of confidence in the vulnerability data soucre. From 0.0 (not valid) to 10.0 (highly confident); in general, values up to 3 represent low confidence (usually due to only speculative match of the package to product on which the vulnerability was reported); values up to 7 represent medium confidence (typically to insufficient confirmation either about the package identification or the vulnerability status); values of 7 and above are represent very high confidence (typically because of exact package match and vulnerability data that is cross-checked from multiple sources). Low confidence score may indicate a likely false positive. If not present, the confidence level could not be determined
"description" (n) Human-readable description of the vulnerability (may be multiline)
"vector" (n) Attack vector for this vulnerability, with possible values L for local access exploits, N for network access, A for adjacent network access (e.g., same broadcast domain) and P for physical access
"fixes" (n) Whether there are fixes available for affected packages that resolve this vulnerability. none means no fixes/updates are available, full means that there are updates that fix this vulnerability for all affected packages and partial means that fixes are available for some but not all affected packages
"changed" (n) Changed date for this vulnerability with respect to this system. Tracked changes include: vulnerability affects the system; a fix has become available for the vulnerability; or the vulnerability severity or description has changed.
"packages" [ (e) List of affected packages, with the following elements (see the corresponding fields in the systems/<system_id>/packages data structure
    "type" Package type
    "name" Package name
    "vendor" Package vendor
    "version" Package version
    "release" Package release
    "epoch" Package version epoch (may be omitted if 0)
    "arch" Package architecture
    ]

Example requests:

curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems/i-ba8c1113/vulns'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems/i-ba8c1113/vulns?vuln.severity=min:7'
curl --basic --user '3nFw3v92KVA7zbC1:Ga2Ozx9LR8ocpgfg' 'https://api.datagridsys.com/api/v3/systems/i-ba8c1113/vulns?vuln.changed=min:2016-04-01'

Example response (partial):

[
   {
     "changed": "2015-11-18T00:00:00Z",
     "confidence": "9.0",
     "description": "The std::random_device class in libstdc++ in the GNU Compiler Collection...",
     "fixes": "none",
     "id": "CVE-2015-5276",
     "packages": [
        {
        "arch": "amd64",
        "name": "gcc-5-base",
        "release": "12ubuntu4",
        "type": "deb",
        "version": "5.3.1"
        }
     ],
     "severity": "5.0",
     "vector": "N"
   },
...
]

GET systems/<system_id>/history

Return history of the system; more specifically, the configuration change history (including the current state)

The response data structure is a list of configuration history objects, each containing some or all of the following fields:

Field Description
"start" Timestamp of when this state started
"end" Timestamp of when this state ended. Omitted for the current state
"config_id" Configuration ID for this state of the system; object name, relative to /configs/

GET systems/<system_id>/repos

Return list of package repositories configured on the system.

The response data structure is a list of configuration history objects, each containing some or all of the following fields:

Field Description
"type" Repository type, such as yum, apt, etc. Similar to package type but refers to the repo/package manager rather than the type of package in the repository
"id" Repository ID assigned by the repo; not present for all repo types
"name" Repository name/description; may be omitted if not available
"base_url" Base URL of the repository (the first returned if more than one are configured). May be omitted if mirrors_url is available"
"mirrors_url" URL to a mirror list, in addressable form, with any substitions performed (such as distro version and architecture). May be empty or missing if no mirrorlist is defined (in that case, the base_url will likely be defined)
"sections" (e) List of repo sections (missing or empty if not used, e.g., for yum). This field is used in apt repos, TBD details

Note: the type and name of reposistories may not be unique or the same across systems. The URL(s) are the true identifiers of repositories

GET configs/<config_id>

Return information about the specified configuration

Typically, a configuration ID is obtained from the config.id field from a GET systems/<system_id> request (i.e., the system's current configuration), or from the config_id field in the history returned by GET systems/<system_id>/history request (i.e., one of the system's past configurations). It is not, however, necessary that the configuration ID refers to any particular subscriber's system.

Upon successful retrieval, the response data structure contains some or all of the following fields (level of detail depends on the requested view):

Field Description
"id" Configuration ID (the same as the configuration ID in the request)
"os" { Operating system information (fields may be omitted if not known)
    "name" OS name suitable for display, such as CentOS 7.2
    "type" (e) OS type, such as linux or windows
    "distro" (e) OS distro name, such as centos, ubuntu, rhel, etc.
    "version" (e) OS distro version, such as 7.2
    "arch" (n) OS architecture, such as x86, x86-64, etc.
    "edition" (e) OS edition, if defined (e.g., server, desktop, home, pro, etc.). Omitted if not applicable
    "cpe" (e) canonical CPE name for the OS (see Common Platform Enumeration specs at mitre.org)
    }
"vuln" { (e) Vulnerability metrics about this configuration
    "count" Number of identified vulnerabilities affecting this configuration
    "max_severity" The highest severity level of all vulnerabilities affecting this configuration
    "fix_max_severity" The highest severity level of all vulnerabilities that will remain if all available updates that resolve vulnerabilities are applied (i.e., max. level for which fixes are not available)
    "last_eval" Timestamp of the last time vulnerabilities were evaluated for this configuration
    }
"packages" [ (f) List of packages installed in this configuration
    ... See /systems/<system_id>/packages for package fields and their descriptions
    ]
"vulns" [ (f) List of known vulnerabilities affecting this configuration
    ... See /systems/<system_id>/vulns for vulnerability fields and their descriptions
    ]

GET configs/<config_id>/packages

Return information about packages installed in this configuration.

Note that the elements in this list don’t have an ‘id’ field as there is no single field that is a unique identifier of a package (multiple versions of the same packag may be installed - primarily in kernels and libraries).

This request returns a list of package objects; see systems/<system_id>/packages for package fields and their descriptions.

GET configs/<config_id>/vulns

Return information about identified vulnerabilities affecting systems with this configuration.

A vuln filter may be specified to limit the vulnerabilities returned by this request by characteristic (such as minimum severity). If no filters are specified, all vulnerabilities affecting the configuration are returned.

This request returns a list of vulnerability objects; see systems/<system_id>/vulns for vulnerability fields and their descriptions.

GET vulns

Return list of all vulnerabilities affecting subscriber’s systems. System and vulnerability filters may be specified to limit the returned list only to systems and/or vulnerabilities matching the filters.

If no filters are specified, a union of all vulnerabilities affecting all systems belonging to the subscriber’s account are returned. The following filters and filter type combinations are permitted on this request: system filters (see definition below) AND/OR vuln filters

The response data structure is a list of vulnerability objects, each containing some or all of the following fields:

Field Description
"id" Vulnerability primary ID, such as CVE-2015-1234
"severity" Severity level of the vulnerability, from 0.0 (least severe) to 10.0 (most severe). String
"confidence" Confidence score for this identified vulnerability, representing how precisely the installed package was matched to known vulnerability data, as well as the level of confidence in the vulnerability data soucre. From 0.0 (not valid) to 10.0 (highly confident); in general, values up to 3 represent low confidence (usually due to only speculative match of the package to product on which the vulnerability was reported); values up to 7 represent medium confidence (typically to insufficient confirmation either about the package identification or the vulnerability status); values of 7 and above are represent very high confidence (typically because of exact package match and vulnerability data that is cross-checked from multiple sources). Low confidence score may indicate a likely false positive. If not present, the confidence level could not be determined
"vector" (n) Attack vector for this vulnerability, with possible values L for local access exploits, N for network access, A for adjacent network access (e.g., same broadcast domain) and P for physical access
"fixes" (n) Whether there are fixes available for affected packages that resolve this vulnerability. none means no fixes/updates are available, full means that there are updates that fix this vulnerability for all affected packages and partial means that fixes are available for some but not all affected packages

GET vulns/<vuln_id>

Return a vulnerability detail record for the specified vulnerability.

The object identifier <vuln_id> is in the standard form for CVEs: CVE-YYYY-NNNN[N*], where:

  • YYYY is the year of record and is >= 1999 (usually the year in which the ID was assigned).
  • NNNN is a serial number within the year-of-record group and is zero-padded to 4 digits if less than 1000. It may have any number of digits above the minimum 4 and numbers are not necessarily assigned sequentially.

Requests with <vuln_id> in an unrecognized form as well as requests for valid CVE identifiers that do not match an existing record will both return a not_found status.

Unlike configs/<config_id>/vulns, this request is not in the context of a specific system/configuration/distro, so it contains mostly generic information (i.e., NIST NVD without vendor/distro-specific enrichments and corrections)

Field Description
"id" Vulnerability ID, such as CVE-2015-1234 (the same as the one given as <vuln_id> in the request)
"severity" Severity level of the vulnerability, from 0.0 (least severe) to 10.0 (most severe). String. Note that the severity associated with the generic vulnerability object may be different from the one associated with a particular system or configuration, as vendors occasionally re-evaluate the severity in the context of their specific product/version
"vector" (n) Attack vector for this vulnerability, with possible values L for local access exploits, N for network access, A for adjacent network access (e.g., same broadcast domain) and P for physical access. Note that the vector associated with the generic vulnerability object may be different from the one associated with a particular system or configuration, as vendors occasionally re-evaluate how the vulnerability can be exploited in the context of their specific product/version
"changed" (n) Timestamp when the vulnerability info was last changed
"published" (e) Date when this vulnerability was published
"description" (n) Human-readable description of the vulnerability (may be multiline)
"url" (e) External reference URL where more information on this vulnerability can be found, including vendor specific links
"cvss" { (f) Common vulnerability scoring system - generic score (not distro-specific)
    "base_score" CVSS base score, from 0.0 to 10.0. String
    "impact_score" CVSS impact score, from 0.0 to 10.0. String
    "exploit_score" CVSS exploit score, from 0.0 to 10.0. String
    "base_vector" CVSS base vector string
    }

Filters

The Datagrid API supports filtering lists by one or more filters. Filters are specified in the following generic form, as URL query parameters:

object.field=[operator:]value[,value]*

Examples:

  • system.id=1234-5678-9999
  • system.hostname=*.foo.com
  • vuln.severity=min:7
  • vuln.vector=A,N (equivalent to vuln.vector=not:L,P)
  • vuln.changed=min:2016-04-01
  • repo.url=not:redhat.com,centos.org

Filters can be combined:

  • system.hostname=*.foo.com&vuln.severity=min:7
  • vuln.severity=min:7&vuln.vector=N

Note: Not all filters are applicable to all lists; not all filters can be combined. See the descriptions in each API request for information on supported filters and filter combinations.

The following matching operators are defined; see field definition for which operators are allowed for each filter field:

Operator Description
is or (empty/none) Is. This is the default; if there is no operator, is is assumed. is may mean an exact match (if a single value is given); may mean "value in set" if a list of values is given (the filter matches if the field matches one of the values in the list); or may mean wildcard match (*.example.com matches foo.example.com and bar.example.com)
not Not. It is the opposite of the is operator. It may mean not equal to value (single value); not-in-set (i.e., not equal to any of the values in the list); or not matching a wildcard
min Minimum. Produces a match if the field is greater than or equal to the filter value (for numbers); for dates, it means "since" (at this date or later)
max Maximum. Produces a match if the field is less than or equal to the filter value (for numbers); for dates, it means "until" (at this date or earlier)

The following object types and fields are supported.

System Filters

Filter Description
system.id System ID filter. Allowed operator: is (default). Supports matching a single value or any of a list of values
system.hostname System’s host name (fully qualified domain name). Allowed operator: is (default), which supports exact match, match a item in a list or match a wildcard (wildcard matches may be partially limited in case the anonymizing gateway is in use). Note that list of wildcard strings is not supported (must be a single wildcard)
system.parent_id The system ID of this system's parent system (e.g., a container's host). Allowed operator: is (default). Supports matching a single value or any of a list of values
system.ip_addr System's IP address. Allowed operator: is (default), which supports exact match from a single value or a list. For systems with more than one IP address, the value may match any of the addresses
system.config_id System configuration ID. Allowed operators: is (default), not (not equal). Single value and lists are supported (i.e., config is equal to value, or config is other than a value; config is in a list of values, or config is not on a list of values)
system.created System’s creation timestamp. Allowed operators: is (TBD deafult match: partial compare to match the date or date+time within the timestamp), min (since/after), max (until/before). Currently ranges are not supported
system.last_signal Timestamp of the last received signal. Allowed operators: same as for system.created
system.config_start Timestamp of the last configuration change (i.e., when the current config was first reported). Allowed operators: same as for system.created

Vulnerability Filters

Filter Description
vuln.id Vulnerability ID (e.g., CVE-2015-1234). Allowed operators: is (default) supporting single value and list match
vuln.severity Severity. Allowed operators: min (default?TBD) and max
vuln.vector Attack vector. Allowed operators: is (default) and not. Both single values and lists are supported (i.e., vuln.vector=A,N is the same as vuln.vector=not:L; vuln.vector=L is the same as vuln.vector=not:A,N,P)
vuln.fixes Whether a fix is available. Allowed operators: is and not. Allowed only in searches on specific systems and/or configurations
vuln.confidence Vulnerability identification confidence level. Allowed operators: min and max
vuln.changed Date on which the vulnerability info or status last changed. Allowed operators: min (default) and max

Repository Filters

Filter Description
repo.url URL to match (match a string anywhere in the base URL or mirror list URL for the repo). Allowed operators: is (default) and not (not-equal). Both single value and lists are supported, and imply partial string match (equivalent to a *<value>* wildcard). This filter can also be used to check for blacklisted repos (e.g., repo.url=rpmforge,atomicorp.com) and for exceptions to whitelisted repos (e.g., use repo.url=not:centos.org,fedoraproject.org/pub/epel to match any system that has repos that are not centos or epel)

References