Cortex XSOAR for Developers (Formerly Demisto)

FireEye HX

Use the FireEye HX integration to access information about endpoints, acquisitions, alerts, indicators, and containment.

Use Cases

FireEye HX integration can be used for the following use cases:

Monitor FireEye HX alerts

Simply use the ‘fetch-incidents’ option in the integration settings (as explained in ‘Fetched incidents data’ section above) for a continues pull of alerts to the Demisto platform.

Search Hosts

Search all hosts or a subset of hosts for a specific file or indicator.
The produces a list of hosts with a list of results for each host.

Find more information on ‘Additional Information’ section below.

Apply or remove containment from hosts

Containment prevents further compromise of a host system and its components by restricting the hostʼs ability to communicate.

Host containment

To request that a specific host be contained so that it no longer has access to other systems, run the fireeye-host-containment command and pass either the host name or its agent ID, for example, fireeye-host-containment hostname=“DESKTOP-HK8OI62”

Notes:

  • Some hosts are ineligible for containment.
  • The time it takes to contain a host varies, based on factors such as agent connectivity, network traffic, and other jobs running in your environment .
  • You cannot contain a host if the agent package for that host is not available on the FireEye HX Series appliance.

Host containment removal

To release a specific host from containment, run the fireeye-cancel-containment command and pass either the host name or its agent ID, for example fireeye-cancel-containment agentId=”uGvn34ZkM3bfSf1nOT”

Prerequisites

Make sure you have a valid user account on the FireEye HX Series appliance associated with the api_admin or api_analyst role.

For more information about setting up user accounts on the FireEye HX Series appliance, see the FireEye HX Series System Administration Guide.

Configure FireEye HX on Demisto

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for FireEye HX.
  3. Click Add instance to create and configure a new integration instance.
    • Name : A textual name for the integration instance.
    • Server URL : Exchange server URL.
    • Credentials: Your personal account username.
    • Password : Your personal account password.
    • Version : The API version. Default is 3.
    • Fetched incidents data : The integration imports FireEye HX alerts as Demisto incidents . The first pull of incidents will fetch the last 100 alerts on FireEye HX.
  4. Click Test to validate the URLs and token.

Commands

You can execute these commands from the Demisto 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.

  1. Contain a host: fireeye-hx-host-containment
  2. Release host from containment: fireeye-hx-cancel-containment
  3. Get alert list: fireeye-hx-get-alerts
  4. Get alert details: fireeye-hx-get-alert
  5. Suppress an alert: fireeye-hx-suppress-alert
  6. Get indicator list: fireeye-get-indicators
  7. Get indicator information: fireeye-get-indicator
  8. Find hostname correlated with agent-ID or agent-ID correlated with hostname: fireeye-get-host-information
  9. Acquire a file: fireeye-file-acquisition
  10. Delete a file acquisition: fireeye-delete-file-acquisition
  11. Acquire data: fireeye-data-acquisition
  12. Delete data acquisition: fireeye-delete-data-acquisition

1. Contain a host

Contains a specific host, so it cannot access to other systems.

Command Limitations
  • Some hosts cannot be contained.
  • The time it takes to contain a host varies, based on factors such as agent connectivity, network traffic, and other jobs running in your environment.
  • You can only contain a host if the agent package for that host is available on the FireEye HX Series appliance.
Base Command

fireeye-hx-host-containment

Input

All arguments are optional, but you need to specify at least one to run this command.

Argument Name Description Required
hostName The host name to be contained. If the hostName is not specified, the agentId is required. Optional
agentId The agent ID running on the host to be contained. If the agentId is not specified, the hostName is required. Optional
Context Output
Path Description
FireEyeHX.Hosts._id FireEye HX Agent ID
FireEyeHX.Hosts.agent_version The agent version
FireEyeHX.Hosts.excluded_from_containment Determines whether the host is excluded from containment
FireEyeHX.Hosts.containment_missing_software Boolean value to indicate for containment missing software
FireEyeHX.Hosts.containment_queued Determines whether the host is queued for containment
FireEyeHX.Hosts.containment_state The containment state of the host. Possible values normal
FireEyeHX.Hosts.stats.alerting_conditions The number of conditions that have alerted the host
FireEyeHX.Hosts.stats.alerts Total number of alerts, including exploit-detection alerts
FireEyeHX.Hosts.stats.exploit_blocks The number of blocked exploits on the host
FireEyeHX.Hosts.stats.malware_alerts The number of malware alerts associated with the host
FireEyeHX.Hosts.hostname Host name
FireEyeHX.Hosts.domain Domain name
FireEyeHX.Hosts.timezone Host time zone
FireEyeHX.Hosts.primary_ip_address Host IP address
FireEyeHX.Hosts.last_poll_timestamp The timestamp of the last system poll performed on the host
FireEyeHX.Hosts.initial_agent_checkin Timestamp of the initial agent check-in
FireEyeHX.Hosts.last_alert_timestamp The time stamp of the last alert for the host
FireEyeHX.Hosts.last_exploit_block_timestamp Time when the last exploit was blocked on the host. The value is null if no exploits were blocked
FireEyeHX.Hosts.os.product_name Operating system
FireEyeHX.Hosts.os.bitness OS bitness (32 or 64)
FireEyeHX.Hosts.os.platform

