DarkOwl v1.0.0

About the connector

DarkOwl allows you to access the world's largest database of darknet content to monitor for the presence of your data on the darknet and shorten the time frame taken for its detection.

This document provides information about the DarkOwl connector, which facilitates automated interactions, with a DarkOwl server using FortiSOAR™ playbooks. Add the DarkOwl connector as a step in FortiSOAR™ playbooks and perform automated operations, such as submitting a new score request for asynchronous processing to DarkOwl or retrieving the status and result of a completed score request from DarkOwl.

Version information

Connector Version: 1.0.0

Authored By: Fortinet

Certified: No

Installing the connector

From FortiSOAR™ 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 FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-darkowl

Prerequisites to configuring the connector

• You must have the URL of DarkOwl server to which you will connect and perform automated operations.
• You must have the public and private key that is configured for your account to access the DarkOwl server to which you will connect and perform the automated operations.
• 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 DarkOwl 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 DarkOwl server to which you will connect and perform the automated operations.
Public Key	Public key for your account that is issued by a DarkOwl Product Engineer to access the DarkOwl server to which you will connect and perform the automated operations.
Private Key	Private key for your account that is issued by a DarkOwl Product Engineer to access the DarkOwl server to which you will connect and perform the automated operations.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True.

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 FortiSOAR™ release 4.10.0 and onwards:

Function	Description	Annotation and Category
Get Usage Status	Retrieves Vision API usage details for your account from DarkOwl. Details retrieved include the number of valid requests you have made to DarkOwl and your subscription information.	get_usage_status Investigation
Submit score request	Submits new score request for asynchronous processing to DarkOwl, based on the domains and email domains you have specified.	submit_score_request Investigation
Get Score Request Status	Retrieves the status of a submitted score request from DarkOwl, based on the request ID you have specified.	get_score_request_status Investigation
Get Score Request Result	Retrieves the result of a completed score request from DarkOwl, based on the request ID you have specified.	get_score_request_result Investigation
Search Resource	Queries DarkOwl Vision’s DARKNET data collection based on various query parameters and response options you have specified.	search_resource Investigation
Get Document	Retrieves an individual document from DarkOwl Vision, based on the document ID you have specified.	get_document Investigation

operation: Get Usage Status

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"score": {
"subscription": "",
"used": "",
"message": "",
"quota": "",
"end-date": ""
},
"search": {
"subscription": "",
"used": "",
"message": "",
"quota": "",
"end-date": ""
}
}

operation: Submit score request

Input parameters

Parameter	Description
Domains	List of one or more website domains and/or associated subdomains whose score request you want to submit to DarkOwl. For example, domain.com. Note: Wildcards are not allowed.
Email Domains	List of one or more email domains and/or associated subdomains whose score request you want to submit to DarkOwl. Note: Leading wildcards can be used to match multiple subdomains, such as *.domain.com. However, such a pattern must not include the root domain (domain.com).

Output

The output contains the following populated JSON schema:
{
"request_id": ""
}

operation: Get Score Request Status

Input parameters

Parameter	Description
Request ID	Unique identifier of a completed score request whose status you want to retrieve from DarkOwl.

Output

The output contains the following populated JSON schema:
{
"code": "",
"text": "",
"time": ""
}

operation: Get Score Request Result

Input parameters

Parameter	Description
Request ID	Unique identifier of a completed score request whose result you want to retrieve from DarkOwl.

Output

The output contains the following populated JSON schema:z
{
"result": {
"emailDark": "",
"emailPaste": "",
"domainPaste": "",
"emailBreach": "",
"score": "",
"hackishnessDarkPaste": "",
"date": "",
"domainDark": "",
"domainBreach": "",
"hackishnessBreach": ""
},
"request": {
"domains": [],
"emailDomains": []
}
}

operation: Search Resource

Input parameters

