Perch

Perch is a co-managed threat detection and response platform.

Network Security · Perch

Details

ID	`Perch`
Provider	Razor Group
Category	Network Security
From Version	5.0.0
Docker Image	`demisto/python3:3.12.13.10116658`
Supported Modules	Agentix XSIAM

README

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

Navigate to Settings > Integrations > Servers & Services.
Search for Perch.
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
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.

Search for alerts: perch-search-alerts
Get information for a community: perch-get-community
Get a list of all communities: perch-list-communities
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

Configuration parameters

url — Server URL (e.g., https://api.perch.rocks/) (required)
api-key — API Token
api-key_creds —
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
fetch_time — Previous days to fetch
credentials — Credentials
isFetch — Fetch incidents
incidentType — Incident type
incidentFetchInterval — Incidents Fetch Interval
soc_status — Incident Soc Statuses to Fetch

Commands (4)

perch-create-indicator
Creates an indicator in Perch.
perch-get-community
Gets community information by ID.
perch-list-communities
Lists all communities.
perch-search-alerts
Searches for alerts in Perch.

Source

Perch.py Perch_test.py Perch.yml Perch_description.md

Download History Raw

import json


ALERTS = {
    "results": [
        {
            "closed_at": "2020-11-20T01:18:30.224654Z",
            "community_id": 8,
            "count": 0,
            "created_at": "2020-11-19T15:28:03.451476Z",
            "dest_geo_ip": {},
            "dest_ip": "8.8.8.8",
            "dest_port": 1122,
            "dest_subnet_id": None,
            "full_url": None,
            "id": 1,
            "indicator_id": "indicator_id",
            "indicator_loaded": None,
            "observable_id": 4563855,
            "protocol": "TCP",
            "sensor_id": 9185,
            "sensor_name": "Demisto Integration",
            "src_geo_ip": {
                "ip": "8.8.8.8",
                "latitude": 52.2394,
                "timezone": "Europe/Warsaw",
                "longitude": 21.0362,
                "coordinates": [21.0362, 52.2394],
                "country_name": "Poland",
                "country_code2": "PL",
                "country_code3": "PL",
                "continent_code": "EU",
            },
            "src_ip": "8.8.8.8",
            "src_port": 25845,
            "src_subnet_id": None,
            "status": 0,
            "status_updated_at": None,
            "team_id": 5394,
            "title": "ET POLICY MS Terminal Server Root login 1",
            "ts": "2020-11-19T15:25:42.576650+0000",
        },
        {
            "closed_at": "2020-11-18T20:05:58.969797Z",
            "community_id": 8,
            "count": 0,
            "created_at": "2020-11-18T03:14:25.451196Z",
            "dest_geo_ip": {},
            "dest_ip": "8.8.8.8",
            "dest_port": 3389,
            "dest_subnet_id": None,
            "full_url": None,
            "id": 2,
            "indicator_id": "EmergingThreats:Indicator-2012710",
            "indicator_loaded": None,
            "observable_id": 4552422,
            "protocol": "TCP",
            "sensor_id": 9185,
            "sensor_name": "Demisto Integration",
            "src_geo_ip": {
                "ip": "8.8.8.8",
                "latitude": 52.2394,
                "timezone": "Europe/Warsaw",
                "longitude": 21.0362,
                "coordinates": [21.0362, 52.2394],
                "country_name": "Poland",
                "country_code2": "PL",
                "country_code3": "PL",
                "continent_code": "EU",
            },
            "src_ip": "8.8.8.8",
            "src_port": 21364,
            "src_subnet_id": None,
            "status": 0,
            "status_updated_at": None,
            "team_id": 5394,
            "title": "ET POLICY MSS Terminal Server Root login 2",
            "ts": "2020-11-18T02:38:14.828625+0000",
        },
        {
            "closed_at": "2020-11-18T20:05:58.969797Z",
            "community_id": 8,
            "count": 0,
            "created_at": "2020-11-17T03:14:25.451196Z",
            "dest_geo_ip": {},
            "dest_ip": "8.8.8.8",
            "dest_port": 3389,
            "dest_subnet_id": None,
            "full_url": None,
            "id": 3,
            "indicator_id": "EmergingThreats:Indicator-2012710",
            "indicator_loaded": None,
            "observable_id": 4552422,
            "protocol": "TCP",
            "sensor_id": 9185,
            "sensor_name": "Demisto Integration",
            "src_geo_ip": {
                "ip": "8.8.8.8",
                "latitude": 52.2394,
                "timezone": "Europe/Warsaw",
                "longitude": 21.0362,
                "coordinates": [21.0362, 52.2394],
                "country_name": "Poland",
                "country_code2": "PL",
                "country_code3": "PL",
                "continent_code": "EU",
            },
            "src_ip": "8.8.8.8",
            "src_port": 21364,
            "src_subnet_id": None,
            "status": 2,
            "status_updated_at": None,
            "team_id": 5394,
            "title": "ET POLICY MSF Terminal Server Root login 3",
            "ts": "2020-11-18T02:38:14.828625+0000",
        },
    ]
}


def get_alerts_by_status(method, url, params=None, data=None, headers=None):
    """
    The function simulate the http_request method for the test_fetch_alerts_command_by_soc_status.
    The function got the params as the http_request got, and return from the json above only the incidents
    that are in the given status.
    """
    status = params["soc_status"]
    results = {"results": [alert for alert in ALERTS["results"] if int(status) == alert["status"]]}
    return results


def test_fetch_alerts_command_by_soc_status(requests_mock, mocker):
    """
    Given:
        - List of statuses to fetch
    When
        - Running fetch_incident
    Then
        - Verify the returned incidents is with the expected status
    """
    params = {
        "credentials": {"identifier": 1234, "password": 5678},
        "url": "https://api.perch.rocks",
        "soc_status": ["Not Reviewed"],
    }
    mocker.patch("demistomock.params", return_value=params)

    from Perch import fetch_alerts

    mocker.patch("Perch.http_request", side_effect=get_alerts_by_status)

    headers = {"Content-Type": "application/json"}
    last_run = {"time": 1561017202}

    _, incidents = fetch_alerts(last_run, headers)

    assert len(incidents) == 2

    assert incidents[0]["name"] == "Perch Incident: ET POLICY MSS Terminal Server Root login 2"
    assert incidents[1]["name"] == "Perch Incident: ET POLICY MS Terminal Server Root login 1"

    raw_json = json.loads(incidents[0]["rawJSON"])
    assert raw_json["status"] == 0

    raw_json = json.loads(incidents[1]["rawJSON"])
    assert raw_json["status"] == 0