Family of operating systems

  • win
  • osx
  • linux
FireEyeHX.Hosts.primary_mac The host MAC address
Command Examples

!fireeye-hx-host-containment agentId=”uGvn34ZkM3bfSf1nOT”

!fireeye-hx-host-containment hostname=“DESKTOP-HK8OI62”

Context Example 
 {  
   "FireEyeHX":{  
      "Hosts":{  
         "last_alert":{  
            "url":"/hx/api/v3/alerts/5",
            "_id":5
         },
         "domain":"DEMISTO",
         "last_exploit_block_timestamp":null,
         "containment_state":"contain",
         "timezone":"Eastern Daylight Time",
         "gmt_offset_seconds":-14400,
         "initial_agent_checkin":"2018-03-26T14:21:31.273Z",
         "stats":{  
            "alerting_conditions":1,
            "exploit_alerts":0,
            "acqs":11,
            "malware_false_positive_alerts":0,
            "alerts":1,
            "exploit_blocks":0,
            "malware_cleaned_count":0,
            "malware_alerts":0,
            "malware_quarantined_count":0
         },
         "primary_mac":"XX-XX-XX-XX-XX-XX",
         "hostname":"DESKTOP-XXX",
         "primary_ip_address":"^^^XX.XX.XX.XX^^^",
         "last_audit_timestamp":"2018-05-03T13:59:23.000Z",
         "last_alert_timestamp":"2018-04-16T08:59:51.693+00:00",
         "containment_queued":false,
         "sysinfo":{  
            "url":"/hx/api/v3/hosts/uGvnGVpZkDSFySf2ZOiT/sysinfo"
         },
         "last_exploit_block":null,
         "reported_clone":false,
         "url":"/hx/api/v3/hosts/uGvnGVpZkeySf2ZOiT",
         "excluded_from_containment":false,
         "last_poll_timestamp":"2018-05-03T14:01:22.000Z",
         "last_poll_ip":"^^^XX.XX.XX.XX^^^",
         "containment_missing_software":false,
         "_id":" uGvnGVpZkDSFySf2ZOiT ",
         "os":{  
            "kernel_version":null,
            "platform":"win",
            "patch_level":null,
            "bitness":"64-bit",
            "product_name":"Windows 10 Enterprise Evaluation"
         },
         "agent_version":"26.21.10"
      }
   }
}

2. Release host from containment

Releases a specific host from containment.

Base Command

fireeye-hx-cancel-containment

Input

All arguments are optional, but you need to specify at least one to run this command.

Argument Name Description Required
hostName The host name to be contained. If the hostName is not specified, the agentId is required. Optional
agentId The agent ID running on the host to be contained. If the agentId is not specified, the hostName is required. Optional
Context Output
Path Description
FireEyeHX.Hosts._id FireEye HX Agent ID
FireEyeHX.Hosts.agent_version The agent version
FireEyeHX.Hosts.excluded_from_containment Determines whether the host is excluded from containment
FireEyeHX.Hosts.containment_missing_software Boolean value to indicate for containment missing software
FireEyeHX.Hosts.containment_queued Determines whether the host is queued for containment
FireEyeHX.Hosts.containment_state The containment state of the host. Possible values normal
FireEyeHX.Hosts.stats.alerting_conditions The number of conditions that have alerted the host
FireEyeHX.Hosts.stats.alerts Total number of alerts, including exploit-detection alerts
FireEyeHX.Hosts.stats.exploit_blocks The number of blocked exploits on the host
FireEyeHX.Hosts.stats.malware_alerts The number of malware alerts associated with the host
FireEyeHX.Hosts.hostname Host name
FireEyeHX.Hosts.domain Domain name
FireEyeHX.Hosts.timezone Host time zone
FireEyeHX.Hosts.primary_ip_address Host IP address
FireEyeHX.Hosts.last_poll_timestamp The timestamp of the last system poll performed on the host
FireEyeHX.Hosts.initial_agent_checkin Timestamp of the initial agent check-in
FireEyeHX.Hosts.last_alert_timestamp The time stamp of the last alert for the host
FireEyeHX.Hosts.last_exploit_block_timestamp Time when the last exploit was blocked on the host. The value is null if no exploits were blocked
FireEyeHX.Hosts.os.product_name Operating system
FireEyeHX.Hosts.os.bitness OS bitness (32 or 64)
FireEyeHX.Hosts.os.platform

Family of operating systems

  • win
  • osx
  • linux
FireEyeHX.Hosts.primary_mac The host MAC address
Command Examples

!fireeye-hx-cancel-containment agentId=”uGvn34ZkM3bfSf1nOT”

