Collect data using HTTP

See the changelog of the HTTP Listener type here.

Overview

Onum supports integration with HTTP.

HTTP, which stands for Hypertext Transfer Protocol, is a foundational protocol for communication on the World Wide Web. It defines how messages are formatted and transmitted between web servers and browsers, enabling the retrieval and display of webpages and other web content.

Prerequisites

Contact Onum to get the cert information needed for TLS communication, which will be needed on the Listener setup.

Important notes

• The SIEM type will be Other.

• You must generate a JWT token and add it as an HTTP header. Add the word Bearer before the token value (Bearer <token>). The corresponding secret value will be added in the Onum configuration later.

Contact us if you cannot generate a JWT token.

Onum Setup

1

Log in to your Onum tenant and click Listeners > New listener.

2

Double-click the HTTP Listener.

3

Enter a Name for the new Listener. Optionally, add a Description and some Tags to identify the Listener.

4

In the Socket section, enter the required Port. By default, all TCP ports from 1024 to 10000 are open.

Note that you won't see the Socket and TLS configuration sections in the creation form if you're defining this Listener in a Cloud instance, as Onum already provides these. Learn more about Cloud Listeners in this article.

5

In the TLS configuration section, enter the data you received from the Onum team (Certificate, Private key and CA chain). Choose No client certificate as Client authentication method and TLS v.1.0 as the Minimum TLS version.

Note that the parameters in this section are only mandatory if you decide to include TLS authentication in this Listener. Otherwise, leave blank.

6

If your connection does not require Authentication, leave as None. Otherwise, choose the authentication type and enter the details.

The options provided will vary depending on the type chosen to authenticate your API. This is the type you have selected in the API end, so it can recognize the request.

Basic

Enter the following:

• Username* - The user sending the request.

• Password* - Choose the basic auth password from your list of Secrets or create a new one.

Bearer

Bearer Token Authentication

Enter your Token Secret for the API request using an existing Secret or creating a new one if you haven't stored it in Onum yet.

This grants access without needing to send credentials (like username and password) in every request.

Example

Let's say you have the following configuration:

• Port - 8080

• Authentication Type - Bearer

• Bearer Token Secret - a-string-secret-at-least-256-bits-longthis is the value you enter into Onum as the secret.

• Request path - localhost

When you Listen for the HTTP request, the token will be encoded (generated by https://jwt.io/ here) eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

This entire request will show as follows: "http://localhost:8080/bearer" 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30'

API Key in URL Params

Enter the following:

• API Key Name* - A label assigned to the API key for identification. You can find it depending on where the API key was created.

• API Key Value* - API keys are usually stored in developer portals, cloud dashboards, or authentication settings. Choose the existing Secret or create a new one if you haven't stored this key within Onum.

Note that if you select this option, the HTTP Listener expects the API Key to be included in the URL, as a query parameter. For example:

curl --location 'http://customer.in.prod.onum.com:2250/test?My-Token=1234567890qwerty' \
--header 'Content-Type: application/json' \
--data '{"message": "hello, how are you doing? :)"}'

API Key in Header

Enter the following:

• API Key in Header Name* - A label assigned to the API key for identification. You can find it depending on where the API key was created.

• API Key in Header Value* - API keys are usually stored in developer portals, cloud dashboards, or authentication settings. Choose the existing Secret or create a new one if you haven't stored this key within Onum.

Learn more about secrets in Onum in this article.

7

You can now select the secret you just created in the Token Secret field.

8

In the Endpoint section, choose GET, POST, or PUT method and the Path to the resource being requested from the server.

9

In the Message extraction section, the strategy defines how data extraction should be performed. It is the overall methodology or approach used to extract relevant information from HTTP messages. Choose between:

• Single event with the whole request - Choose this option if you want to include the whole request in each event.

• Single event from request path - Choose this option if you want to include the request paths in each event.

• Single event as query string - Choose this option if you want to include the requests with their whole query strings.

• Single event as query parameter - Choose this option if you want to include a specific request parameter in your events. Specify the required parameter name in the Extraction info option (for example: msg)

• Single event as header - Choose this option if you want to include a specific header in your events. Specify the required header in the Extraction info option (for example: Message)

• Single event as body (partially) - Choose this option if you want to include a part of the request body in your events. Specify the required RegEx rule to match the required part in the Extraction info option (for example: \\[BODY: (.+)\\])

• Single event as body (full) - Choose this option if you want to include the whole request body in your events. Specify the required RegEx rule to match the required part in the Extraction info option (for example: \\[BODY: (.+)\\])

• Multiple events at body with delimiter - Choose this option if you want to include several messages in the same event separated by a delimiter. You must specify the delimiter in the Extraction info option.

• Multiple events at body as JSON array - Choose this option if you want to include several messages formatted as a JSON array in your events.

• Multiple events at body as stacked JSON - Choose this option if you want to include several messages formatted as a stacked JSON in your events.

10

In the General behavior section, choose between None (default option), Allow (enter the required header keys below), or All (all headers will be retrieved in the headers field).

11

Then, configure the following settings:

• Header keys - Enter the required header keys in this field. Click Add element for each one.

• Exported headers format - Choose the required format for your headers. The default value is JSON.

• Maximum message length - Maximum characters of the message. The default value is 4096.

• Response code - Specify the response code to show when successful. The default value is 202 Accepted.

• Response Content-Type -

  The Content-Type: xxx/xxx lets the server know the expected format of the incoming message or request (application/json by default):

  • text/plain - The message body contains plain text.

  • application/json - The message body is formatted as JSON.

  • application/xml - The message body is formatted as XML.

  • text/html - The message body contains HTML.

• Response text - The text that will show in case of success.

12

Copy the DNS Address details to configure your data source in order to communicate with Onum. This contains the IP address of the DNS (Domain Name System) server to connect to.

Note that you will only see this section if you're defining this Listener in a Cloud instance. Learn more about Cloud Listeners in this article.

13

Finally, click Create labels. Optionally, you can set labels to be used for internal Onum routing of data. By default, data will be set as Unlabeled. Click Create listener when you're done.

Learn more about labels in this article.

Click Create listener when you're done.