Cases¶
A Workflow Case is a single instance of an investigation, inquiry, or other procedure. It contains all required elements of a notable event in a logical structure. Cases can be used to capture key evidence to enable security teams to decide if the Case should be escalated.
Endpoint: /api/v3/cases
Endpoint Options¶
Available Fields¶
Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/cases
endpoint:
OPTIONS /v3/cases
Hint
To include read-only fields in the response, append ?show=readonly
to the end of the request URL.
Alternatively, refer to the following tables for a list of available fields that can be included in the body of a POST or PUT request to the /v3/cases
endpoint.
Field | Description | Type | Required for Creation? | Updatable? | Example Value(s) |
---|---|---|---|---|---|
artifacts | A list of Artifacts added to the Case | Artifact Object | FALSE | TRUE | {“data”: [{“summary”: “badguy.com”, “type”: “Host”}]} |
assignee | The user or user group assigned to the Case | Assignee Object | FALSE | TRUE | {“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}}
{“type”: “Group”, “data”: {“name”: “SOC Team”}}
{“type”: “User”, “data”: {“id”: 3}}
|
associatedCases | A list of Cases associated to the Case | Case Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low”}]}
|
associatedGroups | A list of Groups associated to the Case | Group Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
|
associatedIndicators | A list of Indicators associated to the Case | Indicator Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“ip”:”66.96.146.129”, “type”: “Address”}]}
|
attributes [1] | A list of Attributes added to the Case | Case Attribute Object | FALSE | TRUE | {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”}]} |
caseCloseTime | The date and time the Case was closed | Date | FALSE | TRUE | “2021-04-30T00:00:00Z” |
caseDetectionTime | The date and time a security incident or threat was detected (e.g., by a security team) | Date | FALSE | TRUE | “2021-04-30T00:00:00Z” |
caseOccurrenceTime | The date and time a security incident or threat occurred | Date | FALSE | TRUE | “2021-04-30T00:00:00Z” |
caseOpenTime | The date and time the Case was opened | Date | FALSE | TRUE | “2021-04-30T00:00:00Z” |
description | A description of the Case | String | FALSE | TRUE | “This Case is an investigation of a high-level hacker incident that occurred on critical systems.” |
name | The name of the Case | String | TRUE | TRUE | “Hacker Investigation” |
notes | A list of Notes added to the Case | Note Object | FALSE | TRUE | {“data”: [{“text”: “Upload all relevant research performed for this Case to the SOC Team shared drive.”}]} |
resolution [2] | The resolution of the Case | String | FALSE | TRUE | “Containment Achieved”, “False Positive” |
severity [3] | The severity of the Case (accepted values include “Low”, “Medium”, “High”, and “Critical”) | String | TRUE | TRUE | “Low”, “Medium”, “High”, “Critical” |
status [4] | The status of the Case (accepted values include “Open” and “Closed”) | String | TRUE | TRUE | “Open”, “Closed” |
tags | A list of Tags applied to the Case | Tag Object | FALSE | TRUE | {“data”: [{“name”: “Phishing”}]} |
tasks | A list of Tasks added to the Case | Task Object | FALSE | TRUE | {“data”: [{“name”: “Investigate Phishing Email”, “workflowPhase”: 1, “workflowStep”: 1}]} |
userAccess | A list of users that, when defined, are the only ones allowed to view and edit the Case | User Object | FALSE | TRUE | |
workflowEvents | A list of Timeline Events for the Case | Workflow Event Object | FALSE | TRUE | {“data”: [{“summary”: “Case created via API”, “eventDate”: “2021-08-12T12:30:12Z”}]} |
workflowTemplate | The Workflow applied to the Case | Workflow Template Object | FALSE | TRUE | {“name”: “Phishing Email Analysis”}
{“id”: 12345}
|
[1] | Attribute Types for Cases must first be created at the System- or Organization-level before you can add Attributes to a Case, as detailed in the Creating Custom Attribute Types knowledge base article. To retrieve a list of available Attribute Types and determine whether an Attribute Type applies to Cases, send the following request and then review the attributeTypeMappings field included in the response: GET /v3/attributeTypes?fields=mapping . |
[2] | The following are accepted values for the
|
[3] | The following are accepted values for the
|
[4] | The following are accepted values for the
|
Include Additional Fields in Responses¶
When creating, retrieving, or updating data, you can use the fields
query parameter to include additional fields in the API response that are not included by default.
Send the following request to retrieve a list of fields you can include in responses returned from the /v3/cases
endpoint:
OPTIONS /v3/cases/fields
Filter Results¶
When retrieving data, you can use the tql
query parameter to filter results with ThreatConnect Query Language (TQL).
Send the following request to retrieve a list of valid TQL parameters you can use when including the tql
query parameter in a request to the /v3/cases
endpoint:
OPTIONS /v3/cases/tql
Create Cases¶
The following example illustrates the basic format for creating a Case:
POST /v3/cases
{
"name": "Case name",
"status": "Case status",
"severity": "Case severity"
}
For example, the following request will create a Case named “Phishing Investigation.” It will also complete the following actions for the Case:
- Set the Case’s severity to Low
- Set the Case’s status to Open
- Assign the Case to smithj@threatconnect.com
- Create an Artifact within the Case and associate the Artifact to the existing Indicator whose ID is 2
- Apply the T1566 - Phishing ATT&CK® Tag to the Case
Attention
When applying ATT&CK Tags to a Case, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to apply the T1566 - Phishing ATT&CK Tag to a Case, use Phishing as the Tag name.
Also, if you applied a new Tag to a Case and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to a Case and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.
Hint
To include the artifacts
and tags
fields in the API response, append ?fields=artifacts&fields=tags
to the end of the request URL.
POST /v3/cases
{
"artifacts": {
"data": [
{
"summary": "badguy.com",
"type": "Host",
"associatedIndicators": {
"data": [
{
"id": "2"
}
]
}
}
]
},
"assignee": {
"type": "User",
"data": {
"userName": "[email protected]"
}
},
"name": "Phishing Investigation",
"severity": "Low",
"status": "Open",
"tags": {
"data": [
{
"name": "Phishing"
}
]
}
}
JSON Response:
{
"data": {
"id": 1,
"xid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
"name": "Phishing Investigation",
"dateAdded": "2023-03-09T14:41:27Z",
"lastUpdated": "2023-03-09T14:41:27Z",
"caseOpenTime": "2023-03-09T14:41:27.27Z",
"caseOpenUser": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"status": "Open",
"severity": "Low",
"resolution": "Not Specified",
"assignee": {
"type": "User",
"data": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "JMS",
"owner": "Demo Organization"
}
},
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"owner": "Demo Organization",
"ownerId": 1
},
"message": "Created",
"status": "Success"
}
Refer to the Available Fields and section for a list of available fields that can be included in the body of a POST request to the /v3/cases
endpoint.
Create Associations¶
You can create associations between Cases in your Organization and Groups, Indicators, and other Cases in your Organization. If cross-owner associations are enabled on your ThreatConnect instance, you can also create associations between Groups and Indicators in Communities and Sources to which you have access and Cases in your Organization.
When creating associations for Cases using the ThreatConnect v3 API, follow these guidelines:
- To create an association to a new Case, include all fields required to create a Case when setting the
associatedCases
field. - To create an association to an existing Case, use the Case’s ID when setting the
associatedCases
field (e.g.,"associatedCases": {"data": [{"id": 12345}]}
). - To create an association to a new Group, include all fields required to create the type of Group when setting the
associatedGroups
field. To create the Group in a Community or Source, include theownerId
orownerName
field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Group when setting theassociatedGroups
field. - To create an association to an existing Group, use the Group’s ID when setting the
associatedGroups
field. - To create an association to a new Indicator, include all fields required to create the type of Indicator when setting the
associatedIndicators
field. To create the Indicator in a Community or Source, include theownerId
orownerName
field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Indicator when setting theassociatedIndicators
field. - To create an association to an existing Indicator, use the Indicator’s ID, or use its summary and type (e.g.,
"associatedIndicators": {"data": [{"type": "Host", "hostname": "badguy.com"}]}
), when setting theassociatedIndicators
field. To create an association to an Indicator in a Community or Source using the Indicator’s summary and type, include theownerId
orownerName
field and specify the ID or name, respectively, of the Community or Source to which the Indicator belongs when setting theassociatedIndicators
field.
Note
You can associate multiple Cases, Indicators, and Groups to a Case in a single POST or PUT request.
Retrieve Cases¶
Retrieve All Cases¶
Send the following request to retrieve data for all Cases:
GET /v3/cases
JSON Response:
{
"data": [
{
"id": 1,
"xid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
"name": "Phishing Investigation",
"dateAdded": "2023-03-09T14:41:27.622Z",
"lastUpdated": "2023-03-09T14:41:27.622Z",
"caseOpenTime": "2023-03-09T14:41:27.622Z",
"caseOpenUser": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"status": "Open",
"severity": "Low",
"resolution": "Not Specified",
"assignee": {
"type": "User",
"data": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "JMS",
"owner": "Demo Organization"
}
},
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"owner": "Demo Organization",
"ownerId": 1
},
{
"id": 2,
"xid": "b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2",
"name": "Malware Investigation",
"description": "Case to investigate new malware",
"dateAdded": "2023-03-17T18:56:22Z",
"lastUpdated": "2023-03-25T11:25:34Z",
"caseOpenTime": "2023-03-17T18:56:22Z",
"caseOpenUser": {
"id": 2,
"userName": "[email protected]",
"firstName": "Pat",
"lastName": "Jones",
"pseudonym": "patjones",
"owner": "Demo Organization"
},
"status": "Open",
"severity": "Critical",
"resolution": "Not Specified",
"createdBy": {
"id": 2,
"userName": "[email protected]",
"firstName": "Pat",
"lastName": "Jones",
"pseudonym": "patjones",
"owner": "Demo Organization"
},
"owner": "Demo Organization",
"ownerId": 1
},
{...}
],
"status": "Success"
}
Attention
Only Cases to which your API user account has viewing access will be included in the API response.
Retrieve a Specific Case¶
Send a request in the following format to retrieve data for a specific Case:
GET /v3/cases/{caseId}
For example, the following request will retrieve data for the Case whose ID is 3:
GET /v3/cases/3
JSON Response:
{
"data": {
"id": 3,
"xid": "c3c3c3c3-c3c3-c3c3-c3c3-c3c3c3c3c3c3",
"name": "Analyze Suspicious Email and Report Findings",
"dateAdded": "2023-03-19T14:41:27.622Z",
"lastUpdated": "2023-03-21T09:22:39.622Z",
"caseOpenTime": "2023-03-09T14:41:27.622Z",
"caseOpenUser": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "JMS",
"owner": "Demo Organization"
},
"status": "Open",
"severity": "Medium",
"resolution": "Not Specified",
"assignee": {
"type": "Group",
"data": {
"id": 1,
"name": "SOC Team",
"description": "Members of the SOC team.",
}
},
"createdBy": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "JMS",
"owner": "Demo Organization"
},
"owner": "Demo Organization",
"ownerId": 1
},
"status": "Success"
}
Update Cases¶
The following example illustrates the basic format for updating a Case:
PUT /v3/cases/{caseId}
{
{updatedField}: {updatedValue}
}
For example, the following request will make the following updates to the Case whose ID is 1:
- Set the Case’s resolution to False Positive
- Set the Case’s status to Closed
- Create a new Adversary Group named Extreme Bad Guy that is associated to the Artifact whose ID is 4, and then associate the Group to the Case
Hint
To include the associatedGroups
field in the API response, append ?fields=associatedGroups
to the end of the request URL.
PUT /v3/cases/1
{
"resolution": "False Positive",
"status": "Closed",
"associatedGroups": {
"data": [
{
"name": "Extreme Bad Guy",
"type": "Adversary",
"associatedArtifacts": {
"data": [
{
"id": 4
}
]
}
}
]
}
}
JSON Response:
{
"data": {
"id": 1,
"xid": "aa1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
"name": "Phishing Investigation",
"dateAdded": "2023-03-09T14:41:27.27Z",
"lastUpdated": "2023-03-30T13:27:41Z",
"caseOpenTime": "2023-03-09T14:41:27Z",
"caseOpenUser": {
"id": 3,
"userName": "11112222333344445555"
},
"caseCloseTime": "2021-04-12T18:36.18Z",
"caseCloseUser": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"status": "Closed",
"severity": "Low",
"resolution": "False Positive",
"assignee": {
"type": "User",
"data": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "JMS",
"owner": "Demo Organization"
}
},
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"owner": "Demo Organization",
"ownerId": 1
},
"message": "Updated",
"status": "Success"
}
Refer to the Available Fields and section for a list of available fields that can be included in the body of a PUT request to the /v3/cases
endpoint.
Hint
When updating a Case, you can use the mode
field to add or remove the following metadata:
associatedCases
associatedGroups
associatedIndicators
attributes
tags
See Update an Object’s Metadata for instructions on using the mode
field.
Attention
If you try to add an Attribute to a Case when the Attribute Type’s Max Allowed limit for Cases has been reached, the API will return a 400 Bad Request error.
Delete Cases¶
Send a request in the following format to delete a Case:
DELETE /v3/cases/{caseId}
For example, the following request will delete the Case whose ID is 1:
DELETE /v3/cases/1
JSON Response:
{
"message": "Deleted",
"status": "Success"
}
Delete Cases in Bulk¶
For instructions on deleting Cases in bulk, refer to Delete Case Objects in Bulk.
MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.