API Documentation. Introduction. General request structure. Authentication. Account and Site Identifiers. Name Description Optional

Transcription

1 API Documentation Introduction Incapsula provides customers and partners with the ability to manage accounts and sites via an API. The API has the following characteristics: Requests are HTTP POST Parameters are specified in the request body in HTML form style, e.g: param1=value1&param2=value2 All requests are in SSL Response content is provided as a JSON document UTF-8 encoding is always used General request structure Authentication In order to use the API, the client must be authenticated by Incapsula. Authentication is accomplished using two request parameters, for example: api_id=<12345>&api_key=<1234kj-34kj4-lkjdf9823> Account and Site Identifiers Most API operations operate on a specific account or site. Use the following parameters to specify the account or site to operate on: Name Description Optional account_id Numeric identifier of the account to operate on

2 Name Description Optional site_id Numeric identifier of the site to operate on. Pagination Some API operations may return a list of objects. Use the following parameters to enable paging: Name Description Optional page_size The number of objects to return in the response. Defaults to 50. page_num The page to return starting from 0. Default to 0. General Response Structure Every response contains the following fields in the returned JSON document: Name Description Optional res The numeric result code for the operation. A result code of 0 indicates success. res_message The textual representation of the result code (for example: "OK" - for success) debug_info General information which is not strictly required for using the API, but is helpful to have

3 For example: "res": 0, "res_message": "OK", "debug_info": } } General error codes Code Description Comment 1 Unexpected error api.response.comment.1 2 Invalid input Input missing or incorrect 9411 Authentication missing or invalid Authentication parameters missing or incorrect 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it 9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it 9414 Feature not permitted Feature is not available on account's plan. Contact support Operation not allowed The requested operation is not allowed. Contact support.

4 Specifying time range Specifying time range Some operations require the user to specify a time range. This is done via the time_range parameter, which takes the following values: Name Description today Retrieve data from midnight today until the current time last_7_days Retrieve data from midnight of 7 days ago until the current time last_30_days Retrieve data from midnight of 30 days ago until the current time last_90_days Retrieve data from midnight od 90 days ago until the current time month_to_date Retrieve data from midnight of the first day of the month until the current time custom Specify a custom time range using two additional parameters: start and end Note the following: If a time range is not specified, today is selected by default. All dates should be specified as number of milliseconds since midnight 1970 (UNIX time * 1000). See: Some time ranges may not be allowed since customer is not on a supporting plan Add a new managed account Available only to Reseller accounts

5 Use this operation to add a new account that should be managed by the account of the API client (the parent account). The new account will be configured according to the preferences set for the parent account by Incapsula. Depending on these preferences, an activation will be sent to the specified address. After the user responds to this activation and selects a password, she can log directly into the Incapsula console. The same address can also be used to send system notifications to the account. The new account is identified by a numeric value as provided by Incapsula in the response in field account_id. /api/prov/v1/accounts/add Parameters: Name Description Optional api_id api_key address, for example: "[email protected]" user_name The account owner's name, for example: "John Doe" plan_id An identifier of the plan to assign to the new account. ref_id Customer specific identifier for this operation. account_name Account name. Response structure: "account": " ":"[email protected]", "plan_id":34,

6 "account_id":4722, "user_name":"john Doe", "account_name":"demo Account", "logins": "login_id":1243, " _verified":true } }, "res":0, "res_message":"ok" } Specific error codes: Code Description Comment invalid Malformed, missing or empty parameter 1003 Plan ID invalid The specified plan is missing, invalid or not allowed Account exists The specified address is already associated with an account Live Test List managed accounts Available only to Reseller accounts Use this operation to get the list of accounts that are managed by acocunt of the API client (the parent account).

7 /api/prov/v1/accounts/list Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on. If not specified, operation will be performed on the account identified by the authentication parameters. page_size The number of objects to return in the response. Defaults to 50. page_num The page to return starting from 0. Default to 0. Response structure: "accounts":[ "parent_id":123, "plan_id":34, "account_id":4722, "user_name":"john Doe", "account_name":"demo Account", "logins":

8 "login_id":1243, " _verified":true } },...], "res":0, "res_message":"ok" } Live Test Get account status Available only to Reseller accounts Use this operation to get information about the account of the API client or one of its managed accounts. /api/prov/v1/account Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on. If not specified, operation will be performed on the account identified by the authentication parameters. Response structure:

9 "account": "plan_id":34, "plan_name":"enterprise", "trial_end_date":"may 28, 2014", "account_id":4722, "ref_id":"123456", "user_name":"john Doe", "account_name":"demo Account", "logins": "login_id":1243, " _verified":true } }, "res":0, "res_message":"ok" } Live Test Modify account configuration Available only to Reseller accounts Use this operation to change the configuration of the account of the API client or one of its managed accounts. /api/prov/v1/accounts/configure

10 Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on. If not specified, operation will be performed on the account identified by the authentication parameters. param Name of configuration parameter to set, one of: name plan_id error_page_template value According to the param. For name - the updated name, for e- mail - the updated address, for plan_id - a plan id, for error_page_template - a Base64 encoded template for an error page Response structure: "res": 0, "res_message": "OK", "debug_info": " ": "[email protected]" } } Specific error codes:

11 Code Description Comment 6001 Invalid configuration parameter name The specified parameter name is missing or invalid 6002 Invalid configuration parameter value The specified parameter value is missing or invalid Live Test Get account login token Tokens are used instead of user/password based authentication to login to the Incapsula management console. Use this operation to generate a token for an account. In order to use the token, the user must follow the following link: It is also possible to generate tokens by yourself, without making an API call. Contact Incapsula support for details. The generated token is valid for 24 hours. /api/prov/v1/accounts/gettoken Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on. If not specified, operation will be performed on the account identified by the authentication parameters. Response structure:

12 "res": 0, "res_message": "OK", "generated_token": "344ebcaf34dff34" } Live Test Delete managed account Available only to Reseller accounts Use this operation to delete an account. /api/prov/v1/accounts/delete Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on Response structure: "res": 0, "res_message": "OK" }

13 Live Test Get account audit events Available only to Reseller accounts Use this operation to get audit events for an account. /api/prov/v1/accounts/audit Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on. If not specified, operation will be performed on the account identified by the authentication parameters. time_range Time range to fetch data for. See the introduction of the API documentation for a detailed description start Start date in milliseconds since See the introduction of the API documentation for a detailed description end End date in milliseconds since See the introduction of the API documentation for a detailed description type The api key of the event type, e.g.: audit.account_login

14 Name Description Optional page_size The number of objects to return in the response. Defaults to 50. page_num The page to return starting from 0. Default to 0. Response structure: "audit_events":[ "createdat": , "account_id":"278", "user_id":"1", "type_key":"audit.site_acl_change", "type_description":"acl changed", "context":"gui", "site_id":"26688", "changes":"acl was changed" },... ], "res": 0, "res_message": "OK" } Site Management Introduction

15 Use the following operations to add, remove and update sites. The process of adding a site to the service depends on whether the site requires SSL support. If the site requires SSL support, Incapsula needs to generate a proxy SSL certificate on your behalf, which requires your approval and action. Once a site is added, its status is one of the following: Name Description A site with SSL support was added. Domain approval needs to be selected or a new domain validation method should be selected. The site owner needs to approve the SSL certificate generation by completing a domain validation action (following a link in the approval , DNS change, adding an HTML meta tag, adding a new file, etc.) The site is ready for the user to perform the required DNS changes in order to be fully configured on the service pending-selectapprover pendingcertificate pending-dnschanges fullyconfigured Site is active on the Incapsula network Steps to add a non-ssl site: 1. Call the Add Site operation. A successful response will contain the required DNS changes. Site is in pending-dns-changes state. 2. Perform the DNS changes. The system will detect the DNS changes in a few minutes and will set the site to fully-configured state. 3. Call the Get site status operation periodically until the site is in fully-configured state. Steps to add an SSL site: Prerequise: Incapsula must verify that HTTPS is supported by your site, in order to support SSL for your site. 1. Call the Add Site operation. Site is in pending-select-approver state. 2. To continue with based domain validation: 1. Call the Modify site configuration operation and set the SSL domain validation method to Call the Retrieve domain approval s operation and select an address from the list. 3. Call the Modify site configuration operation and set the selected address. The system will send the certificate generation approval and set the site to pending-certificate state. 3. To continue with HTML meta tag domain validation: 1. Call the Modify site configuration operation and set the SSL domain validation method to html. The operation will return the required HTML snippet to place in the homepage of the site and set the site to pending-certificate state. 2. Site owner needs to place the HTML snippet in the homepage of the site 3. Call the Get Site Status operation and use the tests parameter to verify that domain validation was performed successfully 4. To continue with DNS domain validation:

