Extracting Dashboard Metrics

This article reviews how to create your own custom dashboard integration on third-party platforms using Secureworks® Taegis™ VDR metrics data exposed through the Public API.

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

Create a Public API Client in VDR & Get an Authentication Token ⫘

The first step is to make sure you have the necessary API credentials. 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. For more information, see Creating Public API Clients.

The following sections 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 ⫘

The following is a basic Python script to retrieve the current score and score variation. Make sure to replace the <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"))])