!fireeye-hx-cancel-containment hostname=“DESKTOP-HK8OI62”

Context Example 
{
    "FireEyeHX": {
        "Hosts": {
            "last_alert": {
                "url": "/hx/api/v3/alerts/5", 
                "_id": 5
            }, 
            "domain": "DEMISTO", 
            "last_exploit_block_timestamp": null, 
            "containment_state": "normal", 
            "timezone": "Eastern Daylight Time", 
            "gmt_offset_seconds": -14400, 
            "initial_agent_checkin": "2018-03-26T14:21:31.273Z", 
            "stats": {
                "alerting_conditions": 1, 
                "exploit_alerts": 0, 
                "acqs": 11, 
                "malware_false_positive_alerts": 0, 
                "alerts": 1, 
                "exploit_blocks": 0, 
                "malware_cleaned_count": 0, 
                "malware_alerts": 0, 
                "malware_quarantined_count": 0
            }, 
            "primary_mac": "XX-XX-XX-XX-XX-XX", 
            "hostname": "DESKTOP-XXX", 
            "primary_ip_address": "^^^XX.XX.XX.XX^^^", 
            "last_audit_timestamp": "2018-05-03T13:59:23.000Z", 
            "last_alert_timestamp": "2018-04-16T08:59:51.693+00:00", 
            "containment_queued": false, 
            "sysinfo": {
                "url": "/hx/api/v3/hosts/uGvnGVpZkDSFySf2ZOiT/sysinfo"
            }, 
            "last_exploit_block": null, 
            "reported_clone": false, 
            "url": "/hx/api/v3/hosts/uGvnGVpZkeySf2ZOiT", 
            "excluded_from_containment": false, 
            "last_poll_timestamp": "2018-05-03T14:01:22.000Z", 
            "last_poll_ip": "^^^XX.XX.XX.XX^^^", 
            "containment_missing_software": false, 
            "_id": " uGvnGVpZkDSFySf2ZOiT ", 
            "os": {
                "kernel_version": null, 
                "platform": "win", 
                "patch_level": null, 
                "bitness": "64-bit", 
                "product_name": "Windows 10 Enterprise Evaluation"
            }, 
            "agent_version": "26.21.10"
        }
    }
 }
 

3. Get alert list

Gets a list of alerts according to specified filters.

Base Command

fireeye-hx-get-alerts

Input
Argument Name Description Required
hasShareMode Identifies which alerts result from indicators with the specified share mode Optional
resolution Sorts the results by the specified field Optional
agentId Filter by the agent ID Optional
conditionId Filter by condition ID Optional
eventAt Filter event occurred time (ISO-8601 timestamp) Optional
alertId Filter by alert ID Optional
matchedAt Filter by match detection time (ISO-8601 timestamp) Optional
minId Filter that returns only records with an AlertId field value great than the minId value Optional
reportedAt Filter by reported time (ISO-8601 timestamp) Optional
IOCsource Source of alert (indicator of compromise) Optional
EXDsource Source of alert (exploit detection) Optional
MALsource Source of alert (malware alert) Optional
minId Return only records with an ID greater than minId Optional
limit Specifies the number of results to return Optional
sort Sorts the results by the specified field in ascending order Optional
sortOrder The sort order for the results Optional
Context Output
Path Description
FireEyeHX.Alerts._id FireEye alert ID
FireEyeHX.Alerts.agent._id FireEye agent ID
FireEyeHX.Alerts.agent.containment_state Host containment state
FireEyeHX.Alerts.condition._id The condition unique ID
FireEyeHX.Alerts.event_at Time when the event occured
FireEyeHX.Alerts.matched_at Time when the event was matched
FireEyeHX.Alerts.reported_at Time when the event was reported
FireEyeHX.Alerts.source Source of alert
FireEyeHX.Alerts.matched_source_alerts._id Source alert ID
FireEyeHX.Alerts.matched_source_alerts.appliance_id Appliance ID
FireEyeHX.Alerts.matched_source_alerts.meta Source alert meta
FireEyeHX.Alerts.matched_source_alerts.indicator_id Indicator ID
FireEyeHX.Alerts.resolution Alert resolution
FireEyeHX.Alerts.event_type Event type
Command Example

!fireeye-hx-get-alerts limit="10" sort="id" sortOrder="descending"