16 1. Call the Modify site configuration operation and set the SSL domain validation method to dns. The operation will return the required DNS records to set on the site's domain and set the site to pending-certificate state. 2. Site owner needs to set the DNS records on the site's domain 3. Call the Get Site Status operation and use the tests parameter to verify that domain validation was performed successfully 5. Call the Get site status operation periodically until the site is in pending-dns state. The required DNS changes will be provided in the response. 6. Perform the DNS changes. The system will detect the DNS changes in a few minutes and will set the site to fully-configured state. 7. Call the Get site status operation periodically until the site is in fully-configured state. Adding SSL to an existing site: 1. First, Verify that Incapsula has detected that HTTPS is supported by your site: 1. Call the Get Site Status operation and look for the 'detected' field under 'origin_server'. 2. If the 'detected' value is 'false', add the 'services' tests params and call the Get Site Status operation again. 3. Keep calling the Get Site Status operation until the 'detected' value changes to 'true'. 2. Call the Modify site configuration operation and set the SSL domain validation method. Then, continue according to the above flow. Live Test Add a site Add a new site to an account. If the site already exists, its status is returned. /api/prov/v1/sites/add Parameters: Name Description Optional api_id api_key domain The domain name of the site. For example: hello.example.com, example.com

17 Name Description Optional account_id Numeric identifier of the account to operate on. If not specified, operation will be performed on the account identified by the authentication parameters. ref_id Customer specific identifier for this operation. send_site_setup_ s If this value is "false", end users will not get s about the add site process such as "DNS instructions" and "SSL setup" site_ip Manually set the web server IP. This option is only available for specific accounts. Please contact support for more details. force_ssl Manually set the site to support SSL. This option is only available for specific accounts. Please contact support for more details. Required DNS changes: The dns section of the respones contains the list of required DNS changes. Each entry contains the following parameters: Name Description dns_record_name Name of a DNS record to which needs to be set set_type_to The type of DNS record to set, one of: CNAME A. Note: any existing CNAME or A records defined for the specified

18 Name Description DNS_record_name should be removed, but other types of DNS records (e.g. MX, TXT or SPF) should be kept. set_data_to The value to set for the CNAME or A record, typically an IP address or an Incapsula-owned domain name Site configuration warnings: This section contains non critical configurations warnings, while these warings are present your site will still be under Incapsula service. Name Description FTP records Your ftp records are pointing directly to your server instead of Incapsula. set_type_to Your mail records are pointing directly to your server instead of Incapsula. Response Structure: Same as Get Site Status Specific error codes: Code Description Comment 3001 Domain invalid Malformed, missing or empty domain field 3002 Site is on the CloudFlare network Site is on the CloudFlare network and cannot be added. In order to add the site, disable its records on CloudFlare, wait a few minutes for the changes to take effect and try again.

19 Code Description Comment 3003 Site requires SSL Site requires SSL traffic but the account is not on a supporting plan. To add the site first upgrade your plan in the management console Domain belongs to a known service Site cannot be added since the domain belongs to a known service. Add the site's real domain instead Site is on a service (CDN, load-balaner, etc.) that is not supported by the plan of the account. Site is on a service but account is not on a supporting plan. To add the site first upgrade your plan in the management console Site requires multiple IPs support Site requires multiple IPs support but the account is not on a supporting plan. The site was added with a single IP. To enable multiple IPs support upgrade your plan in the management console Site unresolvable No DNS entry exists for this site 3012 Site unreachable Cannot connect to site, so no information can be retrieved regarding SSL status. Note that the site will still be created Site already protected by the service This site already exists on a different account Number of allowed sites exceeded. Account has reached the maximum number of sites. To add an additional site first upgrade your plan.

20 Code Description Comment 3015 Internal error Internal error, please try again. Live Test Get site status Use this operation to get the status of a site. /api/prov/v1/sites/status Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. tests List of tests to run on site before returning its status. A comma separated list of one of: domain_validation, services. Response structure: "res": 0, "res_message": "OK", "status": "pending_dns_changes", "ips": [ " " ],

21 "dns": [ "dns_record_name": " "set_type_to": "CNAME", "set_data_to": "x343.incapdns.net" }, "dns_record_name": "example.com", "set_type_to": "A", "set_data_to": " " ], "original_dns":[ "dns_record_name":"example.com", "set_type_to":"a", "set_data_to":[ " " ] }, "dns_record_name":" "set_type_to":"a", "set_data_to":[ " " ] } ],

22 "warnings": [ "type":"ftp", "dns_record_name": "ftp.example.com", "set_type_to": "A", "set_data_to": " " }, "type":"mail", "mail_record_name": "mail.example.com", "set_type_to": "A", "set_data_to": " " } ], "security": "waf": "rules" : [ "id":"api.threats.bot_access_control", "name":"bot Access Control", "block_bad_bots":true, "challenge_suspected_bots":true },

23 "id":"api.threats.sql_injection", "name":"sql Injection", "action":"api.threats.action.block_request", "action_text":"block Request", }, "id":"api.threats.cross_site_scripting", "name":"cross Site Scripting (XSS)", "exceptions":[ "values":[ "urls":[ "value":"/gsddg", "pattern":"equals" } ], "id":"api.rule_exception_type.url", "name":"url" } ], "id": },...

24 ], "action":"api.threats.action.alert", "action_text":"alert Only", }, "id":"api.threats.illegal_resource_access", "name":"illegal Resource Access", "action":"api.threats.action.block_user", "action_text":"block User", }, "id":"api.threats.ddos", "name":"ddos", "activation_mode":"api.threats.ddos.activation_mode.off", "activation_mode_text":"off", "ddos_traffic_threshold":"api.threats.ddos.ddos_trassic_threshold", "ddos_traffic_threshold_text":"750", }, "id":"api.threats.backdoor", "name":"backdoor Protect", "action":"api.threats.action.quarantine_url", }, "action_text":"auto-quarantine",

25 "action":"api.threats.action.block_ip", "action_text":"block IP", "id":"api.threats.remote_file_inclusion", "name":"remote File Inclusion" } ] }, "acls": "rules":[ "ips":[ " " ], "exceptions":[ "values":[ "urls":[ "value":"/home", "pattern":"equals" } ], "id":"api.rule_exception_type.url",

26 "name":"url" },... ], "id": },... ], "id":"api.acl.blacklisted_ips", "name":"visitors from blacklisted IPs" },... ] } }, "active": "active", "acceleration_level": "advanced", "site_creation_date": "seallocation": "id":"api.seal_location.bottom_right", "name":"bottom right" }, "ssl" : // Example for case HTTPS support was detected on the site "origin_server": "detected":true,

27 "detectionstatus":"ok" }, // Example for case HTTPS support was not detected on the site "origin_server": "detected":false, "detectionstatus":"hostname_mismatch" }, // Example for HTML validation "generated_certificate" : "ca" : "globalsign", "validation_method" : "html", "validation_data" : "<meta name="globalsign-domainverification" content="rgwlwgf7wqsdwdhbd54pggruzskfmvezwmvnutrazw" />", } "san" : ["*.example.com", "example.com"], "validation_status" : "pending_user_action" // Example for DNS validation "generated_certificate" : "ca" : "globalsign", "validation_method" : "dns", "validation_data" : [ "dns_record_name": " "set_type_to": "TXT", "set_data_to": "globalsign-domainverification=rgwlwgf7wqsdwdhbd54pggruzskfmvezwmvnutrazw"},...

28 ], "san" : ["*.example.com", "example.com"], "validation_status" : "pending_user_action" } }, "login_protect": "enabled":true, "specific_users_list":[ " ":"[email protected]", "name":"john Doe", "status":"invitation_sent" }, " ":"[email protected]", "name":"jane Doe", "status":"activated" } ], "send_lp_notifications":true, "allow_all_users":false, "authentication_methods":[ "sms", "ga" ], "urls":[

29 "/wp-admin" ], "url_patterns":[ "PREFIX" ] }, "performance_configuration": "advanced_caching_rules": "never_cache_resources":[ "pattern":"suffix", "url":"/test.html" } ], "always_cache_resources":[ "pattern":"not_equals", "url":"/index.html", "ttl":5, "ttlunits":"seconds" }, "pattern":"equals", "url":"/home.html", "ttl":6, "ttlunits":"days"

30 } ] }, "acceleration_level":"advanced", "async_validation":true, "minify_javascript":true, "minify_css":true, "minify_static_html":true, "compress_jepg":true, "progressive_image_rendering":true, "aggressive_compression":true, "compress_png":true, "on_the_fly_compression":true, "tcp_pre_pooling":true, "comply_no_cache":true, "comply_vary":true, "use_shortest_caching":true, "perfer_last_modified":true, "accelerate_https":true, "disable_client_side_caching":true, "cache_headers":[ "headername":"content-type: application/pdf" } ] },

31 "res":0, "res_message":"ok" } Name Description status The current status of the site ips IP addresses or hostname of the site's servers dns The required DNS changes. Sent when the site is in pending_dns_changes or fully_configured status. warning A list of warnings regarding the configuration of the site. security The security settings of the site active A text string indicating whether the site is active or has been moved into bypass mode, one of: active bypass acceleration_level A text string indicating the acceleration level of the site, one of: off standard advanced site_creation_date The creation date of the site in milliseconds since 1970

