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.