Show search and navigation.

 

Get Event Log Entries

WAF Insights does not support automation via our REST API web service. If you are currently using WAF Insights, upgrade your WAF solution to take advantage of our REST API.

Generates paginated event log data. This data can be filtered by:

A request for event log entries may return information on thousands of requests. Due to the amount of time that it would take to transmit this data, the response for this endpoint has been split up into pages. Retrieve all events that match the specified criteria by requesting each page. Use the page_of response parameter in your script to cycle through each page.

This endpoint only supports JSON.

Request

A request to retrieve event log data is described below.

HTTP Method Request URI

GET

https://api.transactcdn.com/v2/mcc/customers/AccountNumber/waf/eventlogs?start_time=StartDateTime&end_time=EndDateTime&filters=Filters&page=PageNumber&page_size=ItemsPerPage

Define the following terms when submitting the above request:

VariableA variable represents a value that must be replaced. A variable consists of either a URL segment (e.g., "0001" in /0001/) or a query string value (e.g., "3" in mediaTypes=3). Description

AccountNumber

Required

Replace this variable with a customer account number. This account number may be found in the upper left-hand corner of the TCC.

StartDateTime

Replace this variable with the start date/time for the report. Only activity that took place after the specified date/time will be included in the report.

Format:YYYY-MM-DDThh:mm:ss

Key information:

  • A valid request must either include or exclude both date/time parameters (i.e., start_time and end_time).
  • Omitting both date/time parameters (i.e., start_time and end_time) will return the events that took place within the last 24 hours.
  • Time (i.e., Thh:mm:ss) is optional when defining a start and end date/time. If time is not specified, then a default time (i.e., 00:00:00) will be used.

For more information on date/time format, please refer to Report Date/Time Format.

Event log data may only be retrieved for the last 30 days. Specifying an older date will return a 400 Bad Request.

EndDateTime

Replace this variable with the end date/time for the report. Activity that took place after the specified date/time will not be included in the report.

Format:YYYY-MM-DDThh:mm:ss

Key information:

  • A valid request must either include or exclude both date/time parameters (i.e., start_time and end_time).
  • Omitting both date/time parameters (i.e., start_time and end_time) will return the events that took place within the last 24 hours.
  • Time (i.e., Thh:mm:ss) is optional when defining a start and end date/time. If time is not specified, then a default time (i.e., 00:00:00) will be used.

For more information on date/time format, please refer to Report Date/Time Format.

Filters

Replace this variable with the desired filter(s).

Key information:

  • Omitting the filters query string parameter allows the response to include all events that took place within the specified time period.
  • Specify one or more filters using URL-encoded JSON.
  • Only events that satisfy all specified filters may be returned by this endpoint.

  • Specify an event name and a value for each desired filter.

    Use the Get Available Event Log Fields endpoint to retrieve a list of valid event names.

  • Event names and values are case-sensitive.
  • Use a comma to delimit each filter.
  • Set up a filter that can be satisfied by multiple values by comma-delimiting each value within brackets.

    Example (Requires URL-Encoding):

    {"Host":["www.example.com","cdn.example.com","secure.example.com"]}

    Example (URL-Encoded):

    %7B%22Host%22%3A%5B%22www.example.com%22%2C%22cdn.example.com%22%2C%22secure.example.com%22%5D%7D
  • A "starts with" matchMatches any value that starts with the specified value. For example, specifying "www.example.*" will match all of the following: www.example.com, www.example.net, and www.example.org. may be defined by appending an asterisk (i.e., *) to the desired value. Any other usage of an asterisk wildcard is unsupported.

    Example (Requires URL-Encoding):

    {"Host":"www.example.*"}

    Example (URL-Encoded):

    %7B%22Host%22%3A%22www.example.*%22%7D
ClosedView example.

This example will demonstrate the proper syntax for defining the following filters:

  • Host = www.example.com
  • Profile Name = My Profile

The corresponding JSON for the above filters is:

{
	"Host" : "www.example.com",
	"Profile Name" : "My Profile"
}

After URL-encoding reserved characters and removing unnecessary space characters, the above JSON should look similar to the following:

%7B%22Host%22%3A%22www.example.com%22%2C%22Profile%20Name%22%3A%22My%20Profile%22%7D