32 Name Description seal_location The current location of the seal. One of: api.seal_location.bottom_left api.seal_location.none api.seal_location.right_bottom api.seal_location.right api.seal_location.left api.seal_location.bottom_right api.seal_location.bottom ssl Information regarding the SSL configuration of the site and the SSL configuration detected on the site origin server. For more details see below. login_protect The Login Protect configuration of the site. performance_configuration The performance configuration of the site. Details for the ssl.origin_server section: Name Description detected Incapsula detected HTTPS support on the site. detectionstatus HTTPS detection status/failure reason for site. Possible values for ssl.origin_server detectionstatus field: Name Description ok SSL detected

33 Name Description ssl_connection_not_established for example: no server certificate found hostname_mismatch Hostname in certificate did not match invalid_server_response Received an invalid response from server host_unreachable Could not reach host unclassified_error Received an unclassified error ssl_network_detection_not_run SSL network detection test did not run Details for the ssl.generated_certificate section: Name Description ca The certificate authority Incapsula is using to generate the certificate for the site. san The domain names that will be added to the certificate as part of the Subject Alternaitve Names section (SAN) validation_method The SSL domain validation method. One of: html dns.

34 Name Description validation_data For validation the selected approver address, for HTML validation the HTML snippet to use, for DNS validation the DNS records to set validation_data.set_type_to The type of DNS record to set, one of: CNAME TXT validation_status The status of the SSL domain validation process. One of: pending_user_action (system did not detect changes by site owner), pending_ca (system is waiting for the certificate authority to generate the certificate), pending_extended_validation (certificate authority has decided to perform an extended validation procedure, expect delay in certificate generation), done Live Test Get domain approver addresses Use this operation to get the list of addresses that can be used when adding an SSL site. /api/prov/v1/domain/ s Parameters: Name Description Optional api_id api_key

35 Name Description Optional domain The domain name of the site. For example: hello.example.com, example.com Response structure: "res": 0, "res_message": "OK", "domain_ s": [ "[email protected]", "[email protected]" ] } Specific error codes: Code Description Comment 3001 Domain invalid Malformed, missing or empty domain field 3011 Site unresolvable No DNS entry exists for this site Live Test Modify site configuration Use this operation to change one of the basic configuration settings of the site. /api/prov/v1/sites/configure Parameters:

36 Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. param Name of configuration parameter to set, see table below value According to the param value, see table below Name Description active Whether the site is active or bypassed by the Incpasula netowrk. One of: active bypass. site_ip Comma separated list of IPs. For example: , domain_validation Sets the domain validation method that will be used to generate an SSL certificate. One of: html dns approver Sets the approver address that will be used to perform SSL domain validation

37 Name Description ignore_ssl Sets the ignore SSL flag (if the site is in pending-selectapprover state). Pass "true" in the value parameter. acceleration_level Sets the acceleration level of the site, one of: none standard aggressive. It is advised to use the newer â œmodify Caching Modeâ API call instead, as it allows enhanced functionality. seal_location Sets the seal location, e.g. "api.seal_location.bottom_right" domain_redirect_to_full Sets the redirect naked to full flag, Pass "true" in the value parameter remove_ssl Sets the remove SSL from site flag, Pass "true" in the value parameter Response structure: "res": 0, "res_message": "OK", "debug_info": "domain_ ": } } Specific error codes:

38 Code Description Comment 6001 Invalid configuration parameter name The specified parameter name is missing or invalid 6002 Invalid configuration parameter value The specified parameter value is missing or invalid Live Test Modify site security configuration Use this operation to change the security configuration of a site. To modify the configuration for a specific rule, additional parameters may be required, as documented below. /api/prov/v1/sites/configure/security Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. rule_id ID of the security rule to change. For possible values see the security section in the Get Site Status API call.

39 Name Description Optional block_bad_bots Whether or not to block bad bots. One of: true, false challenge_suspected_bots Whether or not to send a challenge to clients that are suspected to be bad bots (CAPTCHA for example). One of: true, false activation_mode One of the following: off (security measures are disabled even if site is under a DDoS attack), auto (security measures will be activated automatically when the system suspects site is under a DDoS attack), on (security measures are enabled even if site is not under a DDoS attack). The syntax is as follows: api.threats.ddos.activation_mode.( e.g. for 'off', use 'api.threats.ddos.activation_mode.off' ). security_rule_action The action that should be taken when a threat is detected, for example: api.threats.action.block_ip. Different actions are allowed per different threats, e.g. backdoors may only be quarantined, ignored or trigger an alert. For possible values see below. quarantined_urls A comma seperated list of encoded URLs to be kept in quarantine ddos_traffic_threshold Consider site to be under DDoS if the request rate is above this threshold. The

40 Name Description Optional valid values are 10, 20, 50, 100, 200, 500, 750, 1000, 2000, 3000, 4000, Bot Access Control Request Example api_id=123 api_key=abcdefg rule_id=api.threats.bot_access_control block_bad_bots=true challenge_suspected_bots=true SQL Injection, Illegal Resource Access, Cross Site Scripting and Backdoor Protect Request Example: api_id=123 api_key=abcdefg rule_id=api.threats.sql_injection security_rule_action=api.threats.action.block_request Values for the security_rule_action parameter: Name Description api.threats.action.disabled Threat is not blocked, site owner is not notified. api.threats.action.alert Threat is not blocked, site owner is notified.

41 Name Description api.threats.action.block_request Threat blocked by stopping the request, site owner is notified. api.threats.action.block_user Threat blocked by stopping the request. Additional requests by the client application will be automatically blocked for a duration of several minutes. Site owner is notified. api.threats.action.block_ip Threat blocked by stopping the request. Additional requests from the same IP addresses will be automatically blocked for a duration of several minutes. Site owner is notified. api.threats.action.quarantine_url Relevant only for Backdoor Protect. When detecting a backdoor, additional requests to the URL of the backdoor will be automatically blocked. Site owner is notified. DDoS Request Example: api_id=123 api_key=abcdefg rule_id=api.threats.ddos activation_mode=api.threats.ddos.activation_mode.auto ddos_traffic_threshold=750 Response Structure: Same as Get Site Status Specific error codes:

42 Code Description Comment 9414 Feature not permitted Feature is not available on account's plan. Contact support. Live Test Modify site access control list (ACL) configuration Use this operation to change the ACL configuration of a site. To modify the configuration for a specific ACL rule, its values are required, as documented below. To delete an entire ACL list, send an empty string as the list values. /api/prov/v1/sites/configure/acl Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. rule_id The id of the acl, e.g api.acl.blacklisted_ips. See other examples below urls A comma separated list of resource paths. For example, /home and /admin/index.html are resource paths, however is not. Each URL should be encoded separately using percent encoding as specified by RFC 3986 ( An empty URL list will remove all URLs.

43 Name Description Optional url_patterns A comma seperated list of url patterns, one of: contains equals prefix suffix not_equals not_contain not_prefix not_suffix. The patterns should be in accordance with the matching urls sent by the urls parameter. countries A comma seperated list of country codes continents A comma seperated list of continent codes ips A comma seperated list of IPs or IP ranges, e.g: , or /24 Values for the rule_id parameter: Name Description api.acl.blacklisted_countries Visitors from blacklisted countries and/or continents api.acl.blacklisted_urls Visitors from blacklisted URLs api.acl.blacklisted_ips Visitors from blacklisted IPs api.acl.whitelisted_ips Visitors from whitelisted IPs Blacklisted URLs Example: api_id=123

44 api_key=abcdefg rule_id=api.acl.blacklisted_urls urls=%2fadmin%2fdashboard%2fstats%3fx%3d1%26y%3d2%23z%3d3,%2fadmin url_patterns=contains,equals Blacklisted Countries Example: api_id=123 api_key=abcdefg rule_id=api.acl.blacklisted_countries countries=ca,us continents=sa Blacklisted IPs Example: api_id=123 api_key=abcdefg rule_id=api.acl.blacklisted_ips ips= , , /24 Whitelisted IPs Example: api_id=123 api_key=abcdefg rule_id=api.acl.whitelisted_ips ips= Delete the IPs ACL Example (send an empty list of IPs): api_id=123 api_key=abcdefg rule_id=api.acl.blacklisted_ips

45 ips= Response Structure: Same as Get Site Status Live Test Modify whiltelists configuration Use this operation to set whitelists to security rules or ACLs. To update an existing whitelist, send its ID in the id parameter. If the id parameter does not exist a new whitelist will be created. /api/prov/v1/sites/configure/whitelists Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. rule_id The id of the rule (either a security or an acl rule), e.g api.acl.blacklisted_ips. See other examples below whitelist_id The id (an integer) of the whitelist to be set. This field is optional - in case no id is supplied, a new whitelist will be created delete_whitelist An optional boolean parameter, in case it is set to "true" and a whitelist id is sent, then the whitelist will be deleted

