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

Endpoint Options¶

Available Fields¶

Send the following request to retrieve a list of available fields, including the field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/artifacts endpoint:

OPTIONS /v3/artifacts

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/artifacts endpoint.

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 to which the Artifact belongs	Integer	TRUE [1]	FALSE	1, 2, 3
caseXid	The XID of the Case to which the Artifact belongs	String	TRUE [1]	FALSE	“a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1”
derivedLink	Specifies whether the Artifact should be used to potentially associate Cases	Boolean	FALSE	TRUE	true, false
fieldName [2]	The name of the Task Artifact Field to which the Artifact corresponds	String	FALSE	TRUE	“senderAddress”
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 added to the Artifact	Note Object	FALSE	TRUE	{“data”: [{“text”: “This IP address is malicious.”}]}
source	The name of the user who added the Artifact to the Case	String	FALSE	TRUE	“jsmith”
summary	The summary (i.e., name) of the Artifact	String	TRUE	TRUE	“badguy.com”
taskId	The ID of the Task to which the Artifact belongs	Integer	FALSE	FALSE	1, 2, 3
taskXid	The XID of the Task to which the Artifact belongs	String	FALSE	FALSE	“d7dafb59-bf74-46fe-bf18-8da14cc59219”
type [3]	The Artifact’s type	String	TRUE	FALSE	“URL”

[1]	(1, 2) When adding an Artifact to a Case, you must include either the `caseId` or `caseXid` field 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.

[2]	To retrieve the name of a Task’s Artifact Field(s), send a request in the following format and review the `name` field for each Artifact Field contained within the `configTask` object in the response: `GET /v3/tasks/{taskId}`.

[3]	To retrieve a list of available Artifact types, send the following request and review the `type` field in the response: `OPTIONS /v3/artifacts`. You can also retrieve a list of available Artifact types by sending the following request: `GET /v3/artifactTypes`.

Note

If adding an Artifact to a Task, you do not need to specify the ID of the Case to which the Task belongs in your request. You only need to specify the ID or XID of the Task to which the Artifact will be added.

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/artifacts endpoint:

OPTIONS /v3/artifacts/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/artifacts endpoint:

OPTIONS /v3/artifacts/tql

Create Artifacts¶

The following example illustrates the basic format for creating an Artifact:

POST /v3/artifacts
{
    "caseId": 1,
    "summary": "Summary of the data contained in the Artifact",
    "type": "The Artifact's data type"
}

For example, the following request will add an Email Address Artifact with a summary of badguy@bad.com to the Case whose ID is 1. It will also complete the following actions for the Artifact:

Create a new Bad Guy Adversary Group and associate it to the Artifact
Add a Note to the Artifact

Hint

To include the associatedGroups and notes fields in the API response, append ?fields=associatedGroups&fields=notes to the end of the request URL.

POST /v3/artifacts
{
    "caseId": 1,
    "summary": "[email protected]",
    "type": "Email Address",
    "associatedGroups": {"data": [{"name": "Bad Guy", "type": "Adversary"}]},
    "notes": {"data": [{"text": "This email address belongs to a bad guy."}]}
}

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="
    },
    "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/artifacts endpoint.

Note

To create an Artifact that is displayed in the Task Artifacts section when viewing the Task in the ThreatConnect UI, the following conditions must be met:

The Artifact must be added to a Task
The Task to which the Artifact is added must have an Artifact Field that accepts the Artifact’s type
The fieldname field must be defined when creating the Artifact, and the value for this field must be the Task’s Artifact Field that accepts the Artifact’s type

If these conditions are not met, the Artifact will be listed as a related Artifact when viewing the Task in the ThreatConnect UI. For more information about Artifact Fields, see the “Artifact Fields” section of the Adding Tasks to a Case knowledge base article.

Create Associations¶

You can create associations between Artifacts in your Organization and Groups and Indicators in your Organization.

When creating associations for Artifacts using the ThreatConnect v3 API, follow these guidelines:

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 an association to an existing Group, use the Group’s ID when setting the associatedGroups field (e.g., "associatedGroups": {"data": [{"id": 12345}]}).
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 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 the associatedIndicators field.

Note

You can associate multiple Indicators and Groups to an Artifact in a single POST or PUT request.

Retrieve Artifacts¶

Retrieve All Artifacts¶

Send the following request to retrieve data for all Artifacts:

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 Specific Artifact¶

Send a request in the following format to retrieve data for a specific Artifact:

GET /v3/artifacts/{artifactId}

For example, the following request will retrieve data for the Artifact whose ID is 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"
}

Update Artifacts¶

The following example illustrates the basic format for updating an Artifact:

PUT /v3/artifacts/{artifactId}
{
    {updatedField}: {updatedValue}
}

For example, the following request will update the summary of the Artifact whose ID is 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 to the /v3/artifacts endpoint.

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 belong to a Task, and that Task must contain multiple Artifact Fields that accept the Artifact’s type. For more information about Artifact Fields, see the “Artifact Fields” section of the Adding Tasks to a Case knowledge base article.

Delete Artifacts¶

Send a request in the following format to delete an Artifact:

DELETE /v3/artifacts/{artifactId}

For example, the following request will delete the Artifact whose ID is 1:

DELETE /v3/artifacts/1

JSON Response:

{
    "message": "Deleted",
    "status": "Success"
}

Delete Artifacts in Bulk¶

For instructions on deleting Artifacts in bulk, refer to Delete Case Objects in Bulk.