Raw Output 
 {
    "FireEyeHX": {
        "Alerts": {
            "_id": 5,
            "agent": {
                "_id": "uGvnGVp…4bKeySf2ZOiT",
                "containment_state": "normal",
                "url": "/hx/api/v3/hosts/ uGvnGVp…4bKeySf2ZOiT "
            },
            "condition": {
                "_id": "CSaoSZFw…JNPW0mw==",
                "url": "/hx/api/v3/conditions/ CSaoSZFw…JNPW0mw =="
            },
            "event_at": "2018-04-16T08:59:02.061Z",
            "event_id": 7885715,
            "event_type": "fileWriteEvent",
            "event_values": {
                "fileWriteEvent/closed": 1,
                "fileWriteEvent/dataAtLowestOffset": "dGVzdGVzdA==",
                "fileWriteEvent/devicePath": "\\Device\\HarddiskVolume2",
                "fileWriteEvent/drive": "C",
                "fileWriteEvent/fileExtension": "txt",
                "fileWriteEvent/fileName": "testest - Copy.txt",
                "fileWriteEvent/filePath": "Users\\demistodev\\Documents",
                "fileWriteEvent/fullPath": "C:\\Users\\User\\Documents\\testest - Copy.txt",
                "fileWriteEvent/lowestFileOffsetSeen": 0,
                "fileWriteEvent/md5": " c3add7b947…817c79f7b7bd ",
                "fileWriteEvent/numBytesSeenWritten": 7,
                "fileWriteEvent/pid": 3308,
                "fileWriteEvent/process": "explorer.exe",
                "fileWriteEvent/processPath": "C:\\Windows",
                "fileWriteEvent/size": 7,
                "fileWriteEvent/textAtLowestOffset": "testest",
                "fileWriteEvent/timestamp": "2018-04-16T08:59:02.061Z",
                "fileWriteEvent/username": "DEMISTO\\User",
                "fileWriteEvent/writes": 1
            },
            "is_false_positive": null,
            "matched_at": "2018-04-16T08:59:10.000Z",
            "matched_source_alerts": [],
            "reported_at": "2018-04-16T08:59:51.693Z",
            "resolution": "ALERT",
            "source": "IOC",
            "url": "/hx/api/v3/alerts/5"
        }
    },
    "File": [
        {
            "Extension": "txt",
            "MD5": "c3add7b947…817c79f7b7bd",
            "Name": "testest - Copy.txt",
            "Path": "C:\\Users\\User\\Documents\\testest - Copy.txt"
        }
    ],
    "IP": [],	
    "RrgistryKey": []
}

4. Get alert details

Retrieves the details of a specific alert.

Base Command

fireeye-hx-get-alert

Input
Argument Name Description Required
alertId ID of alert to get details of Required

Context Output
Path Description
FireEyeHX.Alerts._id FireEye alert ID
FireEyeHX.Alerts.agent._id FireEye agent ID
FireEyeHX.Alerts.agent.containment_state Host containment state
FireEyeHX.Alerts.condition._id The condition unique ID
FireEyeHX.Alerts.event_at Time when the event occurred
FireEyeHX.Alerts.matched_at Time when the event was matched
FireEyeHX.Alerts.reported_at Time when the event was reported
FireEyeHX.Alerts.source Source of alert
FireEyeHX.Alerts.matched_source_alerts._id Source alert ID
FireEyeHX.Alerts.matched_source_alerts.appliance_id Appliance ID
FireEyeHX.Alerts.matched_source_alerts.meta Source alert meta
FireEyeHX.Alerts.matched_source_alerts.indicator_id Indicator ID
FireEyeHX.Alerts.resolution Alert resolution
FireEyeHX.Alerts.event_type Event type
Command Example

!fireeye-hx-get-alert alertId=5

Context Example 
 {
    "FireEyeHX": {
        "Alerts": {
            "_id": 5,
            "agent": {
                "_id": "uGvnGVpZkM4bKeySf2ZOiT",
                "containment_state": "normal",
                "url": "/hx/api/v3/hosts/uGvnGVpZkM4bKeySf2ZOiT"
            },
            "condition": {
                "_id": "CSaoSZFwVBtjGJBJNPW0mw==",
                "url": "/hx/api/v3/conditions/CSaoSZFwVBtjGJBJNPW0mw=="
            },
            "event_at": "2018-04-16T08:59:02.061Z",
            "event_id": 7885715,
            "event_type": "fileWriteEvent",
            "event_values": {
                "fileWriteEvent/closed": 1,
                "fileWriteEvent/dataAtLowestOffset": "dGVzdGVzdA==",
                "fileWriteEvent/devicePath": "\\Device\\HarddiskVolume2",
                "fileWriteEvent/drive": "C",
                "fileWriteEvent/fileExtension": "txt",
                "fileWriteEvent/fileName": "testest - Copy.txt",
                "fileWriteEvent/filePath": "Users\\demistodev\\Documents",
                "fileWriteEvent/fullPath": "C:\\Users\\demistodev\\Documents\\testest - Copy.txt",
                "fileWriteEvent/lowestFileOffsetSeen": 0,
                "fileWriteEvent/md5": "c3add7b94781ee70ec7c817c79f7b7bd",
                "fileWriteEvent/numBytesSeenWritten": 7,
                "fileWriteEvent/pid": 3308,
                "fileWriteEvent/process": "explorer.exe",
                "fileWriteEvent/processPath": "C:\\Windows",
                "fileWriteEvent/size": 7,
                "fileWriteEvent/textAtLowestOffset": "testest",
                "fileWriteEvent/timestamp": "2018-04-16T08:59:02.061Z",
                "fileWriteEvent/username": "DEMISTO\\demistodev",
                "fileWriteEvent/writes": 1
            },
            "is_false_positive": null,
            "matched_at": "2018-04-16T08:59:10.000Z",
            "matched_source_alerts": [],
            "reported_at": "2018-04-16T08:59:51.693Z",
            "resolution": "ALERT",
            "source": "IOC",
            "url": "/hx/api/v3/alerts/5"
        }
    }
}

