Metadata-Version: 2.1
Name: datadog-iboss
Version: 1.1.0
Summary: The iboss check
Project-URL: Source, https://github.com/DataDog/integrations-core
Author-email: Datadog <packages@datadoghq.com>
Keywords: datadog,datadog agent,datadog check,iboss
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Private :: Do Not Upload
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Requires-Dist: datadog-checks-base>=37.21.0
Provides-Extra: deps
Description-Content-Type: text/markdown

# iboss

## Overview

[iboss][1] provides secure internet access and Zero Trust enforcement for users, wherever they are. It combines key security functions such as Secure Web Gateway (SWG), CASB, ZTNA, and DLP into a single, scalable solution. Traffic is routed through iboss's infrastructure to ensure consistent policy enforcement and threat protection.

This integration parses and ingests the following types of logs:

- **Web Logs**: Provides information about client requests to web resources, enabling monitoring of web traffic and policy enforcement.
- **DLP Logs**: Provides information related to data loss prevention, tracking policy enforcement, and potential sensitive data exposures.
- **Audit Logs**: Provides information about user and system activities to ensure traceability and support compliance monitoring.

You can visualize detailed insights into these logs through the out-of-the-box dashboards. Additionally, ready-to-use Cloud SIEM detection rules are available to help you monitor and respond to potential security threats effectively.

This integration collects the following metrics:

- **Gateway Performance**: Provides insights into request volumes, resource utilization, processing times, and error counts to monitor the health and efficiency of iboss gateways.
- **Bandwidth**: Provides information about data usage across domains, users, locations, and protocols, enabling monitoring of network traffic volume and flow patterns.
- **Digital Experience**: Provides insights into user experience by measuring connection times between clients, proxies, and servers across users, assets, and locations.
- **Web**: Provides visibility into user web activity, including site visits, blocks, malware detections, and search trends, to support usage analysis and policy effectiveness.
- **CASB**: Provides insights into cloud app usage, user behavior, and traffic patterns, enabling visibility, threat detection, and enforcement of cloud access policies.
- **Threat**: Provides visibility into detected and prevented threats across users, assets, IPs, and geolocations, enabling threat trend analysis and risk monitoring.
- **Zero Trust**: Provides visibility into users, devices, resources, and traffic, enabling continuous monitoring, trust evaluation, and policy enforcement within the Zero Trust framework.

**Note:** All metrics except for `Gateway Performance` are collected once per day, only after the complete daily iboss report is available.

Visualize detailed insights into these metrics through the out-of-the-box dashboards. Additionally, monitors are provided to alert you to any potential issues.

### Dashboards

#### Logs

Here is the list of dashboards populated using logs:

- iboss - Logs Overview
- iboss - Web & DLP Logs
- iboss - Audit Logs
- iboss - Real-Time Digital Experience Log Analytics
- iboss - Real-Time Web Log Analytics
- iboss - Real-Time Bandwidth Log Analytics
- iboss - Real-Time Zero Trust Log Analytics
- iboss - Real-Time Threat Log Analytics
- iboss - Real-Time CASB Log Analytics

#### Metrics

Here is the list of dashboards populated using metrics:

- iboss - Gateway Performance Metrics
- iboss - Digital Experience Metrics Report
- iboss - Web Analytics Metrics Report
- iboss - Bandwidth Metrics Report
- iboss - Zero Trust Metrics Report
- iboss - Threat Metrics Report
- iboss - CASB Metrics Report


### Monitors

#### Logs

Here is the list of monitors for logs:

- Excessive bandwidth usage detected
- High average application peer time detected
- High rate of unprevented threats detected

#### Metrics

Here is the list of monitors for metrics:

- Anomalous increase in gateway requests per second detected
- High gateway load detected
- High proxy error rate detected
- High proxy response time detected

**Minimum Agent version:** 7.69.0

## Setup

**Note**: The following steps are required only for collecting metrics. For log collection, see the `Log collection` section below.

### Generate API credentials in iboss

To collect metrics, you can either use an existing user with **Full Administrator** access to the **Reporting & Analytics** module, or create a custom user with a custom RBAC group by following the steps to set up reporting-only permissions and assign the user to that RBAC group.

#### Create New RBAC

1. Log into iboss portal as a System Administrator.
2. Go to **Home** > **System Administrators**.
3. Switch to the **Role-Based Access Control** tab.
4. Click **Add Custom RBAC Group**.
5. Enter a **Display Name** for the RBAC.
6. In the **General Info & Permissions** tab, enable only the **Reporting & Analytics** option to limit permissions to reporting only. Next, go to the **Reporting & Analytics Permissions** tab and choose **Full Administrator** from the **Permission Type** dropdown to allow complete access within the reporting module.
7. Click on **Add RBAC Group**.


#### Create New User

1. Log into iboss portal as System Administrator.
2. Go to **Home** > **System Administrators**.
3. Click **Add New System Administrator**.
4. Add details for **System Administrator Email Address**, **First Name**, and **Last Name**.
5. For **Use RBAC Groups**, select the RBAC group with minimal permissions.
6. Click **Add New System Administrator**.

**Note**: Make sure that MFA is disabled for the user account used by this integration.

### Connect your iboss Account to Datadog

