Examples: Using the API to Retrieve Connector Details

You can use the Stellar Cyber API to query the DP for a list of its configured connectors, either for a specified tenant or, if you have the necessary privileges, for all tenants. The API returns detailed configuration information on all connectors matching the query.

Starting with the 4.3.7 release, you can also use the API to create Connectors. Refer to the interactive API Reference for the syntax.

Refer to Configuring API Authentication for general requirements to use the API.

API Syntax for Retrieving Connector Details

The syntax for retrieving connector details via the API is as follows:

• Query for all connectors:

  https://URL/connect/api/v1/connector

• Query for connectors for a specified tenant:

  https://URL/connect/api/v1/connector?cust_id=<tenant_id>

Arguments:

• <tenant_id> – Optional. You can use this argument to query for all connectors assigned to a specified tenant using its ID retrieved from the System | Administration | Tenants page, as described below.

In response, the API returns detailed information on all connectors matching the API call. The information returned is similar to that presented in the System | Integration | Connectors page and is explained below in Connector Information Returned by the API.

Finding the Tenant ID

To query for the connectors belonging to a specific Tenant, you must know its numerical Tenant ID. You can find this value as follows:

1. Navigate to the System | integration | Connectors page and sort it by the Tenant Name column.

2. Note the name of the Tenant for whose connectors you want to query.

3. Navigate to the System | Administration | Tenants page and sort it by Tenant Name.

4. Locate the table entry for the Tenant for which you want to query.

5. Right-click in the ID column and use the Copy to Clipboard command in the context menu that appears to copy the Tenant ID.

6. Paste the Tenant ID into a text file to store it temporarily.

Examples

The following sections provide examples of common ways to use the connector API. The examples all use Python, though any programming language will work.

Querying for All Connectors Across All Tenants

The following example uses a Python script to query for all connectors across all tenants with the following details:

• Stellar Cyber DP IP Address – myserver.stellarcyber.cloud

• Username – myuser@stellarcyber.ai

• API Key (Refresh Token) from GUI – 2iRpBAyQYEfv77R2QtATlJN6Nvq6uzftBdzotSy2pjT-IvJTLw9aiHyh7Y2mo12IDSWc-FfHwUyPpmiHQnJrSH

Because this script queries for all connectors across all tenants, the Tenant ID is included.

Understanding the Script

This script works as follows:

• The script sets the host, userid, and refresh_token parameters in Step 1 in the sample.

• Because JWTs expire ten minutes after they are generated, this script includes logic that generates and uses a fresh JWT every time the script is run. The script runs the getAccessToken procedure to generate the new JWT (Step 2 in the sample).

• The script uses the generated JWT to make a call to the connector API in the getConnectors procedure (Step 3 in the sample).

• The script also prints the generated JWT to the screen. This, however, is not strictly necessary since the getAccessToken procedure already prints the status code for the call to the access_token API (200 for success; 401 for failure).

#!/usr/bin/python3

import requests
import base64
import json
from urllib.parse import urlunparse
requests.packages.urllib3.disable_warnings()

# Step 1
# Add DP IP/hostname, userid, and refresh token from GUI here
HOST = "myserver.stellarcyber.cloud"
userid = "myuser@stellarcyber.ai"
refresh_token = "2iRpBAyQYEfv77R2QtATlJN6Nvq6uzftBdzotSy2pjT-IvJTLw9aiHyh7Y2mo12IDSWc-FfHwUyPpmiHQnJrSH"

def getAccessToken(userid, refresh_token):
    auth = base64.b64encode(bytes(userid + ":" + refresh_token, "utf-8")).decode("utf-8")
    headers = {
        "Authorization": "Basic " + auth,
        "Content-Type": "application/x-www-form-urlencoded",
    }
    url = urlunparse(("https", HOST, "/connect/api/v1/access_token", "", "", ""))
    res = requests.post(url, headers=headers, verify=False)
    print(res.status_code)
    return res.json()["access_token"]


def getConnectors(token):
    headers = {"Authorization": "Bearer " + token}
    url = urlunparse(("https", HOST, "/connect/api/v1/connector", "", "", ""))
    res = requests.get(url, headers=headers, verify=False)
    print(res.status_code)
    return res.json()

if __name__ == "__main__":

    # Step 2: Use getAccessToken with supplied credentials to generate JWT
    jwt = getAccessToken(userid, refresh_token)
    print("------------ jwt -------------")
    print(jwt)
    print("------------ jwt  end -------------")

    # Step 3: use JWT token to call public API
    connectors = getConnectors(jwt)
    print("------------ call result of /connect/api/v1/connector -------------")
    print(connectors)
    print("------------ end api results -------------")

