How to Use JSONPath in SGNL

What is JSONPath?

JSONPath is a query language for JSON, like XPath is for XML. It provides a way to navigate through and retrieve data from complex JSON structures by specifying the paths to the desired data elements. JSONPath expressions can use either the dot-notation or the bracket-notation for input paths, though internal or output paths will always be converted to the more general bracket-notation. JSONPath allows the use of:

  • the wildcard symbol * for member names and array indices
  • the descendant operator ..
  • the array slice syntax proposal [start:end:step]

Purpose of JSONPath in SGNL

JSONPath helps retrieve specific data from JSON structures without special scripting. Within SGNL, there are many situations where an upstream client of SGNL will send the service JSON, and there are many times when we want to be selective about the data that we extract from that payload. In that way JSON data can be reduced to parts relevant to SGNL.

SoR Entities Example:

Jira Issues can have associated assets represented as a nested list of JSON objects within the Jira Issues API response. To represent these assets as separate entities in your SGNL graph, you can define a child entity and use JSONPath as the ExternalId to represent the children as new entities:

  • Parent Entity: “Jira Issue”
  • Child Entity: “Asset”
  • Child Entity ExternalId: $.assets[*].id (This path would extract the ‘id’ of all assets from the ‘assets’ array within the Jira Issue data).

By defining the “Asset” entity as a child entity with the specified JSONPath, SGNL will automatically create a “parent” relationship between each “Asset” entity and the “Jira Issue” entity that contains it.

JSONPath in SoR Template YAML Files

SGNL allows for the creation of SoRs using YAML templates.

  • UserRiskFactor Entity: CrowdStrike’s SoR template provides an example of the use of JSONPath to define a UserRiskFactor entity as a child of the User entity. In the UserRiskFactor definition, the externalId is set to $.riskFactors, indicating that the UserRiskFactor data is nested within the ‘riskFactors’ array of the User data.
  • UserAccountActiveDirectory Entity: Another example from the CrowdStrike template is the definition of UserAccountActiveDirectory as a child of the User entity. This entity uses a JSONPath expression with a filter to specify the exact Active Directory account details within the User data: $.accounts[?(@.__typename=="ActiveDirectoryAccountDescriptor")].

JSONPath in Event Streams Templates

Event Stream Templates make extensive use of JSONPath to retrieve attributes from a Security Event Token

  • Token ID: The ID of a Security Event Token(SET) is the JTI, SGNL retrieves that using $.jti
  • Subject: We require that a token has a subject in SGNL, and to retrieve that value out of the token, you may use JSONPath Syntax such as $.sub_id.email

JSONPath in Transforms and Provider Hooks

Transorms and Provider Hooks make extensive use of JSONPath to extract mapping values from upstream providers, IdPs, Proxies, and more

  • *Application IDs: Depending on your provider, you might want to extract some ID from a JSON Payload sent by the likes of Entra ID or Okta, in that case, you might use {$.data.authenticationContext.resourceServicePrincipal.appId} for Entra, or {$.data.context.protocol.issuer.id} for Okta

Important Considerations

  • Index Starting Point: JSONPath uses a zero-based index for arrays, meaning the first element has an index of 0. This differs from XPath, which uses a one-based index.
  • Quotes: Currently, only single quotes are allowed inside of JSONPath expressions.
  • Script Expressions: Script expressions inside of JSONPath locations are currently not recursively evaluated by jsonPath. Only the global $ and local @ symbols are expanded by a simple regular expression.

By understanding these concepts and using the provided examples, you can effectively map attributes from your SoRs into the SGNL platform using JSONPath, enabling powerful data representation and analysis within your SGNL graph.