openapi: 3.0.0
info:
  version: 1.0.0
  title: Secure Endpoint Actions API v1
servers:
  - url: https://api.amp.cisco.com
  - url: https://api.apjc.amp.cisco.com
  - url: https://api.consumer.amp.cisco.com
  - url: https://api.eu.amp.cisco.com
paths:
  /v1/events:
    get:
      summary: Fetch list of events
      description: >
        This is a general query interface for events. This is analogous to
        the Events view on the Cisco Secure Endpoint Console.


        Events can be filtered by a variety of criteria. Each criteria type is logically ANDed with the other criteria; each selection of a criteria is logically ORed. For example: with the query string: `connector_guid[]=ead39d47-93bd-4230-b692-454b433faf96&event_type[]=2164260868&event_type[]=1090519054`, it will return any events that match the connector guid ad39d47-93bd-4230-b692-454b433faf96 AND any events with type (1090519054 OR 2164260868).


        The arguments passed to the `event_type` and `group_guid` parameters can be retrieved from their respective endpoints.
      tags:
        - Event
      security:
        - basicAuth: []
      parameters:
        - in: query
          name: event_type
          schema:
            type: number
        - in: query
          name: limit
          schema:
            type: number
        - in: query
          name: start_date
          schema:
            type: string
            format: date
        - in: query
          name: offset
          schema:
            type: number
        - in: query
          name: detection_sha256
          schema:
            type: string
        - in: query
          name: application_sha256
          schema:
            type: string
        - in: query
          name: group_guid
          schema:
            type: string
            format: uuid
        - in: query
          name: connector_guid
          schema:
            type: string
            format: uuid
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  metadata:
                    $ref: "#/components/schemas/Metadata"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        timestamp:
                          type: integer
                        timestamp_nanoseconds:
                          type: integer
                        date:
                          type: string
                          format: date-time
                        event_type:
                          type: string
                        event_type_id:
                          type: integer
                        detection:
                          type: string
                        detection_id:
                          type: string
                        connector_guid:
                          type: string
                        group_guids:
                          type: array
                          items:
                            type: string
                        severity:
                          type: string
                        computer:
                          type: object
                          properties:
                            connector_guid:
                              type: string
                            hostname:
                              type: string
                            external_ip:
                              type: string
                              format: ip-address
                            user:
                              type: string
                            active:
                              type: boolean
                            network_addresses:
                              type: array
                              items:
                                type: object
                                properties:
                                  ip:
                                    type: string
                                    format: ip-address
                                  mac:
                                    type: string
                                    format: style
                            links:
                              type: object
                              properties:
                                computer:
                                  type: string
                                  format: uri
                                trajectory:
                                  type: string
                                  format: uri
                                group:
                                  type: string
                                  format: uri
                        file:
                          type: object
                          properties:
                            disposition:
                              type: string
                            file_name:
                              type: string
                            file_path:
                              type: string
                              format: style
                            identity:
                              type: object
                              properties:
                                sha256:
                                  type: string
                                sha1:
                                  type: string
                                md5:
                                  type: string
                            parent:
                              type: object
                              properties:
                                process_id:
                                  type: integer
                                disposition:
                                  type: string
                                file_name:
                                  type: string
                                identity:
                                  type: object
                                  properties:
                                    sha256:
                                      type: string
                                    sha1:
                                      type: string
                                    md5:
                                      type: string
                        tactics:
                          type: array
                          items:
                            type: string
                        techniques:
                          type: array
                          items:
                            type: string
              example:
                version: v1.2.0
                metadata:
                  links:
                    self: https://api.amp.cisco.com/v1/events?limit=2
                    next: https://api.amp.cisco.com/v1/events?limit=2&offset=2
                  results:
                    total: 1165
                    current_item_count: 2
                    index: 0
                    items_per_page: 2
                data:
                  - id: 6180351977805840000
                    timestamp: 1647602406
                    timestamp_nanoseconds: 548000000
                    date: 2022-03-18T11:20:06+00:00
                    event_type: Threat Detected
                    event_type_id: 1090519054
                    detection: W32.GenericKD:ZVETJ.18gs.1201
                    detection_id: "6180351977805840385"
                    connector_guid: 538738f5-3a14-4449-933b-86142553de06
                    group_guids:
                      - e766a0e9-96da-41b9-b1e8-87dd010d6b68
                    severity: Medium
                    computer:
                      connector_guid: 538738f5-3a14-4449-933b-86142553de06
                      hostname: Demo_Upatre
                      external_ip: xxx.xxx.xxx.xxx
                      user: A@TEMPLATE-W7X86
                      active: true
                      network_addresses:
                        - ip: xxx.xxx.xxx.xxx
                          mac: xx:xx:xx:xx:xx:xx
                      links:
                        computer: https://api.amp.cisco.com/v1/computers/538738f5-3a14-4449-933b-86142553de06
                        trajectory: https://api.amp.cisco.com/v1/computers/538738f5-3a14-4449-933b-86142553de06/trajectory
                        group: https://api.amp.cisco.com/v1/groups/b077d6bc-bbdf-42f7-8838-a06053fbd98a
                    file:
                      disposition: Malicious
                      file_name: wsymqyv90.exe
                      file_path: \\?\C:\Users\Administrator\AppData\Local\Temp\OUTLOOK_TEMP\wsymqyv90.exe
                      identity:
                        sha256: b630e72639cc7340620adb0cfc26332ec52fe8867b769695f2d25718d68b1b40
                        sha1: 70aef829bec17195e6c8ec0e6cba0ed39f97ba48
                        md5: e2f5dcd966e26d54329e8d79c7201652
                      parent:
                        process_id: 4040
                        disposition: Clean
                        file_name: iexplore.exe
                        identity:
                          sha256: b4e5c2775de098946b4e11aba138b89d42b88c1dbd4d5ec879ef6919bf018132
                          sha1: 8de30174cebc8732f1ba961e7d93fe5549495a80
                          md5: b3581f426dc500a51091cdd5bacf0454
                    tactics:
                      - TA0042
                    techniques:
                      - T1204.003
          description: Fetch list of Behavioral Protection Detection events
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    Metadata:
      type: object
      required:
        - links
      properties:
        links:
          type: object
          required:
            - self
          properties:
            self:
              type: string
            next:
              type: string
        results:
          type: object
          properties:
            total:
              type: integer
            current_item_count:
              type: integer
            index:
              type: integer
            items_per_page:
              type: integer
  parameters:
    limitParam:
      in: query
      name: limit
      schema:
        type: integer
        description: Limit the number of items to return
    offsetParam:
      in: query
      name: offset
      schema:
        type: integer
        description: Offset of items to return
    groupGuidParam:
      in: query
      name: group_guid
      schema:
        type: string
        format: uuid
        description: Group GUID
security:
  - basicAuth: []
