VERISIGN OPENHYBRID CLOUD SIGNALLING API SPECIFICATION

Transcription

1 TECHNICAL PAPER VERISIGN OPENHYBRID CLOUD SIGNALLING API SPECIFICATION Version 1.0 January 2015 VerisignInc.com

2 LEGAL DISCLAIMER COPYRIGHT NOTIFICATION Copyright 2015 VeriSign, Inc. All rights reserved as an unpublished work. VERISIGN; the Verisign logo; and other trademarks, service marks and Verisign designs are registered or unregistered trademarks of VeriSign, Inc. and its subsidiaries in the United States and foreign countries. Copyright laws and international treaties protect this document and any Verisign product to which it relates. VERISIGN PROPRIETARY INFORMATION This document is the property of VeriSign, Inc. It may be used by the recipient only for the purpose for which it was transmitted and will be returned upon request or when no longer needed by the recipient. It may not be copied or communicated without the prior written consent of Verisign. DISCLAIMER AND LIMITATION OF LIABILITY VeriSign, Inc. has made efforts to ensure the accuracy and completeness of the information in this document. However, VeriSign, Inc. makes no warranties of any kind (whether express, implied or statutory) with respect to the information contained herein. VeriSign, Inc. assumes no liability to any party for any loss or damage (whether direct or indirect) caused by any errors, omissions or statements of any kind contained in this document. Further, VeriSign, Inc. assumes no liability arising from the application or use of the product or service described herein and specifically disclaims any representation that the products or services described herein do not infringe upon any existing or future intellectual property rights. Nothing herein grants the reader any license to make, use or sell equipment or products constructed in accordance with this document. Finally, all rights and privileges related to any intellectual property right described herein are vested in the patent, trademark or service mark owner and no other person may exercise such rights without express permission, authority or license secured from the patent, trademark or service mark owner. Verisign reserves the right to make changes to any information herein without further notice. NOTICE AND CAUTION Concerning U.S. Patent or Trademark Rights Verisign and other trademarks, service marks and logos are registered or unregistered trademarks of Verisign and its subsidiaries in the United States and in foreign countries. The inclusion in this document, the associated on-line file or the associated software of any information covered by any other patent, trademark or service mark rights does not constitute nor imply a grant of or authority to exercise, any right or privilege protected by such patent, trademark or service mark. All such rights and privileges are vested in the patent, trademark or service mark owner and no other person may exercise such rights without express permission, authority or license secured from the patent, trademark or service mark owner. 2 Verisign Public Verisign OpenHybrid Cloud Signalling API Specification

3 CONTENTS 1 OVERVIEW API Specification API Authentication Model API Call Rate Limits POST Alert RESTful API POST IP Lists RESTful API 6 2 USE CASES Signal threat activity from on-premise DDoS appliance Signal threat activity from on-premise network or security appliances Signal performance impact from public cloud environments or purpose-built monitoring platforms Future Enhancements 8 REVISION HISTORY Revision Date Author(s) Description 1.0 Verisign Public Verisign OpenHybrid Cloud Signalling API Specification 3

4 1 OVERVIEW This document defines a method by which a device or application may share information relating to DDoS attacks to other devices, applications or services such as a Cloud DDoS protection service. This method will allow for a standards-based, vendor-agnostic approach to DDoS threat mitigation utilising multiple layers of protection to respond to the DDoS threat. The dissemination of threat information will occur utilising RESTful communications between devices/ applications via a Restful API. 1.1 API Specification DDoS attacks cause resource exhaustion at multiple layers within a customer s environment affecting devices, applications and services. These elements may be required from time to time to signal to an upstream component or provider that the resource is under exhaustion and necessary action may be needed to respond to the on-going threat. The POST Alert API is designed to signal the resource exhaustion and the need for a mitigative response by sending appropriate information about the affected resource and attack parameters. The POST IP Lists API is designed to send the upstream component or provider a list of IPs that should be white or black listed when a mitigation is performed on behalf of the source. 1.2 API Authentication Model When using this RESTful API the suggested form of Authentication is via an OAuth 2.0 access token or an API key. In addition, a unique Source ID should be provided to identify the device/application sending the request. 1.3 API Call Rate Limits To ensure the receiving service is not overwhelmed with signal requests, it is generally recommended to implement a rate limit such as no more than 100 requests per minute per user. 1.4 POST Alert RESTful API The Post Alert API includes information on the type of threat/attack and the service/destination impacted. The suggested format for the API parameters is JSON and the date/time format is UTC. Method: POST Request: Parameters for this request. 4 Verisign Public Verisign OpenHybrid Cloud Signalling API Specification

