Firebox Reports API

Version: 1.7.0
Version History

Download the API specification

Introduction

The Firebox Reports API is a RESTful API that you can use to retrieve data from Firebox reports.

You can use the Firebox Reports API to retrieve data for only Fireboxes that you have added to WatchGuard Cloud. To add a Firebox to your WatchGuard Cloud account, follow the steps in Add a Firebox to WatchGuard Cloud.

This API documentation explains how to access the Firebox Reports API and includes examples to help you get started.

Get Started

This section describes how to submit requests to the Firebox Reports API.

The Firebox Reports API URL is:

https://{base API URL}/rest/firebox/reports/

The base URL for WatchGuard public APIs varies by region. The base API URL for your account appears on the Managed Access page in WatchGuard Cloud.

Endpoint Path Parameters

Each WatchGuard public API has a version, expressed as <major>.<minor>.<patch>. You specify the major API version, such as v1, as part of the endpoint URI path.

All Firebox Reports API endpoint URIs must include your WatchGuard Cloud account ID in the {accountid} path parameter.

Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. To use the Firebox Management API, you must first enable API access in your WatchGuard Cloud account and make an API request to generate an access token.

You must include the access token and your API Key in the header of each request you make to the Firebox Management API.

For more information, see Authentication.

Request Headers

You must include this information in the header of each request you make to the Firebox Management API:

Content-Type

application/json

Accept

application/json

Authorization

The access token that you generate with the WatchGuard Authentication API. For more information, see Authentication.

WatchGuard-API-Key

The API Key associated with your WatchGuard Cloud account (shown on the Managed Access page in WatchGuard Cloud).

Get Data from the Executive Dashboard Report

/{v1}/report/{accountid}/executive

The Executive Dashboard report in WatchGuard Cloud provides a high-level view of traffic through the selected Firebox.

Make a request to this endpoint to retrieve the specified Executive Dashboard data for the specified devices.

For more information about the Executive Dashboard report, go to Executive Dashboard in the WatchGuard Cloud Help.

Path Parameters

When you send a request to this endpoint, you must include these path parameters:

accountid
string
REQUIRED

Your WatchGuard Cloud account ID. You can see your accountId on the My Account page in WatchGuard Cloud.

Example: WGC-1-123abc456 or ACC-1234567

Request Parameters

When you send a request to this endpoint, you can include these request parameters:

view
string
REQUIRED

Specifies the type of Executive Dashboard records to retrieve.

Specify one of these values:

  • top_countries — Top countries.
  • top_zero_day_malware_apt — Top zero-day malware detected by APT Blocker.
  • top_clients — Top client devices.
  • top_domains — Top domain names.
  • top_url_categories — Top website URL categories.
  • top_destinations — Top destinations for traffic.
  • top_applications — Top applications.
  • top_application_categories — Top application categories.
  • top_protocols — Top network traffic protocols.

Example: top_countries

startDate
string
REQUIRED

Start date and time of the period to retrieve records for.

Example: 2023-10-04T18:30:00

endDate
string
REQUIRED

End date and time of the period to retrieve records for.

Example: 2023-10-04T18:30:00

devices
string

Comma-separated device IDs of the Fireboxes and FireClusters to retrieve records for.

Each device has a unique ID number in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, your device ID is FB-12345.

If you do not specify device IDs, the API returns records for all Fireboxes and FireClusters in the account.

Example: FB-12345,FBCL-11250

rowCount
integer

Number of records to return. The default value is 10 and the maximum value is 500.

Example: 25

filter
string

Type of Executive Dashboard record to filter results on.

Specify the filter in this parameter, then specify a filter value in the filterValue parameter. For example, if the filter parameter value is top_countries, then the filterValue value could be USA.

Specify one of these values:

  • top_countries — Top countries.
  • top_zero_day_malware_apt — Top zero-day malware detected by APT Blocker.
  • top_clients — Top client devices.
  • top_domains — Top domain names.
  • top_url_categories — Top website URL categories.
  • top_destinations — Top destinations for traffic.
  • top_applications — Top applications.
  • top_application_categories — Top application categories.
  • top_protocols — Top network traffic protocols.

