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.