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

category: Network Security
sectionorder:
- Connect
- Collect
provider: Razor Group
commonfields:
  id: Perch
  version: -1
configuration:
- defaultvalue: https://api.perch.rocks/
  display: Server URL (e.g., https://api.perch.rocks/)
  name: url
  required: true
  type: 0
  section: Connect
- display: API Token
  name: api-key
  type: 4
  hidden: true
  required: false
  section: Connect
- name: api-key_creds
  type: 9
  displaypassword: API Token
  hiddenusername: true
  required: false
  section: Connect
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  required: false
  section: Connect
- display: Use system proxy settings
  name: proxy
  type: 8
  required: false
  section: Connect
- display: Previous days to fetch
  name: fetch_time
  type: 0
  defaultvalue: '7'
  required: false
  section: Collect
- display: Credentials
  name: credentials
  type: 9
  required: false
  section: Connect
- display: Fetch incidents
  name: isFetch
  type: 8
  required: false
  section: Collect
- display: Incident type
  name: incidentType
  type: 13
  required: false
  section: Collect
- display: Incidents Fetch Interval
  name: incidentFetchInterval
  defaultvalue: '1'
  required: false
  type: 19
  advanced: true
  section: Collect
- additionalinfo: 'The statuses of the incidents that will be fetched. If no status is provided then incidents of all the statuses will be fetched. Note: an incident whose status was changed to a filtered status after its creation time will not be fetched.'
  display: Incident Soc Statuses to Fetch
  name: soc_status
  options:
  - Not Reviewed
  - Investigating
  - On hold
  - False Positive
  - Escalated
  type: 16
  required: false
  section: Collect
description: Perch is a co-managed threat detection and response platform.
display: Perch
name: Perch
script:
  commands:
  - arguments:
    - description: Page of results to return.
      name: page
    - description: Number of results to return per page.
      name: page_size
    - auto: PREDEFINED
      description: Whether the alert is closed.
      name: closed
      predefined:
      - 'true'
      - 'false'
    - description: Time that the alert was closed.
      name: closed_at
    - description: Community ID that generated the alert.
      name: community_id
    - description: Time that the alert was created.
      name: created_at
    - description: Destination IP address.
      name: dest_ip
    - description: Destination port.
      name: dest_port
    - description: Full URL of the alert.
      name: full_url
    - description: ID of the alert.
      name: id
    - description: ID of the indicator.
      name: indicator_id
    - auto: PREDEFINED
      description: Whether the indicator is loaded.
      name: indicator_loaded
      predefined:
      - 'true'
      - 'false'
    - description: Observable ID.
      name: observable_id
    - description: Protocol effected by the alert.
      name: protocol
    - description: ID of the sensor that generated the alert.
      name: sensor_id
    - description: Name of the sensor that generated the alert.
      name: sensor_name
    - description: Status in the SOC.
      name: soc_status
    - description: Source IP address.
      name: src_ip
    - description: Source port.
      name: src_port
    - description: Status of the alert.
      name: status
    - description: Time that the status was last updated.
      name: status_updated_at
    - description: ID of the team that generated the alert.
      name: team_id
    - description: Title of the alert.
      name: title
    - description: Timestamp of the alert.
      name: ts
    - description: Order of the returned alerts.
      name: ordering
    description: Searches for alerts in Perch.
    name: perch-search-alerts
    outputs:
    - contextPath: Perch.Alert.DestPort
      description: Destination port of the alert.
      type: Number
    - contextPath: Perch.Alert.SrcPort
      description: Source port of the alert.
      type: Number
    - contextPath: Perch.Alert.DestIP
      description: Destination IP of the alert.
      type: Number
    - contextPath: Perch.Alert.IndicatorID
      description: Indicator ID of the alert.
      type: Number
    - contextPath: Perch.Alert.SrcIP
      description: IP address of the source.
      type: String
    - contextPath: Perch.Alert.SrcGeo.Country
      description: Country of the threat.
      type: String
    - contextPath: Perch.Alert.SrcGeo.Latitude
      description: Latitude of the detected threat.
      type: Number
    - contextPath: Perch.Alert.SrcGeo.Longitude
      description: Longitude of the detected threat.
      type: Number
    - contextPath: Perch.Alert.SensorID
      description: ID of the sensor that reported the threat.
      type: Number
    - contextPath: Perch.Alert.Title
      description: Title of the alert.
      type: String
    - contextPath: Perch.Alert.Protocol
      description: Protocol on which the alert was detected.
      type: String
    - contextPath: Perch.Alert.ID
      description: ID of the alert.
      type: Number
    - contextPath: Perch.Alert.ObservableID
      description: ID of the observable event.
      type: Number
    - contextPath: Perch.Alert.TS
      description: Timestamp of the alert.
      type: Date
  - arguments:
    - description: ID of the community.
      name: id
      required: true
    description: Gets community information by ID.
    name: perch-get-community
    outputs:
    - contextPath: Perch.Community.Allsectors
      description: Indicates if the community covers all sectors.
      type: Boolean
    - contextPath: Perch.Community.Credentialreq
      description: Credentials required to interact with the community.
      type: Number
    - contextPath: Perch.Community.Desc
      description: Description of the community.
      type: String
    - contextPath: Perch.Community.Id
      description: ID of the community.
      type: Number
    - contextPath: Perch.Community.Name
      description: Name of the community.
      type: String
    - contextPath: Perch.Community.Poweredby
      description: Organization providing the feed.
      type: String
    - contextPath: Perch.Community.Selectablefeeds
      description: Whether the feeds are selectable.
      type: Boolean
  - description: Lists all communities.
    name: perch-list-communities
    outputs:
    - contextPath: Perch.Community.Allsectors
      description: Indicates if the community covers all sectors.
      type: Boolean
    - contextPath: Perch.Community.Credentialreq
      description: Credentials required to interact with the community.
      type: Number
    - contextPath: Perch.Community.Desc
      description: Description of the community.
      type: String
    - contextPath: Perch.Community.Id
      description: ID of the community.
      type: Number
    - contextPath: Perch.Community.Name
      description: Name of the community.
      type: String
    - contextPath: Perch.Community.Poweredby
      description: Organization providing the feed.
      type: String
    - contextPath: Perch.Community.Selectablefeeds
      description: Whether the feeds are selectable.
      type: Boolean
  - arguments:
    - description: Communities to report the indicator to.
      name: communities
      required: true
    - auto: PREDEFINED
      description: Confidence of the findings.
      name: confidence
      predefined:
      - LOW
      - MEDIUM
      - HIGH
      required: true
    - auto: PREDEFINED
      description: Type of indicator.
      name: type
      predefined:
      - IP
      - Domain
      - URL
      - REGEX
      - File Hash
      required: true
    - description: The value of the indicator.
      name: value
      required: true
    - description: The title of the indicator.
      name: title
      required: true
    - description: Description of the indicator.
      name: description
      required: true
    - description: TLP of the Indicator.
      name: tlp
      required: true
    - description: Operator of the indicator.
      name: operator
    - description: When the indicator was first sighted.
      name: first_sighting
    - description: Sends a email with the summary of the indicator.
      name: email_summary
    description: Creates an indicator in Perch.
    name: perch-create-indicator
    outputs:
    - contextPath: Perch.Indicator.Confidence
      description: Confidence of the indicator.
      type: Unknown
    - contextPath: Perch.Indicator.UpdatedAt
      description: Date and time that the indicator was last updated.
      type: Date
    - contextPath: Perch.Indicator.TLP
      description: TLP of the Indicator.
      type: String
    - contextPath: Perch.Indicator.Title
      description: Title of the indicator.
      type: String
    - contextPath: Perch.Indicator.ID
      description: ID of the indicator.
      type: Number
    - contextPath: Perch.Indicator.CreatedAt
      description: Date that the indicator was created.
      type: Date
    - contextPath: Perch.Indicator.Team
      description: ID of the team.
      type: Number
    - contextPath: Perch.Indicator.PerchID
      description: The Perch ID for the incident.
      type: String
    - contextPath: Perch.Indicator.CreatedBy
      description: ID of user that created the incident.
      type: Number
  dockerimage: demisto/python3:3.12.13.10116658
  isfetch: true
  runonce: false
  script: '-'
  subtype: python3
  type: python
tests:
- Perch-Test
fromversion: 5.0.0