Example: top_countries

filterValue
string

Filter value to filter results by.

Specify the filter in the filter parameter, then specify a filter value in this parameter. For example, if the filter parameter value is top_countries, then the filterValue value could be USA.

Example: USA

Example Request

This request retrieves the countries with the most traffic through the Firebox for the specified period of time:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/reports/v1/report/WGC-1-123abc456/executive?view=top_countries&startDate=2023-10-01T18:30:00&endDate=2023-11-01T18:30:00&devices=FB-12345  
		-H 'Accept: application/json'
		-H 'Content-Type: application/json'
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
	"status": "success",
	"view": "top_countries",
	"data": [
		{
		"bytes": "306456856",
		"connections": "904",
		"detail": "",
		"name": "USA"
		},
		{
		"bytes": "2083419",
		"connections": "61",
		"detail": "",
		"name": "IRL"
		},
		{
		"bytes": "508774",
		"connections": "1",
		"detail": "",
		"name": "GBR"
		},
		{
		"bytes": "297406",
		"connections": "7",
		"detail": "",
		"name": "ESP"
		},
		{
		"bytes": "41288",
		"connections": "7",
		"detail": "",
		"name": "JPN"
		}
		]
	}

This table lists and describes the data returned in the response:

status
string

Status of the request.

Example: Success

view
string

Type of Executive Dashboard records retrieved.

This can be one of these values:

  • top_countries — Top countries.
  • top_zero_day_malware_apt — Top zero-day malware detected by APT Blocker.
  • top_clients — Top client devices.
  • top_domains — Top domain names.
  • top_url_categories — Top website URL categories.
  • top_destinations — Top destinations for traffic.
  • top_applications — Top applications.
  • top_application_categories — Top application categories.
  • top_protocols — Top network traffic protocols.

Example: true

data
object

Data returned by the API.

bytes
string

Total number of bytes of data.

Example: 906 KB

connections
string

Number of connections.

Example: 100

detail
string

Additional detail related to the traffic.

name
string

Name of the Executive Dashboard item. This varies by the type of record.

For example, if you requested Top Domains records, this is a domain name. If you requested Top Countries records, this is a country code.

Example: example.com

Get Data from the Security Dashboard Report

/{v1}/report/{accountid}/security

The Security Dashboard report in WatchGuard Cloud shows the top threats in each security area protected by subscription services on the selected Firebox.

Make a request to this endpoint to retrieve the specified Security Dashboard data for the specified devices.

For more information about the Security Dashboard report, go to Security Dashboard in the WatchGuard Cloud Help.

Path Parameters

When you send a request to this endpoint, you must include these path parameters:

accountid
string
REQUIRED

Your WatchGuard Cloud account ID. You can see your accountId on the My Account page in WatchGuard Cloud.

Example: WGC-1-123abc456 or ACC-1234567

Request Parameters

When you send a request to this endpoint, you can include these request parameters:

view
string
REQUIRED

Specifies the type of Security Dashboard records to retrieve.

Specify one of these values:

  • top_blocked_countries — Top countries blocked by Geolocation.
  • top_blocked_advanced_malware_apt — Top malware blocked by APT Blocker.
  • top_blocked_botnet_sites — Top botnet sites blocked by Botnet Detection.
  • top_blocked_clients — Top clients blocked by the Firebox.
  • top_blocked_destinations — Top destinations of traffic blocked by the Firebox.
  • top_blocked_url_categories — Top website categories blocked by WebBlocker.
  • top_blocked_applications — Top applications blocked by Application Control.
  • top_blocked_application_categories — Top application categories blocked by Application Control.
  • top_blocked_protocols — Top network traffic protocols blocked by the Firebox.
  • top_blocked_attacks — Top attacks blocked by the Firebox.
  • top_blocked_malware — Top malware blocked by the Firebox.

Example: top_blocked_countries

startDate
string
REQUIRED