46 Name Description Optional urls A comma separated list of resource paths. For example, /home and /admin/index.html are resource paths, however is not. Each URL should be encoded separately using percent encoding as specified by RFC 3986 ( An empty URL list will remove all URLs. countries A comma seperated list of country codes continents A comma seperated list of continent codes ips A comma seperated list of IPs or IP ranges, e.g: , or /24 client_app_types A comma seperated list of client application types client_apps A comma seperated list of client application ids parameters A comma seperated list of encoded parameters user_agents A comma seperated list of encoded user agents The following API call adds a whitelist to the SQL injection security rule. SQL injections will not be handled for requests that are either the specified URLs, IPs and countries: api_id=123 api_key=abcdefg

47 rule_id=api.threats.sql_injection urls=%2fadmin%2fdashboard%2fstats%3fx%3d1%26y%3d2%23z%3d3,%2fadmin ips= , , /24 countries=gt,vn The following API call updates a whitelist to the countries acl. SQL injections will not be handled for requests that are from the specified countries: api_id=123 api_key=abcdefg rule_id=api.acl.blacklisted_countries whitelist_id= countries=ca,us continents=sa The following API call removes a whitelist whose id is : api_id=123 api_key=abcdefg rule_id=api.acl.blacklisted_urls whitelist_id= delete_whitelist=true Response Structure: Same as Get Site Status Live Test Delete site Delete the site /api/prov/v1/sites/delete Parameters:

48 Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. Response structure: "res": 0, "res_message": "OK" } Live Test List sites List sites for an account /api/prov/v1/sites/list Parameters: Name Description Optional api_id api_key

49 Name Description Optional account_id Numeric identifier of the account to operate on. If not specified, operation will be performed on the account identified by the authentication parameters. page_size The number of objects to return in the response. Defaults to 50. page_num The page to return starting from 0. Default to 0. Response structure: "res": 0, "res_message": "OK", "sites": [ Same as Get Site Status}, Same as Get Site Status},... ], "debug_info": } } Specific error codes:

50 Code Description Comment 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it Live Test Get site report Use this operation to get a report for a site. Reports are sent using Base64 encoding. /api/prov/v1/sites/report Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. report The report to get, one of: pci-compliance. format The format to get the report in, one of: pdf html time_range Time range to fetch data for. See the introduction of the API documentation for a detailed description

51 Name Description Optional start Start date in milliseconds since See the introduction of the API documentation for a detailed description end End date in milliseconds since See the introduction of the API documentation for a detailed description Response structure: "res": 0, "res_message": "OK", "format" : "pdf", "report" : "JVBERi0xLjUNCiXvv73vv73vv73vv70NCjEgMCBvYmoNCjw8L1R5cGUvQ2F0YWxvZy9QYWdl cyayidagui9myw5nkgvulvvt..." } Specific error codes: Code Description Comment 5001 Report invalid Requested report is missing, empty or malformed or the account is not on a supporting plan 5002 Format invalid Report format missing, empty, malformed or not supported by the specified report Live Test Purge site cache

52 Use this operation to purge all cached content on our proxy servers for a specific site. Our Proxy servers keep cached content of your sites in order to accelerate page load times for your users. When you want this cached content to be refreshed (for example, after making adjustments in your site) you can use this API call. In order to purge the entire cached content for this site just use the API call with no parameters. If you want to purge a specific resource add the resource name as parameter. /api/prov/v1/sites/cache/purge Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. purge_pattern The pattern of the resource to be purged from the cache. For example: (1) Resource_name - resources that contain Resource_name will be purged, (2) ^Resource_name - resources that start with Resource_name will be purged, and (3) Resource_name$ - resources that end with Resource_name will be purged. Response structure: "res": 0, "res_message": "OK" } Specific error codes:

53 Code Description Comment 5010 Pattern invalid The pattern should be of the form ^?.*$? Live Test Get HTML Injection Rules Use this operation to list all the HTML Injection rules /api/prov/v1/sites/htmlinjections Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. Response structure: "html_injections":[ "url":"/", "url_pattern":"prefix", "location":"head", "content":"some content" },

54 ... ], "res":0, "res_message":"ok" } Live Test Add or replace a HTML Injection rule Use this operation to add a new HTML injection rule or to replace and existing rule /api/prov/v1/sites/configure/htmlinjections Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. url The URL where the content is injected url_pattern The url pattern, one of: contains not_contains equals not_equals prefix suffix not_prefix not_suffix.

55 Name Description Optional location The location of the injection inside the URL ('head' or 'body_end') content The injected HTML snippet, Base64-encoded Response structure: Same as Get HTML Injection Rules The following API call adds the HTML content "Hello World!" to any URL containing "/index.php", in the beginning of the HEAD section. In case a content was already injected for the specified configuration, the existing will be replaced by "Hello World!". Note that the text itself is Base64 encoded. api_id=123 api_key=abcdefg url=/index.php url_pattern=contains location=head content=sgvsbg8gv29ybgqh Live Test Remove a HTML Injection rule Use this operation to remove an existing HTML injection rule. To confirm the removal, the parameter delete_content should be set to true. /api/prov/v1/sites/configure/htmlinjections Parameters:

56 Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. url The URL where the content is injected url_pattern The url pattern, one of: contains not_contains equals not_equals prefix suffix not_prefix not_suffix. location The location of the injection inside the URL ('head' or 'body_end') delete_content Should an existing HTML content be deleted Response structure: Same as Get HTML Injection Rules The following API call removes (if exists) the HTML content from any URL ending with ".php", found in the BODY section. The content itself does not have to be supplied, any content previously injected in the specified URL, URL pattern and Location will be removed. api_id=123 api_key=abcdefg url=.php url_pattern=ends_with location=body_end

57 delete_content=true Live Test Modify Caching Mode Use this operation to edit basic site caching settings. /api/prov/v1/sites/performance/cache-mode Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. cache_mode disable static_only static_and_dynamic aggressive : default Static_Only. dynamic_cache_duration Profile dynamic pages and cache duration, pass number followed by '_' and one of: hr min sec days weeks: default: 5_min. aggressive_cache_duration Cache resource duration, pass number followed by '_' and one of: hr min sec days weeks: default: 1_hr. Response structure:

58 "res": 0, "res_message": "OK" } Specific error codes: Code Description Comment 2 Invalid input Input missing or incorrect 9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it Live Test Purge Resources Use this operation to purge site resources. /api/prov/v1/sites/performance/purge Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on.

59 Name Description Optional resource_url Comma seperated list of URLs where the resource is located. resource_pattern Comma seperated list of pattern, one of: contains equals prefix suffix not_equals not_contains not_prefix not_suffix should_purge_all_site_resources Should purge all cached resources on site. Response structure: Same as Modify Caching Mode Specific error codes: Code Description Comment 2 Invalid input Input missing or incorrect 9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it 3015 Internal error Internal error, please try again. Live Test Modify Caching Rules Use this operation to set-up advanced caching rules

60 /api/prov/v1/sites/performance/caching-rules Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. always_cache_resource_url Comma seperated list of always cache resources url always_cache_resource_pattern Comma seperated list of always cache resources pattern, one of: contains equals prefix suffix not_equals not_contains not_prefix not_suffix always_cache_resource_duration Duration that resources will be in cache, pass number followed by '_' and one of: hr min sec days weeks. never_cache_resource_url Comma seperated list of never cache resources url never_cahce_resource_pattern Comma seperated list of never cache resources pattern, one of: contains equals prefix suffix

61 Name Description Optional not_equals not_contains not_prefix not_suffix cahce_headers Comma seperated list of cached headers seperated with comma. Response structure: Same as Modify Caching Mode Specific error codes: Code Description Comment 2 Invalid input Input missing or incorrect 9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it 3015 Internal error Internal error, please try again. Live Test Advanced Caching Settings Use this operation to modify advanced caching settings. /api/prov/v1/sites/performance/advanced Parameters:

62 Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. param Name of configuration parameter to set, see table below value According to the param value, see table below Name Description async_validation Sets Async validation. Pass "true" or "false" in the value parameter minify_javascript Sets the Minify JS. Pass "true" or "false" in the value parameter minify_css Sets the Minify CSS, Pass "true" or "false" in the value parameter minify_static_html Sets Minify static HTML, Pass "true" or "false" in the value parameter

63 Name Description compress_jpeg Sets the Compress JPEG. Pass "true" or "false" in the value parameter. progressive_image_rendering Sets the Progressive Image Rendering, Pass "true" or "false" in the value parameter aggressive_compression Sets the Aggressive compression(may impact quality) rendering flag Pass "true" or "false" in the value parameter compress_png Sets the Compress PNG flag, Pass "true" or "false" in the value parameter on_the_fly_compression "On the fly" Compression, Pass "true" or "false" in the value parameter tcp_pre_pooling TCP Pre-Pooling, Pass "true" or "false" in the value parameter comply_no_cahce Comply with no-cache and max-age directives in client requests, Pass "true" or "false" in the value parameter comply_vary Comply with Vary: User-Agent, Pass "true" or "false" in the value parameter use_shortest_caching Use shortest caching duration in case of conflicts, Pass "true" or "false" in the value parameter