Parameter	Description
Query	Specify the query, based on which you want to search a resource in DarkOwl. The query parameter is the base search field which should be used with all searches. This field accepts letters, numbers, special characters, and operators. Wildcards are generally allowed, except for leading wildcards. You can use quotations, parentheses, and booleans. The query parameter determines relevancy. The relevancy score, i.e., how well the result matches the query submitted is determined by the content in the query parameter. Note that filters are not used in the calculation of relevancy.
Crawl date (lower bound)	(Optional) Start datetime from when you want to filter data. This parameter is used to filter to results collected after this datetime (UTC). Input format is in Zulu: YYYY-MM-DDThh:mm:ssZ. Use this parameter in conjunction with the 'Crawl date (upper bound)' parameter to form a range.
Crawl date (upper bound)	(Optional) End datetime till when you want to filter data. This parameter is used to filter to results collected before this datetime (UTC). Input format is in Zulu: YYYY-MM-DDThh:mm:ssZ. Use this parameter in conjunction with the 'Crawl date (lower bound)' parameter to form a range.
Request Data	Select this option to return the request data that was used to run the search, along with the search results. By default, this is checked, i.e., set as True.
Similar	Select this option, i.e., set it to True, to return all similar results, per request. Clearing this option, i.e., set it to False, will remove all similar results, per request. Note: Setting this parameter to False might return fewer documents than the count selected.
Highlight	Select this option, i.e., set it to True, to return highlighted values sent in the query parameter in the body field. By default, this option is cleared, i.e., set as False.
Sort	Field by which you want to sort the results of this operation. You can choose from the following options: Relevancy, Hackishnes, or Date Crawled. By default, this is set to Relevancy.
Detail	Specify the detail level about the result you want to retrieve from DarkOwl. You can choose from the following options: Full, Non Body, or Snippet. By default, this is set to Full.
Has	Select the attribute(s) based on which you want to filter results retrieved from DarkOwl. You can choose the following attributes: CCN, SSN, or Email. Important: If you select any attribute, then you must specify the value of that attribute. For example, if you select CCN, then in the CCN field, you must specify the credit card number that will be searched in the body of the result and accordingly the results will be filtered.
Email Domain	Specify the email domain, whose associated email addresses will be searched in the body of a result, based on which you want to filter results retrieved from DarkOwl. Input format of this parameter is domain.com or subdomain.domain.com, without special characters such as the @ symbol.
Location	Specify the country/countries based on which you want to filter results retrieved from DarkOwl to match only those resources that are registered in certain countries. Country is determined by a geolocation lookup on the target IP (if available). A list of country values is available at darkowl.com/docs/vision-resources. Exclude countries by prefixing their values with a hyphen (-).
Languages	Specify the language(s) based on which you want to filter results retrieved from DarkOwl to match only those resources that match the specified languages. Language is assigned by DarkOwl Vision at the time of ingestion. A list of language values is available at darkowl.com/docs/vision-resources. Exclude languages by prefixing their values with a hyphen (-).
Domain	Specify the domain(s) based on which you want to filter results retrieved from DarkOwl to match only those resources that match the results that are collected from one or more specified domains. Exclude domains by prefixing their values with a hyphen (-).
IP	Specify the IP address based on which you want to filter results retrieved from DarkOwl to match only those resources that match the specified IP address. The IP address that you specify in this parameter is searched in the body of a result. Use this parameter in conjunction with the query parameter and highlight="true" to highlight the IP address in the body of a result. Use quotations around the IP address in the query parameter.
Leak	Specify the data leak or breach based on which you want to filter results retrieved from DarkOwl to match only those resources that match the specified data leak. A list of acceptable leak values is available at darkowl.com/docs/vision-resources. Exclude leaks by prefixing their values with a hyphen (-).
Offset	A maximum of 20 results is returned per request, with maximum pagination of 1000 results returned per query. Offset is used to ‘skip’ a number of results. In this parameter, you can specify any integer between 1 and 980. By default, this value is set as 0.
Count	Specify the number of results returned per request. By default, this is set as 20, which is the maximum number of results allowed per request.
Credit Card Count Range	Range (minimum-maximum) of credit card numbers that should be contained in the results retrieved from DarkOwl. In this parameter, you can specify integer values between 0 and 999999. For example, 0-10000.
Social Security Number Count Range	Range (minimum-maximum) of social security numbers that should be contained in the results retrieved from DarkOwl. In this parameter, you can specify integer values between 0 and 999999.
Email Count Range	Range (minimum-maximum) of email addresses that should be contained in the results retrieved from DarkOwl. In this parameter, you can specify integer values between 0 and 999999.
Hackishness Range	Range (minimum-maximum) of hackishness rating that should be contained in the results retrieved from DarkOwl. In this parameter, you can specify integer values between 0.0 and 1.0. For example, 0.5.

Output

The output contains the following populated JSON schema:
{
"total": "",
"resultCount": "",
"results": [
{
"body": "",
"hackishness": "",
"id": "",
"domain": "",
"country": "",
"headers": [],
"fileSize": "",
"ip": "",
"title": "",
"ccns": [],
"crawlDate": "",
"emails": [],
"ssns": [],
"snippet": "",
"url": ""
}
],
"request": {
"email": [],
"leak": [],
"ssn": [],
"cssn_max": "",
"lang": [],
"emailDomain": [],
"has": [],
"sort": "",
"ip": [],
"offset": "",
"loc": [],
"detail": "",
"cemail_min": "",
"cccn_max": "",
"from": "",
"similar": "",
"hack_min": "",
"domain": [],
"hack_max": "",
"q": "",
"cemail_max": "",
"to": "",
"req": "",
"ccn": [],
"count": "",
"highlight": "",
"cccn_min": "",
"cssn_min": ""
}
}

operation: Get Document

Input parameters

Parameter	Description
Document ID	ID of the document that you want to retrieve from DarkOwl. Note: You can enter letters and numbers as the document identifier.

Output

The output contains the following populated JSON schema:
{
"query": {
"id": ""
},
"result": {
"body": "",
"hackishness": "",
"id": "",
"domain": "",
"country": "",
"headers": [],
"fileSize": "",
"ip": "",
"title": "",
"ccns": [],
"crawlDate": "",
"emails": [],
"ssns": [],
"snippet": "",
"url": ""
}
}

Included playbooks

The Sample - DarkOwl - 1.0.0 playbook collection comes bundled with the DarkOwl 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 DarkOwl connector.

• Get Document
• Get Score Request Status
• Get Score Request Result
• Get Usage Status
• Search Resource
• Submit score request

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 connector upgrade and delete.