Querying for a Single Tenant's Connectors

The following example uses a Python script to query for all connectors belonging to a specific tenant with the following details:

• Stellar Cyber DP IP Address – myserver.stellarcyber.cloud

• Username – myuser@stellarcyber.ai

• API Key (Refresh Token) from GUI – 2iRpBAyQYEfv77R2QtATlJN6Nvq6uzftBdzotSy2pjT-IvJTLw9aiHyh7Y2mo12IDSWc-FfHwUyPpmiHQnJrSH

• Tenant ID (cust_id) – 7de229c6998041d1b84d9cb0e8893752

Understanding the Script

This script works as follows:

• The script sets the host, userid, and refresh_token parameters in Step 1 in the sample.

• Because JWTs expire ten minutes after they are generated, this script includes logic that generates and uses a fresh JWT every time the script is run. The script runs the getAccessToken procedure to generate the new JWT (Step 2 in the sample).

• The script uses the generated JWT to make a call to the connector API in the getConnectors procedure (Step 3 in the sample). The script includes the Tenant_ID in the URL.

• The script also prints the generated JWT to the screen. This, however, is not strictly necessary since the getAccessToken procedure already prints the status code for the call to the access_token API (200 for success; 401 for failure).

#!/usr/bin/python3

import requests
import base64
import json
from urllib.parse import urlunparse
requests.packages.urllib3.disable_warnings()

# Step 1
# Add DP IP/hostname, userid, and refresh token from GUI here
HOST = "myserver.stellarcyber.cloud"
userid = "myuser@stellarcyber.ai"
refresh_token = "2iRpBAyQYEfv77R2QtATlJN6Nvq6uzftBdzotSy2pjT-IvJTLw9aiHyh7Y2mo12IDSWc-FfHwUyPpmiHQnJrSH"

def getAccessToken(userid, refresh_token):
    auth = base64.b64encode(bytes(userid + ":" + refresh_token, "utf-8")).decode("utf-8")
    headers = {
        "Authorization": "Basic " + auth,
        "Content-Type": "application/x-www-form-urlencoded",
    }
    url = urlunparse(("https", HOST, "/connect/api/v1/access_token", "", "", ""))
    res = requests.post(url, headers=headers, verify=False)
    print(res.status_code)
    return res.json()["access_token"]


def getSensors(token):
    headers = {"Authorization": "Bearer " + token}
    url = urlunparse(("https", HOST, "/connect/api/v1/connector?cust_id=7de229c6998041d1b84d9cb0e8893752", "", "", ""))
    res = requests.get(url, headers=headers, verify=False)
    print(res.status_code)
    return res.json()

if __name__ == "__main__":

    # Step 2: Use getAccessToken with supplied credentials to generate JWT
    jwt = getAccessToken(userid, refresh_token)
    print("------------ jwt -------------")
    print(jwt)
    print("------------ jwt  end -------------")

    # Step 3: use JWT token to call public API
    sensors = getSensors(jwt)
    print("------------ call result of /connect/api/v1/sensors -------------")
    print(sensors)
    print("------------ end api results -------------")

Connector Information Returned by the API

The API returns the following information for each connector matching the API call in field:value pairs, with fields separated from values by a colon. Separate field:value pairs are separated with commas for easy import. If a field:value pair has subvalues, they are listed inside pairs of backward slashes (for example, \"domain\":\"SMC User\"); refer to Sample Output for an example.

These fields are all specified when the connector is added to Stellar Cyber.

Sample Output

The text below shows sample output of an API call for a specific tenant's connectors. In this case, the tenant has only one connector assigned (a database connector):

{'total': 1, 'connectors': [{'_id': '6542fa41cc22384bd8b468b7', 'active': True, 'category': 'endpoint', 'configuration': '{"interval":5,"oid":"7138a1e2-ebb6-44d8-9666-56a7ca7d48c4","aella_tenantid":"d7e9259bf0cb43578ad6bdae2feb7d99","content_type":["alerts"],"host_url":"https://api.limacharlie.io/v1","log_type":"limacharlie"}', 'created_at': 1698888257, 'tenantid': 'd7e9259bf0cb43578ad6bdae2feb7d99', 'filter_list': [], 'is_collect': True, 'is_respond': False, 'last_activity': 1702375700274, 'last_data_received': 1702341772793, 'name': 'Limacharlie-alert', 'run_on': 'dp', 'status': {'code': 0, 'message': None, 'status_time': 1702375599789}, 'type': 'limacharlie', 'version': '03.11.0000'}]}