Querying the CAT GraphQL API with Python

Step 1: Install Required Packages:

Install the following packages with the command:

!pip install requests pandas matplotlib seaborn

Step 2: Configure the GraphQL Client

Set up a Python script to interact with a GraphQL server. Depending on whether you enforce client certificates, you need to present your client certificate in the request.

import requests
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns

# Set up endpoint
HOST = 'hostname' 
# The ${HTTPS_PORT} parameter from the server setup
PORT = 59000
PATH = 'graphql'
GRAPHQL_ENDPOINT = f"https://{HOST}:{PORT}/{PATH}"

# Paths to mTLS certificate files
CLIENT_CERT_PATH = "mtls-client.crt"
CLIENT_KEY_PATH = "mtls-client.key"

# Optional: path to a CA bundle (self-signed or internal cert)
CA_CERT_PATH = "serverCA.crt"

# Modified query function
def run_query(query: str):
    headers = {"Content-Type": "application/json"}

    try:
        response = requests.post(
            GRAPHQL_ENDPOINT,
            json={"query": query},
            headers=headers,
            cert=(CLIENT_CERT_PATH, CLIENT_KEY_PATH),
            verify=CA_CERT_PATH
        )
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Query failed to run with status code: {response.status_code}. {response.text}")

Step 3: Define and Execute a query for data visualization

Define a GraphQL query to request specific data from the server, then executes it using the secure mTLS connection that is established earlier. The response is parsed to extract raw data, ready for visualization with libraries like pandas, matplotlib, and seaborn.

query = """
query MyQuery {
  getCryptoUsageCount(fieldName: "crypto_usage_id") {
    counts {
      name
      count
    }
    fieldName
  }
}
"""

response = run_query(query)
raw_data = response["data"]["getCryptoUsageCount"]["counts"]

Step 4: Normalize and Transform the Data

Make sure that the data is in a clean, organized format that is suitable for visualization, addressing missing values, and arranging the data in a meaningful order.

df = pd.DataFrame(raw_data)

# Rename null 'name' values to "Unknown"
df["name"] = df["name"].fillna("Unknown")

# Sort the data by 'count' in descending order
df = df.sort_values(by="count", ascending=False)
df

Output example:

|   | name | count |
| - | ---- | ----- | 
| 6 | AES256 | 8137|
| 2 | 93AADZCB | 7706|
| 0 | 93AADY4J | 7686|
| 185 | PRNG | 5641|
| 117 | CSFPKB | 5364|
| ... | ... | ...|
| 194 | SHA3-256 | 1|
| 195 | SHA3-384 | 1|
| 196 | SHA3-512 | 1|
| 149 | CSFSTCS | 1|
| 191 | SHA224 | 1|

Step 5: Visualize the Data

Create a bar chart to visualize the frequency of different cryptographic algorithms used.

plt.figure(figsize=(18, 10))
sns.barplot(data=df.head(50), x="name", y="count")
plt.xticks(rotation=45, ha="right")
plt.title("Top 50 Crypto Usages by Frequency")
plt.xlabel("Crypto Usage")
plt.ylabel("Count")
plt.tight_layout()
plt.show()

Bar chart example:

Alternative query with paginated data

The following is an example of a GraphQL query that is designed to retrieve paginated data from the server.

query = """
query MyQuery {
  getKeyUsageEvents(limit: 10, offset: 10) {
    keyUsageEvents {
      algorithmId
      category
      jobId
      jobName
      keyFingerprint
      keyFingerprintType
      keySecurity
      keyType
      keyUsages
      keyUsedByJobId
      userId
      plex
      service
      startTime
      endTime
      systemId
      systemName
      tokenFormat
      usageCount
    }
  }
}
"""
response = run_query(query)
raw_data = response["data"]["getKeyUsageEvents"]["keyUsageEvents"]
df_raw = pd.DataFrame(raw_data)
df_raw

Output example:

Disable SSL verification (verify=False) only for internal or testing purposes, as it bypasses certificate validation.

For schema types, see CC CAT GraphQL reference.