5. Suppress an alert

Suppresses an alert.

Base Command

fireeye-hx-suppress-alert

Input
Argument Name Description Required
alertId ID of alert to suppress (listed in the output of the get-alerts command) Required

Context Output

There is no context output for this command.

Command Example

!fireeye-hx-suppress-alert alertId=2

6. Get indicator list

Gets a list of indicators.

Base Command

fireeye-hx-get-indicators

Input
Argument Name Description Required
category The indicator category Optional
searchTerm The searchTerm can be any name, category, signature, source, or condition value. Optional
shareMode Determines who can see the indicator. You must belong to the correct authorization group . Optional
sort Sorts the results by the specified field in ascending order Optional
createdBy Person who created the indicator Optional
alerted Whether the indicator resulted in alerts Optional
limit Limit the number of results Optional
Context Output
Path Description
FireEyeHX.Indicators._id FireEye unique indicator ID
FireEyeHX.Indicators.name The indicator name as displayed in the UI
FireEyeHX.Indicators.description Indicator description
FireEyeHX.Indicators.category.name Category name
FireEyeHX.Indicators.created_by The Created By field as displayed in UI
FireEyeHX.Indicators.active_since Date that the indicator became active
FireEyeHX.Indicators.stats.source_alerts Total number of source alerts associated with this indicator
FireEyeHX.Indicators.stats.alerted_agents Total number of agents with FireEye HX alerts associated with this indicator
FireEyeHX.Indicators.platforms List of OS families
Command Example

!fireeye-hx-get-indicators sort="activeSince" alerted="yes"

Raw Output 
    "FireEyeHX": {
        "Indicators": [
            {
                "category": {
                    "url": "/hx/api/v3/indicator_categories/custom", 
                    "_id": 2, 
                    "uri_name": "Custom", 
                    "name": "Custom", 
                    "share_mode": "unrestricted"
                }, 
                "display_name": null, 
                "description": "", 
                "create_actor": {
                    "username": "admin", 
                    "_id": 1000
                }, 
                "platforms": [
                    "win", 
                    "osx"
                ], 
                "url": "/hx/api/v3/indicators/custom/txt", 
                "_revision": "20180501131901519705101701", 
                "update_actor": {
                    "username": "admin", 
                    "_id": 1000
                }, 
                "create_text": null, 
                "created_by": "admin", 
                "active_since": "2018-05-01T13:19:01.519Z", 
                "meta": null, 
                "signature": null, 
                "stats": {
                    "active_conditions": 2, 
                    "alerted_agents": 0, 
                    "source_alerts": 0
                },
		…
        ]
    }
}
 

7. Get indicator information

Retrieves information of a specific indicator.

Base Command

fireeye-hx-get-indicator

Input
Input Parameter Description Required
category Indicator category Required
name Indicator name Required

Context Output
Path Description
FireEyeHX.Indicators._id FireEye unique indicator ID.
FireEyeHX.Indicators.name The indicator name as displayed in the UI
FireEyeHX.Indicators.description Indicator description
FireEyeHX.Indicators.category.name Category name
FireEyeHX.Indicators.created_by The Created By field as displayed in UI
FireEyeHX.Indicators.active_since Date that the indicator became active
FireEyeHX.Indicators.stats.source_alerts Total number of source alerts associated with this indicator
FireEyeHX.Indicators.stats.alerted_agents Total number of agents with FireEye HX alerts associated with this indicator
FireEyeHX.Indicators.platforms List of OS families
FireEyeHX.Conditions._id FireEye unique condition ID
FireEyeHX.Conditions.event_type Event type
FireEyeHX.Conditions.enabled Indicates whether the condition is enabled
Command Example

!fireeye-hx-get-indicator category=Custom name="test indicator"