64 Name Description perfer_last_modified Prefer 'last modified' over etag, Pass "true" or "false" in the value parameter accelerate_https Apply acceleration setting also to HTTPS, Pass "true" or "false" in the value parameter disable_client_side_caching Disable client side caching, Pass "true" or "false" in the value parameter Response structure: Same as Modify Caching Mode Specific error codes: Code Description Comment 6001 Invalid configuration parameter name The specified parameter name is missing or invalid 6002 Invalid configuration parameter value The specified parameter value is missing or invalid Live Test Purge Hostname from Cache Use this operation to purge the hostname from the cache. This API is for customers who use the same CNAME provided by Incapsula for multiple hostnames and would like to change the CNAME for a particular hostname. Purging the hostname is required for the CNAME change to take effect. /api/prov/v1/sites/hostname/purge Parameters:

65 Name Description Optional api_id api_key host_name The hostname to purge from cache Response structure: "res": 0, "res_message": "OK" } Specific error codes: Code Description Comment 2 Invalid input Input missing or incorrect 3015 Internal error Internal error, please try again Unauthorized domain The client is not authorized to purge this specified hostname Traffic Statistics and Details Use the following operations to retrieve traffic statistics and logs for sites or accounts. Data can be fetched for one or more sites or for an account.

66 Fetching data for sites or accounts To fetch data for a managed account, specify its id in the account_id parameter. To fetch data for specific sites, specify their ids in a comma separated list in the site_id parameter. To fetch data for all sites of the current account, do not specify the account_id or site_id parameters. Live Test Get statistics Use this operation to get site statistics for one or more sites. This operation may return multiple statistics, as specified in the stats parameter. /api/stats/v1 Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to fetch data for. If not specified, data will be fetched for all site of the account identified by the authentication parameters. time_range Time range to fetch data for. See the introduction of the API documentation for a detailed description start Start date in milliseconds since See the introduction of the API documentation for a detailed description end End date in milliseconds since See the introduction of the API documentation for a detailed description

67 Name Description Optional site_id Numeric identifier of the site to fetch data for. Multiple sites can be specified in a comma separated list. For example: 123,124,125. stats Statistics to fetch, as specified in the table below. Multiple statistics can be specified in a comma seaprated list. For possible values see below. granularity Time interval in milliseconds between data points for time series stats. Default is (1 day) for a range of less than 30 days and (3 days) for a range of less than 90 days. Values for stats parameter: Name Description visits_timeseries Number of visits by type (Humans/Bots) over time hits_timeseries Number of hits by type (Humans/Bots/Blocked) over time and per second bandwidth_timeseries Amount of bytes (bandwith) and bits per second (throughput) transferred via the Incapsula network from clients to proxy servers and vice-versa over time. requests_geo_dist_summary Total number of requests routed via the Incapsula network by datacenter location

68 Name Description visits_dist_summary Total number of visits per client application and country caching Total number of requests and bytes that were cached by the Incapsula network caching_timeseries Number of requests and bytes that were cached by the Incapsula network, with one day resolution, with info regarding the caching mode (standard or advanced) threats Total number of threats by type with additional information regarding security rules configuration Structure of the threats statistics: The threats statistics provides the number of security incidents per threat type and additional information regarding the configuration of the site with respect to each threat type. When fetching data for multiple sites or for an account only the name and incidents parameters will be returned. Name Description name Name of threat incidents Total number of security incidents of this threat type. A negative value represents N/A, i.e. data is not available. status Status of this security rule for the site. One of the following: ok warning error

69 Name Description status_text_id ID of the status_text field status_text Name of this security rule status. For example, one of the following: Block Not Supported 3 ips in blacklist... followup Followup action. For example: api.threats.followup.view or api.threats.followup.upgrade followup_text Name of followup action. One of the following: View Incidents Upgrade followup_url URL for followup action Response structure: "res": 0, "res_message": "OK", "visits_timeseries" : [ "id":"api.stats.visits_timeseries.human", "name":"human visits", "data":[ [ ,50], [ ,40],...

70 ] }, "id":"api.stats.visits_timeseries.bot", "name":"bot visits", "data":[ [ ,10], [ ,20],... ] } ], "requests_geo_dist_summary" : "id":"api.stats.requests_geo_dist_summary.datacenter", "name":"requests by data-center location", "data":[ ['Tokyo, JA', ], ['Los Angeles, CA', ],... ] }, "caching" : "saved_requests": , "total_requests": , "saved_bytes": , "total_bytes":

71 }, "caching_timeseries":[ "id":"api.stats.caching_timeseries.hits.standard", "name":"standard Requests Caching", "data":[ [ , 5 ],... ] }, "id":"api.stats.caching_timeseries.bytes.standard", "name":"standard Bandwidth Caching", "data":[ [ , 3440 ],... ] }, "id":"api.stats.caching_timeseries.hits.advanced",

72 "name":"advanced Requests Caching", "data":[ [ , 0 ],... ] }, "id":"api.stats.caching_timeseries.bytes.advanced", "name":"advanced Bandwidth Caching", "data":[ [ , 0 ],... ] }, "id":"api.stats.caching_timeseries.hits.total", "name":"total Requests", "data":[ [ ,

73 5000 ],... ] }, "id":"api.stats.caching_timeseries.bytes.total", "name":"total Bandwidth", "data":[ [ , ],... ] }, ], "hits_timeseries":[ "id":"api.stats.hits_timeseries.human", "name":"human requests", "data":[ [ , ],

74 ... ] }, "id":"api.stats.hits_timeseries.bot", "name":"bot requests", "data":[ [ , ],... ] }, "id":"api.stats.hits_timeseries.blocked", "name":"blocked requests", "data":[ [ , 629 ],... ] },

75 "id":"api.stats.hits_timeseries.human_ps", "name":"human requests per second", "data":[ [ , 427 ],... ] }, "id":"api.stats.hits_timeseries.bot_ps", "name":"bot requests per second", "data":[ [ , 261 ],... ] }, "id":"api.stats.hits_timeseries.blocked_ps", "name":"blocked requests per second", "data":[ [

76 , 0 ],... ] } ], "threats" : [ "id":"api.threats.bot_access_control" "name: "Badbot Visits", "incidents": 12, "status": "ok", "status_text_id": "api.threats.action.block_request", "status_text": "Block", "followup":"api.threats.followup.view", "followup_text": "View Incidents", "followup_url": " b94&timeFrame=last_7_days&extSiteId=123&threatFilters=badBot" }, "id":"api.threats.sql_injection" "name": "SQL Injection", "incidents": 3, "status": "error", "status_text_id": "api.threats.rule_support.not_supported",

77 "status_text": "Not Supported", "followup":"api.threats.followup.upgrade", "followup_text": "Upgrade", "followup_url": " d b94" ], },... "visits_dist_summary":[ }, "data":[ ], [ ], [ ],... "np", 11 "no", 778 "id":"api.stats.visits_dist_summary.country", "name":"visits by country"

78 "data":[ [ "lwp-request", 122 ], [ "elkmonitor", ],... ], "id":"api.stats.visits_dist_summary.client_app", "name":"visits by client application" } ], "bandwidth_timeseries":[ "data":[ [ , ],... ], "id":"api.stats.bandwidth_timeseries.bandwidth",

79 "name":"bandwidth" }, "data":[ [ , ],... ], "id":"api.stats.bandwidth_timeseries.bps", "name":"bits per second" } ], "res":0, "res_message":"ok" } "res":0, "res_message":"ok" } "debug_info": "timerange": "last_7_days", "site_id": 123 } } Specific error codes:

80 Code Description Comment Timerange invalid Timerange malformed, missing or the account is not on a supporting plan Granularity Invalid Granularity malformed or not a number Live Test Get events Available only to Enterprise plan accounts Organizations that need to closely monitor events typically have systems that can consume "data feeds". Typically, this is done via syslog interface. Incapsula allows partners to emulate this functionality by providing a generic interface for retrieving monitoring records. This API can be easily used to allow systems such as splunk or RSA Envision to consume the log information from Incapsula using simple scripts, rather than having to set up a VPN or complex tunnling infra-structure. The log API consist of a single call to the server, that is repeated continuously, retrieving new records on each call. The information is retrieved in a format that can be easily parsed and consumed by utilities such as splunk. This call fetches data for all sites of an account, event sites of accounts that are managed by the current account. /api/events/v1 Parameters: Name Description Optional api_id api_key from Timestamp in milliseconds since 1970 to fetch events from

81 Name Description Optional max_events Maximum number of events to fetch. Default and maximal value is 100. list_live_visits Whether or not to list visits that did not end and that may still be updated. One of: true false. Default: true What is an event? An event is a collection of one or more user/bot visits, which were aggregated together by Incapsula. For example, two distinct visits which arrived from the same IP address in close succession will be logged as a single event. An event is thus comprised of the following: Site and event information - the site that was visited, an event identifier and aggregative information regarding the event's origins (IP addresses and client application software that was used). Visits - one or more visit (identified by either a session cookie, IP address or some other correlation mechanism). Each visit is comprised of details about HTTP requests, including attack information and specific attack vectors identified on the request. For brevity's sake, data for each unique request is logged once while occurrences of this request are logged by specifying the total number of such requests and their chronological order. For example, a visit might be comprised of three identical reqeusts for The log will contain the information for this request only once and will specify that this request was repeated 3 times, in the 1st, 3rd and 15th request in the visit. The fields that constitute a unique request are the protocol (http/https), URL, query string, POST data and request result (see below). These fields may change from time to time. Event fields: Name Description AccountID The numeric identifier of the account of the site owner AccountName The account name of the site owner SiteID The numeric identifier of the site

