Examples: Using the API to Update Tags, Status, and Comments for Events

This section describes how to use the Stellar Cyber update_ser API to perform the following tasks for an event:

Add or delete custom Tags
Update the Status or Comments fields

Any changes you make via the API to these fields are visible in the Event Details display for the event.

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

Finding the Index and ID for an Event

To find the index and _id:

Log in to Stellar Cyber.
Navigate to the event.
Click More Info for more information on the event. The Event Details screen appears.
Click the Details entry in the left navigation panel (or JSON) and scroll to the bottom of the display.
The _index field is the index, and _id field is the ID.

The following example illustrates this procedure for an Alert:

Navigate to the Alerts page and scroll to the Alerts table.
Click the View button for the Alert whose Index and ID you want to retrieve.
Scroll to the bottom of the Alert Detail page where the Documents supporting the alert are listed and click the More Info button.
Scroll to the bottom of the listed fields and locate the _id and _index fields, as illustrated in the figure below.
Use these fields in your API call.

Using update_ser to Add or Delete Custom Tags for Events

You can use the update_ser API to add or delete custom tags for events. As summarized in the table below, your call must have the following:

The header and the /connect/api/update_ser path.
The index and ID of the event.
The event_tag field.
The op field set to either add or delete, depending on the type of operation you are performing.
The tag to be added or deleted in the tag field.

Task	Description	Parameters
Add a Tag	/connect/api/update_ser	{ "index": "Index", "_id": "ID", "event_tag": { "op":"add", "tag": "my_tag" } }
Delete a Tag	/connect/api/update_ser	{ "index": "Index", "_id": "ID", "event_tag": { "op":"delete", "tag": "my_tag" } }

Task

Description

Parameters

Add a Tag

/connect/api/update_ser