1. Add your iboss email address and password.

   | Parameters                        | Description                                                                          |
   | --------------------------------- | ------------------------------------------------------------------------------------ |
   | Email Address                     | The email address of your iboss account.                                             |
   | Password                          | The password of your iboss account.                                                  |
   | Collect gateway performance metrics   | Enable to collect gateway performance metrics from iboss. The default value is `true`. |
   | Collect bandwidth metrics             | Enable to collect bandwidth metrics from iboss. The default value is `true`.           |
   | Collect Digital Experience metrics    | Enable to collect digital experience metrics from iboss. The default value is `true`.  |
   | Collect web metrics                   | Enable to collect web metrics from iboss. The default value is `true`.                 |
   | Collect CASB metrics                  | Enable to collect CASB metrics from iboss. The default value is `true`.                |
   | Collect threat metrics                | Enable to collect threat metrics from iboss. The default value is `true`.              |
   | Collect Zero Trust metrics            | Enable to collect zero trust metrics from iboss. The default value is `true`.          |

2. Click **Save**.

### Installation

**Note**: These steps are only required for collecting logs.

To install the iboss integration, run the following Agent installation command in your terminal, then complete the configuration steps below. For more information, see the [Integration Management][4] documentation.

**Note**: This step is not necessary for Agent version >= 7.69.0 .

```shell
sudo -u dd-agent -- datadog-agent integration install datadog-iboss==1.0.0
```

### Configuration

#### Log collection

1. Collecting logs is disabled by default in the Datadog Agent. Enable it in `datadog.yaml`:

   ```yaml
   logs_enabled: true
   ```

2. Open your `iboss.d/conf.yaml` file, and add the following block to enable log collection.

   See the sample configuration file ([iboss.d/conf.yaml][5]) for available options.

   ```yaml
   logs:
     - type: tcp # or 'udp'
       port: <PORT>
       source: iboss
       service: iboss
   ```

   **Note**:

   - `PORT`: Port should be similar to the port provided in **Configure syslog message forwarding from iboss** section.
   - Datadog recommends that you do not change the service and source values, as these parameters are integral to the pipeline's operation.

3. [Restart the Agent][2].

#### Configure syslog message forwarding from iboss

1. Log into the iboss portal.
2. Navigate to **Integration Marketplace**, then select **Log Forwarding** from the left-hand menu and click the **Configure** button associated with the **Syslog Log Forwarding** widget.
3. Click the **Add Integration** button to add the Syslog integration.
4. Configure the settings as follows:
   - **Forward From**: Select **Reporter** from the dropdown.
   - **Select Reporting Database**: Select the Reporting Database.
   - **Service Name**: Choose a descriptive name for the integration.
   - **Enable Service**: Set this to Enabled.
   - **Log Type**: Select **URL** from the dropdown.
   - **Protocol Type**: Select **UDP** or **TCP** from the dropdown.
   - **Syslog Facility Level**: Select **Facility Syslog** from the dropdown.
   - **Reporting Group**: Select **All** from dropdown.
   - **Host Name**: Enter the fully qualified domain name or IP address of the syslog server.
   - **Port**: Enter the port.
   - **Log Format**: Select **JSON** from the dropdown.
   - **Transfer Interval**: Select **Continuous** from the dropdown.
   - **Field Delimiter**: Select **SPACE** from the dropdown.
   - **Send DLP/Web/DNS/Malware/Audit/ConnectionError Logs**: Set to Enable based on your preference for sending logs.
   - **Fields to Forward**: Add all fields except **DLP Base64 Encoded Meta Data**, **Base64 Encoded Meta Data**, and **Chat GPT Message**.
     <br>After entering the required details, click **Add Service**.

**Note:** 
- If you have multiple reporter nodes, make sure to repeat steps 3 and 4 for each reporter node.
- The `Send Connection Error Logs` toggle in iboss should only be visible if `Send Web Logs` toggle is disabled.

### Validation

[Run the Agent's status subcommand][6] and look for `iboss` under the Logs Agent section.

## Data Collected

### Logs

| Format                    | Event Types                                      |
| ------------------------- | ------------------------------------------------ |
| JSON                      | Web Logs, DLP Logs, Audit Logs                   |

### Metrics

The iboss integration collects and forwards Gateway Performance, Bandwidth, Digital Experience, Web, CASB, Threat, and Zero Trust metrics to Datadog.

{{< get-metrics-from-git "iboss" >}}

### Events

The iboss integration does not include any events.

## Troubleshooting

### Permission denied while port binding

If you see a **Permission denied** error while port binding in the Agent logs:

1. Binding to a port number under 1024 requires elevated permissions. Grant the necessary permissions using the `setcap` command:

   ```shell
   sudo setcap CAP_NET_BIND_SERVICE=+ep /opt/datadog-agent/bin/agent/agent
   ```

2. Verify the setup is correct by running the `getcap` command:

   ```shell
   sudo getcap /opt/datadog-agent/bin/agent/agent
   ```

   You should see output similar to:

   ```shell
   /opt/datadog-agent/bin/agent/agent = cap_net_bind_service+ep
   ```

   **Note**: Re-run this `setcap` command every time you upgrade the Agent.

3. [Restart the Agent][2].

### Data is not being collected

Ensure firewall settings allow traffic through the configured port.

### Port already in use

On systems running Syslog, the Agent may fail to bind to port 514 and display the following error: 
   
    Can't start UDP forwarder on port 514: listen udp :514: bind: address already in use

This error occurs because Syslog uses port 514 by default. 

To resolve:
  - Disable Syslog, OR
  - Configure the Agent to listen on a different, available port.

For further assistance, contact [Datadog support][3].

[1]: https://www.iboss.com/
[2]: https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent
[3]: https://docs.datadoghq.com/help/
[4]: https://docs.datadoghq.com/agent/guide/integration-management/?tab=linux#install
[5]: https://github.com/DataDog/integrations-core/blob/master/iboss/datadog_checks/iboss/data/conf.yaml.example
[6]: https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information
