Box audit logs

Lakewatch provides an API connector to ingest enterprise audit events from Box. This article covers prerequisites, configuration instructions, the connector schema, and Lakewatch parser indicators.

Prerequisites

The connector requires:

1. Serverless Lakeflow pipelines turned on in your workspace.
2. Unity Catalog, with privileges to create or use a Unity Catalog connection. See Connection permissions.
3. Multi-factor authentication (MFA) enabled on the Box account that creates the app. Box requires MFA before it shows the client secret. See Setup with Client Credentials Grant.
4. An enterprise admin, or a co-admin with the Run new reports and access existing reports permission. The Events API requires this permission. See Get enterprise events. For a co-admin, enable that permission in the Role and Access Permission section of the co-admin details page. See Co-admin permissions required to run reports.

Known limitations

• Slowly changing dimension (SCD) type 2 is not supported because the destination schema includes VARIANT columns.
• The connector supports OAuth machine-to-machine (M2M) authentication with a Box Server Authentication app that uses Client Credentials Grant. OAuth user-to-machine and basic authentication aren't supported.
• Box retains admin_logs_streaming events for 14 days. The first sync starts at stream position 0 and later syncs resume from the last _stream_position.

Configure Box for ingestion

The connector authenticates with a Box Server Authentication app that uses Client Credentials Grant. See Setup with Client Credentials Grant.

1. Sign in to Box and open the Developer Console.
2. Select New App.
3. Select Server as the app type.
4. Leave Client Credentials Grant selected under Select Method.
5. Select Create.
6. On the Configuration tab, set App Access Level to App + Enterprise Access. The Manage enterprise properties scope requires App + Enterprise Access. See Scopes.
7. Under Application Scopes, select Manage enterprise properties. This is the only scope the connector requires. See Get events.
8. Select Save in the upper right.
9. If App Details doesn't show Authorization as Authorized, authorize the app. Server authentication apps must be authorized before use. See Platform app approval.
   • If you are an enterprise admin or co-admin and the Configuration tab prompts you to authorize, authorize the app there.
   • If you are not an admin or co-admin, select Submit app for authorization when prompted. Then give an admin the Client ID.
   • As an admin, you can also authorize the app in the Admin Console. Select Platform in the left navigation, then Platform Apps. Select Add in the upper right, or select ... on the app row, then enter the Client ID.
10. In App Details, under Access:
    • Copy the Client ID.
    • Select Fetch Secret. If Box asks you to sign in again, sign in, then copy the Client Secret.
11. Select your account icon in the upper right, then select Copy Enterprise ID. See Locating IDs.

tip

When you create a connection through the Lakewatch UI, enter the Client ID, Client Secret, and Enterprise ID gathered above.

Next steps

After completing the configuration above, create a datasource with the Box connector in the Lakewatch UI. See API connectors for instructions.

---

Connector and Lakewatch schemas

The connector ingests the following source table from the default source schema:

Source table	Box data	Built-in Lakewatch parser
event_logs	Enterprise audit events, such as user and file activity	box_event_logs

Source table	Box data	Built-in Lakewatch parser
event_logs	Enterprise audit events, such as user and file activity	box_event_logs

The connector writes the source table to the datasource's raw destination. The built-in parser writes a separate parsed table named after the parser, unless you set a parsed destination when you configure the datasource.

Lakewatch-managed columns

The connector uses the source event_id field as the non-null primary key and the source created_at field as the cursor for incremental ingestion. Unlike connectors that synthesize a Lakewatch ID, this connector doesn't add an lw_id column. The API offset _stream_position is not in the destination schema.

For Lakewatch-created pipelines, the connector also adds lw_meta and lw_observables to the raw table. lw_meta contains standard Lakewatch processing metadata. lw_observables contains values extracted from fields marked as security indicators. The parsed table carries these columns forward. See Parser reference.

Raw connector table schema

The following schema includes the Box enterprise audit event fields.

Schema

Column	Data type
event_id	STRING
event_type	STRING
type	STRING
created_at	TIMESTAMP
recorded_at	TIMESTAMP
session_id	STRING
ip_address	STRING
created_by	VARIANT
action_by	VARIANT
source	VARIANT
additional_details	VARIANT

Column	Data type
event_id	STRING
event_type	STRING
type	STRING
created_at	TIMESTAMP
recorded_at	TIMESTAMP
session_id	STRING
ip_address	STRING
created_by	VARIANT
action_by	VARIANT
source	VARIANT
additional_details	VARIANT

Parser indicators

The box_event_logs parser writes nested objects as VARIANT and extracts the following fields into lw_observables.

Indicators

Field	Indicator
ip_address	ip
created_by.login	email
action_by.login	email
source.login	email
source.owned_by.login	email
created_by.id	actor_id
action_by.id	actor_id

Field	Indicator
ip_address	ip
created_by.login	email
action_by.login	email
source.login	email
source.owned_by.login	email
created_by.id	actor_id
action_by.id	actor_id