Skip to content

Commit 3f34724

Browse files
manan-crestavaid-crest
manan-crest
and
avaid-crest
authored
[SAASINT-4327] [AI-5677] [INTS-417] DDS: BeyondTrust Password Safe (Crawler + Agent) Integration v1.0.0 (DataDog#20630)
* beyondtrust-password-safe integration without assets * Adding indentation changes * Add: BeyondTrust Password Safe Events * Update: readme, pipeline and dashboards * Update: add images and minor update in readme * Update: pipeline results * Update: rename changelog.d file * Update: changelog.md file * Update: readme as suggestions and minor dashboard updates * Update: add logo * Update: minor reformating in dashboard panels * Added changes as per review comments * Adding changelog changes * Minor change in readme due crawler code updation * Update: regex to notspace parser for function_domain and port attributes in rule * Add: Note for data collection method in dashboards --------- Co-authored-by: Akshit Vaid <akshit.vaid@crestdata.ai>
1 parent 62adfc8 commit 3f34724

21 files changed

+8488
-24
lines changed

‎beyondtrust_password_safe/CHANGELOG.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
11
# CHANGELOG - BeyondTrust Password Safe
22

3-
## 1.0.0 / 2025-06-25
4-
5-
***Added***:
6-
7-
* Initial Release
3+
<!-- towncrier release notes start -->

‎beyondtrust_password_safe/README.md‎

Lines changed: 194 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,219 @@
1-
# Agent Check: BeyondTrust Password Safe
1+
# BeyondTrust Password Safe
22

33
## Overview
44

5-
This check monitors [BeyondTrust Password Safe][1].
5+
[BeyondTrust Password Safe][1] is a privileged access management solution designed to securely store, manage, and rotate privileged credentials (like administrative or root passwords) used to access critical systems. It automates password rotation and provides comprehensive session monitoring and recording to help organizations maintain strict control over privileged credentials.
6+
7+
This integration parses and ingest the following types of logs:
8+
- **Password and Session Activities**: Captures events related to password retrievals, password rotations, session requests, approvals, and denials.
9+
- **Managed Systems and Managed Accounts**: Logs information about the addition, modification, or removal of managed systems and accounts.
10+
- **Secret Safe Activities**: Tracks the creation, retrieval, and deletion of secrets stored in the secret safe.
11+
- **Audit Logs**: Tracks activities performed by platform users.
12+
13+
Visualize detailed insights into these logs through out-of-the-box dashboards. Cloud SIEM also provides detection rules to help you monitor and respond to potential security threats effectively.
614

715
## Setup
816

9-
### Installation
17+
### Log Collection Overview
18+
19+
**Note**: To collect all the log types, configure both log collection methods.
20+
21+
The following table shows the log collection methods, the logs collected, and the dashboards populated for each methods.
22+
| Log Collection Method | Logs Collected | Dashboards Populated |
23+
|-----------------------------------------|---------------------------------------------------------------------------|------------------------------|
24+
| [Agent and Event Forwarder Configuration](#agent-and-event-forwarder-configuration) | <li> Password and Session Activities<br><li> Managed Systems and Managed Accounts<br><li> Secret Safe Activities | <li>BeyondTrust Password Safe - Overview<br><li>BeyondTrust Password Safe - Password and Session Insights<br><li>BeyondTrust Password Safe - Management and Secret Safe Insights |
25+
| [Audit API Configuration](#audit-api-configuration) | <li>Audit Logs | <li>BeyondTrust Password Safe - Audit Insights |
26+
27+
### Agent and Event Forwarder Configuration
28+
29+
#### Installation
30+
31+
To install the BeyondTrust Password Safe integration, run the following Agent installation command in your terminal, then complete the configuration steps. For more information, see the [Integration Management][4] documentation.
32+
33+
**Note**: This step is not necessary for Agent version >= 7.69.0.
34+
35+
```shell
36+
sudo -u dd-agent -- datadog-agent integration install datadog-beyondtrust_password_safe==1.0.0
37+
```
38+
39+
40+
#### Log collection
41+
42+
1. Collecting logs is disabled by default in the Datadog Agent. Enable it in `datadog.yaml`:
43+
44+
```yaml
45+
logs_enabled: true
46+
```
47+
48+
2. Add this configuration block to your `beyondtrust_password_safe.d/conf.yaml` file to start collecting your logs.
49+
50+
See the sample [beyondtrust_password_safe.d/conf.yaml][8] for available configuration options.
51+
52+
```yaml
53+
logs:
54+
- type: tcp
55+
port: <PORT>
56+
source: beyondtrust-password-safe
57+
service: password-safe
58+
```
59+
60+
**Note**:
61+
62+
- `PORT`: Port should be similar to the port provided in **Configure log forwarding from BeyondTrust Password Safe via Universal Event Forwarder** section.
63+
- It is recommended not to change the service and source values, as these parameters are integral to the pipeline's operation.
64+
65+
3. [Restart the Agent][6].
66+
67+
#### Configure log forwarding from BeyondTrust Password Safe through the Universal Event Forwarder
68+
69+
1. Log in to BeyondTrust Password Safe with an Administrator account.
70+
2. In BeyondTrust Password Safe, go to **Configuration > General > Connectors**.
71+
3. From the Connectors panel, click **Create New Connector**.
72+
4. Enter a name for the connector.
73+
5. Select **Universal Event Forwarder** from the list.
74+
6. Click **Create Connector**.
75+
7. Leave Active (yes) enabled.
76+
8. Select **TCP** in the **Available Output Pipelines** dropdown.
77+
9. Enter the IP address where your Datadog Agent is running in the **Host Name** field.
78+
10. Enter the Port on which the Datadog Agent is listening.
79+
11. Select **JSON** in **Available Formatters** dropdown.
80+
12. Select Local0 in **Facility** dropdown.
81+
13. Expand Event Filters, and then enable **BeyondInsight Application Audit** and **Password Safe** options.
82+
14. Click **Create Connector**.
83+
84+
#### Validation
85+
86+
[Run the Agent's status subcommand][5] and look for `beyondtrust_password_safe` under the Checks section.
87+
88+
### Audit API Configuration
1089

11-
The BeyondTrust Password Safe check is included in the [Datadog Agent][2] package.
12-
No additional installation is needed on your server.
90+
#### Retrieve Datadog CIDR Range
1391

14-
### Configuration
92+
1. Use an API platform such as Postman, or curl to make a GET request to the [Datadog API endpoint][7].
93+
2. Once you receive the response, locate the **webhooks** section in the JSON. It will look something like this:
94+
```json
95+
"webhooks": {
96+
"prefixes_ipv4": [
97+
"0.0.0.0/32",
98+
...
99+
],
100+
"prefixes_ipv6": []
101+
}
102+
```
103+
3. From the **prefixes_ipv4** list under the Webhooks section, copy each CIDR entry.
15104

16-
!!! Add list of steps to set up this integration !!!
105+
#### Configure API Access Policy and retrieve API Base Endpoint
17106

18-
### Validation
107+
1. Log in to the BeyondTrust Password Safe using Administrator account.
108+
2. Go to **Configuration > General > API Registrations**.
109+
3. Click **Create API Registration**.
110+
4. Select **API Access Policy** from the dropdown list.
111+
5. Fill out the new API registration details, and set the **Access Token Duration** to 30 minutes.
112+
6. Click **Add Authentication Rule** for each of the CIDR entries retrieved in step "Retrieve Datadog CIDR Range".
113+
- For Type, select **CIDR** from the dropdown list.
114+
- Enter the **CIDR** entry in the CIDR field.
115+
7. Click **Create Rule** and then click **Create Registration**.
116+
8. Copy **API Base Endpoint**.
19117

20-
!!! Add steps to validate integration is functioning as expected !!!
118+
#### Generate Client ID and Client Secret
119+
120+
1. Log in to the BeyondTrust Password Safe with an Administrator account.
121+
2. Go to **Configuration > Role Based Access > User Management**.
122+
3. Click the **Users** tab to display the list of users in the grid.
123+
4. Click **Create New User**.
124+
5. Select **Add an Application User** from the dropdown list.
125+
6. Add a Username.
126+
7. Under API Access Policy, select the policy created. To create a policy, see [Configure API Access Policy and Retrieve API Base Endpoint](#configure-api-access-policy-and-retrieve-api-base-endpoint).
127+
8. Copy the information from the **Client ID** and **Client Secret** fields for later use.
128+
9. Click **Create User**.
129+
10. Assign the user to a group that has the **User Audits (Read-Only)** permission. To create a group, see the [BeyondTrust documentation][2].
130+
- Click the vertical ellipsis for the user, and then select **View User Details**.
131+
- From the User Details pane, click **Groups**.
132+
- Locate the group, select it, and click **Assign Group** above the grid.
133+
134+
#### Connect your BeyondTrust Password Safe Account to Datadog
135+
136+
1. Add the application user's BeyondTrust Password Safe Client ID, Client Secret, and API Base Endpoint.
137+
138+
| Parameters | Description |
139+
| --------------------------------- | ------------------------------------------------------------------------------------ |
140+
| API Base Endpoint | API Base Endpoint used to make requests to the Password Safe public API (Example: https://beyondtrustcloud.com/BeyondTrust/api/public/v3). |
141+
| Client ID | Client ID of the application user present in BeyondTrust Password Safe. |
142+
| Client Secret | Client Secret of the application user present in BeyondTrust Password Safe. |
143+
144+
2. Click **Save**.
21145

22146
## Data Collected
23147

24-
### Metrics
148+
### Logs
25149

26-
BeyondTrust Password Safe does not include any metrics.
150+
The BeyondTrust Password Safe integration collects and forwards Passwords, Sessions, Managed Systems, Managed Accounts, Secrets Safe activities, and audit logs to Datadog.
27151

28-
### Service Checks
152+
### Metrics
29153

30-
BeyondTrust Password Safe does not include any service checks.
154+
BeyondTrust Password Safe integration does not include any metrics.
31155

32156
### Events
33157

34-
BeyondTrust Password Safe does not include any events.
158+
BeyondTrust Password Safe integration does not include any events.
35159

36160
## Troubleshooting
37161

38-
Need help? Contact [Datadog support][3].
162+
### Permission denied while port binding
39163

40-
[1]: **LINK_TO_INTEGRATION_SITE**
41-
[2]: https://app.datadoghq.com/account/settings/agent/latest
42-
[3]: https://docs.datadoghq.com/help/
164+
If you see a **Permission denied** error while port binding in the Agent logs:
165+
166+
1. Binding to a port number under 1024 requires elevated permissions. Grant access to the port using the `setcap` command:
167+
168+
```shell
169+
sudo setcap CAP_NET_BIND_SERVICE=+ep /opt/datadog-agent/bin/agent/agent
170+
```
171+
172+
2. Verify the setup is correct by running the `getcap` command:
173+
174+
```shell
175+
sudo getcap /opt/datadog-agent/bin/agent/agent
176+
```
177+
178+
With the expected output:
179+
180+
```shell
181+
/opt/datadog-agent/bin/agent/agent = cap_net_bind_service+ep
182+
```
183+
184+
**Note**: Re-run this `setcap` command every time you upgrade the Agent.
185+
186+
3. [Restart the Agent][6].
43187

188+
### Data is not being collected
189+
190+
Ensure firewall settings allow traffic through the configured port.
191+
192+
### Port already in use
193+
194+
On systems running Syslog, the Agent may fail to bind to port 514 and display the following error:
195+
196+
Can't start UDP forwarder on port 514: listen udp :514: bind: address already in use
197+
198+
This error occurs because Syslog uses port 514 by default.
199+
200+
To resolve:
201+
- Disable Syslog, OR
202+
- Configure the Agent to listen on a different, available port.
203+
204+
### Error related to unidentified CIDR Range
205+
206+
If you encounter an error indicating that the request is originating from an unidentified CIDR range, it may be due to a change in Datadog's outbound IP ranges. To retrieve and update the allowed CIDR ranges, follow the steps in [Retrieve Datadog CIDR Range](#retrieve-datadog-cidr-range).
207+
208+
## Support
209+
210+
For further assistance, contact [Datadog support][3].
211+
212+
[1]: https://www.beyondtrust.com/sem/password-safe
213+
[2]: https://docs.beyondtrust.com/bips/docs/bi-cloud-configure-groups#create-a-group-and-assign-roles
214+
[3]: https://docs.datadoghq.com/help/
215+
[4]: https://docs.datadoghq.com/agent/guide/integration-management/?tab=linux#install
216+
[5]: https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information
217+
[6]: https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent
218+
[7]: https://docs.datadoghq.com/api/latest/ip-ranges/
219+
[8]: https://github.com/DataDog/integrations-core/blob/master/beyondtrust_password_safe/datadog_checks/beyondtrust_password_safe/data/conf.yaml.example

0 commit comments

Comments
 (0)