Extracting dashboard metrics

How to create your own custom dashboard integration using Delve metrics exposed through the Public API.

In this article, we will demonstrate how to fetch metrics data from the Delve Public API in order to generate your own dashboard on third-party platforms.

You will need a Delve API Client ID and Secret and basic Python language knowledge.

Create a Public API Client in Delve & get an Authentication Token

The first step is to make sure you have the sufficient API credentials: you should start by creating a new API Client ID and use it through the built-in Swagger UI to fetch back the authentication bearer token to use in your scripted requests.

 

The following sections will cover the metrics extraction for:

  • Health score

  • Vulnerability variation
  • Contextual Vulnerability Prioritization Distribution

All examples are available in a git repository at the following address: https://github.com/delvelabs/awesome-public-api-examples

Health score

Here is a basic Python script to retrieve the the current score and score variation. Make sure to replace your <YOUR_TOKEN> and <YOUR_INSTANCE> variables. You may also update or remove the query parameters available for the metrics endpoints. 

from datetime import datetime, timedelta
import os
import requests


ACCESS_TOKEN = os.getenv("ACCESS_TOKEN", "<YOUR_TOKEN>")
API_BASE_URL = os.getenv("API_BASE_URL", "<YOUR_INSTANCE>")

now = datetime.now()
start_date = (now - timedelta(days=30)).strftime("%s")
end_date = now.strftime("%s")
params = dict(team="1", tag="12", start_date=start_date, end_date=end_date)

response = requests.get(
f"{API_BASE_URL}/metrics/health-score",
params=params,
headers=headers,
verify=False)

response.raise_for_status()

series = response.json().get("health").get("series")
timestamp = next(entry.get("data") for entry in series if entry.get("label") == "timestamp")
values = next(entry.get("data") for entry in series if entry.get("label") == "health")

print(f"Current Health Score: {values[-1]}")
print(f"Current Health Score Variation: {values[-1] - values[0]}")

Vulnerability variation

Use the following script to retrieve the current vulnerability variation.

from datetime import date, timedelta
from enum import Enum
import json
import os
import requests


class Precision(Enum):
day = "Day"
week = "Week"
month = "Month"


ACCESS_TOKEN = os.getenv("ACCESS_TOKEN", "")
API_BASE_URL = os.getenv("API_BASE_URL", "")

TEAM_ID = 1
TAG_ID = 12
START_DATE = date.today() - timedelta(days=30)
END_DATE = date.today()
PRECISION = Precision.day.value

headers = {
"authorization": f"Bearer {ACCESS_TOKEN}",
"accept": "application/json",
"accept-language": "fr"
}
query = {
"bool": {
"must": [
{"team": {"id": f"{TEAM_ID}"}},
{"tag": {"id": f"{TAG_ID}"}},
],
"should": [
{"first_discovery_date": {"gte": START_DATE.isoformat()}},
{"last_seen_date": {"lte": END_DATE.isoformat()}},
]
}
}
params = dict(q=json.dumps(query), limit=0, offset=0)
response = requests.get(f"{API_BASE_URL}/vulnerability-groups/distribution",
params=params,
headers=headers,
verify=False)
response.raise_for_status()

series = dict(
first=response.json().get(f"firstDiscoveryDate{PRECISION}").get("series"),
last=response.json().get(f"lastSeenDate{PRECISION}").get("series"),
)
values = dict(
first=next(x.get("data") for x in series.get("first") if x.get("label") == "count"),
last=next(x.get("data") for x in series.get("last") if x.get("label") == "count")
)
vulnerability_variation = sum(values["first"]) - sum(values["last"])

print(f"Current Vulnerability Variation: {vulnerability_variation}")

Contextual Vulnerability Prioritization Distribution

from datetime import date, timedelta
import json
import os
import requests


ACCESS_TOKEN = os.getenv("ACCESS_TOKEN", "")
API_BASE_URL = os.getenv("API_BASE_URL", "")

TEAM_ID = 1
TAG_ID = 12
START_DATE = date.today() - timedelta(days=30)
END_DATE = date.today()

headers = {
"authorization": f"Bearer {ACCESS_TOKEN}",
"accept": "application/json",
"accept-language": "fr"
}
query = {
"bool": {
"must": [
{"team": {"id": f"{TEAM_ID}"}},
{"tag": {"id": f"{TAG_ID}"}},
],
"should": [
{"first_discovery_date": {"gte": START_DATE.isoformat()}},
{"last_seen_date": {"lte": END_DATE.isoformat()}},
]
}
}
params = dict(q=json.dumps(query), limit=0, offset=0)
response = requests.get(f"{API_BASE_URL}/vulnerability-groups/distribution",
params=params,
headers=headers,
verify=False)
response.raise_for_status()

series = dict(
base=response.json().get("scoreStepBase").get("series"),
final=response.json().get("scoreStepFinal").get("series"),
)
values = dict(
base=next(x.get("data") for x in series.get("base") if x.get("label") == "count"),
final=next(x.get("data") for x in series.get("final") if x.get("label") == "count")
)

print("Score Distribution Base:")
print([(k, v) for k, v in enumerate(values.get("base"))])

print("\nScore Distribution Final:")
print([(k, v) for k, v in enumerate(values.get("final"))])