Sample request:

https://api.transactcdn.com/v2/mcc/customers/0001/waf/eventlogs/fields?start_time=2014-10-20&end_time=2014-10-21&filters=%7B%22Host%22%3A%22www.example.com%22%2C%22Profile%20Name%22%3A%22My%20Profile%22%7D
ClosedFilters & 500 Internal Server Error Response

Specifying invalid filter syntax may generate a 500 Internal Server Error. Sample syntax issues are listed below:

  • An event name is invalid if it is misspelled or if it uses the wrong case (e.g., HOST).

    Use the Get Available Event Log Fields endpoint to retrieve a list of valid event names.

  • A comma must separate each specified filter (e.g., {"Host":"w*","URL":"w*"}. An error will be generated if a comma is missing when multiple filters have been specified.
  • Brackets must enclose a field that contains multiple values. An error will be generated if a field that can be satisfied by multiple values is not enclosed within brackets.

    • Syntax (Requires URL-Encoding):

    {"Host":["www.example.com","secure.example.com"]}

    Valid Syntax (URL-Encoded):

    %7B%22Host%22%3A%5B%22www.example.com%22%2C%22secure.example.com%22%5D%7D

    Invalid Syntax:

    {"Host":"www.example.com","secure.example.com"}

PageNumber

Replace this variable with the page number that will be returned. The response will only include log events corresponding to that page in the response.

Omitting the page query string parameter in the request will return the first page.

ItemsPerPage

Replace this variable with the number of log events that may be included on each page.

The number of items per page determines the number of pages that may be returned.

Omitting the page_size query string parameter in the request will return a maximum of 100 log events per page.

The maximum value for this variable is 1000.

Request Headers

This endpointIdentifies a request's connection point to our REST API service. only takes advantage of common request headers.

Request Body

Request body parameters are not required by this endpoint.

Response

The response to the above request includes an HTTP status code, response headers, and a response body.

This endpoint only supports JSON.

Status Code

A status code indicates whether the request was successfully performed.

Response Headers

The response for this endpoint only includes standard HTTP response headers.

View common response headers.

Response Body

The response body for a successful request reports:

This endpoint only returns event fields (e.g., Epoch Time or Matched On) that contain data. Therefore, the set of event fields returned by this endpoint may vary by event.

Name Data Type Description

events

Array

Objects

Contains a list of fields for each event reported on this page.

Only fields that contain data for the event being reported will be included in the response. This means that the set of fields reported for each event may vary.

page

Integer

Indicates the number of the page that was returned.

page_of

Integer

Indicates the total number of pages required to return the event log data that matches the criteria defined in the request.

The total number of pages is determined as indicated below.

(# of Eligible Log Events) / (ItemsPerPage)

The result of the above formula is rounded up to the nearest whole integer.

time_from

Number

floating-point

Indicates the report's start date/time, in seconds, using Unix time.

Sample value:

1473638400.0

time_to

Number

floating-point

Indicates the report's end date/time, in seconds, using Unix time.

Sample value:

1473638400.0

events Array

The events array contains an object for each event reported on this page. The members of this object are described below.

Name Data Type Description

Acl ID

String

Reserved for future use.

Acl Name

String

Reserved for future use.

Action Type

String

Indicates the action that was triggered as a result of the violation.

Valid values are:

  • ALERT: This term has been deprecated in favor of NOP.
  • BLOCK_REQUEST: Indicates that the request that violated a rule was blocked.
  • BLOCK: This term has been deprecated in favor of BLOCK_REQUEST.
  • NOP: Indicates that an alert was generated in response to the rule violation.
  • REDIRECT_302: Indicates that the request that violated a rule was redirected to the URL associated with the instance defined by the Instance Name field.
  • CUSTOM_RESPONSE: Indicates that a custom response was returned to the client that submitted a request that violated a rule.

Bots ID

String

Reserved for future use.

Bots Name

String

Reserved for future use.

City Name

String

Identifies the city from which the request originated.

Client IP

String

Identifies the IP address of the client from which the violation originated.

Country Code

String

Identifies the country from which the request originated by its country code.

View a list of country codes.

Country Name

String

Identifies the country from which the request originated.

Epoch Time

Number

floating-point

Indicates the Unix time, in seconds, at which the violation took place.

Syntax:

Seconds.Microseconds

Sample value:

1473207640.345809

Event ID

String

Indicates the unique ID assigned to the event.

Pass this ID to the Get Event Log Entry endpoint to retrieve this event log entry.

Host

String

Indicates the hostname that was requested.

id

String

Indicates the hash value for the event's ID.

Instance Name

String

Indicates the name of the instance that activated the profile containing the rule that the requested violated.

Matched Data

Deprecated

String

This parameter has been deprecated.

Signature Detection Mode Only

Indicates the client-side data that triggered the violation.

Matched On

Deprecated

String

This parameter has been deprecated. This information may be found within the Sub Events object.

Signature Detection Mode Only

Indicates the variable that identifies where the violation was found.

Matched Value

Deprecated

String

This parameter has been deprecated. This information may be found within the Sub Events object.

Signature Detection Mode Only

Indicates the value of the variable defined in the Matched On parameter.

Profile Name

String

Indicates the name of the profile that triggered the violation.

Profile Type

String

Indicates whether the request was screened as a result of an instance’s production or audit profile. Valid values are:

PRODUCTION | AUDIT

Referer

String

Indicates the request’s referrer as defined by the Referer request header.

Referrer

Deprecated

String

This parameter has been replaced by the Referer parameter and is no longer included in the response.

Indicates the request’s referrer as defined by the Referer request header.

Rule ID

Deprecated

Integer

This parameter has been deprecated.

The ID for each rule that was violated is reported under the Sub Events parameter.

Rule Message

String

Provides the following basic information about the anomaly score violation(s).

Inbound Anomaly Score Exceeded (Total Score: #Represents the total anomaly score for the logged request., SQLi=#Represents the SQL injection attack score for the logged request., XSS=#Represents the cross-site scripting attack score for the logged request.): Last Matched Message: RuleIDRepresents the ID of the last rule that was violated by the request in question.-RuleMessageRepresents the message of the last rule that was violated by the request in question.

Rule Policy

String

Indicates the name of the policy that was violated.

Rule Severity

Deprecated

Integer

This parameter has been deprecated. This information may be found within the Sub Events object.

Signature Detection Mode Only

Indicates the severity of the violation. This value may range from -1 to 6 where 6 represents the lowest severity level.

Rule Tags

String

Indicates the tags associated with the rule that the request violated. These tags may be used to determine whether a rule, access control, or global setting was violated.

Rules Config ID

String

Reserved for future use.

Rules Config Name

String

Reserved for future use.

Scope ID

String

Reserved for future use.

Scope Name

String

Reserved for future use.

Sub Event Count

Integer

Indicates the total number of sub events reported for the current event log entry.

Sub Events

Array

Objects

Contains a list of fields that describe each sub event associated with the current event. A sub event is reported for each rule violation incurred by a request.

Timestamp

String

Indicates the date and time (UTC) at which the violation took place.

Format:YYYY-MM-DDThh:mm:ss.ffffffZ

Learn more.

URL

String

Indicates the URL that was requested.

User Agent

String

Indicates the user agent that submitted the request that triggered the rule violation.
Sub Events Array

The Sub Events array contains an object that describe each sub event associated with the current event. A sub event is reported for each rule violation incurred by a request.

Name Data Type Description

Matched Data

String

This parameter has been deprecated.

Indicates the client-side data that triggered the violation.

Matched On

String

Indicates the variable that identifies where the violation was found.

View variable definitions.

Matched Value

String

Indicates the value of the variable defined in the Matched On parameter.

Rule ID

Integer

Indicates the ID for the rule that the request violated.

Rule Message

String

Provides a description of the rule that the request violated.

Rule Severity

Integer

Indicates the severity of the violation. This value may range from -1 to 6 where 6 represents the lowest severity level.

Total Anomaly Score

Integer

Indicates the total anomaly score for the current rule violation. This score is calculated by summing the anomaly score of the current rule violation with all rule violations reported above this sub event.

ClosedView example.

The anomaly score incurred by each sub event in this example is listed below.

  • Sub Event 1: Anomaly Score 2
  • Sub Event 2: Anomaly Score 3
  • Sub Event 3: Anomaly Score 2

The total anomaly score for each sub event is listed below.

  • Sub Event 1: Total Anomaly Score = 2
  • Sub Event 2: Total Anomaly Score = 5
  • Sub Event 3: Total Anomaly Score = 7

Errors

The response body for an unsuccessful request will contain an error response that provides additional information.

View common error messages.

Sample Request and Response

A sample JSON request is shown below.

GET https://api.transactcdn.com/v2/mcc/customers/0001/waf/eventlogs?start_time=2016-09-01&end_time=2016-09-12&page_size=2 HTTP/1.1

Authorization: TOK:12345678-1234-1234-1234-1234567890ab

Accept: application/json

Host:api.transactcdn.com

A sample JSON response is shown below.

HTTP/1.1 200 OK

Cache-Control: private

Content-Type: application/json; charset=utf-8

Date: Thu, 15 Apr 2021 12:00:00 GMT

Content-Length: 2676

{
	"page_of" : 100,
	"time_to" : 1473638400.0,
	"time_from" : 1472688000.0,
	"events" : [{
			"Epoch Time" : 1473207640.345809,
			"Profile Type" : "PRODUCTION",
			"Client IP" : "192.12.22.25",
			"Rule Message" : "Inbound Anomaly Score Exceeded (Total Score: 5, SQLi=3, XSS=0): Last Matched Message: 981255-Detects MSSQL code execution and information gathering attempts",
			"Sub Event Count" : 1,
			"Timestamp" : "2016-09-07T00:20:40.345809Z",
			"URL" : "http://www.example.com/mywebpage.html",
			"Country Code" : "US",
			"Rule Policy" : "Inbound blocking",
			"Action Type" : "CUSTOM_RESPONSE",
			"Host" : "www.example.com",
			"Instance Name" : "My Instance",
			"Profile Name" : "My Profile",
			"Rule Tags" : "OWASP_CRS/ANOMALY/EXCEEDED",
			"Sub Events" : [{
					"Matched On" : "ARGS:a",
					"Rule Message" : "Detects MSSQL code execution and information gathering attempts",
					"Matched Data" : "'select *",
					"Total Anomaly Score" : 5,
					"Rule ID" : 981255,
					"Rule Severity" : 2,
					"Matched Value" : "'select * from site'"
				}
			],
			"User Agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.116 Safari/537.36",
			"id" : "udidK2wtEHpw4OQkoQKa3JI06QAeUKXwYqM_dgbsuvYwygOWO_uTVGQPxR5ELPpJ19wTpnflk7ynrIJzAMH2tA=="
		}, {
			"Epoch Time" : 1473207637.5252609,
			"Profile Type" : "PRODUCTION",
			"Client IP" : "192.144.23.52",
			"Rule Message" : "Inbound Anomaly Score Exceeded (Total Score: 5, SQLi=3, XSS=0): Last Matched Message: 981255-Detects MSSQL code execution and information gathering attempts",
			"Sub Event Count" : 1,
			"Timestamp" : "2016-09-07T00:20:37.525261Z",
			"URL" : "http://www.example.com/mywebpage.html",
			"Country Code" : "US",
			"Rule Policy" : "Inbound blocking",
			"Action Type" : "CUSTOM_RESPONSE",
			"Host" : "www.example.com",
			"Instance Name" : "My Instance",
			"Profile Name" : "My Profile",
			"Rule Tags" : "OWASP_CRS/ANOMALY/EXCEEDED",
			"Sub Events" : [{
					"Matched On" : "ARGS:a",
					"Rule Message" : "Detects MSSQL code execution and information gathering attempts",
					"Matched Data" : "'select *",
					"Total Anomaly Score" : 5,
					"Rule ID" : 981255,
					"Rule Severity" : 2,
					"Matched Value" : "'select * from site'"
				}
			],
			"User Agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2743.116 Safari/537.36",
			"id" : "kYSbc5AqNC7kD9k38me0Mu9f_hEuHkQhTJqzK0IKP1Oxux2sUgh5GQEPL004Wcan7RSqjGT4nv_bRvfeZSGwkQ==",
			"Event ID": "54973727612018659117005509529321564774"
		}
	],
	"page" : 1
}