Fortinet Document Library

Version:


Table of Contents

Digital Shadows

1.0.0
Copy Link

About the connector

Digital Shadows monitors and manages an organization's digital risk across the widest range of data sources within the open, deep, and dark web.

This document provides information about the Digital Shadows connector, which facilitates automated interactions, with a Digital Shadows server using FortiSOAR™ playbooks. Add the Digital Shadows connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving all or specific data breach records from the Digital Shadows, or searching for records associated with threats in Digital Shadows.

Version information

Connector Version: 1.0.0

Authored By: Community

Certified: No

Installing the connector

From version 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a repository. Therefore, you must set up your repository and run the yum command as a root user to install connectors:

yum install cyops-connector-digital-shadows

Prerequisites to configuring the connector

  • You must have the URL of Digital Shadows server to which you will connect and perform automated operations and the API key and secret to access the Digital Shadows endpoint
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Digital Shadows connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server URL URL of the Digital shadow server to which you will connect and perform automated operations.
API Key API key to access the Digital Shadows REST API endpoint.
Secret Secret to access the Digital Shadows endpoint.
Verify SSL Select this option if you want the SSL certificate of the server to be verified.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from release 4.10.0 and onwards:

Function Description Annotation and Category
Find Breach Records Retrieves all the data breach records of all existing data breaches or specific data breaches from Digital Shadows, based on the input parameters you have specified. find_breach_records
Investigation
Get Data Breach Retrieves information for a specific data breach from Digital Shadows based on the breach ID you have specified. get_breach
Investigation
Get Data Breach Records Retrieves data breach records for data breaches from Digital Shadows, based on the breach ID and other input parameters you have specified. get_breach_records
Investigation
Find Incidents Retrieves details of all incidents from the Digital Shadows or specific incidents from Digital Shadows, based on the input parameters you have specified. find_incidents
Investigation
Get Incident Retrieves information for a specific incident from Digital Shadows based on the incident ID you have specified. get_incident
Investigation
Find Intelligence Incidents Retrieves all the intelligence incidents from Digital Shadows, or specific intelligence incidents from Digital Shadows, based on the input parameters you have specified. find_intelligence_incidents
Investigation
Get Intelligence Incident Retrieves information for a specific intelligence incident from Digital Shadows based on the intelligence incident ID you have specified. get_intelligence_incident
Investigation
Get Intelligence Incident IOCs Retrieves all the intelligence incident IOCs associated with a specific intelligence incident from Digital Shadows, based on the intelligence incident ID you have specified. get_intelligence_incident_iocs
Investigation
Find Intelligence Threats Retrieves all the intelligence threats from Digital Shadows, or specific intelligence threats from Digital Shadows, based on the input parameters you have specified. find_intelligence_threats
Investigation
Get Intelligence Threat Retrieves information for a specific intelligence threat from Digital Shadows based on the threat ID you have specified. get_intelligence_threat
Investigation
Get Intelligence Threat IOCs Retrieves all the intelligence threat IOCs associated with a specific intelligence threat from Digital Shadows, based on the intelligence threat ID you have specified. get_intelligence_threat_iocs
Investigation
Search Records Retrieves records associated with the threats from Digital Shadows, based on the search query and other input parameters you have specified.
Note: The search results include both IOCs from the threat itself and also those present in any APT reports that are associated with the threat.
search_records
Investigation

operation: Find Breach Records

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Domain Name Name of the domains for which you want to retrieve data breach records from Digital Shadows.
Published Date time when the data breach records were published based on which you want to retrieve data breach records from Digital Shadows.
Review Statuses Review Status of the data breach records based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Open, Closed, or Ignored.
Property Property of the data breach record based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Username, Password, or Published.
Direction Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "username": "",
             "contentHighlights": [
                 {
                     "highlightLocations": [
                         {
                             "offset": "",
                             "length": ""
                         }
                     ]
                 }
             ],
             "review": {
                 "status": ""
             },
             "dataBreach": {
                 "externalSource": "",
                 "domainName": "",
                 "incident": {
                     "scope": "",
                     "id": ""
                 },
                 "occurred": "",
                 "published": "",
                 "id": ""
             },
             "domainNames": [],
             "priorRowTextBreachCount": "",
             "id": "",
             "content": "",
             "published": "",
             "priorUsernameBreachCount": ""
         }
     ]
}

