Skip to content

[beyondtrust_pra] Initial release of the BeyondTrust PRA #13403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 15, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@
/packages/beaconing @elastic/ml-ui @elastic/sec-applied-ml
/packages/beat @elastic/stack-monitoring
/packages/beyondinsight_password_safe @elastic/security-service-integrations
/packages/beyondtrust_pra @elastic/security-service-integrations
/packages/bitdefender @elastic/security-service-integrations
/packages/bitwarden @elastic/security-service-integrations
/packages/blacklens @elastic/security-service-integrations
Expand Down
4 changes: 4 additions & 0 deletions packages/beyondtrust_pra/_dev/build/build.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
dependencies:
ecs:
reference: "[email protected]"
import_mappings: true
79 changes: 79 additions & 0 deletions packages/beyondtrust_pra/_dev/build/docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# BeyondTrust PRA

[BeyondTrust Privileged Remote Access (PRA)](https://www.beyondtrust.com/products/privileged-remote-access) is a solution designed to securely manage and control remote access to critical systems for privileged users, such as administrators, IT personnel, and third-party vendors. PRA is part of our broader suite of Privileged Access Management (PAM) solutions. It provides real-time session monitoring, auditing, and recording, which helps you maintain compliance and detect any unauthorized or risky activities. By enforcing least-privilege access and supporting third-party vendor management, it reduces the attack surface and enhances overall security for remote operations.

## Compatibility

This integration is compatible with **BeyondTrust PRA 24.1.x** and has been tested against the **API Version 1.24.1** for REST API support.

## Data streams

This integration collects the following logs:

- **[Access Session](https://docs.beyondtrust.com/pra/docs/reporting#accesssession)** - Enables users to collect event logs occurred during each AccessSession using the REST API.

## Requirements

### Agentless Enabled Integration
Agentless integrations allow you to collect data without having to manage Elastic Agent in your cloud. They make manual agent deployment unnecessary, so you can focus on your data instead of the agent that collects it. For more information, refer to [Agentless integrations](https://www.elastic.co/guide/en/serverless/current/security-agentless-integrations.html) and the [Agentless integrations FAQ](https://www.elastic.co/guide/en/serverless/current/agentless-integration-troubleshooting.html).

Agentless deployments are only supported in Elastic Serverless and Elastic Cloud environments. This functionality is in beta and is subject to change. Beta features are not subject to the support SLA of official GA features.

### Agent Based Installation
- Elastic Agent must be installed
- You can install only one Elastic Agent per host.
- Elastic Agent is required to stream data from the GCP Pub/Sub or REST API and ship the data to Elastic, where the events will then be processed via the integration's ingest pipelines.

#### Installing and managing an Elastic Agent:

You have a few options for installing and managing an Elastic Agent:

#### Install a Fleet-managed Elastic Agent (recommended):

With this approach, you install Elastic Agent and use Fleet in Kibana to define, configure, and manage your agents in a central location. We recommend using Fleet management because it makes the management and upgrade of your agents considerably easier.

#### Install Elastic Agent in standalone mode (advanced users):

With this approach, you install Elastic Agent and manually configure the agent locally on the system where it is installed. You are responsible for managing and upgrading the agents. This approach is reserved for advanced users only.

#### Install Elastic Agent in a containerized environment:

You can run Elastic Agent inside a container, either with Fleet Server or standalone. Docker images for all versions of Elastic Agent are available from the Elastic Docker registry and we provide deployment manifests for running on Kubernetes.

There are some minimum requirements for running Elastic Agent and for more information, refer to the link [here](https://www.elastic.co/guide/en/fleet/current/elastic-agent-installation.html).

## Setup

### To collect data from the BeyondTrust PRA API:
- If the integration client is not installed follow this [doc](https://docs.beyondtrust.com/pra/docs/integration-client) to setup integration client and add database as guided.
- After having installed integration client & created the settings database, you are prompted to enter information for one or more BeyondTrust PRA sites from which the integration client extracts session data. Click **OK** to continue.
- If you wish to update or add a site, select **Site Configuration** from the integration client Setup dropdown.
- When the **Site Configuration** dialog appears, click the **New button** to input your BeyondTrust PRA site information.
- Enter a name for this site configuration and the URL of the site (note that **https://** should NOT be included)
- For **BeyondTrust PRA** sites on version 16.1 and above, you must provide the **Client ID** and **Client Secret** for an API account with permission to view reports and recordings. If you plan to pull site backups, backup API permissions must also be enabled for the API account. Click Edit on the API user account to identify the OAuth Client ID, and click Generate New Client Secret and record the secret.
- Optionally, you may apply a password to any backups created. If you do choose to set a password, you must provide this password to revert to the backup.
- Test the supplied credentials and then click **Save**.
- When you have finished entering your BeyondTrust site information, click **Next**.
- **Note**: For BeyondTrust PRA sites running version 16.1 and above, if the account's password is reset, the integration client stops pulling data until the site configuration is updated. To prevent this break, it is recommended that you create a special account for the integration client with only permissions needed to retrieve the desired data and with a password set to never expire.
- Integration client supports more than one site. If session data from additional sites needs to be extracted, click the **New** button again and repeat the configuration process. The **host_name** in the session table distinguishes the data.

### Enabling the integration in Elastic:

1. In Kibana navigate to Management > Integrations.
2. In "Search for integrations" top bar, search for `BeyondTrust PRA`.
3. Select the "BeyondTrust PRA" integration from the search results.
4. Select "Add BeyondTrust PRA" to add the integration.
5. Add all the required integration configuration parameters, including the URL, Client ID, Client Secret, Session Timeout, Interval, and Initial Interval, to enable data collection.
6. Select "Save and continue" to save the integration.

## Logs

### Access Session

This is the `Access Session` dataset.

#### Example

{{fields "access_session"}}

{{event "access_session"}}
15 changes: 15 additions & 0 deletions packages/beyondtrust_pra/_dev/deploy/docker/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
version: '2.3'
services:
beyondtrust_pra-access_session:
image: docker.elastic.co/observability/stream:v0.15.0
hostname: beyondtrust_pra-access_session
ports:
- 8090
volumes:
- ./files:/files:ro
environment:
PORT: '8090'
command:
- http-server
- --addr=:8090
- --config=/files/config-access_session.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
rules:
- path: /oauth2/token
methods: ['POST']
responses:
- status_code: 200
headers:
Content-Type:
- 'application/json'
body: |
{"access_token":"xxxx","expires_in":1799,"token_type":"bearer"}
- path: /api/reporting
methods: ['GET']
query_params:
generate_report: "AccessSession"
start_time: "{start_time:.*}"
duration: "0"
responses:
- status_code: 200
body: |-
<?xml version="1.0" encoding="UTF-8"?>
<session_list>
<session>
<session_type>support2</session_type>
<lseq>12345</lseq>
<start_time timestamp="1712235600">2024-04-04T13:00:00Z</start_time>
<end_time timestamp="1712239200">2024-04-04T14:00:00Z</end_time>
<duration>01:00:00</duration>
<jump_group type="shared" id="56789">Support Team</jump_group>
<jumpoint id="98765">Main Jumpoint</jumpoint>
<custom_attributes>
<custom_attribute display_name="priority" code_name="priority">High</custom_attribute>
<custom_attribute display_name="priority" code_name="priority">High</custom_attribute>
</custom_attributes>
<session_chat_view_url>https://example.com/chat_view/12345</session_chat_view_url>
<session_chat_download_url>https://example.com/chat_download/12345</session_chat_download_url>
<session_recording_view_url>https://example.com/recording_view/12345</session_recording_view_url>
<session_recording_download_url>https://example.com/recording_download/12345</session_recording_download_url>
<command_shell_recordings>
<command_shell_recording instance="0">
<download_url>https://example.com/shell_download/12345</download_url>
<view_url>https://example.com/shell_view/12345</view_url>
</command_shell_recording>
</command_shell_recordings>
<file_transfer_count>3</file_transfer_count>
<file_move_count>1</file_move_count>
<file_delete_count>0</file_delete_count>
<primary_customer gsnumber="C12345">Remote PC</primary_customer>
<primary_rep gsnumber="R56789" id="112233">John Doe</primary_rep>
<customer_list>
<customer gsnumber="C12345">
<username>remote_user</username>
<public_ip>81.2.69.192</public_ip>
<private_ip>1.128.0.1</private_ip>
<hostname>remote-host</hostname>
<os>Windows 10</os>
</customer>
</customer_list>
<rep_list>
<representative gsnumber="R56789" id="112233">
<username>admin_user</username>
<display_name>Admin</display_name>
<public_ip>175.16.199.0</public_ip>
<private_ip>1.128.0.2</private_ip>
<hostname>admin-host</hostname>
<os>Windows 11</os>
<session_owner>1</session_owner>
<seconds_involved>3600</seconds_involved>
<invited>1</invited>
</representative>
</rep_list>
<session_details>
<event timestamp="2024-04-04T13:30:00Z" event_type="Session Start">
<performed_by gsnumber="R56789" type="representative" />
<destination gsnumber="C12345" type="customer" />
<body>Session started by Admin</body>
<encoded_body>U2Vzc2lvbiBzdGFydGVkIGJ5IEFkbWlu</encoded_body>
<filename>logfile.txt</filename>
<filesize>1024</filesize>
<files>
<file>
<filename>logfile.txt</filename>
<filesize>1024</filesize>
</file>
</files>
<system_information>
<category name="OS Information">
<description>
<field name="hostname">Hostname</field>
<field name="hostid">Hostid</field>
</description>
<data>
<row>
<field name="hostname">remote-host1</field>
<field name="hostname">h1234</field>
</row>
<row>
<field name="hostname">remote-host2</field>
<field name="hostname">h5647</field>
</row>
</data>
</category>
</system_information>
</event>
</session_details>
</session>
</session_list>
6 changes: 6 additions & 0 deletions packages/beyondtrust_pra/changelog.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# newer versions go on top
- version: "0.1.0"
changes:
- description: Initial release.
type: enhancement
link: https://github.com/elastic/integrations/pull/13403
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
fields:
tags:
- preserve_duplicate_custom_fields
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"body":"Session started by Admin","data":{"value":[{"name":"username","value":"JohnDoe"},{"name":"private_ip","value":"128.0.0.1"}]},"destination":{"display_name":"Admin","gsnumber":"R56789","hostname":"admin-host","id":"112233","invited":1,"os":"Windows 11","private_ip":"1.128.0.0","public_ip":"81.2.69.142","seconds_involved":3600,"session_owner":1,"type":"representative","username":"admin_user"},"encoded_body":"U2Vzc2lvbiBzdGFydGVkIGJ5IEFkbWlu","event_type":"Session Start","filename":"logfile.txt","filesize":1024,"files":{"file":[{"filename":"logfile.txt","filesize":1024},{"filename":"logfile.txt","filesize":1024}]},"performed_by":{"display_name":"Admin","gsnumber":"R56789","hostname":"admin-host","id":"112233","invited":1,"os":"Windows 11","private_ip":"1.128.0.1","public_ip":"216.160.83.56","seconds_involved":3600,"session_owner":1,"type":"representative","username":"admin_user"},"system_information":{"category":[{"data":{"row":[{"field":[{"name":"os","#text":"Windows 10"},{"name":"hostname","#text":"remote-host"}]}]},"description":{"field":[{"name":"os","#text":"Operating System"},{"name":"hostname","#text":"Hostname"}]}}]},"timestamp":"2024-01-01T12:30:00Z","session":{"lsid":"12345","jump_group":{"#text":"Support Team","id":"56789","type":"shared"},"jumpoint":{"id":"98765","#text":"Main Jumpoint"},"command_shell_recordings":{"command_shell_recording":[{"download_url":"https://example.com/shell_download/12345","view_url":"https://example.com/shell_view/12345","instance":"0"},{"view_url":"https://example.com/shell_view/12345","instance":"0","download_url":"https://example.com/shell_download/12345"}]},"duration":"01:00:00","lseq":"12345","session_chat_view_url":"https://example.com/chat_view/12345","session_recording_view_url":"https://example.com/recording_view/12345","end_time":{"#text":"2024-01-01T13:00:00Z","timestamp":"1704114000"},"file_transfer_count":3,"start_time":{"timestamp":"1704110400","#text":"2024-01-01T12:00:00Z"},"file_move_count":1,"session_recording_download_url":"https://example.com/recording_download/12345","primary_customer":{"#text":"Remote PC","gsnumber":"C12345"},"custom_attributes":{"custom_attribute":[{"code_name":"priority","#text":"High","display_name":"priority"},{"code_name":"priority","#text":"High","display_name":"priority"}]},"primary_rep":{"gsnumber":"R56789","id":"112233","#text":"John Doe"},"session_chat_download_url":"https://example.com/chat_download/12345","session_type":"support"}}
Loading