Save and Link Artifacts to Incident‎

POST /Command/SaveArtifactForIncident

Create artifacts or update existing artifacts and link to incident.

Request

Authentication: API keys or JSON web tokens (JWT)

Body Parameters

Parameter Name	Type	Required/Optional	Description
Username	`string`	Required	The username of your D3 SOAR account.
Site	`string`	Required	The D3 SOAR site to run the remote command.
Artifact Type	`string`	Required	The type of the artifact(s). The command supports both system artifact and user-defined artifact types. System composite artifact types include: URL, User, File, ExternalEndpoint, InternalEndpoint, EmailAddress, Process, Service, Module, Driver, Signature, Certificate, Registry. System single-field artifact types include: Username, Filename, File Hash SHA256, File Hash MD5, File Hash SHA1, Process Guid, Signature Identity, Host Name, Internal Endpoint Domain Name, Internal IP, External Endpoint Domain Name, External IP, Registry Key. If this parameter is left blank, the command will automatically detect and match system composite artifact types based on the values provided in Artifact Fields.
Artifact Fields	`array<JSON Object>`	Required	For user-defined artifacts, an Identity field needs to be added to the collection of fields.
Incident Number	`string`	Required	Incident Number.

Body Sample Data

application/json

{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Artifact Type": null,
    "Artifact Fields": [
      {
        "URL": "http://example.com",
        "Reputation": "Low"
      },
      {
        "UserName": "Administrator"
      },
      {
        "FileName": "playbookfile.exe",
        "FilePath": "C:\\Windows\\System32\\playbookfile.exe",
        "SHA256": "2afa7715181f03b6fe5acd7c82b8e818303a5de567af1a83d8c283010af2db44",
        "MD5": "b0778a411c26f7b9b9ef5db8ed99566e",
        "SHA1": "62678242ac69a2fb5cfa6a2cc3256fd8229fd7f4",
        "Reputation": "High"
      },
      {
        "External_HostName": "D3Admin",
        "External_HostFQDN": "D3Admin.example.ca",
        "Reputation": "Medium",
        "External_IPAddress": "0:0:1:0:0:aaaa:cd9:d0a"
      },
      {
        "Internal_HostName": "D3Example",
        "Internal_HostFQDN": "D3Example.example.ca",
        "Internal_IPAddress": "192.168.2.112"
      },
      {
        "EmailAddress": "admin@example.com"
      },
      {
        "ProcessGuid": "1589170327575",
        "ProcessName": "powershell.exe",
        "ProcessID": "21721",
        "ProcessIntegrityLevel": "",
        "ProcessCurrentDirectory": "",
        "ProcessCommandLine": "powershell -Command $File=\\C:\\Users\\devin\\AppData\\Local\\Temp\\bbotstage.png\\;$Content=get-content $File;$Contento=[System.Text.Encoding]::ASCII.GetString([System.Convert]::FromBase64String($Content));Set-ExecutionPolicy Bypass -Scope Process -Force;IEX($Contento)",
        "ProcessOS": ""
      },
      {
        "ServiceId": "sampleServiceId",
        "ServiceName": "sampleServiceName",
        "ServiceStartMode": "sampleServiceStartMode",
        "ServiceStatus": "sampleServiceStatus"
      },
      {
        "ModuleBaseAddr": "sampleModuleBaseAddr.com"
      },
      {
        "DriverBaseAddr": "sampleDriverBaseAddr.com"
      },
      {
        "Signature": "sampleSignature",
        "SignatureID": "sampleSignatureID",
        "SignatureSeverity": "Low",
        "SignatureSource": "",
        "SignatureType": ""
      },
      {
        "CertName": "sampleCertName",
        "CertSerial": "sampleCertSerial"
      },
      {
        "RegistryKey": "sampleRegistryKey",
        "RegistryPath": "sampleRegistryPath",
        "RegistryValueName": "sampleRegistryValueName",
        "RegistryValueData": "sampleRegistryValueData",
        "RegistryDetails": "sampleRegistryDetails"
      },
      {
        "Identity": "customartifactid",
        "Reputation": "High",
        "Additional": {
          "Action result": "action result update",
          "Action result ID": "",
          "Action taken": "",
          "Affected Machine Name": "affected Machines Name"
        }
      }
    ],
    "Incident Number": "20220114-11"
  }
}

Response

200 OK

application/json

Field Name	Type	Description
error	`string`	The error message if the API request has failed.
returnData	`string`	The return data from the API request.
contextData	`array<JSON Object>`	The context data from the API request.