Raw Output 
 {
    "FireEyeHX": {
        "Indicators": {
            "category": {
                "url": "/hx/api/v3/indicator_categories/custom", 
                "_id": 2, 
                "uri_name": "Custom", 
                "name": "Custom", 
                "share_mode": "unrestricted"
            }, 
            "display_name": null, 
            "description": "", 
            "create_actor": {
                "username": "admin", 
                "_id": 1000
            }, 
            "platforms": [
                "win", 
                "osx"
            ], 
            "url": "/hx/api/v3/indicators/custom/txt", 
            "_revision": "20180501131901519705101701", 
            "update_actor": {
                "username": "admin", 
                "_id": 1000
            }, 
            "create_text": null, 
            "created_by": "admin", 
            "active_since": "2018-05-01T13:19:01.519Z", 
            "meta": null, 
            "signature": null, 
            "stats": {
                "active_conditions": 2, 
                "alerted_agents": 0, 
                "source_alerts": 0
            }, 
            "_id": "00807331-8982-4e27-94f0-abe873f88366", 
            "uri_name": "txt", 
            "name": "txt"
        }, 
        "Conditions": [
            {
                "tests": [
                    {
                        "operator": "equal", 
                        "token": "ipv4NetworkEvent/remoteIP", 
                        "type": "text", 
                        "value": "^^^8.8.8.8^^^"
                    }
                ], 
                "event_type": "ipv4NetworkEvent", 
                "url": "/hx/api/v3/conditions/G7fmpVr1gxFU2JKXUIu2Cg", 
                "enabled": true, 
                "_id": "G7fmpVr1gxFU2JKXUIu2Cg==", 
                "is_private": false, 
                "uuid": "1bb7e6a5-5af5-4311-94d8-9297508bb60a"
            }, 
            {
                "tests": [
                    {
                        "operator": "equal", 
                        "token": "dnsLookupEvent/hostname", 
                        "type": "text", 
                        "value": "google.com"
                    }
                ], 
                "event_type": "dnsLookupEvent", 
                "url": "/hx/api/v3/conditions/vCc2bJosTJdxrhkqvanEFw", 
                "enabled": true, 
                "_id": "vCc2bJosTJdxrhkqvanEFw==", 
                "is_private": false, 
                "uuid": "bc27366c-9a2c-4c97-b1ae-192abda9c417"
            }
        ]
    }
}

8. Find hostname correlated with agent-ID or agent-ID correlated with hostname

Returns agent-ID for specified hostname, or hostname for specified agent-ID.

Base Command

fireeye-hx-get-host-information

Input
Argument Name Description Required
agentId The agent ID. If the agent ID is not specified, the host Name must be specified. Optional
hostName The host name. If the host name is not specified, the agent ID must be specified. Optional
Context Output
Path Description
FireEyeHX.Hosts._id FireEye HX Agent ID
FireEyeHX.Hosts.agent_version The agent version
FireEyeHX.Hosts.excluded_from_containment Determines whether the host is excluded from containment
FireEyeHX.Hosts.containment_missing_software Boolean value to indicate for containment missing software
FireEyeHX.Hosts.containment_queued Determines whether the host is queued for containment
FireEyeHX.Hosts.containment_state The containment state of the host. Possible values normal
FireEyeHX.Hosts.stats.alerting_conditions The number of conditions that have alerted for the host
FireEyeHX.Hosts.stats.alerts Total number of alerts, including exploit-detection alerts
FireEyeHX.Hosts.stats.exploit_blocks The number of blocked exploits on the host
FireEyeHX.Hosts.stats.malware_alerts The number of malware alerts associated with the host
FireEyeHX.Hosts.hostname The host name
FireEyeHX.Hosts.domain Domain name
FireEyeHX.Hosts.timezone Host time zone
FireEyeHX.Hosts.primary_ip_address The host IP address
FireEyeHX.Hosts.last_poll_timestamp The timestamp of the last system poll performed on the host
FireEyeHX.Hosts.initial_agent_checkin Timestamp of the initial agent check-in
FireEyeHX.Hosts.last_alert_timestamp The time stamp of the last alert for the host
FireEyeHX.Hosts.last_exploit_block_timestamp Time when the last exploit was blocked on the host. The value is null if no exploits have been blocked.
FireEyeHX.Hosts.os.product_name Specific operating system
FireEyeHX.Hosts.os.bitness OS Bitness (32 or 64)
FireEyeHX.Hosts.os.platform

OS families

  • win
  • osx
  • linux
FireEyeHX.Hosts.primary_mac The host MAC address
Command Example

!fireeye-hx-get-host-information hostName=”DESKTOP-XXX”

