FOSSA provides over-the-air (OTA) updates to on-premise vulnerability databases. This documentation will describe how to access the feature.

API Keys

You will need a vulnerability Service API token ID and Secret provisioned by FOSSA.

If you do not already have an API key, request one to be provisioned for you by contacting [email protected] with the subject line "Vulnerability Snapshot API Keys".

Automatic Updates for On-Prem (Helm Configuration)

To enable automatic updates of an on-prem instance's vulnerability database, use the following guide to set up the necessary helm values.

Helm Configuration

Within the on-premise Helm chart values, there is a section as follows (in it's default state)

## Configuration for Vulnerability Database OTA Updates
vulns:
  updater:
    enabled: false

    # URL of the FOSSA Vulns update service.
    host: https://vulns.fossa.com

    # These values are provided by FOSSA and authenticate your installtion
    # to our update service.
    auth:
      id: ""
      secret: ""

Once you have API Key id and secret provisioned, the updated values should look like this:

# Configuration for Vulnerability Database OTA Updates
vulns:
  updater:
    enabled: true # * this is updated from false -> true

    # URL of the FOSSA Vulns update service.
    host: https://vulns.fossa.com

    # These values are provided by FOSSA and authenticate your installtion
    # to our update service.
    auth:
      id: "<provisioned key ID>" # this field should be the value of the provided key ID
      secret: "<provisioned key secret>"  # this field should be the value of the provided key secret

After the configuration is updated, you can apply the changes by running helm upgrade to ensure that the feature is turned on. Under the hood, this operates as a cron job, so it might not run immediately. The update should be applied within 24 hours of applying the updated helm charts.

Operation

The OTA feature will run in the background as a daily cron job. No additional steps need be taken by the Organization with the on premise installation.

You can monitor OTA updates by looking at the daily OTA cron job status, or by running a database query to get the time passed since the last successful update:

SELECT (now() - (SELECT "createdAt" FROM "VulnMigrations" ORDER BY id DESC LIMIT 1))
-- example: 0 years 0 mons 0 days 4 hours 23 mins 9.114582 secs

Usage with REST APIs

On every request that requires API tokens, there must be an Authorization header like so: Authorization: token <tokenId>:<tokenSecret>

Requests that require these tokens will be explicitly defined in the documentation, and this authorization header information will be repeated in line.

Requesting Vulnerability Snapshot

You will make a request to FOSSA's servers that will return a pre-signed AWS S3 URL that will allow you to download a copy of the data.

Request

Method: `GET`

Headers: `Authorization: token <tokenId>:<tokenSecret>`

Endpoint: `vulns.fossa.com/api/vulns/snapshot`

Response:

On success: { url: string }

Make a GET request to the provided URL to download the vuln snapshot JSON. The file is a gzipped tarball

On failure:

You will receive an error description describing the reason for the failure. If you are unable to resolve the issue on your own, please contact [email protected] and provide the error UUID

The returned JSON will be an array of shallow JSON objects. This schema describes a single JSON object within that array.

Schema

type SingleVulnSnapshotSchema = {
  // the package type of the affeced package (e.g. mvn (maven), deb (debian), npm (npm/node), etc ...)
  fetcher: string;

  // Name of the affected package
  package: string;

  // CVE related to this vuln, or null if vuln doesn't have CVE
  cve: string;

  // CWEs related to this vuln, or null if we don't have enough information.
  cwes: string;

  // CVSS V2 Enum Vector
  cvssV2Vector: string;

  // CVSS V3 Enum Vector
  cvssV3Vector: string;

  // FOSSA computed severity vector, or null if we don't have enough information.
  cvss: string;

  affectedVersionRanges: string;

  // A long-form explanation of the vuln, or null if we don't have enough information.
  description: string;
  
  // EPSScore (Exploit Predictability and Sophistication Score) is a metric used to quantify the predictability 
  // and sophistication of exploits, with higher scores indicating more predictable and less sophisticated exploits, 
  // and lower scores indicating the opposite.
  epssSscore: number;
  
  // EPSSPercentile (Exploit Predictability and Sophistication Percentile) represents the percentile ranking of a particular 
  // exploit's EPSScore relative to other exploits, providing context on its predictability and sophistication 
  // compared to a broader set of exploits.
  epssPercentile: number;
  
  // Exploit maturity refers to the accessibility of code samples for exploiting vulnerabilities, 
  // with mature exploits having readily available code and POC exploits relying on documented methods without code samples. 
  // Refer to CISA Known Exploit catalog, as these are the current exploits FOSSA has.
  exploitability: string;

  // Important dates related to this vulnerability. (datetime as string)
  published: string;

  // Links to external references (disclosures, blog posts, teardowns, writeups, post-mortems, etc.).
  references: string;

  // When FOSSA first created the vuln entry. (datetime as string)
  createdAt: string;

  // When FOSSA last updated the vuln entry. (datetime as string)
  updatedAt: string;
};

IP Space Whitelisting

For proper functionality on premise, if there is a firewall then the following IP spaces should be whitelisted (follow the links for more information on whitelisting these addresses).

Feature Access Restrictions

Access to this feature is subject to contractual agreements, and there may be additional steps that need to have access to this feature authorized. Authorized usage of this data will be outlined within the contractual agreement with FOSSA.