5 Name Type Required Default Value Description source_id string true A string that uniquely identifies the source sending the request. Examples of sources include on-premise DDoS devices, firewalls or load balancers or devices in a cloud environment where the service/destination is being hosted. incident_id string true A string that uniquely identifies the alert from a given source. alert_type string false Description of the type of attack that caused the alert. This data will assist in the mitigation of the attack. start_time string true The start time of the attack. source_ip(s) string false 1 or more IPs/CIDRs that are sending traffic to destination. (suggest limiting to 60 characters). destination string true Either the Domain Name, IP or CIDR of the service/ application that is receiving the traffic and needs protection. destination_ port destination_ protocol integer false The port of the customer service/application that is receiving the traffic (suggest between 0 to 65535). integer false The protocol impacted by the attack. misc_info string false Information that will be useful for the mitigation in the format of pipe delimited name value pairs. For example, providing threshold information to describe the impact of the attack on the service/ application: cpu_utilization_threshold:95 current_cpu_ utilization:98 bandwidth_usage_threshold:90 current_ bandwidth_usage:95. (suggest limiting the size of this field to 1,000 characters). Verisign Public Verisign OpenHybrid Cloud Signalling API Specification 5

6 Example Request: Method Request Body POST { source_id : acme1234, incident_id : , alert_type : SYN-FLOOD, start_time : :50:55, source_ips : 172.X.X.X, 173.X.X.X, destination : /24, destination_port : 80, destination_protocol : HTTP, misc_info : { cpu_utilization_threshold:95 current_cpu_ utilization:98 bandwidth_usage_threshold:90 current_bandwidth_usage:95 Response: Data alert_id Description Alert ID that uniquely identifies the Alert within the receiving device Example Response: Response Status HTTP Response Status Code Request Body Success 201 { alert_id : Error 400 { errors : [{ code : 400, message : source_id is required. ] 1.5 POST IP Lists RESTful API The Post IP Lists API includes information on the IPs that should be white or black listed when mitigating an attack. The suggested format for the API parameters is JSON. Method: POST Request: Parameters for this request. 6 Verisign Public Verisign OpenHybrid Cloud Signalling API Specification

7 Name Type Required Default Value Description source_id string false A string that uniquely identifies the source sending the request. Examples of sources include on-premise DDoS devices, firewalls or load balancers or devices in a cloud environment where the service/destination is being hosted. Providing this ID will allow the receiving service to link the list of IPs to a specific source so that attacks reported by that source will have the list applied during mitigation. type string true The type of the list being created. Values accepted are Blacklist or Whitelist. ips string true The IPs or prefixes that need to be utilised for the purpose mentioned in the type of the request. Example Request: Method Request Body POST { source_id : acme1234, type : Whitelist, ips : 11.x.x.x, 11.x.x.0/24, Response: Data iplist_id type Description An ID that uniquely identifies the list within the receiving device The type of list. Values are: Blacklist Whitelist Example Response: Response Status HTTP Response Status Code Request Body Success 201 { iplist_id : type : Whitelist: Error 400 { errors : [{ code : 400, message : IP addresses invalid. ] Verisign Public Verisign OpenHybrid Cloud Signalling API Specification 7

8 2 USE CASES 2.1 Signal threat activity from on-premise DDoS appliance On-premise DDoS appliances that integrate with this API can send threat signals to cloud providers about an ongoing DDoS attack reaching a threshold. This would necessitate the need for the cloud provider to step in and take over the DDoS mitigation and bring to effect the scale required to deal with volumetric DDoS attacks. 2.2 Signal threat activity from on-premise network or security appliances On-premise devices such as Routers, Firewalls, IDS/IPS etc. typically are not designed to withstand volumetric DDoS attack activity and can get easily exhausted. Integrating with the API can allow customers to send signals from various layers within their network environment thereby achieving more comprehensive security posture. 2.3 Signal performance impact from public cloud environments or purpose-built monitoring platforms Customers with services or applications deployed in public cloud environments or in data centres can utilise the API to integrate with their existing monitoring services and indicate performance impact due to a potential DDoS activity. This would signal to the upstream cloud protection provider to take the necessary action to mitigate the threat. 2.4 Future Enhancements API can be further enhanced to signal more advanced information related to on-going threats such as details about on-going attack counter-measures being applied etc. 8 Verisign Public Verisign OpenHybrid Cloud Signalling API Specification

9 NOTES Verisign Public Verisign OpenHybrid Cloud Signalling API Specification 9

10 VerisignInc.com 2015 VeriSign, Inc. All rights reserved. VERISIGN and other trademarks, service marks and designs are registered or unregistered trademarks of VeriSign, Inc. and its subsidiaries in the United States and in other countries. All other trademarks are property of their respective owners. Verisign Public VRSN_DDoS-PS_CloudSignAPI_Specs_201501