# Actions

These are a collection of endpoints that allow you to interact with incidents.

# Acknowledge Incident

POST /api/v1/incident/acknowledge

Acknowledge a specified incident.

Required Parameters

auth_token string
A valid auth token
incident string
A valid incident key

Response

JSON structure with result indicator.

Example

    Response
    {
      "action": "acknowledged",
      "key": "<incident_key>",
      "result": "success"
    }
    
    1
    2
    3
    4
    5

    # Delete Incident

    DELETE /api/v1/incident/delete

    Deletes a specified incident.

    Required Parameters

    auth_token string
    A valid auth token
    incident string
    A valid incident key

    Response

    JSON structure with result indicator.

    Example

      Response
      {
        "action": "deleted",
        "key": "<incident_key>",
        "result": "success"
      }
      
      1
      2
      3
      4
      5

      # Fetch Incident

      GET /api/v1/incident/fetch

      Retrieve a specified incident.

      Required Parameters

      auth_token string
      A valid auth token

      Optional Parameters

      incident string
      A valid incident key
      hash_id string
      A valid incident hash
      extended_details boolean
      Return all incident fields
      tz string
      Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone

      TIP

      Either incident or hash_id is required.

      Response

      JSON structure containing the specified incident.

      Example

        Response
        {
          "incident": {
            "acknowledged": "False",
            "created": "1586260854",
            "created_std": "2020-04-07 12:00:54 UTC+0000",
            "description": "Telnet Login Attempt",
            "dst_host": "<destination_ip>",
            "dst_port": "23",
            "events": [
              {
                "PASSWORD": "<password>",
                "TERMSIZE": "91x44",
                "TERMTYPE": "XTERM-256COLOR",
                "USERNAME": "<username>",
                "timestamp": 1586260854,
                "timestamp_std": "2020-04-07 12:00:54 UTC+0000"
              },
            ],
            "events_count": "3",
            "id": "<incident_key>",
            "ip_address": "",
            "ippers": "",
            "local_time": "2020-04-07 12:00:53",
            "logtype": "6001",
            "mac_address": "",
            "node_id": "<node_id>",
            "notified": "False",
            "src_host": "<source_ip>",
            "src_host_reverse": "<source_hostname>",
            "src_port": "54968"
          },
          "result": "success"
        }
        
        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33

        # Unacknowledge Incident

        POST /api/v1/incident/unacknowledge

        Unacknowledge a specified incident.

        Required Parameters

        auth_token string
        A valid auth token
        incident string
        A valid incident key

        Response

        JSON structure with result indicator.

        Example

          Response
          {
            "action": "unacknowledged",
            "key": "<incident_key>",
            "result": "success"
          }
          
          1
          2
          3
          4
          5

          # Acknowledge Multiple Incidents

          POST /api/v1/incidents/acknowledge

          Acknowledge multiple incidents.

          Required Parameters

          auth_token string
          A valid auth token

          Optional Parameters

          flock_id string
          Acknowledge incidents for a specific flock
          node_id string
          Acknowledge incidents for a specific node (cannot be used in conjunction with src_host)
          src_host string
          Acknowledge incidents for a specific source IP address (cannot be used in conjunction with node_id)
          older_than string
          Acknowledge incidents older than the provided period. Periods are "[quantity][unit]", where "[unit]" is one of 'h', 'd', 'w' (hours, days or weeks) e.g. 1h or 1d or 1w
          filter_str string
          The string used when searching for incidents to be acknowledged. This string will attempt to match against incident details such as Source IP, Canary Name, Token Name, NodeID and Reverse IP Lookup.
          filter_logtypes string
          The logtype of the incidents to be acknowledged

          TIP

          At least one of the optional parameters is required.

          Response

          JSON structure with result indicator.

          Example

            Response
            {
              "action": "acknowledged",
              "keys": [
                "<incident_key>",
                "<incident_key>",
                "<incident_key>",
                "<incident_key>",
                "<incident_key>",
                "<incident_key>",
                "<incident_key>"
              ],
              "result": "success"
            }
            
            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13

            # Delete Multiple Incidents

            DELETE /api/v1/incidents/delete

            Delete multiple acknowledged incidents.

            Required Parameters

            auth_token string
            A valid auth token

            Optional Parameters

            flock_id string
            Delete incidents for a specific flock
            node_id string
            Delete incidents for a specific node (cannot be used in conjunction with src_host)
            src_host string
            Delete incidents for a specific source IP address (cannot be used in conjunction with src_host)
            older_than string
            Delete incidents older than the provided period. Periods are "[quantity][unit]", where "[unit]" is one of 'h', 'd', 'w' (hours, days or weeks) e.g. 1h or 1d or 1w
            filter_str string
            The string used when searching for incidents to be deleted. This string will attempt to match against incident details such
            filter_logtypes string
            The logtype of the incidents to be deleted
            include_unacknowledged boolean
            Include unacknowledged incidents when deleting

            TIP

            At least one of the optional parameters is required.

            Response

            JSON structure with result indicator.

            Example

              Response
              {
                "action": "deleted",
                "keys": [
                  "<incident_key>",
                  "<incident_key>",
                  "<incident_key>",
                  "<incident_key>"
                ],
                "result": "success"
              }
              
              1
              2
              3
              4
              5
              6
              7
              8
              9
              10

              # Unacknowledge Multiple Incidents

              POST /api/v1/incidents/unacknowledge

              Unacknowledge multiple incidents.

              Required Parameters

              auth_token string
              A valid auth token

              Optional Parameters

              flock_id string
              Unacknowledge incidents for a specific flock
              node_id string
              Unacknowledge incidents for a specific node (cannot be used in conjunction with src_host)
              src_host string
              Unacknowledge incidents for a specific source IP address (cannot be used in conjunction with src_host)
              older_than string
              Unacknowledge incidents older than the provided period. Periods are "[quantity][unit]", where "[unit]" is one of 'h', 'd', 'w' (hours, days or weeks) e.g. 1h or 1d or 1w
              filter_str string
              The string used when searching for incidents to be unacknowledged. This string will attempt to match against incident details such
              filter_logtypes string
              The logtype of the incidents to be unacknowledged

              TIP

              At least one of the optional parameters is required.

              Response

              JSON structure with result indicator.

              Example

                Response
                {
                  "action": "unacknowledged",
                  "keys": [
                    "<incident_key>",
                    "<incident_key>",
                    "<incident_key>",
                    "<incident_key>",
                    "<incident_key>",
                    "<incident_key>",
                    "<incident_key>"
                  ],
                  "result": "success"
                }
                
                1
                2
                3
                4
                5
                6
                7
                8
                9
                10
                11
                12
                13