operation: Get Data Breach

Input parameters

Parameter Description
Breach ID ID of the breach whose details you want to retrieve from Digital Shadows.
Note: To retrieve breach IDs use the "Find Breach Records" action.

Output

The output contains the following populated JSON schema:
{
     "externalSource": "",
     "title": "",
     "domainName": "",
     "sourceUrl": "",
     "incident": {
         "title": "",
         "type": "",
         "scope": "",
         "severity": "",
         "closedSource": "",
         "id": ""
     },
     "occurred": "",
     "id": "",
     "dataClasses": [],
     "domainCount": "",
     "recordCount": "",
     "modified": ""
}

operation: Get Data Breach Records

Input parameters

Parameter Description
Breach ID ID of the breach whose details you want to retrieve from Digital Shadows.
Note: To retrieve breach IDs, you can use the "Find Breach Records" action
Domain Name (Optional) Name of the domains for which you want to retrieve data breach records from Digital Shadows.
Property (Optional) Property of the data breach record based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Username, Password, or Published.
Published Date time when the data breach records were published based on which you want to retrieve data breach records from Digital Shadows.
Review Statuses (Optional) Review Status of the data breach records based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Open, Closed, or Ignored.
Direction (Optional) Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "username": "",
             "review": {
                 "status": ""
             },
             "priorRowTextBreachCount": "",
             "id": "",
             "published": "",
             "priorUsernameBreachCount": ""
         }
     ]
}

operation: Find Incidents

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Date Range Field Date range of the incident based on which you want to retrieve incidents from Digital Shadows. You can choose from the following options: Verified, Occurred, Modified, or Published.
Domain Selection Domain of the incident based on which you want to retrieve incidents from Digital Shadows. You can choose from the following options:  None, Custom, Internal, or External.
Direction Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Property Property of the incident based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Severity, Verified, Occurred, Published, Modified, or Date.
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "review": {
                 "version": "",
                 "status": "",
                 "created": ""
             },
             "description": "",
             "verified": "",
             "closedSource": "",
             "mitigation": "",
             "internal": "",
             "linkedContentIncidents": [],
             "severity": "",
             "occurred": "",
             "id": "",
             "score": "",
             "subType": "",
             "scope": "",
             "impactDescription": "",
             "tags": [
                 {
                     "name": "",
                     "type": "",
                     "id": ""
                 }
             ],
             "title": "",
             "type": "",
             "entitySummary": {
                 "screenshotId": "",
                 "contentRemoved": "",
                 "type": "",
                 "originalDomains": [],
                 "screenshot": {
                     "link": "",
                     "id": ""
                 },
                 "source": "",
                 "domain": "",
                 "sourceDate": ""
             },
             "takedownRequestCount": "",
             "version": "",
             "modified": "",
             "restrictedContent": "",
             "alerted": "",
             "published": ""
         }
     ]
}

operation: Get Incident

Input parameters

Parameter Description
Incident ID ID of the incident whose details you want to retrieve from Digital Shadows.
Note: To retrieve incident IDs use the "Find Incidents" action.
Full Text (Optional) Select this option to retrieve full-text details of the specified incident from Digital Shadows.

Output

The output contains the following populated JSON schema:
{
     "review": {
         "user": {
             "fullName": "",
             "permissions": [],
             "status": "",
             "id": ""
         },
         "version": "",
         "status": "",
         "created": ""
     },
     "description": "",
     "verified": "",
     "entitySummary": {
         "details": {
             "ipAddress": "",
             "location": {
                 "latitude": "",
                 "countryCode": "",
                 "country": "",
                 "postcode": "",
                 "city": "",
                 "longitude": ""
             },
             "serviceProvider": "",
             "captured": "",
             "assignee": "",
             "autonomousSystemNumber": ""
         },
         "type": "",
         "ports": [
             {
                 "scannedOn": "",
                 "review": {
                     "status": ""
                 },
                 "banner": "",
                 "transport": "",
                 "portNumber": "",
                 "id": ""
             }
         ],
         "source": "",
         "whitelistedPorts": [],
         "associatedDomainNames": [],
         "sourceDate": ""
     },
     "closedSource": "",
     "mitigation": "",
     "internal": "",
     "linkedContentIncidents": [],
     "severity": "",
     "occurred": "",
     "id": "",
     "score": "",
     "subType": "",
     "scope": "",
     "tags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "title": "",
     "type": "",
     "impactDescription": "",
     "takedownRequestCount": "",
     "version": "",
     "modified": "",
     "restrictedContent": "",
     "published": ""
}

