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:
-
Navigate to the System | integration | Connectors page and sort it by the Tenant Name column.
-
Note the name of the Tenant for whose connectors you want to query.
-
Navigate to the System | Administration | Tenants page and sort it by Tenant Name.
-
Locate the table entry for the Tenant for which you want to query.
-
Right-click in the ID column and use the Copy to Clipboard command in the context menu that appears to copy the Tenant ID.
-
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.
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.
API Field Name | Description |
---|---|
total |
The total number of connector entries returned for the query, followed by the type of entity returned for the query (connectors in this context). For example: {"total":88,"connectors" |
_id |
The internal ID for the connector. |
category |
The category assigned to the connector when it was created. For example, Cloud Security, Firewall, and so on. |
configuration |
The configuration section provides different details depending on the connector's category. The information reported corresponds directly to Step 2 Configuration in the Add Connector/Edit Connector workflow. For example, the Configuration step for a Firewall connector looks like this: The configuration API output for this same connector appears like this: Refer to Working with the Connectors Table for details on the different fields available for each connector type. |
tenant_id | The numerical Tenant ID for the connector. Tenant IDs are listed in System | Administration | Tenants. |
is_collect | Indicates whether the Collect funtion is enabled for the connector. |
is_respond | Indicates whether the Respond function is enabled for the connector. |
name | The name assigned to the connector. |
run_on | Indicates whether the connector runs on the DP (dp) or a data sensor (ds). |
type | Shows the connector type (for example, Checkpoint, MySQL, and so on). |
version |
The version number for the connector. |
last_activity |
The last activity time for the connector, expressed in epoch time. |
last_data_received |
The last time data was received by this connector, expressed in epoch time. |
status |
The health status of the connector. |
active |
Indicates whether the connector is active or not (boolean). |
filter_list |
The log filters applied to this connector. |
created_at |
The time at which the connector was first created, expressed in epoch time. |
modified_at |
The last time at which the connector was modified, expressed in epoch time. |
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'}]}