Findings

Findings

Findings are the relation of an issue present in a target.

They are the main “citizen” of the Vulnerability DB and the one that provides more information about the relation of an issue, the target on which that issue was found, and the source from which it was detected and reported.

Regarding the source information for a finding, we have to make clear that, for the Vulnerability DB, a finding is primarely the relation of an issue for a target, regardless of which source detected it. It’s important to understand that, therefore, a finding can have been found multiple times, maybe by the same type of source, or maybe by different ones. So there is not a clear 1:1 relation between a finding and a source. Now you might be wondering why, when querying the API for findings, we get information for one source associated for each finding. The reason for this is that we made a decision to, when requesting information related to findings to the API, return only the data for the last source that reported that finding.

Finding endpoints also provide other data like the total_exposure and current_exposure. The total_exposure is the total amount of time (hours) that the issue has been open for that target. If the issue has been through numerous cycles of OPEN -> FIXED -> OPEN -> FIXED, then the total_exposure is the sum of days for the periods of time on which the finding had a status of OPEN. If the finding is still OPEN at the time of the request, total_exposure includes the hours since the last OPEN event for the finding up until the time of the request. The current_exposure, which only applies for findings that are currently OPEN, is the number of hours that the finding has been OPEN since the last time it was detected, or, if it has not been through cycles of OPEN -> FIXED, the time since it was first discovered.

Another important thing to mention regarding target information for a finding is the teams list. Vulnerability DB allows to associate a list of teams for each target. These teams can be used afterwards when querying the API. For example we can query only the findings that are associated with targets that belong to a specific team or group of teams.

Querying the API for findings

The Vulnerability Database API provides different methods to query information about the findings currently present in the system.

List Findings

List findings endpoint allows to query all the findings currently present in the Vulnerability Database.

curl -H "Content-Type: application/json" \
"https://vulnerabilitydb.example.com/findings"

This endpoint has support for many query string filter parameters, including filters for score, status, date, teams, etc. You can see the whole list of options in the API Reference section.

It’s important though, to give a clear explanaiton about how the date filter options work. The endpoint has support for three date related filters:

  • minDate: Specifies the minimum date to query for.
  • maxDate: Specifies the maximum date to query for.
  • atDate: Specifies the exact moment in time to query for.

Obviously atDate parameter is incompatible with the other two.

At the same time it’s important to note that date ranges filters MUST be used along with the status filter. It does not make sense to query for the findings between dateA and dateB. It makes sense to query for the findings that have been OPEN/FIXED between dateA and dateB.

We also have to clarify the behavior when performing queries for date ranges:

  • When querying for OPEN findings in a specific time range, the endpoint returns every finding that has been found in that time range, regardless if that finding has also been FIXED in that span of time.
  • When querying for FIXED findings in a specific time range, the endpoint returns every finding that has been FIXED in that time and is also FIXED at the end of that time span. So a finding that has been FIXED, then OPEN and then FIXED withing that time range, will be returned. But a finding that has been FIXED and then OPEN and is still OPEN at the end of that time range, will not be returned.

With the atDate parameter we can retrieve the list of findings with their data and status correspondent to the specified date. That means that total_exposure and current_exposure fields are recalculated up until the time specified in the atDate parameter.

For example we could query for all the high and critical severity findings that were FIXED during Q4 of 2019:

curl -H "Content-Type: application/json" \
"https://vulnerabilitydb.example.com/findings?minDate=2019-10-01&maxDate=2019-12-31&status=FIXED&minScore=7"

Or we could query for all the findings that were OPEN at the beginning of Q1 2020 for targets that are associated with the Security Team:

curl -H "Content-Type: application/json" \
"https://vulnerabilitydb.example.com/findings?atDate=2020-01-01&status=OPEN&team=e84cfeeb-7a2b-442b-b1cf-15af8b4a52d3"

Get Finding

The Get Finding endpoint allows to query information related with a particular finding, specifying its ID.

curl -H "Content-Type: application/json" \
"https://vulnerabilitydb.example.com/findings/0205a902-64a7-4c77-8d00-5d4c8d06399a"

List Events by Finding

As we said, a finding can be reported many times by different sources, each one of these FOUND events is a finding_event.

We can list all the events for a specific finding:

curl -H "Content-Type: application/json" \
"https://vulnerabilitydb.example.com/findings/afd5234d-dceb-4c8b-93f2-4ec0eae5a35d/events"

Finding MTTR

MTTR stands for Mean Time To Remediate, and is the average time that elapses since the vulnerability is found until it is fixed.

As we said, a vulnerability can go through different states during its lifecycle. For example it can be OPEN, then FIXED, then OPEN again, and finally FIXED for the same target. In this case the finding MTTR would be the average time (days) on which it had the status of OPEN.

This endpoint allows to query that average time specifically for one particular finding.

curl -H "Content-Type: application/json" \
"https://vulnerabilitydb.example.com/issues/20289f5d-8c6e-40e7-81a3-b3e2e0f7fbe5/mttr"