Examples: Using the API to Update Case Details

You can use Stellar Cyber's Cases API to update any combination of a specified case's priority, status, assignee, or tags. Any changes you make via the API to these fields are visible in the Case Details display for the event. I

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

Cases API URL

The Cases API is available at the following URL. Note that the ID of the case to be updated is included as a parameter in the URL:

/connect/api/v1/cases?id=<case_id>

Finding the ID for an Case

Using the API to update an case always requires the ID of the case to be updated as part of the URL. For example:

/connect/api/v1/cases?id=<case_id>

The easiest way to find the ID for an case is to use the cases API to retrieve details. Refer to Using the API to Retrieve Case Details. Once you have retrieved case details, search on the _id field to find the case ID.

Updating Case Details with the API

You can use POST calls to update any combination of the priority, status, assignee, tags, or description for a specified case.

You can use any language to make the call. For our example, we use Python.

For a POST call you need the ID of the event whose fields you want to update.

Your call must have the header, the /connect/api/v1/cases path, and at least one of the priority, status, assignee, or tags parameters. These are the different case details you an update using the API. Enter your own information for the arguments in the table below.

Here is an example with the arguments filled in:

This example performs a POST call as the user admin with the fake API key of MyAPIKey. The call is to the Stellar Cyber server at 192.168.1.24 to add the tag October-event to the case with the ID of 60ee186c1bb89d729e54ffc0.

Sample insert_ser Script

The sample script below 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 POST to the cases API in the putCase procedure (Step 3 in the sample). The script posts the tag October-event to the case with the ID of 1674728869334287aba4486901d24c4189a6fe8eab6efe05:

• 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
import time
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 putCase(token):
    headers = {"Authorization": "Bearer " + token, 'content-type': 'application/json' }
    url = urlunparse(("https", HOST, "/connect/api/v1/cases?id=1674728869334287aba4486901d24c4189a6fe8eab6efe05", "", "", ""))
    json_data = {
      "tags": {
    "add": [ "October-event"],
    },
    }
    query = json.dumps(json_data)
    res = requests.post(url, data=query, headers=headers, verify=False)
    print(res.text)
    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
    data = putCase(jwt)
    print("------------ show result of put case -------------")
    print(data)
    print("------------ end api results -------------")

Using the API to Verify the Update

You can always use the Stellar Cyber user interface to check whether your updates were successful – just navigate to the Case Details display for the event you changed and check the fields for your updates. For example, you can see the changes made by our earlier Python script in the image below. Note that the History tab even indicates which changes were made via the API:

Alternatively, you can make a query using the cases API to make sure your POST call worked. For example, we just used our script in in Updating Case Details with the API to set a tag called October-event. Let's query for all cases matching that tag:

https://192.168.1.24/connect/api/v1/cases?tags=October-event

In response, the API returns something similar to the following. We've highlighted the fields we updated using our script so you can see that we were successful:

{"data":{"cases":[{"_id":"62fceb4a48be7776c793a02a","acknowledged":1660826741467,"assignee":"826ef6979788454297c85cbba4a51c08","closed":0,"created_at":1660742474343,"created_by":"System","cust_id":"","end_timestamp":1660746082000,"event_ids":[{"_id":"1660742114240099585db8ba9885406fa18b4e5bb17bf874","_index":"aella-ser-1658966542094-"},{"_id":"1660742114240077448eded96a4d44f98ff799c2c1eff806","_index":"aella-ser-1658966542094-"},{"_id":"1660746284032781eb7f78bcca0d4338a1735a18ef4204e3","_index":"aella-ser-1658966542094-"},{"_id":"1660746284032809727da67ccaa44a40b5d44988225d4932","_index":"aella-ser-1658966542094-"},{"_id":"1660746284032814d3f911301821452288bf56fb28044235","_index":"aella-ser-1658966542094-"},{"_id":"16607462840328180a41d20f86ec4859bb58287257039af9","_index":"aella-ser-1658966542094-"},{"_id":"1660746283932546ec880b60ae844b28948e8aa94580e33c","_index":"aella-ser-1658966542094-"},{"_id":"16607462839325661fb284acec084cc891316858d370ac3a","_index":"aella-ser-1658966542094-"},{"_id":"1660746283944871a9b08d76659b4b2c87a49336e6e7edb5","_index":"aella-ser-1658966542094-"},{"_id":"1660746283966094a94025c6dd4b4bdcbfd9d5c6e995a7fc","_index":"aella-ser-1658966542094-"},{"_id":"16607462840328035b525a3073784daea7a7ac22bbd699a5","_index":"aella-ser-1658966542094-"},{"_id":"1660746641444416cfd9d568ca6b49a489c9290cf5566ff9","_index":"aella-ser-1658966542094-"},{"_id":"1660746641444450a171db849aca4da4be696854821fb33e","_index":"aella-ser-1658966542094-"},{"_id":"1660746641461483100262e736a54f09922d3d1dd7133f09","_index":"aella-ser-1658966542094-"},{"_id":"166074664150905734be5e848aa94e179505bef7657f6864","_index":"aella-ser-1658966542094-"},{"_id":"1660746641444581daaad835dae04cb4a0fdf56e8fa45253","_index":"aella-ser-1658966542094-"},{"_id":"16607466415090878b99ce29201e4fa9923da5d92b52fbc1","_index":"aella-ser-1658966542094-"}],"history":[{"field":"created_at","timestamp":1660742474343,"user":"System"},{"field":"assignee","from":"","timestamp":1660826741467,"to":"826ef6979788454297c85cbba4a51c08","user":"5f80e442-1555-4621-9ec3-c5bd284adee5"},{"field":"description","from":"","timestamp":1660826939220,"to":"unusual","user":"5f80e442-1555-4621-9ec3-c5bd284adee5"},{"api":true,"field":"tags","from":[],"timestamp":1660835991729,"to":["October-event"],"user":"826ef6979788454297c85cbba4a51c08"},],"case_score":25,"metadata":{"algorithm":"algorithm_4.0","automatic_version":17,"description_auto":"'Carbon Black:XDR Endpoint Indicator of Threat' along was 16 other alerts involving host Desktop-CB and user CORP\\jamesmurphy\nObserved 1 XDR killchain stages: Persistent Foothold\nObserved 1 tactics: XDR EBA\nObserved 1 techniques: XDR Endpoint Indicator of Threat\nInvolved 1 hosts: Desktop-CB\nInvolved 1 users: CORP\\jamesmurphy","entity_id":"asset,,10.10.30.20","modified_at_auto":1660747038253,"name_auto":[]},"modified_at":1660835991789,"modified_by":"ohtani","name":"Carbon Black:XDR Endpoint Indicator of Threat and 16 others","priority":"Medium","priority_num":2,"resolution":"","size":17,"start_timestamp":1660741616000,"status":"New","tags":["October-event"],"ticket_id":67535,"version":17}],"total":1}}