Start date and time of the period to retrieve records for.

Example: 2023-10-04T18:30:00

endDate
string
REQUIRED

End date and time of the period to retrieve records for.

Example: 2023-10-04T18:30:00

devices
string

Comma-separated device IDs of the Fireboxes and FireClusters to retrieve records for.

Each device has a unique ID number in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, your device ID is FB-12345.

If you do not specify device IDs, the API returns records for all Fireboxes and FireClusters in the account.

Example: FB-12345,FBCL-11250

rowCount
integer

Number of records to return. The default value is 10 and the maximum value is 500.

Example: 25

filter
string

Type of Security Dashboard record to filter results on.

Specify the filter in this parameter, then specify a filter value in the filterValue parameter. For example, if the filter parameter value is top_blocked_countries, then the filterValue value could be USA.

Specify one of these values:

  • top_blocked_countries — Top countries blocked by Geolocation.
  • top_blocked_advanced_malware_apt — Top malware blocked by APT Blocker.
  • top_blocked_botnet_sites — Top botnet sites blocked by Botnet Detection.
  • top_blocked_clients — Top clients blocked by the Firebox.
  • top_blocked_destinations — Top destinations of traffic blocked by the Firebox.
  • top_blocked_url_categories — Top website categories blocked by WebBlocker.
  • top_blocked_applications — Top applications blocked by Application Control.
  • top_blocked_application_categories — Top application categories blocked by Application Control.
  • top_blocked_protocols — Top network traffic protocols blocked by the Firebox.
  • top_blocked_attacks — Top attacks blocked by the Firebox.
  • top_blocked_malware — Top malware blocked by the Firebox.

Example: top_blocked_countries

filterValue
string

Filter value to filter results by.

Specify the filter in the filter parameter, then specify a filter value in this parameter. For example, if the filter parameter value is top_blocked_countries, then the filterValue value could be USA.

Example: USA

Example Request

This request retrieves the top countries blocked by the Firebox for the specified period of time:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/reports/v1/report/WGC-1-123abc456/security?view=top_blocked_countries&startDate=2023-10-01T18:30:00&endDate=2023-11-01T18:30:00&devices=FB-12345  
		-H 'Accept: application/json'
		-H 'Content-Type: application/json'
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
	"status": "success",
	"view": "top_blocked_countries",
	"data": [
		{
		"bytes": "0",
		"connections": "6",
		"detail": "",
		"name": "AUS"
		},
		{
		"bytes": "0",
		"connections": "2",
		"detail": "",
		"name": "GBR"
		},
		{
		"bytes": "0",
		"connections": "2",
		"detail": "",
		"name": "NZL"
		}
		]
	}

This table lists and describes the data returned in the response:

status
string

Status of the request.

Example: Success

view
string

Name of the Security Dashboard records retrieved.

This can be one of these values:

  • top_blocked_countries — Top countries blocked by Geolocation.
  • top_blocked_advanced_malware_apt — Top advanced malware blocked by APT Blocker.
  • top_blocked_botnet_sites — Top botnet sites blocked by Botnet Detection.
  • top_blocked_clients — Top clients blocked by the Firebox.
  • top_blocked_destinations — Top destinations of traffic blocked by the Firebox.
  • top_blocked_url_categories — Top website categories blocked by WebBlocker.
  • top_blocked_applications — Top applications blocked by Application Control.
  • top_blocked_application_categories — Top application categories blocked by Application Control.
  • top_blocked_protocols — Top network traffic protocols blocked by the Firebox.
  • top_blocked_attacks — Top attacks blocked by the Firebox.
  • top_blocked_malware — Top malware blocked by the Firebox.

Example: true

data
object

Data returned by the API.

bytes
string

Total number of bytes.

Example: 906 KB

connections
string

Number of connections.

Example: 100

detail
string

Additional detail related to the traffic.

name
string

Name of the Security Dashboard item. This varies by the type of record.

For example, if you requested Top Blocked Domains records, this is a domain name. If you requested Top Blocked Countries records, this is a country code.

Example: example.com