82 Name Description SiteName The name of the site EventID The indication of the event EventType The type of event. For example: [EventType=ThreatAlert] EventTimestamp The timestamp in which this event was last updated ClientIP The IP address and the number of visits from each address. For example: [ClientIP= :3] indicates three visits from IP address ClientApp The client application software and the number of visits from each application. For example: [ClientApp=Skipfish:4] Visit fields: Name Description VisitID The ID of this visit StartTime The time in which this visit started, in UTC. For example: [StartTime=2011/10/07 01:59: ] Timestamp The timestamp in which this visit started. For example: [Timestamp= ]

83 Name Description BadBot Indicates whether the client application software is considered as bad bot. For example: [BadBot] ClientApplication The client software application, for Example: Firefox ClientType The client software application category, for example, Browser UserAgent The UserAgent header value OS The operating system type Ver The operating system version SupportsCookies Whether or not the client application software supports cookies. For example, [SupportsCookies=true]. SupportsJavaScript Whether or not the client application software supports JavaScript. For example, [SupportsJavaScript=true]. ClientIP The IP address used to visit the site Country The country the site was visited from

84 Name Description NumberOfHitsOnSession The total number of HTTP requests in this visit, including requests to images, static resources, etc NumberOfPageViewsOnSession The total number of pages viewed in this visit EntryReferer The referer header value of the first request to this visit, i.e. the last URL viewed by the client application before navigating to the site EntryPage The URL of the first request in this visit ServedVia The Incapsula data-center from which this request was served Request fields: Name Description URL The URL of the request ResponseCode The HTTP response code returned to the client. When requests are blocked, no response code is provided. RequestResult The method in which Incapsula processed the request. Either REQ_PASSED in case the request was routed to the site's web server, REQ_CACHED_X in case a response was returned from the datacenter's cache, REQ_BAD_X in case of a protocol or network error, REQ_CHALLENGED_X in case a challenge was returned to the client or REQ_BLOCKED_X in case the request was blocked.

85 Name Description QueryString The query string of the request PostData The post body data of the request Referer The URL of the previous page the client visited IncidentID The incident ID string displayed to clients when a request could not be processed successfully, either due to a protocol or network error or due to a security block. NumRequests The number of identical HTTP requests Attack Info fields: Name Description Rid The threat rule Id that this request triggered. For example: 0. RuleName The threat rule name that this request triggered. For example: SQL Injection ActionTaken The action taken by Incapsula when handling this threat. May be one of the following: Request blocked Alert raised IP blocked User blocked Attack vector fields:

86 Name Description AttemptedOn The location of the attack. May be one of the following: request parameter name, request parameter value or URL. ThreatPattern The payload of the attack, either the parameter name, parameter value or the URL. AttackInternalCode The Incapsula internal attack code Response Structure: The response is comprised of a list of events, separated by a line of 50 '=' characters. The response ends with a maxts field which indicates the latest event timestamp that was displayed. This value should be used in the from parameter to fetch the next batch of events. Event ================================================== Event ================================================== Event ================================================== max-ts: xxx The event structure is: Event Info --- Visits Visit --- (multiple, one per visit, up to 5 visits per event) Visit Info --- Request --- (multiple, one per request)

87 Request Info --- Attack Info --- (multiple, one per threat rule) Attack Info --- Attack Vector --- (multiple, one per attack vector) Attack Vector Inf An example response: [AccountID=1209] [SiteId=3055] [SiteName= [EventID=4f38d6a21e0bb548f200021a] [EventTimestamp= ] [EventType=ThreatAlert] [ClientIP= :1] [ClientApp=Bot:1] ---- VISITS VISIT ---- [VisitID= ][StartTime=2012/02/12 20:09: ] [BadBot] [Timestamp= ] [ClientApplication=Bot][ClientType=Unknown] [UserAgent=DogSniffer] [SupportsCookies=COOKIES_NOT_DETERMINED] [SupportsJavaScript=JS_NOT_DETERMINED] [ClientIP= ]

88 [Country=United States] [ServedVia=Ashville, NC] [NumberOfHitsOnVisit=10][NumberOfPageViewsOnVisit=10] [EntryReferer=] [EntryPage= -- Request [URL=/][ResponseCode=][RequestResult=REQ_BLOCKED_COOKIELESS_SESSION] [NumRequests=10] [RequestsIndexOnVisit=1] [QueryString=] [PostData=] [Referer=] -- Attack Info: [Rid=4][RuleName=Bad Bots] [ActionTaken=Request blocked] -- Attack Vector: [AttemptedOn=URL] [ThreatPattern= [AttackInternalCode=9412.0] -- Request [URL=/][ResponseCode=][RequestResult=REQ_BLOCKED_COOKIELESS_SESSION] [NumRequests=10] [RequestsIndexOnVisit=2] [QueryString=] [PostData=] [Referer=] -- Attack Info:

89 [Rid=4][RuleName=Bad Bots] [ActionTaken=Request blocked] -- Attack Vector: [AttemptedOn=URL] [ThreatPattern= [AttackInternalCode=9412.0] -- Request [URL=/][ResponseCode=][RequestResult=REQ_BLOCKED_COOKIELESS_SESSION] [NumRequests=10] [RequestsIndexOnVisit=3] [QueryString=] [PostData=] [Referer=] -- Attack Info: [Rid=4][RuleName=Bad Bots] [ActionTaken=Request blocked] -- Attack Vector: [AttemptedOn=URL] [ThreatPattern= [AttackInternalCode=9412.0] -- Request [URL=/][ResponseCode=][RequestResult=REQ_BLOCKED_COOKIELESS_SESSION] [NumRequests=10] [RequestsIndexOnVisit=4] [QueryString=] [PostData=] [Referer=]

90 -- Attack Info: [Rid=4][RuleName=Bad Bots] [ActionTaken=Request blocked] -- Attack Vector: [AttemptedOn=URL] [ThreatPattern= [AttackInternalCode=9412.0] -- Request [URL=/][ResponseCode=][RequestResult=REQ_BLOCKED_COOKIELESS_SESSION] [NumRequests=10] [RequestsIndexOnVisit=5] [QueryString=] [PostData=] [Referer=] -- Attack Info: [Rid=4][RuleName=Bad Bots] [ActionTaken=Request blocked] -- Attack Vector: [AttemptedOn=URL] [ThreatPattern= [AttackInternalCode=9412.0] ================================================== max-ts: Specific error codes:

91 Code Description Comment Timerange invalid Timerange malformed, missing or the account is not on a supporting plan Live Test Get visits /api/visits/v1 Use this operation to get a log of recent visits to a website. The visits are fetched in reverse chronological order, starting with the most recent visit. Not all visits are recorded - only visits with abnormal activity are recorded e.g. violation of security rules, visits from black-listed IPs/Countries, etc. A visit may still be updated even after it was retrieved. To avoid retrieving such visits and to retrieve only visits that will no longer be updated use the list_live_visits parameter. Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. time_range Time range to fetch data for. Default is last_7_days. start Start date in milliseconds since See the introduction of the API documentation for a detailed description

92 Name Description Optional end End date in milliseconds since See the introduction of the API documentation for a detailed description page_size The number of objects to return in the response. Defaults to 10. page_num The page to return starting from 0. Default to 0. security Filter the sessions that were handled according to the security-related specifications. Multiple values are supported, e.g.: "api.threats.action.block_ip, api.threats.sql_injection" country Filter the sessions coming from the specified country ip Filter the sessions coming from the specified IP visit_id Comma separated list of visit IDs to load list_live_visits Whether or not to list visits that did not end and that may still be updated. One of: true false. Default: true Visit fields: Name Description Optional id The ID of this visit

93 Name Description Optional starttime The timestamp in which this visit started. For example: endtime The timestamp in which this visit ended. For example: clientips The IP addresses used by the client countrycode The code of the country the site was visited from country The country the site was visited from clienttype The client software application category, for example, Browser clientapplication The client software application, for Example: Firefox clientapplicationversion The version of the client software application useragent The UserAgent header value os The operating system type

94 Name Description Optional osversion The operating system version supportscookies Whether or not the client application software supports cookies supportsjavascript Whether or not the client application software supports JavaScript hits The total number of HTTP requests in this visit, including requests to images, static resources, etc. pageviews The total number of pages viewed in this visit entryreferer The referer header value of the first request to this visit, i.e. the last URL viewed by the client application before navigating to the site entrypage The URL of the first request in this visit servedvia The Incapsula datacenter from which this request was served actions The actions that took place for the current session. Each such session may include specific threats, with its related details

95 Name Description Optional securitysummary A mapping between the security rules (and acls) that took place per this session, and their frequency Actions fields: Name Description Optional threats The threats associated with the action postdata For post requests, the request body. The value is Base64- encoded. requestresult The descision taken by Incapsula proxy server on how to process the request responsetime The number of milliseconds it took the server to return the response thinktime The number of milliseconds it took the server to generate the response Threats fields: Name Description Optional securityrule The security rule associated with the threat, e.g. api.threats.illegal_resource_access

96 Name Description Optional attackcodes Incapsula internal threat categorization threatlocation The location of the alert, "api.alert_location." + one of: path, param_name, param_value, response_data threatpattern The payload of the threat Response structure: "visits":[ "id":" ", "siteid":7, "starttime": , "clientips":[ " " ], "country":[ "Sweden" ], "countrycode":[ "SE" ], "clienttype":"unclassified", "clientapplication":"bot",

97 "clientapplicationversion":"0", DigExt)", "useragent":"mozilla/4.0 (compatible; MSIE 5.0; Windows 95; "os":"windows", "osversion":"windows", "supportscookies":true, "supportsjavascript":false, "hits":1, "pageviews":1, "entryreferer":" 557&incident_id= &edet=12&cinfo=2ef678e2c ", "entrypage":" threats "servedvia":[ "Los Angeles, CA" ], "securitysummary": // The following lists detected "api.threats.sql_injection" : 2, "api.threats.cross_site_scripting" : 1, "api.threats.illegal_resource_access" : 3, "api.threats.remote_file_inclusion" : 2, "api.threats.customrule" : 3, "api.threats.ddos=ddos" : 4, "api.threats.backdoor" : 2, // Bot Access Control may only take 1 as value, indicating the session was identified as a bot

98 "api.threats.bot_access_control" : 1, // Blacklists may only take 1 as value, indicating some requests were blocked due the the blacklists }, "actions":[ "api.acl.blacklisted_countries" : 1, "api.acl.blacklisted_urls" : 1, "api.acl.blacklisted_ips" : 1 "requestresult":"api.request_result.req_challenge_javascript", "issecured":false, "url":" "threats":[ "securityrule":"api.threats.illegal_resource_access", "alertlocation":"api.alert_location.alert_location_path", "attackcodes":[ "9070.0" ] }, "securityrule":"api.threats.bot_access_control", "alertlocation":"api.alert_location.alert_location_path", "attackcodes":[

99 "915.0" ] } ] } ] },... ], "res": 0, "res_message": "OK", "debug_info": "site_id": 123 } } Live Test Get notifications Available only to Reseller accounts Incapsula regularly sends notifications to customers regarding various events that occurred in their sites or account. In some cases, an Incapsula partner would like these notifications to be sent using a different mechanism. In order to achieve this, Incapsula provides partners with access to a log of notifications for all sites or accounts that are managed by the partner. /api/notifications/v1/url Parameters:

100 Name Description Optional api_id api_key Response structure: "url":"/api/notifications/v1/data/123_ _c3e8e3d428c6bca690ceb9 fee4e9e95a", } "res":0, "res_message":"ok" Log file structure The log file consists of Google Protocol Buffer messages and is stored in binary format. Messages are separated by an 8-byte message header that indicates the size of the message and its type. When the server decides to stop appending data to the file and start appending data to the next file it will append a single EndOfFile message to the log, to indicate to clients to start reading the new file. The following example shows a log consisting of two messages and the EndOfFile message. The first message takes up 28 bytes (bytes 8 throught 35), the seconds message takes up 13 bytes (bytes 44 through 56) and the end of file message takes up 25 bytes (bytes 65 through 89). msg_type (0-3) msg_length (4-7) message (8-35) msg_type (36-39) msg_length (40-43) message (44-56) msg_type (57-60) msg_length (61-64) EndOfFile (65-89) Accessing the logs The notifications log is accessible via a secure URL that may change from time to time. To get the currently active URL, use this API call. Clients should call this URL again only if access to the URL has stopped (e.g. when the URL had moved and the server returns a 404 Not Found response). Polling algorithm

101 Clients should read the log files using simple HTTP GET range requests (e.g. using the Range request header) to the secure URL. On each request the client needs to ask for the next block of un-read data. The server will return the requested data if available. As specified above, when the client reads an EndOfFile message it needs to start reading the next log file. The server will respond with an HTTP 416 Requested Range not satisfiable error if the client asked for a block that does not exist. This indicates to the client that it has read all the data in the file and since no EndOfFile message has been read, the file is still active. In such cases the client should repeat the call at a later time, when more data is available in the file. A complete client implementation in python is provided below. It is encouraged to use it as reference. Notes Sample client implementation in python and the updated protobuf schema can be downloaded here. Incapsula uses Google Protobuf v2.3.0 Live Test Upload Public Key Available only for Enterprise Plan customers that purchased the Security Logs Integration SKU. Overview Organizations that purchased the Security Logs Integration SKU can download security events created for their account and archive or push those events into their SIEM solution. In both cases, it is highly recommended to encrypt the events using a private-public key pair generated by the customer. Incapsula uses two layers for encrypting the security events: 1. Incapsula encrypts the security events using a symmetric key. 2. The symmetric key itself is asymmetrically encrypted using a public key supplied by the customer. In order to decrypt the security events, the customer needs to: 1. Use the private key to decrypt the symmetric key. 2. Use the symmetric key to decrypt the security events in the log file sent by Incapsula. Using the API The Upload Public Key API is used to upload the public key created by the customer. Once the API is successfully invoked, the new public key is used to encrypt the symmetric key (used for encrypting the log files). Since the process of replacing/updating the public key may take several seconds, the customer decrypting the log files should prepare to use the correct private key. To let the customer know what public key was used for the encryption (and accordingly what private key to use for the decryption), the Upload Public Key API returns an ID uniquely identifying the key pair. This ID is also added to the log file s metadata. Customers should maintain the mapping between the ID and the key pair.

102 /api/logscollector/upload/publickey Parameters: Name Description Optional api_id api_key logs_collector_type the logs collector type (currently the only value is SIEM) config_id The Logs Collector configuration identifier public_key The public key file(2048bit) in base64 format (without password protection) Response Structure: The response contains the public key ID generated by Incapsula. "publickeyid":1, "res":0, "res_message":"ok" } Specific error codes:

103 Code Description Comment Invalid public key The input is not a valid RSA public key Invalid configuration ID The configuration ID doesn t exist or is not authorized with the provided API key and ID insufficient key length The uploaded key length is insufficient, please uplaod 2048bit length key. 2 Invalid input Input missing or incorrect Live Test Change Logs Collector Configuration Status Available only for Enterprise Plan customers that purchased the Security Logs Integration SKU. Use this operation to change the status of the Logs Collector configuration. /api/logscollector/change/status Parameters: Name Description Optional api_id api_key config_id The Logs Collector configuration identifier

104 Name Description Optional logs_config_new_status The new configuration status of the Logs Collector. Values can be ACTIVE or SUSPENDED Response Structure: "res":0, "res_message":"ok" } Specific error codes: Code Description Comment 2 Invalid input Input missing or incorrect Invalid configuration ID The configuration ID doesn t exist or is not authorized with the provided API key and ID Integration API The following operations may be used to implement various integration scenarios with the Incapsula service. Live Test Get Incapsula IP Ranges Use this operation to get the updated list of Incapsula IP ranges. This list may be used to define firewall rules that restrict access to customers sites from non-incapsula IPs.

105 /api/integration/v1/ips Parameters: Name Description Optional resp_format Response format. One of: json apache nginx iptables text. Default is json. Response structure: // JSON format "res": 0, "res_message": "OK", "ipranges" : [ " /21", " /19",... ] } // Apache htaccess format order deny,allow deny from all allow from /21 allow from /19... // Nginx format

106 allow /21; allow /19;... // iptables format iptables allow host tcp:in:d=80:s: /21 tcp:in:d=80:s: /19... // text format / /19 Specific error codes: Code Description Comment Format invalid Format malformed or missing Live Test Get Texts Use this operation to retrieve a list of all text messages that may be part of API responses. For each message a key and a value are provided: the key is the unique identifier of the message and the value is the message text itself, in the API's default locale (English). /api/integration/v1/texts Parameters:

107 Name Description Optional api_id api_key Response structure: "texts" : "api.stats.visits_timeseries.human":"human visits", "api.stats.visits_timeseries.bot":"bot visits",... "api.threats.followup.view":"view Incidents" }, "res": 0, "res_message": "OK", } Live Test Get Geographical Info Use this operation to retrieve a list of all the countries and continents codes. /api/integration/v1/geo Parameters:

108 Name Description Optional api_id api_key Response structure: "countriescodes": "BD":"Bangladesh", "BE":"Belgium",... }, "continentscodes": "AF":"Africa",... }, "res": 0, "res_message": "OK", } Live Test Get Client Applications Info Use this operation to retrieve a list of all the client applications. /api/integration/v1/clapps Parameters:

109 Name Description Optional api_id api_key Response structure: "clientapps": "1":"Firefox",... }, "clientapptypes": "1":"Browser",... }, "res": 0, "res_message": "OK", } Change Log Date Operation Description Modify site security configuration Enriched activation_mode parameter's description.

