KnowBe4 API Source

The KnowBe4 API integration collects user events data into Sumo Logic for storage, analysis, and alerting. It ingests events data from the Events API, phishing security tests from the Phishing Security Tests API, and recipient results from the Recipient Results API.

note

This source is available in all deployments, including the Fed deployment.

Data collected

Polling Interval	Data
5 min	User Event
24 hours	Phishing Security Tests

note

C2C will skip the record if started_at data is not in the format of yyyy-MM-ddTHH:mm:ss.SSSZ.

Setup

Vendor configuration

note

KnowBe4 APIs are only limited to Platinum and Diamond customers.

Before you begin setting up your KnowBe4 Source, which is required to connect to the KnowBe4 API, you'll need to configure your integration with the Region and KnowBe4 API Token.

Region

The Region is the region where your KnowBe4 account is located. To know your region, follow the steps below:

1. Sign in to the KnowBe4 application.
2. At the top of the browser, you will see the Region inside the address bar.
3. Choose the Region from the dropdown based on the location of your KnowBe4 account. The following are the supported regions:
   • US
   • EU
   • CA
   • UK
   • DE

API Token

The API security token is used to authenticate with KnowBe4 API. To get the KnowBe4 API token, follow the steps below:

1. Sign in to the KnowBe4 application as an Admin user.
2. Navigate to the Account Settings.
3. Click Account Integrations from the left menu, and then click API option.
4. Under the API section, checkmark the Enable Reporting API Access. The KnowBe4 Secure API token is displayed.
5. Save this API key to use while configuring the Source.
6. Click Save Changes.

Source configuration

When you create a KnowBe4 API Source, you add it to a Hosted Collector. Before creating the Source, identify the Hosted Collector you want to use or create a new Hosted Collector. For instructions, see Configure a Hosted Collector.

To configure the KnowBe4 API Source:

1. In Sumo Logic, select Manage Data > Collection > Collection. 
2. On the Collectors page, click Add Source next to a Hosted Collector.
3. Select KnowBe4 icon.
4. Enter a Name to display for the Source in the Sumo Logic web application. The description is optional.
5. (Optional) For Source Category, enter any string to tag the output collected from the Source. Category metadata is stored in a searchable field called _sourceCategory.
6. (Optional) Fields. Click the +Add Field link to define the fields you want to associate. Each field needs a name (key) and value.
   •  A green circle with a check mark is shown when the field exists in the Fields table schema.
   •  An orange triangle with an exclamation point is shown when the field doesn't exist in the Fields table schema. In this case, an option to automatically add the nonexistent fields to the Fields table schema is provided. If a field is sent to Sumo Logic that does not exist in the Fields schema it is ignored, known as dropped.
7. In Region, choose the region where your KnowBe4 account is located. See Region section to know your Region.
8. In API Key, authenticate your account by entering your secret API key. You can access your API key or generate a new one from User Event API Management Console. See API Token section.
9. In Data Types, you can select the Phishing Tests data type to fetch a list of all recipients for each phishing security test on your KnowBe4 account.
10. In Phishing Poll Interval, enter the phishing poll interval frequency, which must be between 1 hour and 24 hours.
11. When you are finished configuring the Source, click Submit.

Metadata Field

If the Source is configured with the SIEM forward option, the metadata field _siemparser will be set to /Parsers/System/KnowBe4/KnowBe4 KMSAT.

info

The _siemparser is currently available only for the External Events source.

JSON schema

Sources can be configured using UTF-8 encoded JSON files with the Collector Management API. See how to use JSON to configure Sources for details. 

Parameter	Type	Value	Required	Description
schemaRef	JSON Object	{"type":"KnowBe4 KMSAT"}	Yes	Define the specific schema type.
sourceType	String	"Universal"	Yes	Type of source.
config	JSON Object	Configuration object	Yes	Source type specific values.

Configuration Object

Parameter	Type	Required	Default	Description	Example
name	String	Yes	null	Type a desired name of the source. The name must be unique per Collector. This value is assigned to the metadata field _source.	"mySource"
description	String	No	null	Type a description of the source.	"Testing source"
category	String	No	null	Type a category of the source. This value is assigned to the metadata field _sourceCategory. See best practices for details.	"mySource/test"
fields	JSON Object	No	null	JSON map of key-value fields (metadata) to apply to the Collector or Source. Use the boolean field _siemForward to enable forwarding to SIEM.	{"_siemForward": false, "fieldA": "valueA"}
region	String	Yes	null	Region of the KnowBe4 application.
apiKey	String	Yes	null	Secret api key to authenticate your account.
dataTypes	Array	Yes	null	Data sources to fetch from KnowBe4.
phishingPollInterval	Integer	Yes	1 hour	The Polling interval for phishing data requests. The minimum interval is 1 hour, and the maximum is 24 hours.

JSON example

{
    "api.version": "v1",
    "source": {
        "config": {
  		"name": "KnowBe4",
 	 	"description": "Test Source",
  		"category": "source_category",
  		"region": "US",
  		"apiKey": "************",
		"dataTypes": [
    		         "phishingTests"
  		],
		"phishingPollInterval": 1
          },
        "schemaRef": {
            "type": "KnowBe4 KMSAT"
        },
        "sourceType": "Universal"
    }
}

Download example

Terraform example

resource "sumologic_cloud_to_cloud_source" "knowbe4-api-source" {
  collector_id = sumologic_collector.collector.id
  schema_ref = {
    type = "KnowBe4 KMSAT"
  }
  config = jsonencode({
  		"name": "KnowBe4",
 	 	"description": "Test Source",
  		"category": "source_category",
  		"region": "US",
  		"apiKey": "************",
		"dataTypes": [
    		         "phishingTests"
  		],
		"phishingPollInterval": 1
  })
}
resource "sumologic_collector" "collector" {
  name        = "my-collector"
  description = "Just testing this"
}

Download example

Limitations

There are two limitations to access KnowBe4 APIs:

• Access to the KnowBe4 Event APIs is limited to 10 requests per licensed user account per day, with a maximum of 4 requests per second.
• Access to the KnowBe4 Phishing APIs is limited to 1,000 requests per day plus the number of licensed users on the account. The API allows a maximum of 4 requests per second, and has a burst limit of 50 requests per minute which starts around 5 minutes and the daily limit starts around 24 hours from the first API request.

FAQ

info

Click here for more information about Cloud-to-Cloud sources.