Digital Shadows v1.0.0

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.