110 Date Operation Description Get Site Status Added the site's hostname for sites that are configured with a hostname Get Account Status Aligned response with documentation and the general response structure. Information should be read from the fields that reside under the account field. Previous fields are kept for backwards compatibility and will be removed eventually Modify Account Configuration When using param=name, the account's name is now modified instead of the personal name of the account's admin Add Managed Account/Get Account Status plan_id parameter is no longer numeric. Contact Incapsula Support for an updated list of values Get Incapsula IP ranges Fix incorrect nginx format Add site Adding optional parameter send_site_setup_ s Get site status Adding acceleration method Get events Changed URL from /api/log/v1/get to /api/events/v1. Old URL will be removed in up-coming releases Sign-up a new stand-alone account Add a new managed account Optional parameter account_desc has been removed and is no longer used. Use account_name instead

111 Date Operation Description Sign-up a new stand-alone account Aligning all urls to start with /api/prov while keeping backward compatibility. The new URLs are Retrieve authentication parameters for an existing account Get account status /api/prov/v1/accounts/connect /api/prov/v1/accounts/signup /api/prov/v1/account all List sites Using numeric values for account_id. /accounts/add can be invoked without sending account_id. /accounts/add returns numeric account_id. adding pagination to /accounts/list and /sites/list. account_id is optional for /gettoken. Fixing values on status to be aligned with documentation : pendingselect-approver, pending-certificate, pending-dnschanges, orfully-configured List sites Adding active/bypass to each site List sites Sorting sites according to account_id and display_name List managed accounts List managed accounts Sorting accounts by the account_id adding fields account. users is deprecated and will be removed in the next deployment What is Login Protect? Incapsula s Login Protect feature lets online businesses implement strong two-factor authentication on any website or application without integration, coding or software changes. Single-click activation lets you instantly protect administrative access to any page or URL, secure remote access to corporate web applications, and restrict access to a particular webpage. Login Protect manages and controls multiple logins across several websites in a centralized manner. Two-factor authentication is supported using either , SMS or Google Authenticator. Login Protect API The API can be used in order to provision Login Protect users and also in order to configure the protected pages. User Provisioning

112 Login Protect users are the users that will be allowed to access the protected pages. They are added to the account s Login Protect users list. Access permissions for specific sites can be decided during site protected pages configuration process. Login Protect users can be provisioned using the Add Login Protect User API call. If user details are available they can be associated with each user using the Name, and phone parameters. If the details are not available the should_send_activation_ parameter should be set to True, in which case users will get an activation in which they will be able to enter their details. (The Send SMS API call can be used in order to validate a user s phone number, in case the should_send_activation_ option is not used. In that case, it is advised to generate a random code, and send it to the user s phone using the Send SMS API call ). Configuring protected pages for a site Protected pages are added using the Modify Site Login Protect Configuration API call. The URLs of the protected pages can be entered, comma separated, using the urls parameter. In order to define URL patterns (e.g. URL starts with or URL contains ) use the url_patterns parameters in accordance with the entered URLs. It is also possible to allow access to specific users out of the account s Login Protect users list using the specific_users_list parameter. In order to get notifications on successful user logins to the protected pages use the send_lp_notifications. Allowed authentication methods for the site can be decided using the authentication_methods parameter. Live Test Add Login Protect User Use this operation to add Login Protect user for site. /api/prov/v1/sites/lp/add-user Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on

113 Name Description Optional address, for example: name Example: John Smith phone Phone number, country code - number, for example: " " is_ _verified Whether or not to skip address verificaion is_phone_verified Whether or not to skip phone address verificaion should_send_activation_ Whether or not to send activation E- Mail to user Response structure: "res": 0, "res_message": "OK", "debug_info": "user ": "[email protected]" } } Specific error codes:

114 Code Description Comment 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it invalid Malformed, missing or empty parameter Login Protect User Exists This user already exists under this account Operation Not Allowed Skipping login protect verification is not allowed for this account Not Supported Action Your account is not allowed to skip Login Protect verification Failed to Send Could not send , please check syntax Live Test Edit Login Protect User Use this operation to edit Login Protect user's settings. /api/prov/v1/sites/lp/edit-user Parameters: Name Description Optional api_id

115 Name Description Optional api_key account_id Numeric identifier of the account to operate on address, for example: name Example: John Smith phone Phone number, country code - number, for example: " " is_ _verified Whether or not to skip address verificaion is_phone_verified Whether or not to skip phone address verificaion should_send_activation_ Whether or not to send activation E- Mail to user Edit user's phone number example: api_id=123 api_key=your key account_id=1234

116 phone= is_phone_verified=true Response structure: "res": 0, "res_message": "OK", "debug_info": "user ": } } Specific error codes: Code Description Comment 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it invalid Malformed, missing or empty parameter Login Protect User Exists This user already exists under this account Operation Not Allowed Skipping login protect verification is not allowed for this account

117 Code Description Comment Not Supported Action Your account is not allowed to skip Login Protect verification Failed to Send Could not send , please check syntax Live Test Get Login Protect Users Use this operation to get the account's login protect user list. /api/prov/v1/sites/lp/users Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on Response structure: "users":[ "phone":" ", "creation_date":"jun 17, :20:04 AM",

118 "name":"john Doe", "status":"invitation_sent" }, "phone":" ", "creation_date":"may 15, :01:11 PM", "name":"jane Doe", "status":"revoked" } ] } Specific error codes: Code Description Comment Invalid phone number Phone number is invalid or does not fit the region Failed to Send Could not send , please check syntax 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it invalid Malformed, missing or empty parameter

119 Code Description Comment Login Protect User Exists This user already exists under this account Operation Not Allowed Skipping login protect verification is not allowed for this account Live Test Remove Login Protect User Use this operation to remove login protect user from account's user list. /api/prov/v1/sites/lp/remove Parameters: Name Description Optional api_id api_key account_id Numeric identifier of the account to operate on address, for example: Specific error codes:

120 Code Description Comment Invalid phone number Phone number is invalid or does not fit the region Failed to Send Could not send , please check syntax 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it invalid Malformed, missing or empty parameter Login Protect User Exists This user already exists under this account Operation Not Allowed Skipping login protect verification is not allowed for this account Live Test Send SMS to User Use this operation to send SMS to login protect user. /api/prov/v1/sites/lp/send-sms Parameters: Name Description Optional api_id

121 Name Description Optional api_key account_id Numeric identifier of the account to operate on address, for example: sms_text Text that will be sent in SMS. Specific error codes: Code Description Comment Invalid phone number Phone number is invalid or does not fit the region Invalid SMS Text Please provide text for the SMS 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it Invalid User Login Protect user does not exist on this account Exceeded Allowed SMS Number of allowed SMS a day is exceeded Failed to Send SMS Could not send SMS, try again later Live Test

122 Modify Site Login Protect Configuration Use this operation to change Login Protect settings for site. /api/prov/v1/sites/lp/configure Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. enabled Pass true to enable login protect on site, and false to disable it. Default is true. specific_users_list Comma seperated list to set login protect users for the site, if the list is empty all users will be allowed to access the site using Login Protect. send_lp_notifications Pass true to send notification on successful login using login protect. Default is false. allow_all_users Pass true to allow all login protect users to access the site. If you choose to allow only spesific list of users to access the site using Login Protect set this to false, and add the list to specific_user_list. Default value is true.

123 Name Description Optional authentication_methods Comma seperated list of allowed authentication methods sms ga urls A comma separated list of resource paths. For example, /home and /admin/index.html are resource paths, however is not. Each URL should be encoded separately using percent encoding as specified by RFC 3986 ( 2.1). An empty URL list will remove all URLs. url_patterns A comma seperated list of url patterns, one of: contains equals prefix suffix not_equals not_contain not_prefix not_suffix. The patterns should be in accordance with the matching urls sent by the urls parameter. Edit Specific Users list example api_id=123 api_key=your key site_id=1234 [email protected],[email protected],[email protected] allow_all_users=false Add URL list api_id=123

124 api_key=your key site_id=1234 urls=/admin,index.php url_patterns=equals,contains Response structure: "res": 0, "res_message": "OK" } Specific error codes: Code Description Comment 9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it Format invalid Invalid for specific user list Application invalid Application is not one of wordpress joomla phpbb Invalid SMS Text Please provide text for the SMS 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it

125 Code Description Comment invalid Malformed, missing or empty parameter Invalid phone number Phone number is invalid or does not fit the region Live Test Configure Login Protect on Admin Areas Use this operation to configure Login Protect on wordpress joomla phpbb admin areas. /api/prov/v1/sites/lp/configure-app Parameters: Name Description Optional api_id api_key site_id Numeric identifier of the site to operate on. protected_app Protect admin areas of joomla wordpress phpbb Configure admin areas for wordpress api_id=123 api_key=your key site_id=1234

126 protected_app=wordpress Specific error codes: Code Description Comment 9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it Format invalid Invalid for specific user list Application invalid Application is not one of wordpress joomla phpbb Invalid SMS Text Please provide text for the SMS 9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it invalid Malformed, missing or empty parameter Invalid phone number Phone number is invalid or does not fit the region 2015, Imperva, Inc. All rights reserved. Imperva, the Imperva logo, SecureSphere, Incapsula and Skyfence are trademarks of Imperva, Inc. and its subsidiaries. All other brand or product names are trademarks or registered trademarks of their respective holders.