operation: Find Intelligence Incidents

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Date Range Field Date range of the intelligence incident based on which you want to retrieve intelligence incidents from Digital Shadows. You can choose from the following options: Verified, Occurred, Modified, or Published.
Domain Selection Domain of the intelligence incident based on which you want to retrieve intelligence incidents from Digital Shadows. You can choose from the following options:  None, Custom, Internal, or External.
Direction Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Property Property of the intelligence incident based on which you want to retrieve intelligence incidents from Digital Shadows. You can choose from the following options: Severity, Verified, Occurred, Modified, Published, or Date.
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "internal": "",
             "score": "",
             "scope": "",
             "verified": "",
             "tags": [
                 {
                     "name": "",
                     "type": "",
                     "id": ""
                 }
             ],
             "linkedContentIncidents": [],
             "closedSource": "",
             "title": "",
             "type": "",
             "version": "",
             "description": "",
             "severity": "",
             "entitySummary": {
                 "source": "",
                 "type": "",
                 "sourceDate": "",
                 "summaryText": "",
                 "domain": ""
             },
             "occurred": "",
             "id": "",
             "indicatorOfCompromiseCount": "",
             "published": "",
             "modified": ""
         }
     ]
}

operation: Get Intelligence Incident

Input parameters

Parameter Description
Intel Incident ID ID of the intelligence incident whose details you want to retrieve from Digital Shadows.
Note: To retrieve intelligence incident IDs use the "Find Intelligence Incidents" action.

Output

The output contains the following populated JSON schema:
{
     "internal": "",
     "score": "",
     "summary": "",
     "scope": "",
     "verified": "",
     "tags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "linkedContentIncidents": [],
     "closedSource": "",
     "title": "",
     "type": "",
     "version": "",
     "description": "",
     "severity": "",
     "entitySummary": {
         "contentRemoved": "",
         "type": "",
         "summaryText": "",
         "source": "",
         "domain": "",
         "sourceDate": ""
     },
     "occurred": "",
     "id": "",
     "restrictedContent": "",
     "indicatorOfCompromiseCount": "",
     "published": "",
     "modified": ""
}

operation: Get Intelligence Incident IOCs

Input parameters

Parameter Description
Intel Incident ID ID of the intelligence incident whose associated IOCs you want to retrieve from Digital Shadows.
Note: To retrieve intelligence incident IDs use the "Find Intelligence Incidents" action
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "intelIncident": {
                 "scope": "",
                 "id": ""
             },
             "lastUpdated": "",
             "type": "",
             "aptReport": {
                 "id": ""
             },
             "source": "",
             "value": "",
             "id": ""
         }
     ]
}

operation: Find Intelligence Threats

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Date Range Field Date range of the intelligence threats based on which you want to retrieve intelligence threats from Digital Shadows. You can choose between Last Active or Modified.
RelevantTo Relevance of the intelligence threats based on which you want to retrieve intelligence threats from Digital Shadows. You can choose between the following options: Any, Organisation, or Industry Sector.
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "lastActive": "",
             "type": "",
             "overviewTags": [
                 {
                     "id": ""
                 }
             ],
             "imageThumbnailId": "",
             "ovewview": "",
             "primaryTag": {
                 "id": ""
             },
             "threatLevel": {
                 "type": ""
             },
             "activityLevel": "",
             "id": ""
         }
     ]
}

operation: Get Intelligence Threat

Input parameters

Parameter Description
Threat ID ID of the threat whose details you want to retrieve from Digital Shadows.
Note: To retrieve threat IDs use the "Find Intelligence Threats" action.

Output