{

"index": "Index",

"_id": "ID",

"event_tag": {

"op":"add",

"tag": "my_tag"

}

Delete a Tag

/connect/api/update_ser

{

"index": "Index",

"_id": "ID",

"event_tag": {

"op":"delete",

"tag": "my_tag"

}

Procedure: Using a Python Script to Update the Tag Field for an Event

You can use POST calls to add or delete Tags for an event. You can use any language to make the call. The example below uses Python to add two tags to a specific event. You can copy and paste the example below, replacing the fields in boldto match your environment.

Find the API key for the account used to make the API call.
Find the Event ID and Index for the event whose tag you want to add or delete.
Create a Python script similar to the following:

headers={'Accept': 'application/json', 'Content-type': 'application/json'}

elastic_url ='https:// YourStellarCyberServer/connect/api/update_ser'

json_data = {

"index": "Index",

"_id": "ID",

"event_tag": {

"op": "add",

"tag": "my_tag"

}

}

query = json.dumps(json_data)

response = requests.post(elastic_url, auth=('Username','API Key'), data=query, verify=False, headers = headers)

print (response.text)
Enter your own information for the arguments in bold using the table below and run the script.

Argument	Description
Username	User name of the admin making the call
API Key	API key for that user name (edit a user on the Admin \| User Management page to generate an API key)
YourStellarCyberServer	The URL or IP address of your Stellar Cyber server
Index	The index to be queried
ID	The ID of the event to change
event_tag	Must be included to indicate that you are adding or deleting a tag for the specified event.
op	Can be either add or delete, depending on the type of operation you want to perform.
tag	The actual tag to be added or deleted for the specified event.

Examples

The following examples demonstrate common ways to use the update_ser API to add and delete tags. These examples use Python, though any programming language will work.

Example: Using a Python Script to Update the Tag Field for an Event

The following example uses a Python script to add a "You_Are_It" tag to an event with the following details:

Stellar Cyber DP IP Address –192.168.12.25
Username:API Key – ohtani:UmT58sxx3We52W5y
Index – aella-ser-2022.03.01-
ID – qe2RR38Boj-otBRJ5J4w

#!/usr/bin/env python

import json

import requests

headers={'Accept': 'application/json', 'Content-type': 'application/json'}

elastic_url ='https://10.33.6.2/connect/api/update_ser'

json_data = {

"index": "aella-ser-2022.03.01-",

"_id": "qe2RR38Boj-otBRJ5J4w",

"event_tag": {

"op": "add",

"tag": "You_Are_It"

}

query = json.dumps(json_data)

response = requests.post(elastic_url, auth=('ohtani', '0MGDNJ5dcHPtNSWy'), data=query, verify=False, headers = headers)

print (response.text)

Values in bold are the values you must supply as part of a similar query. The figure below shows the event after the tag has been added:

Example: Using a Python Script to Delete the Tag Field for an Event

Now, we'll use a different script to delete the "You_Are_It" tag from that same event. The only change from the previous script it to set op to delete instead of add.

#!/usr/bin/env python

import json

import requests

headers={'Accept': 'application/json', 'Content-type': 'application/json'}

elastic_url ='https://10.33.6.2/connect/api/update_ser'

json_data = {

"index": "aella-ser-2022.03.01-",

"_id": "qe2RR38Boj-otBRJ5J4w",

"event_tag": {

"op": "delete",

"tag": "You_Are_It"

}

query = json.dumps(json_data)

response = requests.post(elastic_url, auth=('ohtani', '0MGDNJ5dcHPtNSWy'), data=query, verify=False, headers = headers)

print (response.text)

Using update_ser to Update the Status and Comments Fields for Events

You can use POST calls to update the Status and Comments fields for an event. You can use any language to make the call. For our example, which is formatted so you can cut and paste, replacing the text in bold, we use Python.

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

headers={'Accept': 'application/json', 'Content-type': 'application/json'}

elastic_url ='https:// YourStellarCyberServer/connect/api/update_ser'

json_data = {

"index": "Index",

"_id": "ID",

"status": "Status",

"comments": "Comment")

}

query = json.dumps(json_data)

response = requests.post(elastic_url, auth=('Username','API Key'), data=query, verify=False, headers = headers)

print (response.text)

Your call must have the header and the /connect/api/update_ser path, and must have either status or comments (or both). Enter your own information for the arguments in bold.

Argument	Description
Username	User name of the admin making the call
API Key	API key for that user name (edit a user on the Admin \| User Management page to generate an API key)
YourStellarCyberServer	The URL or IP address of your Stellar Cyber server
Index	The index to be queried
ID	The ID of the event to change
Status	You can change the status to: New In Progress Ignored Closed
Comments	You can add whatever comments you want

The contents of response.txt indicate success or failure and will be similar to:

OK 200—your API call was successful
Invalid event status value: closed—your API call failed because the status is invalid (in this case due to the lower case "c")
Missing fields to be updated for the event—your API call failed because you left out the fields to be updated (Status or Comments)

For an example with the arguments filled in:

headers={'Accept': 'application/json', 'Content-type': 'application/json'}

elastic_url ='https://192.168.1.24/connect/api/update_ser'

json_data = {

"index": "aella-ser-1610496070892-",

"_id": "7PW5SXcBlxPU3jFcFJ_s",

"status": "Closed",

"comments": "Analysis complete.",

}

query = json.dumps(json_data)

response = requests.post(elastic_url, auth=('admin','APISquared'), data=query, verify=False, headers = headers)

print (response.text)

This example performs a POST call as the user admin with the obviously fake API key of APISquared. The call is to the Stellar Cyber server at 192.168.1.24 to update status for the event 7PW5SXcBlxPU3jFcFJ_s in the aella-ser-1610496070892- index to Closed and add the comment Analysis complete..

Combining Updates to Tags, Status, and Comments

You can also combine updates to the Tags, Status, and Comments for an event in a single script. For example:

#!/usr/bin/env python

import json

import requests

headers={'Accept': 'application/json', 'Content-type': 'application/json'}

elastic_url ='https://10.33.6.2/connect/api/update_ser'

json_data = {

"index": "aella-ser-1645142612360-",

"_id": "Jfl7SH8Boj-otBRJeTR7",

"status": "Closed",

"comments": "Analysis complete",

"event_tag": {

"op": "add",

"tag": "DevOps"

}

query = json.dumps(json_data)

response = requests.post(elastic_url, auth=('ohtani', '0MGDNJ5dcHPtNSWy'), data=query, verify=False, headers = headers)

print (response.text)

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 Event Details display for the event you changed and check the fields for your updates.

Alternatively, you can use a GET call to make sure your POST call worked. You can use any language to make the call. This ElasticSearch example uses Python with the Index and ID from the example in Using update_ser to Update the Status and Comments Fields for Events. The procedure is the same regardless of the type of update_ser call you made – just make sure you use the correct _index and _id in the URL.

headers={'Accept': 'application/json', 'Content-type': 'application/json'}

elastic_url ='https://172.16.1.31/connect/api/data/aella-ser-1610496070892-/amsg/7PW5SXcBlxPU3jFcFJ_s'

response = requests.get(elastic_url, auth=('admin','5w3sfoGA-lz23GFR'), verify=False, headers = headers)

print (response.text)

The output will be similar to: