HomeGuides
Try a DemoGet the Latest ReleaseSee the CHANGELOGCreate a Feature Request / Bug ReportJoin the Conversation
Guides

Enrich

Enrich transforms enrich data using an external system or process.

enrich.aws.dynamodb.query

Transforms data by querying an AWS DynamoDB table and returning all matched items as an array of objects.

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object for transformation.

If the key is an array that contains two values, then the values are sent to DynamoDB as a composite key (parition key and sort key).
No
object.target_keystringPlaces a value into an object after transformation.No
aws.arnstringAWS resource (DynamoDB table) that is accessed.Yes
aws.assume_role_arnstringAWS role that is used to authenticate.

Defaults to an empty string (no role assumption is used).
No
attributes.partition_keystringPartition key column in the DynamoDB table.Yes
attributes.sort_keystringSort key column in the DynamoDB table.

Defaults to an empty string (no Sort Key is used by the table).
No
limitintegerDetermines the maximum number of items to evaluate in the DynamoDB query.

Defaults to zero (no limit).
No
scan_index_forwardbooleanSpecifies the order of index traversal. If set to true, then traversal is performed in ascending order; if set to false, then traversal is performed in descending order.No

Example

sub.transform.enrich.aws.dynamodb.query({
  object: { source_key: 'id', target_key: 'id_val' },
  aws: { arn: 'arn:aws:dynamodb:us-east-2:123456789012:table/my-table' },
})
sub.tf.enrich.aws.dynamodb.query({
  object: { source_key: 'id', target_key: 'id_val' },
  aws: { arn: 'arn:aws:dynamodb:us-east-2:123456789012:table/my-table' },
)

enrich.aws.lambda

Transforms data by synchronously invoking an AWS Lambda function and returning the payload.

If you need to asynchronously invoke a Lambda function, then use the send AWS Lambda transform.

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object for transformation.No
object.target_keystringPlaces a value into an object after transformation.No
aws.regionstringAWS region that the Lambda function is in.

Defaults to the AWS_REGION and AWS_DEFAULT_REGION environment variables.
No
aws.role_arnstringAWS role that is used to authenticate.

Defaults to an empty string (no role assumption is used).
No
retry.countintMaximum number of times to retry invocations to the Lambda function.

Defaults to the AWS_MAX_ATTEMPTS environment variable.
No
function_namestringThe Lambda function that is synchronously invoked.Yes

Example

sub.transform.enrich.aws.lambda(
  settings={function_name: 'myFunction'}
)
sub.tf.enrich.aws.lambda({function_name: 'myFunction'})

enrich.dns.domain_lookup

Transforms data by querying a domain in the Domain Name System (DNS).

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object for transformation.No
object.target_keystringPlaces a value into an object after transformation.No
request.timeoutstringMaximum time to wait for a query to complete.

Defaults to 1s.
No

Example

sub.transform.enrich.dns.domain_lookup(
  settings={object: {source_key: 'domain'}}
)
sub.tf.enrich.dns.domain_lookup({obj: {src: 'domain'}})

enrich.dns.ip_lookup

Transforms data by querying an IP address in the Domain Name System (DNS).

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object for transformation.No
object.target_keystringPlaces a value into an object after transformation.No
request.timeoutstringMaximum time to wait for a query to complete.

Defaults to 1s.
No

Example

sub.transform.enrich.dns.ip_lookup(
  settings={object: {source_key: 'ip'}}
)
sub.tf.enrich.dns.ip_lookup({obj: {src: 'ip'}})

enrich.dns.txt_lookup

Transforms data by querying a TXT record in the Domain Name System (DNS).

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object for transformation.No
object.target_keystringPlaces a value into an object after transformation.No
request.timeoutstringMaximum time to wait for a query to complete.

Defaults to 1s.
No

Example

sub.transform.enrich.dns.txt_lookup(
  settings={object: {source_key: 'ip'}}
)
sub.tf.enrich.dns.txt_lookup({obj: {src: 'ip'}})

enrich.http.get

Transforms data by performing a GET request to an HTTP(S) URL.

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object for transformation.No
object.target_keystringPlaces a value into an object after transformation.No
urlstringThe HTTP(S) URL used in the GET request.

URLs support loading secrets.
Yes
headers[]objectAn array of objects that contain HTTP headers sent in the request. Header values support loading secrets.

Defaults to no headers.
No

Example

sub.transform.enrich.http.get(
  settings={url: 'https://my.url/'}
)
sub.tf.enrich.http.get({url: 'https://my.url/'})

enrich.http.post

Transforms data by performing a POST request to an HTTP(S) URL.

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object for transformation.No
object.target_keystringPlaces a value into an object after transformation.No
object.body_keystringRetrieves a value from an object that is used as the message body.Yes
urlstringThe HTTP(S) URL used in the GET request.

URLs support loading secrets.
Yes
headers[]objectAn array of objects that contain HTTP headers sent in the request. Header values support loading secrets.

Defaults to no headers.
No

Example

sub.transform.enrich.http.post(
  settings={object: {body_key: 'payload'}, url: 'https://my.url/'}
)
sub.tf.enrich.http.post({object: {body_key: 'payload'}, url: 'https://my.url/'})

enrich.kv_store.item.get

Transforms data by retrieving an item from a key-value store.

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object that is used as the key in the KV store.Yes
object.target_keystringPlaces the KV store result into an object.Yes
prefixstringString that is prepended to the value retrieved by object.key.

Defaults to an empty string (no prefix is used).
No
kv_storeobjectThe KV store configuration settings. Refer to each KV store backend described in Key-Value Stores for more information.Yes
close_kv_storebooleanDetermines if the KV store should be closed when a control message is received.

Defaults to false (KV store is not closed).
No

Example

sub.transform.enrich.kv_store.item.get(
  settings={kv_store: sub.kv_store.memory(settings={}), object: {source_key: 'ip', target_key: 'domain'}}
)
sub.tf.enrich.kv_store.iget({kv_store: sub.kv_store.memory(settings={}), obj: {src: 'ip', trg: 'domain'}})

enrich.kv_store.item.set

Transforms data by setting an item into a key-value store.

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object that is used as the key in the KV store.Yes
object.target_keystringPlaces an item from an object that is used as the value in the KV store.Yes
object.ttl_keystringRetrieves a value from an object that is used as the time-to-live (TTL) of the item set into the KV store. This value must be an integer that represents the Unix time when the item will be evicted from the store. Any precision greater than seconds (e.g., milliseconds, nanoseconds) is truncated to seconds.

Defaults to an empty string (no TTL is used when setting items into the store).
No
prefixstringString that is prepended to the value retrieved by object.key.

Defaults to an empty string (no prefix is used).
No
ttl_offsetstringAn offset used to determine the time-to-live (TTL) of the item set into the KV store. If ttl_key is configured, then this value is added to the TTL value retrieved from the object. If ttl_key is not used, then this value is added to the current time.

For example, if ttl_key is not configured and the offset is "1d" (1 day), then the value will be evicted from the store when more than 1 day from now has passed.

Defaults to an empty string (no TTL is used when setting items into the store).
No
kv_storeobjectThe KV store configuration settings. Refer to each KV store backend described in Key-Value Stores for more information.Yes
close_kv_storebooleanDetermines if the KV store should be closed when a control message is received.

Defaults to false (KV store is not closed).
No

Example

sub.transform.enrich.kv_store.item.set(
  // The value of `domain` is put into the KV store as the value of `ip`.
  settings={kv_store: sub.kv_store.memory(settings={}), object: {source_key: 'ip', target_key: 'domain'}}
)
sub.tf.enrich.kv_store.iset({kv_store: sub.kv_store.memory(settings={}), obj: {src: 'ip', trg: 'domain'}})

enrich.kv_store.set.add

Transforms data by adding to a set (unique, unordered list) in a key-value store.

Settings

FieldTypeDescriptionRequired
object.source_keystringRetrieves a value from an object that is used as the key in the KV store.Yes
object.target_keystringPlaces an item from an object that is used as the value in the KV store.Yes
object.ttl_keystringRetrieves a value from an object that is used as the time-to-live (TTL) of the item set into the KV store. This value must be an integer that represents the Unix time when the item will be evicted from the store. Any precision greater than seconds (e.g., milliseconds, nanoseconds) is truncated to seconds.

Defaults to an empty string (no TTL is used when setting items into the store).
No
prefixstringString that is prepended to the value retrieved by object.key.

Defaults to an empty string (no prefix is used).
No
ttl_offsetstringAn offset used to determine the time-to-live (TTL) of the item set into the KV store. If ttl_key is configured, then this value is added to the TTL value retrieved from the object. If ttl_key is not used, then this value is added to the current time.

For example, if ttl_key is not configured and the offset is "1d" (1 day), then the value will be evicted from the store when more than 1 day from now has passed.

Defaults to an empty string (no TTL is used when setting items into the store).
No
kv_storeobjectThe KV store configuration settings. Refer to each KV store backend described in Key-Value Stores for more information.Yes
close_kv_storebooleanDetermines if the KV store should be closed when a control message is received.

Defaults to false (KV store is not closed).
No

Example

sub.transform.enrich.kv_store.set.add(
  // The value of `domain` is added to a set in the KV store indexed by the value of `ip`.
  settings={kv_store: sub.kv_store.memory(settings={}), object: {source_key: 'ip', target_key: 'domain'}}
)
sub.tf.enrich.kv_store.sadd({kv_store: sub.kv_store.memory(), obj: {src: 'ip', trg: 'domain'}})

Use Cases

Data Interpolation

The enrich_http_get and enrich_http_post transforms can optionally interpolate data into the URL by placing the string ${data} anywhere in the URL. For example:

Configured URLDataInterpolated URL
hxxps://foo.com/path/to/${data}{"ip_addr":"8.8.8.8"}hxxps://foo.com/path/to/8.8.8.8
hxxps://foo.com/path/to/${data}8.8.8.8hxxps://foo.com/path/to/8.8.8.8

Secrets Interpolation

The enrich_http_get and enrich_http_post transforms can also optionally interpolate secrets with the URL and header values. Multiple secrets can be interpolated in a single string. For example:

Configured URLDataEnvironment VariablesInterpolated URL
hxxps://foo.com/path/to/${data}?token=${SECRETS_ENV:TOKEN}{"ip_addr":"8.8.8.8"}TOKEN=mysecrethxxps://foo.com/path/to/8.8.8.8?token=mysecret
hxxps://foo.com/path/to/${data}?token=${SECRETS_ENV:TOKEN}&user=${SECRETS_ENV:USERNAME}{"ip_addr":"8.8.8.8"}TOKEN=mysecret
USERNAME=myusername
hxxps://foo.com/path/to/8.8.8.8?token=mysecret&user=myusername

Enriching Data with HTTP APIs

The enrich_http_get transform is the recommended method for interacting with external HTTP/S APIs:

sub.tf.util.secret(settings={ 
  secret: sub.secrets.environment_variable({ id: 'ENV_VAR', name: 'API_KEY' }) 
}),
sub.tf.enrich.http.get(settings={ 
  // The value of `ip_addr` is interpolated into the URL and the API 
  // results are set into `api_result`.
  object: {source_key: 'ip_addr', target_key: 'api_result'}, 
  url: 'hxxps://api.foo.com/${DATA}',
  // The secret is interpolated into the TOKEN header for auth.
  headers: {
    TOKEN: '${SECRET:ENV_VAR}',
  },
}),

Downloading Text Files via HTTP

The enrich_http_get transform can be used to download text files from any HTTP/S endpoint. For example, it can download Moby Dick by Herman Melville:

URLMessage
https://www.gutenberg.org/files/2701/old/moby10b.txt{"moby_dick":"**The Project Gutenberg Etext of Moby Dick, by Herman Melville**"}

This can be combined with the object_copy transform to overwrite the original data, leaving only the downloaded file.

Downloading Non-Text Files via HTTP

The enrich_http_get transform can also be used to retrieve non-text (e.g., binary) files. For example, it can be used to download a PDF version of Moby Dick:

URLCapsule
http://www.gasl.org/refbib/Melville__Moby_Dick.pdf{"moby_dick":"JVBERi0xLjU="}

KV Store

The KV store transforms enable several use cases, see Key-Value Stores for detailed examples.