Skip to main content

Perch

Use the Perch integration to manage alerts, indicators, and communities.

This integration was integrated and tested with the latest version of Perch.

Configure Perch on Cortex XSOAR

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for Perch.
  3. Click Add instance to create and configure a new integration instance.
    • Name : a textual name for the integration instance.
    • Server URL (e.g., https://api.perch.rocks/)
    • API Token
    • Trust any certificate (not secure)
    • Use system proxy
    • Previous days to fetch
    • Credentials
    • Incident Soc Statuses to Fetch
  4. 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.

  1. Search for alerts: perch-search-alerts
  2. Get information for a community: perch-get-community
  3. Get a list of all communities: perch-list-communities
  4. Create an indicator: perch-create-indicator

1. Search for alerts

Searches for alerts in Perch.

Base Command

perch-search-alerts

Input
Argument Name Description Required
page Page of results to return. Optional
page_size Number of results to return per page. Optional
closed Whether the alert is closed. Optional
closed_at Time that the alert was closed. Optional
community_id Community ID that generated the alert. Optional
created_at Time that the alert was created. Optional
dest_ip Destination IP address. Optional
dest_port Destination port. Optional
full_url Full URL of the alert. Optional
id ID of the alert. Optional
indicator_id ID of the indicator. Optional
indicator_loaded Whether the indicator is loaded. Optional
observable_id Observable ID. Optional
protocol Protocol effected by the alert. Optional
sensor_id ID of the sensor that generated the alert. Optional
sensor_name Name of the sensor that generated the alert. Optional
soc_status Status in the SOC. Optional
src_ip Source IP address. Optional
src_port Source port. Optional
status Status of the alert. Optional
status_updated_at Time that the status was last updated. Optional
team_id ID of the team that generated the alert. Optional
title Title of the alert. Optional
ts Timestamp of the alert. Optional
ordering Order of the returned alerts. Optional

Context Output
Path Type Description
Perch.Alert.DestPort Number Destination port of the alert.
Perch.Alert.SrcPort Number Source port of the alert.
Perch.Alert.DestIP Number Destination IP of the alert.
Perch.Alert.IndicatorID Number Indicator ID of the alert.
Perch.Alert.SrcIP String IP address of the source.
Perch.Alert.SrcGeo.Country String Country of the threat.
Perch.Alert.SrcGeo.Latitude Number Latitude of the detected threat.
Perch.Alert.SrcGeo.Longitude Number Longitude of the detected threat.
Perch.Alert.SensorID Number ID of the sensor that reported the threat.
Perch.Alert.Title String Title of the alert.
Perch.Alert.Protocol String Protocol on which the alert was detected.
Perch.Alert.ID Number ID of the alert.
Perch.Alert.ObservableID Number ID of the observable event.
Perch.Alert.TS Date Timestamp of the alert.

Command Example 
!perch-search-alerts page_size=1
Context Example 
{
    "Perch": {
        "Alert": [
            {
                "Protocol": "TCP", 
                "Title": "ET TOR Known Tor Relay/Router (Not Exit) Node Traffic group 82", 
                "SrcPort": 30834, 
                "TS": "2019-07-22T08:49:28.518216+0000", 
                "ID": 854408, 
                "ObservableID": 908757, 
                "DestIP": "172.31.46.243", 
                "IndicatorID": "EmergingThreats:Indicator-2522162", 
                "SrcIP": "77.247.181.163", 
                "SensorID": 9185, 
                "SrcGeo": {
                    "Latitude": 52.3824, 
                    "Country": "Netherlands", 
                    "Longitude": 4.8995
                }, 
                "DestPort": 22
            }
        ]
    }
}
Human Readable Output

ET TOR Known Tor Relay/Router (Not Exit) Node Traffic group 82

Destination IP Destination Port ID Indicator ID Observable ID Protocol Sensor ID Source Geo Source IP Source Port Timestamp Title
172.31.46.243 22 854408 EmergingThreats:Indicator-2522162 908757 TCP 9185 Latitude: 52.3824<br>Longitude: 4.8995<br>Country Name: Netherlands 77.247.181.163 30834 2019-07-22T08:49:28.518216+0000 ET TOR Known Tor Relay/Router (Not Exit) Node Traffic group 82

2. Get information for a community

Gets community information by ID.

Base Command

perch-get-community

Input
Argument Name Description Required
id ID of the community. Required

Context Output
Path Type Description
Perch.Community.Allsectors Boolean Indicates if the community covers all sectors.
Perch.Community.Credentialreq Number Credentials required to interact with the community.
Perch.Community.Desc String Description of the community.
Perch.Community.Id Number ID of the community.
Perch.Community.Name String Name of the community.
Perch.Community.Poweredby String Organization providing the feed.
Perch.Community.Selectablefeeds Boolean Whether the feeds are selectable.

Command Example 
!perch-get-community id=1
Context Example 
{
    "Perch": {
        "Community": {
            "Selectablefeeds": true, 
            "Allsectors": true, 
            "Name": "Hail-a-TAXII", 
            "Credentialreq": 2, 
            "Poweredby": "Soltra Edge", 
            "Id": 1, 
            "Desc": "A repository of Open Source Cyber Threat Intellegence feeds in STIX format"
        }
    }
}
Human Readable Output

Communities Found

Allsectors Credentialreq Desc Id Name Poweredby Selectablefeeds
true 2 A repository of Open Source Cyber Threat Intelligence feeds in STIX format 1 Hail-a-TAXII Soltra Edge true

3. Get a list of all communities

Returns a list of all communities.

Base Command

perch-list-communities

Input

There are no input arguments for this command.

Context Output
Path Type Description
Perch.Community.Allsectors Boolean Indicates if the community covers all sectors.
Perch.Community.Credentialreq Number Credentials required to interact with the community.
Perch.Community.Desc String Description of the community.
Perch.Community.Id Number ID of the community.
Perch.Community.Name String Name of the community.
Perch.Community.Poweredby String Organization providing the feed.
Perch.Community.Selectablefeeds Boolean Whether the feeds are selectable.

Command Example 
!perch-list-communities
Context Example 
{
    "Perch": {
        "Community": [
            {
                "Selectablefeeds": true, 
                "Allsectors": true, 
                "Name": "Hail-a-TAXII", 
                "Credentialreq": 2, 
                "Poweredby": "Soltra Edge", 
                "Id": 1, 
                "Desc": "A repository of Open Source Cyber Threat Intellegence feeds in STIX format"
            }, 
            {
                "Selectablefeeds": false, 
                "Allsectors": true, 
                "Name": "DHS AIS", 
                "Credentialreq": 2, 
                "Poweredby": "Flare", 
                "Id": 5, 
                "Desc": "Department of Homeland Security - Automated Indicator Sharing"
            }, 
            {
                "Selectablefeeds": true, 
                "Allsectors": true, 
                "Name": "Emerging Threats", 
                "Credentialreq": 0, 
                "Poweredby": "Emerging Threats", 
                "Id": 8, 
                "Desc": "Open source intelligence data provided by Emerging Threats/ProofPoint"
            }
        ]
    }
}
Human Readable Output

Communities Found

Allsectors Credentialreq Desc Id Name Poweredby Selectablefeeds
true 2 A repository of Open Source Cyber Threat Intellegence feeds in STIX format 1 Hail-a-TAXII Soltra Edge true
true 2 Department of Homeland Security - Automated Indicator Sharing 5 DHS AIS Flare false
true 0 Open source intelligence data provided by Emerging Threats/ProofPoint 8 Emerging Threats Emerging Threats true

4. Create an indicator

Creates an indicator in Perch.

Base Command

perch-create-indicator

Input
Argument Name Description Required
communities Communities to report the indicator to. Required
confidence Confidence of the findings. Required
type Type of indicator. Required
value The value of the indicator. Required
title The title of the indicator. Required
description Description of the indicator. Required
tlp TLP of the Indicator. Required
operator Operator of the indicator. Optional
first_sighting When the indicator was first sighted. Optional
email_summary Sends an email with the summary of the indicator. Optional

Context Output
Path Type Description
Perch.Indicator.Confidence Unknown Confidence of the indicator.
Perch.Indicator.UpdatedAt Date Date and time that the indicator was last updated.
Perch.Indicator.TLP String TLP of the Indicator.
Perch.Indicator.Title String Title of the indicator.
Perch.Indicator.ID Number ID of the indicator.
Perch.Indicator.CreatedAt Date Date that the indicator was created.
Perch.Indicator.Team Number ID of the team.
Perch.Indicator.PerchID String The Perch ID for the incident.
Perch.Indicator.CreatedBy Number ID of the user that created the incident.

Command Example 
!perch-create-indicator communities=8 confidence=LOW description="Sample Alert Generated via Demisto" title="Sample Alert" tlp=WHITE type=Domain value="sample.com"
Context Example 
{
    "Perch": {
        "Indicator": [
            {
                "Description": "Sample Alert Generated via Demisto", 
                "Title": "Sample Alert", 
                "UpdatedAt": "2019-07-23T20:06:26.046774Z", 
                "PerchID": "41716ec9-4001-4d20-8aba-04137fa47c83", 
                "CreatedBy": 11728, 
                "Team": 5394, 
                "ID": 1236830, 
                "CreatedAt": "2019-07-23T20:06:26.046757Z"
            }
        ]
    }
}
Human Readable Output

Sample Alert

Created At Created By Description ID Perch ID Team Title Updated At
2019-07-23T20:06:26.046757Z 11728 Sample Alert Generated via Demisto 1236830 41716ec9-4001-4d20-8aba-04137fa47c83 5394 Sample Alert 2019-07-23T20:06:26.046774Z
Edit this page
Report an Issue