Skip to main content

JSON Connector

A JavaScript Object Notation (JSON) file is a lightweight and text-based data interchange format. JSON files organize data into a structured hierarchy, containing arrays and objects to represent data, making it an ideal format for storing and transporting data across a network. This format is extensively used to store configurations, settings, and detailed information about systems, assets, and users in various cybersecurity applications.

Brinqa offers a JSON Connector to facilitate the ingestion of data from JSON files. Assuming that your data is stored in a proprietary format that the existing connectors cannot accommodate, you have the option of exporting your data to JSON files, and then leveraging the JSON Connector to ingest your data into the Brinqa Platform for further processing. This integration empowers you to build a unified view of your attack surface and strengthen your cybersecurity posture.

This document details the information you must provide for the connector to retrieve JSON files. See create a data integration for step-by-step instructions on setting up the integration.

Required connection settings​

When setting up a data integration, select JSON Connector from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information:

  • Server: The connector requires that you create a data server for the machine where the JSON files reside. Select the data server that you've created.

  • Data directory: Enter the fully qualified path to the data directory where the JSON files reside. You can use wildcards (*) in the path, e.g., feed/vendors/vendor_*.json or /feed/mobile/mobile_device*.*.

  • JSON path: Represents the parsing path to target the JSON objects within the document. For example, a path such as $.[*] indicates that the connector should navigate through the array of objects at the root of your JSON document.

  • Date fields: (Optional) Enter a comma-separated list of fields that contain dates, such as date_created or date_modified. You can use delimiters such as ,, ;, or : to separate multiple date fields.

  • Date format: (Optional) The date format for parsing the date fields, such as MM/dd/yyyy. This configuration supports both custom date formats and static values such as ISO_OFFSET and ISO_UTC.

  • Max age: (Optional) The maximum number of days that a file is retained. A value less than zero implies that the file never expires, while zero indicates that the file should not be retained.

  • Max files: (Optional) The maximum number of files to retain. A value less than zero implies that there is no limit to the number of files to retain, while zero indicates that no files should be kept.

  • Rename or move the file after its processed: Select this option if you want the connector to rename or move the file after it has been processed.

    tip

    If you enable this option, after a file has been ingested, the connector renames the file by appending .processed to the file name. This ensures that the same file won't be ingested multiple times in subsequent sync operations.

  • Target: Specify the unified data model (UDM) to map your data to. The default selection is Record.

Types of data to retrieve​

The JSON Connector retrieves records from JSON files and maps them to the data model you specify in the Target field.

info

The JSON Connector does not currently support operation options for the types of data it retrieves.

For detailed steps on how to view the data retrieved from the JSON Connector in the Brinqa Platform, see How to view your data.

Supported JSON structure​

The JSON Connector is optimized for working with Flat JSON files. This means that the ideal JSON file should not have deeply nested structures. However, if your data includes nested items, you can utilize JSON Path expressions to effectively navigate through the JSON document and reach the desired flat object.

For more detailed guidance on using JSON Path expressions, please see the Oracle documentation on JSON Path Expressions.

Sample JSON file​

Below is an example of a flat JSON structure, compatible with the JSON Connector, that represents device information:

[
  {
    "firstSeen": "2023-01-15T08:00:00Z",
    "lastAssessed": "2023-03-01T08:00:00Z",
    "lastUpdated": "2023-03-10T08:00:00Z",
    "macAddresses": ["00:1B:44:11:3A:B7", "00:1B:44:11:3A:B8"],
    "manufacturer": "Dell",
    "owners": ["John Doe", "Jane Smith"]
  },
  {
    "firstSeen": "2023-02-20T08:00:00Z",
    "lastAssessed": "2023-03-05T08:00:00Z",
    "lastUpdated": "2023-03-12T08:00:00Z",
    "macAddresses": ["00:1B:44:22:3A:C7", "00:1B:44:22:3A:C8"],
    "manufacturer": "Apple",
    "owners": ["Alice Johnson", "Bob Brown"]
  }
]

In the above example, each object within the array represents a record with flat attributes (firstSeen, lastAssessed, lastUpdated, macAddresses, manufacturer, owners).

If your JSON files contain nested structures, consider restructuring them into a similar flat format or using JSON Path to specify the location of the desired data. Identify the key containing the flat object list and use a JSON Path expression such as $.path.to.flat.object[*] to extract it for processing.

APIs​

As the JSON Connector is file-based, it doesn't rely on any API endpoints and thus, doesn't offer any operation options.

Changelog​

The JSON Connector has undergone the following changes:

3.0.0