Context Example 
 {
    "FireEyeHX": {
        "Hosts": {
            "last_alert": {
                "url": "/hx/api/v3/alerts/5", 
                "_id": 5
            }, 
            "domain": "DEMISTO", 
            "last_exploit_block_timestamp": null, 
            "containment_state": "normal", 
            "timezone": "Eastern Daylight Time", 
            "gmt_offset_seconds": -14400, 
            "initial_agent_checkin": "2018-03-26T14:21:31.273Z", 
            "stats": {
                "alerting_conditions": 1, 
                "exploit_alerts": 0, 
                "acqs": 11, 
                "malware_false_positive_alerts": 0, 
                "alerts": 1, 
                "exploit_blocks": 0, 
                "malware_cleaned_count": 0, 
                "malware_alerts": 0, 
                "malware_quarantined_count": 0
            }, 
            "primary_mac": "XX-XX-XX-XX-XX-XX", 
            "hostname": "DESKTOP-XXX", 
            "primary_ip_address": "^^^XX.XX.XX.XX^^^", 
            "last_audit_timestamp": "2018-05-03T13:59:23.000Z", 
            "last_alert_timestamp": "2018-04-16T08:59:51.693+00:00", 
            "containment_queued": false, 
            "sysinfo": {
                "url": "/hx/api/v3/hosts/uGvnGVpZkDSFySf2ZOiT/sysinfo"
            }, 
            "last_exploit_block": null, 
            "reported_clone": false, 
            "url": "/hx/api/v3/hosts/uGvnGVpZkeySf2ZOiT", 
            "excluded_from_containment": false, 
            "last_poll_timestamp": "2018-05-03T14:01:22.000Z", 
            "last_poll_ip": "^^^XX.XX.XX.XX^^^", 
            "containment_missing_software": false, 
            "_id": " uGvnGVpZkDSFySf2ZOiT ", 
            "os": {
                "kernel_version": null, 
                "platform": "win", 
                "patch_level": null, 
                "bitness": "64-bit", 
                "product_name": "Windows 10 Enterprise Evaluation"
            }, 
            "agent_version": "26.21.10"
        }
    },
    "Endpoint": {
        "MACAddress": "XX-XX-XX-XX-XX-XX", 
        "Domain": "DEMISTO", 
        "IPAddress": "^^^XX.XX.XX.XX^^^", 
        "Hostname": "DESKTOP-XXX", 
        "OSVersion": "Windows 10 Enterprise Evaluation", 
        "OS": "win", 
        "ID": " uGvnGVpZkDSFySf2ZOiT "
    }, 
}

9. Acquire file

Acquires a specific file as a password protected zip file.

Command Limitations

  • Acquisitions are stored for 14 days or until the aggregate size of all acquisitions exceeds the acquisition space limit, which is from 30 GB to 9 TB, depending on the HX Series appliance .
  • When the acquisition space is completely full and automatic triages fill 10 percent of the acquisition space, the HX Series appliance reclaims disk space by removing automatic triage collections.
  • When the acquisition space is 90 percent full, no new acquisitions can be created, and bulk acquisitions that are running might be canceled .
Base Command

fireeye-hx-file-acquisition

Input
Argument Name Description Required
fileName The file name Required
filePath The file path Required
acquireUsing Whether to aqcuire the file using the API or RAW. By default, raw file will be acquired. Use API option when file is encrypted. Optional
agentId The agent ID associated with the host that holds the file. If the hostName is not specified, the agentId must be specified. Optional
hostName The host that holds the file. If the agentId is not specified, hostName must be specified. Optional
Context Output
Path Description
FireEyeHX.Acquisitions.Files._id The acquisition unique ID
FireEyeHX.Acquisitions.Files.state The acquisition state
FireEyeHX.Acquisitions.Files.md5 File MD5
FireEyeHX.Acquisitions.Files.req_filename The file name
FireEyeHX.Acquisitions.Files.req_path The file path
FireEyeHX.Acquisitions.Files.host._id FireEye HX agent ID
Command Example

!fireeye-hx-file-acquisition fileName="test.txt"filePath="C:\\Users\\user\\Documents" hostName="DESKTOP-DES01"

Raw Output 
     "FireEyeHX": {
        "Acquisitions": {
            "Files": {
                "_id": 13,
                "_revision": "206073441021688",
                "alert": null,
                "comment": null,
                "condition": null,
                "error_message": "The acquisition completed with issues.",
                "external_id": null,
                "finish_time": "2018-04-26T07:34:14.100Z",
                "host": {
                    "_id": "uGvnGVpZkKeySf2ZT",
                    "url": "/hx/api/v3/hosts/ uGvnGVpZkKeySf2ZT "
                },
                "indicator": null,
                "md5": "ee26908bf9…64b37da4754a",
                "req_filename": "ex.txt",
                "req_path": "C:\\Users\\user\\Documents",
                "req_use_api": null,
                "request_actor": {
                    "_id": 1001,
                    "username": "api"
                },
                "request_time": "2018-04-26T07:33:03.000Z",
                "state": "COMPLETE",
                "url": "/hx/api/v3/acqs/files/13",
                "zip_passphrase": "unzip-me"
            }
        }
    }

10. Delete file acquisition

Deletes the file acquisition, by acquisition ID.

Base Command

fireeye-hx-delete-file-acquisition

Input
Argument Name Description Required
acquisitionId The acquisition ID Required

Context Output

There is no context output.

Command Example

!fireeye-hx-delete-file-acquisition acquisitionId=10

11. Acquire data

Initiate a data acquisition process that gathers artifacts from the system disk and memory. The data is fetched as a MANS file.

Limitations

  • Acquisitions are stored for 14 days or until the aggregate size of all acquisitions exceeds the acquisition space limit, which is from 30 GB to 9 TB, depending on the HX Series appliance .
  • When the acquisition space is completely full and automatic triages fill 10 percent of the acquisition space, the HX Series appliance reclaims disk space by removing automatic triage collections.
  • When the acquisition space is 90 percent full, no new acquisitions can be created, and bulk acquisitions that are running might be canceled .
Base Command

fireeye-hx-data-acquisition

