Awake Security
This Integration is part of the Awake Security Pack.#
Overview
Use the Awake Security integration to manage and respond to network threats.
Configure Awake Security on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services .
- Search for Awake Security.
-
Click
Add instance
to create and configure a new integration instance.
- Name : a textual name for the integration instance.
- Credentials
- Awake Security server address
- Trust any certificate (not secure)
- Fetch incidents
- Incident type
- Use system proxy settings
- Comma-separated list of threat behaviors to generate incidents for, e.g., "Exfiltration: SSL upload from non-browser to notable domain, Lateral Movement: Unix-based PSEXEC, C2: Possible ICMP tunnel"
- Period between incident fetch interval (in minutes)
- Minimum threshold to determine an indicator suspicious in Cortex XSOAR
- Minimum threshold to determine an indicator malicious in Cortex XSOAR
- Click Test to validate the URLs, token, and connection.
Commands
You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.
- Query devices: awake-query-devices
- Query activities: awake-query-activities
- Query domains: awake-query-domains
- Download a PCAP: awake-pcap-download
- Lookup and enrich a domain: domain
- Lookup and enrich an IP address: ip
- Lookup and enrich an email address: email
- Lookup and enrich a device: device
1. Query devices
Query devices in Awake Security.
Base Command
awake-query-devices
Input
| Argument Name | Description | Required |
|---|---|---|
| queryExpression | A query expression in Awake Query Language | Optional |
| startTime | Query start time ("2000-01-01T00:00:00Z") | Required |
| endTime | Query end time ("2000-01-01T00:00:00Z") | Required |
| ipAddress | IP address to filter by (exact match) | Optional |
| deviceName | Device name to filter by (regular expression) | Optional |
| domainName | Domain name to filter by (regular expression) | Optional |
| protocol | Protocol to filter by (all uppercase, i.e. "TLS") | Optional |
| tag | Tag to filter by (regular expression) | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AwakeSecurity.Devices.deviceId | string | Awake Security unique identifier for the specified device |
| AwakeSecurity.Devices.deviceName | string | Device name |
| AwakeSecurity.Devices.firstSeen | string | Date that the specified device was first seen |
| AwakeSecurity.Devices.lastSeen | string | Date that the specified device was last seen |
| AwakeSecurity.Devices.os | string | Operating system associated with the specified device |
| AwakeSecurity.Devices.deviceType | string | Device type |
| AwakeSecurity.Devices.ips | unknown | List of IP addresses associated with the specified device |
| AwakeSecurity.Devices.monitoringPointIds | string | List of monitoring point IDs the specified device was seen on |
| AwakeSecurity.Devices.application | string | List of applications the specified device was seen using |
| AwakeSecurity.Devices.notabilityPercentile | number | How the notability of this device compares to other devices |
| AwakeSecurity.Devices.numberSimilarDevices | number | Number of devices that are similar to this device |
| AwakeSecurity.Devices.numberSessions | number | Number of TCP sessions for this device |
| AwakeSecurity.Devices.ackTime | number | Date of the last TCP session acknowledgment of the device associated with the specified email address |
| AwakeSecurity.Devices.whiteListed | bool | Is the device associated with the specified email address in the allow list |
Command Example
!awake-query-devices startTime="2018-07-18T07:00:00Z" endTime="2018-07-18T07:30:00Z"
Human Readable Output
2. Query activities
Query activities in Awake Security
Base Command
awake-query-activities
Input
| Argument Name | Description | Required |
|---|---|---|
| queryExpression | A query expression in the Awake Query Language | Optional |
| startTime | Query start time ("2000-01-01T00:00:00Z") | Required |
| endTime | Query end time ("2000-01-01T00:00:00Z") | Required |
| ipAddress | IP address to filter by (exact match) | Optional |
| deviceName | Device name to filter by (regular expression) | Optional |
| domainName | Domain name to filter by (regular expression) | Optional |
| protocol | Protocol to filter by (all uppercase, e.g., "TLS") | Optional |
| tag | Tag to filter by (regular expression) | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AwakeSecurity.Activities.activityId | string | UUID that uniquely identifies the activity |
| AwakeSecurity.Activities.sessionId | string | UUID that uniquely identifies the corresponding session |
| AwakeSecurity.Activities.sourceIP | string | IP address of the source |
| AwakeSecurity.Activities.sourceHost | string | Hostname of the source |
| AwakeSecurity.Activities.sourcePort | number | Port of the source |
| AwakeSecurity.Activities.destinationIP | string | IP address of the destination |
| AwakeSecurity.Activities.destinationHost | string | Hostname of the destination |
| AwakeSecurity.Activities.destinationPort | number | Port of the destination |
| AwakeSecurity.Activities.directionKnown | bool | Do we know for sure which endpoint was the client? |
| AwakeSecurity.Activities.activityDeviceName | string | Device name for the endpoint within your network |
| AwakeSecurity.Activities.activityStart | string | Date when the activity began |
| AwakeSecurity.Activities.activityEnd | string | Date when the activity ended |
| AwakeSecurity.Activities.protocols | string | Protocols that the activity used |
Command Example
!awake-query-activities startTime="2018-07-01T00:00:00Z" endTime="2018-08-01T00:00:00Z" domainName="kck.st"
Human Readable Output
3. Query domains
Query domains in Awake Security
Base Command
awake-query-domains
Input
| Argument Name | Description | Required |
|---|---|---|
| queryExpression | A query expression in the Awake Query Language | Optional |
| startTime | Query start time ("2000-01-01T00:00:00Z") | Required |
| endTime | Query end time ("2000-01-01T00:00:00Z") | Required |
| ipAddress | IP address to filter by (exact match) | Optional |
| deviceName | Device name to filter by (regular expression) | Optional |
| domainName | Domain name to filter by (regular expression) | Optional |
| protocol | Protocol to filter by (all uppercase, e.g., "TLS") | Optional |
| tag | Tag to filter by (regular expression) | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AwakeSecurity.Domains.name | string | Domain name |
| AwakeSecurity.Domains.created | string | Date the specified domain was created |
| AwakeSecurity.Domains.lastUpdated | string | Date the specified domain was last updated |
| AwakeSecurity.Domains.registrantOrg | string | Organization of the registrant |
| AwakeSecurity.Domains.registrantCountry | string | Country of the registrant |
| AwakeSecurity.Domains.registrarName | string | Name of the registrar |
| AwakeSecurity.Domains.whoisServer | string | Address of the WHOIS server |
| AwakeSecurity.Domains.whoisFound | bool | Was this domain found via WHOIS |
| AwakeSecurity.Domains.deviceCount | number | Number of devices currently interacting with the specified domain |
| AwakeSecurity.Domains.totalDevices | number | Total number of devices that have interacted with the specified domain |
| AwakeSecurity.Domains.intelCount | number | Number of matches of imported intel against the specified domain |
| AwakeSecurity.Domains.lastSeen | number | Date of the most recent interaction with the specified domain |
| AwakeSecurity.Domains.nameservers | string | List of authoritative nameservers for the specified domain |
| AwakeSecurity.Domains.notability | number | Notability score of the domain |
| AwakeSecurity.Domains.whiteListed | bool | Is the specified domain in allow list |
Command Example
!awake-query-domains startTime="2018-07-18T07:00:00Z" endTime="2018-07-18T07:30:00Z"
Human Readable Output
4. Download a PCAP
Download a PCAP.
Base Command
awake-pcap-download
Input
| Argument Name | Description | Required |
|---|---|---|
| protocol | Protocol to filter by (all uppercase, e.g., "TLS") | Optional |
| hostA | First host's address | Optional |
| portA | First host's port | Optional |
| hostB | Second host's address | Optional |
| portB | Second host's port | Optional |
| startTime | Query start time ("2000-01-01T00:00:00Z") | Optional |
| endTime | Query end time ("2000-01-01T00:00:00Z") | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| File.Size | number | File size |
| File.MD5 | string | MD5 of the file |
| File.SHA1 | string | SHA-1 of the file |
| File.SHA256 | string | SHA-256 of the file |
| File.Name | string | File name |
| File.SSDeep | string | SSDeep hash of the file |
| File.EntryID | string | War Room Entry ID of the file |
| File.Info | string | File common metadata |
| File.Type | string | File type |
| File.Extension | string | File Extension e.g., "pcap" |
Command Example
!awake-pcap-download hostA="10.200.103.100" hostB="10.200.103.100" portA="67" portB="68"
Human Readable Output
5. Lookup and enrich a domain
Lookup and enrich a domain.
Base Command
domain
Input
| Argument Name | Description | Required |
|---|---|---|
| domain | The domain name | Required |
| lookback_minutes | How many minutes of history to query from the current time. Default is 480. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AwakeSecurity.Domains.approxBytesTransferred | number | Approximate bytes the indicator transferred |
| AwakeSecurity.Domains.DomainWithSameRegistrant | unknown | Domains with the same registrant |
| AwakeSecurity.Domains.domainsWithSameRegistrant.registrationDate | string | Date that the domain with the same registrant as the specified domain was registered |
| AwakeSecurity.Domains.IntelSources | string | Indicators of compromise from Awake Security |
| AwakeSecurity.Domains.ipAddresses | string | IP addresses associated with the domain |
| AwakeSecurity.Domains.isAlexaTopOneMillion | string | Does the domain appear in Alexa 1 million list |
| AwakeSecurity.Domains.isDGA | boolean | Is domain generation algorithm |
| AwakeSecurity.Domains.lastSeen | string | Last time the domain was seen |
| AwakeSecurity.Domains.notabillity | number | Notability score of the domain |
| AwakeSecurity.Domains.numAssociatedActivities | number | Number of network activities associated with the domain |
| AwakeSecurity.Domains.numAssociatedADevices | number | Number of devices associated with the domain |
| AwakeSecurity.Domains.protocols | string | List of protocols used in the domain activities |
| AwakeSecurity.Domains.relatedSubdomains | string | Related subdomains of the specified domain |
| AwakeSecurity.Domains.subdomains | string | Subdomains of the specified domain |
| AwakeSecurity.Domains.topDevices | string | List of devices that accessed the specified domain (maximum is 10) |
| AwakeSecurity.Domains.totalNumDevices | number | Total number of devices that accessed the specified domain |
| AwakeSecurity.Domains.whiteListed | boolean | Is the specified domain in allow list |
| DBotScore.Indicator | string | The specified domain |
| DBotScore.Score | number | Severity score of the specified domain in Cortex XSOAR |
| DBotScore.Type | string | Indicator type in Cortex XSOAR |
| DBotScore.Vendor | string | Vendor used to assess the specified domain |
Command Example
!domain domain="adobesc.com"
Human Readable Output
6. Lookup and enrich an IP address
Lookup and enrich an IP address.
Base Command
ip
Input
| Argument Name | Description | Required |
|---|---|---|
| ip | The IP address | Required |
| lookback_minutes | How many minutes of history to query from the current time. Default is 480. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AwakeSecurity.IPs.activityCount | number | Number of activities associated with the specified IP address |
| AwakeSecurity.IPs.deviceCount | number | Number of devices associated with the specified IP address |
| AwakeSecurity.IPs.devices | unknown | Device object associated with the specified IP address |
| AwakeSecurity.IPs.domains | unknown | Domain object associated with the specified IP address |
| AwakeSecurity.IPs.ipFirstSeen | string | Date that the IP address was first seen in Awake Security |
| AwakeSecurity.IPs.ipLastSeen | string | Date that the IP address was last seen in Awake Security |
| DBotScore.Indicator | string | The specified IP address |
| DBotScore.Score | number | Severity score of the specified IP address in Cortex XSOAR |
| DBotScore.Vendor | string | Vendor used to assess the specified IP address |
| DBotScore.Type | string | Indicator type in Cortex XSOAR |
Command Example
!ip ip="10.200.104.236"
Human Readable Output
7. Lookup and enrich and enrich an email address
Lookup and enrich an email address.
Base Command
email
Input
| Argument Name | Description | Required |
|---|---|---|
| The email address | Optional | |
| lookback_minutes | How many minutes of history to query from the current time. Default is 480. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AwakeSecurity.Emails.deviceId | string | Device ID associated with the specified email address |
| AwakeSecurity.Emails.deviceName | string | Device name associated with the specified email address |
| AwakeSecurity.Emails.firstSeen | string | Date that the email address was first seen in Awake Security |
| AwakeSecurity.Emails.lastSeen | string | Date that the email address was last seen in Awake Security |
| AwakeSecurity.Emails.duration | string | Time (in seconds) between the email address first seen date and last seen date in Awake Security |
| AwakeSecurity.Emails.os | string | Operating system of the device associated with the specified email address |
| AwakeSecurity.Emails.deviceType | string | Device type associated with the specified email address |
| AwakeSecurity.Emails.ips | string | IP addresses that the device associated with the specified email address accessed |
| AwakeSecurity.Emails.monitoringPointIds | string | Monitoring point IDs on which the device associated with the specified email address were seen |
| AwakeSecurity.Emails.application | string | Email applications associated with this email address |
| AwakeSecurity.Emails.notabilityPercentile | number | Notability (risk score) of the specified email address |
| AwakeSecurity.Emails.numberSimilarDevices | number | Number of similar devices associated with the device of the specified email addresses |
| AwakeSecurity.Emails.numberSessions | number | Number of TCP sessions the device associated with this email address initiated |
| AwakeSecurity.Emails.ackTime | string | Date of the last TCP session acknowledgment of the device associated with the specified email address |
| AwakeSecurity.Emails.whiteListed | bool | Is the device associated with the specified email address in the allow list |
| DBotScore.Score | number | Severity score of the specified email address in Cortex XSOAR |
| DBotScore.Type | string | Indicator type in Cortex XSOAR |
| DBotScore.Vendor | string | Vendor used to assess the specified email address |
| DBotScore.Indicator | string | The specified email address |
Command Example
!email email="rajguru2003@yahoo.com"
Human Readable Output
8. Lookup and enrich a device
Lookup and enrich a device.
Base Command
device
Input
| Argument Name | Description | Required |
|---|---|---|
| device | The device ID | Required |
| lookback_minutes | How many minutes of history to query from the current time. Default is 480. | Optional |
Context Output
| Path | Type | Description |
|---|---|---|
| AwakeSecurity.Devices.deviceScore | number | Risk score of the specified device |
| AwakeSecurity.Devices.notableDomainCount.value | number | Number of suspicious domains accessed by the specified device |
| AwakeSecurity.Devices.notableDomainCount.percentile | number | Percentile of the specified device for notable domains accessed |
| AwakeSecurity.Devices.notableDomainCount.weight | number | Importance given to the suspicious domains when calculating the specified device risk score |
| AwakeSecurity.Devices.iocCount.value | number | Number of suspicious IOCs associated with the specified device |
| AwakeSecurity.Devices.iocCount.percentile | number | Percentile of the specified device for notable IOCs |
| AwakeSecurity.Devices.iocCount.weight | number | Importance given to the IOCs when calculating the specified device risk score |
| AwakeSecurity.Devices.watchlistCount.value | number | Total number of current threat behaviors associated with the specified device |
| AwakeSecurity.Devices.watchlistCount.percentile | number | How this device compares to other devices for number of threat behaviors |
| AwakeSecurity.Devices.watchlistCount.weight | number | Importance given to the threat behaviors when calculating the specified device risk score |
| AwakeSecurity.Devices.activityCount.value | number | Number of characteristic artifacts associated with the specified device |
| AwakeSecurity.Devices.activityCount.percentile | number | How this device compares to other devices for characteristic artifacts |
| AwakeSecurity.Devices.activityCount.weight | number | Importance given to the characteristic artifacts when calculating the specified device risk score |
| AwakeSecurity.Devices.deviceName | string | Device name |
| AwakeSecurity.Devices.deviceType | string | Device type |
| AwakeSecurity.Devices.os | string | Operating system associated with the specified device |
| AwakeSecurity.Devices.recentIp | string | Most recent IP address associated with the specified device |
| AwakeSecurity.Devices.activeIp | string | Most common IP address associated with the specified device |
| AwakeSecurity.Devices.commonEmail | string | Most common email address associated with the specified device |
| AwakeSecurity.Devices.commonUsername | string | Most common username associated with the specified device |
| AwakeSecurity.Devices.commonMpid | string | Most common monitoring point ID the specified device was seen on |
| AwakeSecurity.Devices.nSimilarDevices | number | Number of devices that are similar to the specified device |
| AwakeSecurity.Devices.tags | string | Tags applied to the specified device |
| AwakeSecurity.Devices.ipCount | number | Number of IP addresses associated with the specified device |
| AwakeSecurity.Devices.emailCount | number | Number of email addresses associated with this device |
| AwakeSecurity.Devices.usernameCount | number | Number of usernames associated with the specified device |
| AwakeSecurity.Devices.applicationCount | number | Number of applications associated with the specified device |
| AwakeSecurity.Devices.mpids | string | List of monitoring point IDs associated with the specified device |
| AwakeSecurity.Devices.protocols.count | number | Number of time this protocol was used by the specified device |
| AwakeSecurity.Devices.firstSeen | string | Date that the specified device was first seen |
| AwakeSecurity.Devices.lastSeen | string | Date that the specified device was last seen |
| AwakeSecurity.Devices.osVersion | string | Operating system version of the specified device |
| AwakeSecurity.Devices.deviceGuid | string | Awake Security unique identifier for the specified device |
| AwakeSecurity.Devices.ips | unknown | List of IP addresses associated with the specified device |
| AwakeSecurity.Devices.usernames | string | List of usernames that were inferred as accounts on the specified device |
| AwakeSecurity.Devices.emails | string | List of email addresses associated with the specified device |
| AwakeSecurity.Devices.ackTs | string | Date of the last TCP session acknowledgment of the specified device |
| AwakeSecurity.Devices.whiteListed | bool | Is the device associated with the specified email address in the allow list |
| AwakeSecurity.Devices.protocols.name | string | Type of protocol used by the specified device |
Command Example
!device device="dae6720d-0588-d23b-c006-63cf1134537b"
Human Readable Output