{
    "error": "",
    "returnData": "Successful",
    "contextData": [
      {
        "ArtifactType": "URL",
        "Status": "Successful",
        "ArtifactName": "http://example.com",
        "UpdateOrAdd": "Add",
        "ArtifactDetails": {
          "URL": "http://example.com",
          "Reputation": "Low"
        }
      },
      {
        "ArtifactType": "User",
        "Status": "Successful",
        "ArtifactName": "Administrator",
        "UpdateOrAdd": "Update",
        "ArtifactDetails": {
          "UserName": "Administrator"
        }
      },
      {
        "ArtifactType": "File",
        "Status": "Successful",
        "ArtifactName": "playbookfile.exe",
        "UpdateOrAdd": "Update",
        "ArtifactDetails": {
          "Old": {
            "FileName": "playbookfile.exe",
            "FilePath": "C:\\Windows\\System32\\playbookfile.exe",
            "SHA256": "2afa7715181f03b6fe5acd7c82b8e818303a5de567af1a83d8c283010af2db44",
            "MD5": "b0778a411c26f7b9b9ef5db8ed99566e",
            "SHA1": "62678242ac69a2fb5cfa6a2cc3256fd8",
            "Reputation": "Medium"
          },
          "New": {
            "FileName": "playbookfile.exe",
            "FilePath": "C:\\Windows\\System32\\playbookfile.exe",
            "SHA256": "2afa7715181f03b6fe5acd7c82b8e818303a5de567af1a83d8c283010af2db44",
            "MD5": "b0778a411c26f7b9b9ef5db8ed99566e",
            "SHA1": "62678242ac69a2fb5cfa6a2cc3256fd8",
            "Reputation": "High"
          }
        }
      },
      {
        "ArtifactType": "External_Endpoint",
        "Status": "Successful",
        "ArtifactName": "D3Admin.example.ca",
        "UpdateOrAdd": "Update",
        "ArtifactDetails": {
          "Old": {
            "External_HostName": "D3Admin",
            "External_HostFQDN": "D3Admin.example.ca",
            "External_IPAddress": "66.249.64.167, 0:0:1:0:0:aaaa:cd9:d0a, 0:1:1:1:0:ffff:cd9:d0a",
            "Reputation": "High"
          },
          "New": {
            "External_HostName": "D3Admin",
            "External_HostFQDN": "D3Admin.example.ca",
            "External_IPAddress": "66.249.64.167, 0:0:1:0:0:aaaa:cd9:d0a, 0:1:1:1:0:ffff:cd9:d0a",
            "Reputation": "Medium"
          }
        }
      },
      {
        "ArtifactType": "Internal_Endpoint",
        "Status": "Successful",
        "ArtifactName": "D3Example.example.ca",
        "UpdateOrAdd": "Add",
        "ArtifactDetails": {
          "Internal_HostName": "D3Example",
          "Internal_HostFQDN": "D3Example.example.ca",
          "Internal_IPAddress": [
            "192.168.2.112"
          ]
        }
      },
      {
        "ArtifactType": "Email",
        "Status": "Successful",
        "ArtifactName": "admin@example.com",
        "UpdateOrAdd": "Update",
        "ArtifactDetails": {
          "EmailAddress": "admin@example.com"
        }
      },
      {
			"ArtifactType":"Process",
			"Status":"Successful",
			"Artifactname":,
			"UpdateOrAdd": "Add",
			"ArtifactDetails":{
				"ProcessGuid":"1589170327575",
				"ProcessName":"powershell.exe",
				"ProcessID":"21721",
				"ProcessIntegrityLevel":"",
				"ProcessCurrentDirectory":"",
				"ProcessCommandLine":"powershell -Command $File=\\C:\\Users\\devin\\AppData\\Local\\Temp\\bbotstage.png\\;$Content=get-content $File;$Contento=[System.Text.Encoding]::ASCII.GetString([System.Convert]::FromBase64String($Content));Set-ExecutionPolicy Bypass -Scope Process -Force;IEX($Contento)",
				"ProcessOS":""
			}
      }
    ]
}

401 Unauthorized

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

{"Error": "Invalid authentication key."}

429 TooManyRequests

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

{"Error": "The request exceeds rate limits or is otherwise blocked by rate limiting policies."}

500 InternalServerError

application/json

Response Fields

Field Name	Type	Description
Error	`string`	A error message when the API request fails.

Sample Data

{"Error": "Unexpected Error."}