Pull data from the Box API

Overview

Use the HTTP Pull Listener to collect data from the Box API. Currently, we support the events endpoint.

HTTP Pull Listener configuration

In Falcon Onum, go to the Listeners area and click New Listener > HTTP Pull. Give a name to your new Listener and enter the following data:

Parameters

N/A

Secrets

You must define these credentials in Onum:

• client_id will reference your Box Client ID.

• client_secret will reference your Box Client Secret.

To do it, click Add element and enter a Name for the secret (in this case, client_id). Then, click the Value field and select New secret to create a new one:

• Give the secret a Name.

• Turn off the Expiration date option.

• Click Add new value and paste the secret corresponding to the value.

• Click Save.

You can now select the secret you just created in the Value field list. Repeat the process for the client_secret.

Learn more about secrets in Onum in this article.

Setup

After entering the required parameters and secrets, you can choose to manually enter the rest of configuration fields, or simply paste the given YAML:

Config as YAML

Toggle ON the Config as YAML option to enable a free text field where you can paste the following YAML:

withTemporalWindow: true
temporalWindow:
  duration: 30s
  offset: 30s
  tz: UTC
  format: RFC3339
withAuthentication: true
authentication:
  type: token
  token:
    request:
      method: POST
      url: https://api.box.com/oauth2/token 
      headers:
        - name: Content-Type
          value: application/x-www-form-urlencoded
      bodyType: urlEncoded
      bodyParams:
        - name: grant_type
          value: client_credentials
        - name: client_id
          value: '${secrets.client_id}'
        - name: client_secret
          value: '${secrets.client_secret}'
        - name: box_subject_id
          value: 62685208
        - name: box_subject_type
          value: enterprise
    tokenPath: ".access_token"
    authInjection:
      in: header
      name: Authorization
      prefix: 'Bearer '
      suffix: ''
withEnumerationPhase: false
collectionPhase:
  paginationType: "cursor"
  cursorSelector: ".next_stream_position"
  initialRequest:
    responseType: json
    method: GET
    url: "https://api.box.com/2.0/events"
    headers:
      - name: Accept
        value: application/json
    queryParams:
      - name: stream_type
        value: admin_logs
      - name: created_after
        value: ${temporalWindow.from}
      - name: created_before
        value: ${temporalWindow.to}
      - name: limit
        value: '100'
      # REMOVED: event_type parameter - either remove entirely or use valid Box event types
      # Valid types: ACCESS_GRANTED, ADMIN_LOGIN, FILE_MARKED_MALICIOUS, etc.
  nextRequest:
    responseType: json
    method: GET
    url: "https://api.box.com/2.0/events"
    headers:
      - name: Accept
        value: application/json
    queryParams:
      - name: stream_type
        value: admin_logs
      - name: stream_position
        value: '${pagination.cursor}'
      - name: created_after
        value: ${temporalWindow.from}
      - name: created_before
        value: ${temporalWindow.to}
      - name: limit
        value: '100'
output:
    select: ".entries"
    map: "."
    outputMode: "element"

Manually configure

When you're done, click Create labels to move on to the next step and define the required Labels if needed.