Artifacts¶
An Artifact in Workflow is any piece of data not captured in a Note that provides information relevant to a Workflow Case that may be useful to an analyst. Potential Artifact types include all ThreatConnect Indicator types, as well as a variety of other data types. Examples of Artifacts include domains, email addresses, log files, emails, PCAP files, screenshots, SIEM event files, and malware documents.
Endpoint: /api/v3/artifacts
Available Fields¶
You can retrieve a list of available fields for the /v3/artifacts
endpoint, including the field’s name, description, and accepted data type, by using the following query:
OPTIONS /v3/artifacts
Hint
To view all fields, including read-only fields, include the ?show=readonly
query parameter.
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 for the artifacts
object.
Field | Description | Type | Required for Creation? | Updatable? | Example Value(s) |
---|---|---|---|---|---|
associatedGroups | A list of Groups associated to the Artifact | Group Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
|
associatedIndicators | A list of Indicators associated to the Artifact | Indicator Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“hostName”:”badguy.com”, “type”: “Host”}]}
|
caseId | The ID of the Case that contains the Artifact | Integer | TRUE* | FALSE | 1, 2, 3 |
caseXid | The XID of the Case that contains the Artifact | String | TRUE* | FALSE | “a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1” |
derivedLink | Specifies whether the Artifact should be used to potentially associate Cases | Boolean | FALSE | TRUE | true, false |
fieldName | The name of the Artifact Field within a corresponding Task | String | FALSE | TRUE | “Sender Address” |
fileData | Base64-encoded file attachment (required only for certain Artifact types) | String | FALSE | TRUE | “UEsDBBQABgAIAA…” |
hashCode | The hash code of File-type Artifacts | String | FALSE | TRUE | “C254ZZjosDoUA2B…” |
notes | A list of Notes corresponding to the Artifact | Note Object | FALSE | TRUE | {“data”: [{“text”: “Note about malware case”}]} |
source | The name of the user who added the Artifact to the Case | String | FALSE | TRUE | “jsmith” |
summary | The data contained in the Artifact | String | TRUE | TRUE | “badguy.com” |
taskId | The ID of the Task corresponding to the Artifact | Integer | FALSE | FALSE | 1, 2, 3 |
taskXid | The XID of the Task corresponding to the Artifact | String | FALSE | FALSE | “d7dafb59-bf74-46fe-bf18-8da14cc59219” |
type | The Artifact’s data type | String | TRUE | FALSE | “URL” |
To view a list of available Artifact data types, use the following query and refer to the type
field:
OPTIONS /v3/artifacts/
Alternatively, refer to Artifact Types for instructions on retrieving available Artifact types.
Note
*When creating an Artifact, either caseId
or caseXid
must be included in the body of the POST request. Only one needs to be included in the body of the POST request, but both can be included, if desired.
Hint
To associate an existing Group to an Artifact, use the Group’s ID when setting the associatedGroups
field (e.g., {"data": [{"id": 12345}]}
). To associate an existing Indicator to an Artifact, use either the Indicator’s ID, or the Indicator’s type and summary (e.g., for a Host Indicator, use its hostName
), when setting the associatedIndicators
field.
Create Artifacts¶
The basic format for creating an Artifact is:
POST /v3/artifacts
{
"caseId": 1,
"summary": "Summary of the data contained in the Artifact",
"type": "The Artifact's data type"
}
For example, the following query will create an Email Address
Artifact with a summary of badguy@bad.com
for the Case with ID 1, create a new Adversary Group named Bad Guy
and associate it to the Artifact, and create a Note for the Artifact:
POST /v3/artifacts
{
"caseId": 1,
"summary": "[email protected]",
"type": "Email Address",
"associatedGroups": {"data": [{"name": "Bad Guy", "type": "Adversary"}]},
"notes": {"data": [{"text": "Note about this artifact"}]}
}
JSON Response:
{
"data": {
"id": 1,
"summary": "[email protected]",
"type": "Email Address",
"intelType": "indicator-EmailAddress",
"dateAdded": "2021-04-22T19:24:06Z",
"notes": {
"data": [
{
"id": 5,
"text": "Note about this artifact",
"summary": "Note about this artifact",
"author": "11112222333344445555",
"dateAdded": "2021-04-22T19:24:06Z",
"lastModified": "2021-04-22T19:24:06Z",
"edited": false,
"artifactId": 1
}
]
},
"associatedGroups": {
"data": [
{
"id": 13,
"ownerName": "Demo Organization",
"dateAdded": "2021-04-22T19:24:06Z",
"webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=13",
"type": "Adversary",
"name": "Bad Guy",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"role": "Api User"
},
"lastModified": "2021-04-22T19:24:06Z"
}
]
},
"derivedLink": true,
"hashCode": "a/mHEtrRoPrG9csrdltEY73kdKHihi2jow40V3WFYrU="
},
"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 for the artifacts
object.
Note
When creating or updating an Artifact, you can associate Indicators and Groups that do not yet exist in ThreatConnect to the Artifact. To do so, fill out all required fields for the type of Indicator or Group being associated to the Artifact. Upon creation of the new Artifact, any associated objects included in the body of the POST request that do not yet exist in ThreatConnect will also be created. In addition, you can associate multiple Indicators and Groups to the Artifact being created in a single POST request.
Note
To create an Artifact that is displayed in the Task Artifacts section of a Task, the following conditions must be met:
- The Artifact must correspond to a Task;
- The corresponding Task must have an Artifact Field that accepts the same data type as the Artifact;
- The
fieldname
field must be defined when creating the Artifact.
Otherwise, the Artifact will be displayed in the Related Artifacts section of the Task. For more information about Artifact Fields, see the “Artifact Fields” section of theection of the Task. For more information about Artifact Fields, see the “Artifact Fields” section of the Workflow Cases: Phases and Tasks knowledge base article.
Retrieve Artifacts¶
Retrieve All Artifacts¶
To retrieve all Artifacts, use the following query:
GET /v3/artifacts
JSON Response:
{
"data": [
{
"id": 1,
"summary": "[email protected]",
"type": "Email Address",
"intelType": "indicator-EmailAddress",
"dateAdded": "2021-04-22T19:24:06Z",
"derivedLink": true,
"hashCode": "a/mHEtrRoPrG9csrdltEY73kdKHihi2jow40V3WFYrU="
},
{
"id": 2,
"summary": "123.456.78.90",
"type": "IP Address",
"intelType": "indicator-Address",
"source": "johnsmith",
"dateAdded": "2021-03-08T13:24:38Z",
"derivedLink": true,
"hashCode": "cbdb4defdbb9433683a9daa0764c58a45bddd729"
},
{...}
],
"status": "Success"
}
Retrieve a Single Artifact¶
To retrieve a specific Artifact, use a query in the following format:
GET /v3/artifacts/{artifactId}
For example, the following query will return information about the Artifact with ID 3:
GET /v3/artifacts/3
JSON Response:
{
"data": {
"id": 3,
"summary": "URGENT - APPROVAL IS REQUIRED!!!",
"type": "Email Subject",
"fieldName": "helloSubject",
"intelType": "indicator-Email Subject",
"source": "patjones",
"dateAdded": "2021-03-15T10:16:40Z",
"derivedLink": true,
"hashCode": "fec31a1f2937c37b110d467cf78c03d820954596"
},
"status": "Success"
}
Request Additional Fields¶
To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.
Filter Results¶
To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.
Update Artifacts¶
The basic format for updating an Artifact is:
PUT /v3/artifacts/{artifactId}
{
{updatedField}: {updatedValue}
}
For example, the query below will update the summary for the Artifact with ID 1.
PUT /v3/artifacts/1
{
"summary": "[email protected]"
}
JSON Response:
{
"data": {
"id": 1,
"summary": "[email protected]",
"type": "Email Address",
"intelType": "indicator-EmailAddress",
"dateAdded": "2021-04-22T19:24:06Z",
"derivedLink": true,
"hashCode": "bR3jGyx3DqnOrXQ/dI/pYeYOpGOgxalv64tymVN661M="
},
"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 for the artifacts
object.
Hint
When updating an Artifact, you can use the mode
field to add or remove the following metadata:
associatedGroups
associatedIndicators
See Update an Object’s Metadata for instructions on using the mode
field.
Note
To update an Artifact’s fieldName
, the Artifact must correspond to a Task, and that Task must have multiple Artifact Fields defined. For more information about Artifact Fields, see the “Artifact Fields” section of the Workflow Cases: Phases and Tasks knowledge base article.
Delete Artifacts¶
The basic format to delete an Artifact is:
DELETE /v3/artifacts/{artifactId}
For example, the following query will delete the Artifact with ID 1:
DELETE /v3/artifacts/1
JSON Response:
{
"message": "Deleted",
"status": "Success"
}
Delete Artifacts in Bulk¶
To delete Artifacts in bulk, refer to Delete Case Objects in Bulk.