The output contains the following populated JSON schema:
{
     "tacticTags": [
         {
             "name": "",
             "type": "",
             "parent": {
                 "id": ""
             },
             "id": ""
         }
     ],
     "associatedEvents": [],
     "associatedActorTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "targetGeographyTags": [
         {
             "name": "",
             "type": "",
             "parent": {
                 "id": ""
             },
             "id": ""
         }
     ],
     "sourceGeographyTags": [
         {
             "name": "",
             "type": "",
             "parent": {
                 "id": ""
             },
             "id": ""
         }
     ],
     "overview": "",
     "motivationTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "activityLevel": "",
     "lastActive": "",
     "associatedLocations": [
         {
             "type": "",
             "primaryTag": {
                 "name": "",
                 "type": "",
                 "id": ""
             },
             "activityLevel": "",
             "id": ""
         }
     ],
     "imageThumbnailId": "",
     "identifiers": [],
     "primaryTag": {
         "name": "",
         "type": "",
         "id": ""
     },
     "imageId": "",
     "overviewTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "id": "",
     "detailLevel": "",
     "summary": "",
     "primaryLanguageTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "associatedCampaignTags": [],
     "aptReports": [
         {
             "id": ""
         }
     ],
     "attackIncidents": [],
     "intendedEffectTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "sites": [],
     "type": "",
     "knownMembers": [],
     "targetSectorTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "specifiedTargetTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "impactEffectTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "tacticDescription": "",
     "threatLevel": {
         "reason": "",
         "type": ""
     },
     "actorTypeTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "indicatorOfCompromiseCount": ""
}

operation: Get Intelligence Threat IOCs

Input parameters

Parameter Description
Threat ID ID of the threat whose associated IOCs you want to retrieve from Digital Shadows.
Note: To retrieve threat IDs use the "Find Intelligence Threats" action.
Types (Optional) Type of the threat whose associated threat IOCs you want to retrieve from Digital Shadows. You can choose from the following options: IP, IPv4, IPv6, MD5, SHA1, SHA256, URL, CVE, EMAIL, HOST, REGISTRY, FILEPATH, or FILENAME.
Direction (Optional) Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Property (Optional) Property of the threat whose associated threat IOCs you want to retrieve from Digital Shadows. You can choose from the following options: Value, Type, Updated, or Source.
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "data": {
         "currentPage": {
             "offset": "",
             "size": ""
         },
         "total": "",
         "content": [
             {
                 "aptReport": {
                     "id": ""
                 },
                 "type": "",
                 "value": "",
                 "id": ""
             }
         ]
     }
}

operation: Search Records

Input parameters

Parameter Description
Search Query Search query using which you want to retrieve records associated with threats from Digital Shadows. For example, zjvz.pw
Types (Optional) Type of the threat whose associated records you want to retrieve from Digital Shadows. You can choose options such as: ACTORS, AGGREGATE_DATA_BREACH, BLOG_POST, CAMPAIGNS, CHAT_MESSAGE, CLIENT_INCIDENT, CLOSED_SOURCES, DATA_BREACH, DOMAIN_WHOIS, DNS_LOOKUP, EVENT, FORUM_POST, INCIDENTS, INTEL_INCIDENT, INTELLIGENCE, LOCATION, INDICATOR_FEED, etc.
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:

Output schema if 'Types' is ''
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "entity": {},
             "type": ""
         }
     ],
     "facets": {}
}
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "entity": {
                 "lastActive": "",
                 "summary": "",
                 "type": "",
                 "overviewTags": [
                     {
                         "name": "",
                         "type": "",
                         "id": ""
                     }
                 ],
                 "imageThumbnailId": "",
                 "overview": "",
                 "primaryTag": {
                     "name": "",
                     "type": "",
                     "id": ""
                 },
                 "threatLevel": {
                     "reason": "",
                     "type": ""
                 },
                 "activityLevel": "",
                 "id": ""
             },
             "type": "",
             "sortDate": "",
             "snippet": ""
         }
     ],
     "facets": {}
}

Included playbooks

The Sample - Digital Shadows - 1.0.0 playbook collection comes bundled with the Digital Shadows connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Digital Shadows connector.

  • Find Breach Records
  • Find Incidents
  • Find Intelligence Incidents
  • Find Intelligence Threats
  • Get Breach
  • Get Breach Records
  • Get Incident
  • Get Intelligence Incident IOCs
  • Get Intelligence Incidents
  • Get Intelligence Threat
  • Get Intelligence Threat IOCs
  • Search Records

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

About the connector

Digital Shadows monitors and manages an organization's digital risk across the widest range of data sources within the open, deep, and dark web.

This document provides information about the Digital Shadows connector, which facilitates automated interactions, with a Digital Shadows server using FortiSOAR™ playbooks. Add the Digital Shadows connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving all or specific data breach records from the Digital Shadows, or searching for records associated with threats in Digital Shadows.

Version information

Connector Version: 1.0.0

Authored By: Community

Certified: No

Installing the connector

From version 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a repository. Therefore, you must set up your repository and run the yum command as a root user to install connectors:

yum install cyops-connector-digital-shadows

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Digital Shadows connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server URL URL of the Digital shadow server to which you will connect and perform automated operations.
API Key API key to access the Digital Shadows REST API endpoint.
Secret Secret to access the Digital Shadows endpoint.
Verify SSL Select this option if you want the SSL certificate of the server to be verified.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from release 4.10.0 and onwards:

Function Description Annotation and Category
Find Breach Records Retrieves all the data breach records of all existing data breaches or specific data breaches from Digital Shadows, based on the input parameters you have specified. find_breach_records
Investigation
Get Data Breach Retrieves information for a specific data breach from Digital Shadows based on the breach ID you have specified. get_breach
Investigation
Get Data Breach Records Retrieves data breach records for data breaches from Digital Shadows, based on the breach ID and other input parameters you have specified. get_breach_records
Investigation
Find Incidents Retrieves details of all incidents from the Digital Shadows or specific incidents from Digital Shadows, based on the input parameters you have specified. find_incidents
Investigation
Get Incident Retrieves information for a specific incident from Digital Shadows based on the incident ID you have specified. get_incident
Investigation
Find Intelligence Incidents Retrieves all the intelligence incidents from Digital Shadows, or specific intelligence incidents from Digital Shadows, based on the input parameters you have specified. find_intelligence_incidents
Investigation
Get Intelligence Incident Retrieves information for a specific intelligence incident from Digital Shadows based on the intelligence incident ID you have specified. get_intelligence_incident
Investigation
Get Intelligence Incident IOCs Retrieves all the intelligence incident IOCs associated with a specific intelligence incident from Digital Shadows, based on the intelligence incident ID you have specified. get_intelligence_incident_iocs
Investigation
Find Intelligence Threats Retrieves all the intelligence threats from Digital Shadows, or specific intelligence threats from Digital Shadows, based on the input parameters you have specified. find_intelligence_threats
Investigation
Get Intelligence Threat Retrieves information for a specific intelligence threat from Digital Shadows based on the threat ID you have specified. get_intelligence_threat
Investigation
Get Intelligence Threat IOCs Retrieves all the intelligence threat IOCs associated with a specific intelligence threat from Digital Shadows, based on the intelligence threat ID you have specified. get_intelligence_threat_iocs
Investigation
Search Records Retrieves records associated with the threats from Digital Shadows, based on the search query and other input parameters you have specified.
Note: The search results include both IOCs from the threat itself and also those present in any APT reports that are associated with the threat.
search_records
Investigation

operation: Find Breach Records

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Domain Name Name of the domains for which you want to retrieve data breach records from Digital Shadows.
Published Date time when the data breach records were published based on which you want to retrieve data breach records from Digital Shadows.
Review Statuses Review Status of the data breach records based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Open, Closed, or Ignored.
Property Property of the data breach record based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Username, Password, or Published.
Direction Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "username": "",
             "contentHighlights": [
                 {
                     "highlightLocations": [
                         {
                             "offset": "",
                             "length": ""
                         }
                     ]
                 }
             ],
             "review": {
                 "status": ""
             },
             "dataBreach": {
                 "externalSource": "",
                 "domainName": "",
                 "incident": {
                     "scope": "",
                     "id": ""
                 },
                 "occurred": "",
                 "published": "",
                 "id": ""
             },
             "domainNames": [],
             "priorRowTextBreachCount": "",
             "id": "",
             "content": "",
             "published": "",
             "priorUsernameBreachCount": ""
         }
     ]
}

operation: Get Data Breach

Input parameters

Parameter Description
Breach ID ID of the breach whose details you want to retrieve from Digital Shadows.
Note: To retrieve breach IDs use the "Find Breach Records" action.

Output

The output contains the following populated JSON schema:
{
     "externalSource": "",
     "title": "",
     "domainName": "",
     "sourceUrl": "",
     "incident": {
         "title": "",
         "type": "",
         "scope": "",
         "severity": "",
         "closedSource": "",
         "id": ""
     },
     "occurred": "",
     "id": "",
     "dataClasses": [],
     "domainCount": "",
     "recordCount": "",
     "modified": ""
}

operation: Get Data Breach Records

Input parameters

Parameter Description
Breach ID ID of the breach whose details you want to retrieve from Digital Shadows.
Note: To retrieve breach IDs, you can use the "Find Breach Records" action
Domain Name (Optional) Name of the domains for which you want to retrieve data breach records from Digital Shadows.
Property (Optional) Property of the data breach record based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Username, Password, or Published.
Published Date time when the data breach records were published based on which you want to retrieve data breach records from Digital Shadows.
Review Statuses (Optional) Review Status of the data breach records based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Open, Closed, or Ignored.
Direction (Optional) Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "username": "",
             "review": {
                 "status": ""
             },
             "priorRowTextBreachCount": "",
             "id": "",
             "published": "",
             "priorUsernameBreachCount": ""
         }
     ]
}

operation: Find Incidents

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Date Range Field Date range of the incident based on which you want to retrieve incidents from Digital Shadows. You can choose from the following options: Verified, Occurred, Modified, or Published.
Domain Selection Domain of the incident based on which you want to retrieve incidents from Digital Shadows. You can choose from the following options:  None, Custom, Internal, or External.
Direction Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Property Property of the incident based on which you want to retrieve data breach records from Digital Shadows. You can choose from the following options: Severity, Verified, Occurred, Published, Modified, or Date.
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "review": {
                 "version": "",
                 "status": "",
                 "created": ""
             },
             "description": "",
             "verified": "",
             "closedSource": "",
             "mitigation": "",
             "internal": "",
             "linkedContentIncidents": [],
             "severity": "",
             "occurred": "",
             "id": "",
             "score": "",
             "subType": "",
             "scope": "",
             "impactDescription": "",
             "tags": [
                 {
                     "name": "",
                     "type": "",
                     "id": ""
                 }
             ],
             "title": "",
             "type": "",
             "entitySummary": {
                 "screenshotId": "",
                 "contentRemoved": "",
                 "type": "",
                 "originalDomains": [],
                 "screenshot": {
                     "link": "",
                     "id": ""
                 },
                 "source": "",
                 "domain": "",
                 "sourceDate": ""
             },
             "takedownRequestCount": "",
             "version": "",
             "modified": "",
             "restrictedContent": "",
             "alerted": "",
             "published": ""
         }
     ]
}

operation: Get Incident

Input parameters

Parameter Description
Incident ID ID of the incident whose details you want to retrieve from Digital Shadows.
Note: To retrieve incident IDs use the "Find Incidents" action.
Full Text (Optional) Select this option to retrieve full-text details of the specified incident from Digital Shadows.

Output

The output contains the following populated JSON schema:
{
     "review": {
         "user": {
             "fullName": "",
             "permissions": [],
             "status": "",
             "id": ""
         },
         "version": "",
         "status": "",
         "created": ""
     },
     "description": "",
     "verified": "",
     "entitySummary": {
         "details": {
             "ipAddress": "",
             "location": {
                 "latitude": "",
                 "countryCode": "",
                 "country": "",
                 "postcode": "",
                 "city": "",
                 "longitude": ""
             },
             "serviceProvider": "",
             "captured": "",
             "assignee": "",
             "autonomousSystemNumber": ""
         },
         "type": "",
         "ports": [
             {
                 "scannedOn": "",
                 "review": {
                     "status": ""
                 },
                 "banner": "",
                 "transport": "",
                 "portNumber": "",
                 "id": ""
             }
         ],
         "source": "",
         "whitelistedPorts": [],
         "associatedDomainNames": [],
         "sourceDate": ""
     },
     "closedSource": "",
     "mitigation": "",
     "internal": "",
     "linkedContentIncidents": [],
     "severity": "",
     "occurred": "",
     "id": "",
     "score": "",
     "subType": "",
     "scope": "",
     "tags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "title": "",
     "type": "",
     "impactDescription": "",
     "takedownRequestCount": "",
     "version": "",
     "modified": "",
     "restrictedContent": "",
     "published": ""
}

operation: Find Intelligence Incidents

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Date Range Field Date range of the intelligence incident based on which you want to retrieve intelligence incidents from Digital Shadows. You can choose from the following options: Verified, Occurred, Modified, or Published.
Domain Selection Domain of the intelligence incident based on which you want to retrieve intelligence incidents from Digital Shadows. You can choose from the following options:  None, Custom, Internal, or External.
Direction Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Property Property of the intelligence incident based on which you want to retrieve intelligence incidents from Digital Shadows. You can choose from the following options: Severity, Verified, Occurred, Modified, Published, or Date.
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "internal": "",
             "score": "",
             "scope": "",
             "verified": "",
             "tags": [
                 {
                     "name": "",
                     "type": "",
                     "id": ""
                 }
             ],
             "linkedContentIncidents": [],
             "closedSource": "",
             "title": "",
             "type": "",
             "version": "",
             "description": "",
             "severity": "",
             "entitySummary": {
                 "source": "",
                 "type": "",
                 "sourceDate": "",
                 "summaryText": "",
                 "domain": ""
             },
             "occurred": "",
             "id": "",
             "indicatorOfCompromiseCount": "",
             "published": "",
             "modified": ""
         }
     ]
}

operation: Get Intelligence Incident

Input parameters

Parameter Description
Intel Incident ID ID of the intelligence incident whose details you want to retrieve from Digital Shadows.
Note: To retrieve intelligence incident IDs use the "Find Intelligence Incidents" action.

Output

The output contains the following populated JSON schema:
{
     "internal": "",
     "score": "",
     "summary": "",
     "scope": "",
     "verified": "",
     "tags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "linkedContentIncidents": [],
     "closedSource": "",
     "title": "",
     "type": "",
     "version": "",
     "description": "",
     "severity": "",
     "entitySummary": {
         "contentRemoved": "",
         "type": "",
         "summaryText": "",
         "source": "",
         "domain": "",
         "sourceDate": ""
     },
     "occurred": "",
     "id": "",
     "restrictedContent": "",
     "indicatorOfCompromiseCount": "",
     "published": "",
     "modified": ""
}

operation: Get Intelligence Incident IOCs

Input parameters

Parameter Description
Intel Incident ID ID of the intelligence incident whose associated IOCs you want to retrieve from Digital Shadows.
Note: To retrieve intelligence incident IDs use the "Find Intelligence Incidents" action
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "intelIncident": {
                 "scope": "",
                 "id": ""
             },
             "lastUpdated": "",
             "type": "",
             "aptReport": {
                 "id": ""
             },
             "source": "",
             "value": "",
             "id": ""
         }
     ]
}

operation: Find Intelligence Threats

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Date Range Field Date range of the intelligence threats based on which you want to retrieve intelligence threats from Digital Shadows. You can choose between Last Active or Modified.
RelevantTo Relevance of the intelligence threats based on which you want to retrieve intelligence threats from Digital Shadows. You can choose between the following options: Any, Organisation, or Industry Sector.
Size Maximum number of results, per page, that this operation should return.
Offset Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "lastActive": "",
             "type": "",
             "overviewTags": [
                 {
                     "id": ""
                 }
             ],
             "imageThumbnailId": "",
             "ovewview": "",
             "primaryTag": {
                 "id": ""
             },
             "threatLevel": {
                 "type": ""
             },
             "activityLevel": "",
             "id": ""
         }
     ]
}

operation: Get Intelligence Threat

Input parameters

Parameter Description
Threat ID ID of the threat whose details you want to retrieve from Digital Shadows.
Note: To retrieve threat IDs use the "Find Intelligence Threats" action.

Output

The output contains the following populated JSON schema:
{
     "tacticTags": [
         {
             "name": "",
             "type": "",
             "parent": {
                 "id": ""
             },
             "id": ""
         }
     ],
     "associatedEvents": [],
     "associatedActorTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "targetGeographyTags": [
         {
             "name": "",
             "type": "",
             "parent": {
                 "id": ""
             },
             "id": ""
         }
     ],
     "sourceGeographyTags": [
         {
             "name": "",
             "type": "",
             "parent": {
                 "id": ""
             },
             "id": ""
         }
     ],
     "overview": "",
     "motivationTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "activityLevel": "",
     "lastActive": "",
     "associatedLocations": [
         {
             "type": "",
             "primaryTag": {
                 "name": "",
                 "type": "",
                 "id": ""
             },
             "activityLevel": "",
             "id": ""
         }
     ],
     "imageThumbnailId": "",
     "identifiers": [],
     "primaryTag": {
         "name": "",
         "type": "",
         "id": ""
     },
     "imageId": "",
     "overviewTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "id": "",
     "detailLevel": "",
     "summary": "",
     "primaryLanguageTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "associatedCampaignTags": [],
     "aptReports": [
         {
             "id": ""
         }
     ],
     "attackIncidents": [],
     "intendedEffectTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "sites": [],
     "type": "",
     "knownMembers": [],
     "targetSectorTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "specifiedTargetTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "impactEffectTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "tacticDescription": "",
     "threatLevel": {
         "reason": "",
         "type": ""
     },
     "actorTypeTags": [
         {
             "name": "",
             "type": "",
             "id": ""
         }
     ],
     "indicatorOfCompromiseCount": ""
}

operation: Get Intelligence Threat IOCs

Input parameters

Parameter Description
Threat ID ID of the threat whose associated IOCs you want to retrieve from Digital Shadows.
Note: To retrieve threat IDs use the "Find Intelligence Threats" action.
Types (Optional) Type of the threat whose associated threat IOCs you want to retrieve from Digital Shadows. You can choose from the following options: IP, IPv4, IPv6, MD5, SHA1, SHA256, URL, CVE, EMAIL, HOST, REGISTRY, FILEPATH, or FILENAME.
Direction (Optional) Order in which you want to sort the results (breach records) retrieved from Digital Shadows. You can choose between Ascending or Descending. By default, the sort order is set to "Ascending".
Property (Optional) Property of the threat whose associated threat IOCs you want to retrieve from Digital Shadows. You can choose from the following options: Value, Type, Updated, or Source.
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:
{
     "data": {
         "currentPage": {
             "offset": "",
             "size": ""
         },
         "total": "",
         "content": [
             {
                 "aptReport": {
                     "id": ""
                 },
                 "type": "",
                 "value": "",
                 "id": ""
             }
         ]
     }
}

operation: Search Records

Input parameters

Parameter Description
Search Query Search query using which you want to retrieve records associated with threats from Digital Shadows. For example, zjvz.pw
Types (Optional) Type of the threat whose associated records you want to retrieve from Digital Shadows. You can choose options such as: ACTORS, AGGREGATE_DATA_BREACH, BLOG_POST, CAMPAIGNS, CHAT_MESSAGE, CLIENT_INCIDENT, CLOSED_SOURCES, DATA_BREACH, DOMAIN_WHOIS, DNS_LOOKUP, EVENT, FORUM_POST, INCIDENTS, INTEL_INCIDENT, INTELLIGENCE, LOCATION, INDICATOR_FEED, etc.
Size (Optional) Maximum number of results, per page, that this operation should return.
Offset (Optional) Include results at this offset within the full result set, where the first result is at position 0.

Output

The output contains the following populated JSON schema:

Output schema if 'Types' is ''
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "entity": {},
             "type": ""
         }
     ],
     "facets": {}
}
{
     "currentPage": {
         "offset": "",
         "size": ""
     },
     "total": "",
     "content": [
         {
             "entity": {
                 "lastActive": "",
                 "summary": "",
                 "type": "",
                 "overviewTags": [
                     {
                         "name": "",
                         "type": "",
                         "id": ""
                     }
                 ],
                 "imageThumbnailId": "",
                 "overview": "",
                 "primaryTag": {
                     "name": "",
                     "type": "",
                     "id": ""
                 },
                 "threatLevel": {
                     "reason": "",
                     "type": ""
                 },
                 "activityLevel": "",
                 "id": ""
             },
             "type": "",
             "sortDate": "",
             "snippet": ""
         }
     ],
     "facets": {}
}

Included playbooks

The Sample - Digital Shadows - 1.0.0 playbook collection comes bundled with the Digital Shadows connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Digital Shadows connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.