Input
Argument Name Description Required
script Acquisition script in JSON format Optional
scriptName The script name. If the Acquisition script is specified, you must also specify the script name. Optional
defaultSystemScript Use default script. Select the host system. Optional
agentId The agent ID. If the host name is not specified, the agent ID must be specified. Optional
hostName The host name. If the agent ID is not specified, the host name must be specified. Optional
Context Output
Path Description
FireEyeHX.Acquisitions.Data._id The acquisition unique ID
FireEyeHX.Acquisitions.Data.state The acquisition state
FireEyeHX.Acquisitions.Data.md5 File MD5
FireEyeHX.Acquisitions.Data.host._id Time that the acquisition completed
Command Example

! fireeye-hx-data-acquisition hostName="DESKTOP-DES01" defaultSystemScript=win

Raw Output 
{
    "FireEyeHX": {
        "Acquisitions": {
            "Data": {
                "comment": null, 
                "zip_passphrase": null, 
                "request_actor": {
                    "username": "api", 
                    "_id": 1001
                }, 
                "name": "test", 
                "script": {
                    "download": "/hx/api/v3/scripts/131ab1da5086fe09f5a210437de366007867fa26.json", 
                    "url": "/hx/api/v3/scripts/^^^131ab1da5086fe09f5a210437de366007867fa26^^^", 
                    "_id": "^^^131ab1da5086fe09f5a210437de366007867fa26^^^"
                }, 
                "finish_time": "2018-05-15T11:58:18.541Z", 
                "_revision": "20180515115818542250101787", 
                "error_message": "The triage completed with issues.", 
                "state": "COMPLETE", 
                "request_time": "2018-05-15T11:57:22.000Z", 
                "url": "/hx/api/v3/acqs/live/28", 
                "host": {
                    "url": "/hx/api/v3/hosts/uGvnGVpZkM4bKeySf2ZOiT", 
                    "_id": "uGvnGVpZkXXXX2ZOiT"
                }, 
                "download": "/hx/api/v3/acqs/live/28.mans", 
                "_id": 28, 
                "external_id": null, 
                "md5": null
            }
        }
    }, 
    "File": {
        "Info": "mans", 
        "SHA1": "^^^4374d09a27ef85XXXXX66785c040d7febff7d8^^^", 
        "Name": "agent_uGvnGVpZkMXXXX2ZOiT_data.mans", 
        "Extension": "mans", 
        "Size": 5154, 
        "EntryID": "383@1", 
        "SSDeep": "96:JraN9hyFIVls4Dst99i462teLuf0XXXXyU2y46Gd/pV:xapyFIVibPi462teLuf0TXdLNJLU23dt", 
        "SHA256": "7944d5e86ce2bXXXXe154d4c2923ddf47016a07b84b460f08b0f2f", 
        "Type": "Zip archive data, at least v2.0 to extract\n", 
        "MD5": "^^^c24a2c4aeXXXXf89e1e012dae^^^"
    }
}

12. Delete data acquisition

Deletes data acquisition, by acquisition ID.

Base Command

fireeye-hx-delete-data-acquisition

Input
Input Parameter Description Required

acquisitionId

The acquisition ID Required

Context Output

There is no context output for this command.

Command Example

!fireeye-hx-delete-data-acquisition acquisitionId=10

Error Responses - Timeout Error

Timeout error indicates that time limitation for the command has exceeded before results are returned.

To resolve this issue, configure new time limitation for the command.

  1. Navigate to Settings > About > Troubleshooting > Server Configuration .
  2. click Add Server Configuration .
  3. Set the key field using this format: FireEye HX.< command-name >.timeout.
  4. Set the value field to the desired time limit for the command to run (in minutes).

Known Limitations

Acquisitions limitations

  • Acquisitions are stored for 14 days or until the aggregate size of all acquisitions exceeds the acquisition space limit, which is from 30 GB to 9 TB, depending on the HX Series appliance .
  • When the acquisition space is completely full and automatic triages fill 10 percent of the acquisition space, the HX Series appliance reclaims disk space by removing automatic triage collections.
  • When the acquisition space is 90 percent full, no new acquisitions can be created, and bulk acquisitions that are running might be canceled .

Containment Limitations

  • Some hosts cannot be contained.
  • The time it takes to contain a host varies, based on factors such as agent connectivity, network traffic, and other jobs running in your environment.
  • You can only contain a host if the agent package for that host is available on the HX Series appliance.

Command Timeout

The following commands have high potential to exceed the default time limit for a running command. To avoid command timeout, change the command timeout settings.

  • fireeye-hx-search
  • fireeye-hx-data-acquisition
  • fireeye-hx-file-acquisition

Configure Command Timeout

  1. Navigate to Settings > About > Troubleshooting .
  2. In the Server Configuration section, click Add Server Configuration .
  3. Set the K ey ’ field using this format: FireEye HX.timeout
  4. Set the Value field to the timeout you need (in minutes).
Edit this page
Report an Issue