> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/destinations/rapid7-insightidr.md).

# Rapid7 InsightIDR

The InsightIDR destination forwards logs from Bindplane to [Rapid7 InsightIDR](https://docs.rapid7.com/insightidr/), Rapid7's cloud SIEM and XDR platform. Logs are delivered over syslog to an [InsightIDR Collector](https://docs.rapid7.com/insightidr/the-insight-collector/) that you run in your environment, which then forwards events to the InsightIDR platform.

### Supported Telemetry Types

| Platform | Metrics | Logs | Traces |
| -------- | ------- | ---- | ------ |
| Linux    |         | ✓    |        |
| Windows  |         | ✓    |        |
| macOS    |         | ✓    |        |

### Prerequisites

* A running [InsightIDR Collector](https://docs.rapid7.com/insightidr/the-insight-collector/) reachable from the Bindplane collector.
* A syslog event source configured on the InsightIDR Collector, with its listening host/port and transport protocol (TCP or UDP).
* If using TCP with TLS, the InsightIDR event source must be configured to accept TLS, and any required certificate files must be available on the Bindplane collector host.

### Configuration

<figure><img src="/files/7j5YSbAuJcNk3iAmyU6G" alt="Bindplane docs - Rapid7 InsightIDR - image 1"><figcaption></figcaption></figure>

#### Logs

| Parameter        | Type       | Default | Description                                                                                                                                               |
| ---------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Field to Send    | Enum       | `Body`  | Required. The log field to send. One of `Attributes` or `Body`.                                                                                           |
| Attributes Field | OTTL Field |         | The attributes field to send. Use bracket notation for nested fields. An empty value sends all attribute fields. Applies when `raw_base` is `Attributes`. |
| Body Field       | OTTL Field |         | The body field to send. Use bracket notation for nested fields. An empty value sends all body fields. Applies when `raw_base` is `Body`.                  |

#### insightIDR Configuration

| Parameter          | Type   | Default | Description                                                                    |
| ------------------ | ------ | ------- | ------------------------------------------------------------------------------ |
| Syslog Endpoint    | String |         | Required. The endpoint where the InsightIDR Collector is listening for syslog. |
| Transport Protocol | Enum   | `udp`   | The transport protocol to use. One of `tcp` or `udp`.                          |

#### Advanced

| Parameter     | Type    | Default | Description                                                                                      |
| ------------- | ------- | ------- | ------------------------------------------------------------------------------------------------ |
| Drop Raw Copy | Boolean | `true`  | When enabled, the raw copy of the log stored in `log.record.original` is dropped before sending. |

#### TLS

TLS applies only when `insight_transport` is `tcp`.

| Parameter                         | Type    | Default | Description                                                                              |
| --------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------- |
| Enable TLS                        | Boolean | `false` | Whether or not to use TLS. Applies when `insight_transport` is `tcp`.                    |
| Skip TLS Certificate Verification | Boolean | `false` | Skip TLS certificate verification. Applies when TLS is enabled.                          |
| TLS Certificate File              | String  |         | Path to the x509 PEM certificate (required for Mutual TLS). Applies when TLS is enabled. |
| TLS Private Key File              | String  |         | Path to the x509 PEM private key (required for Mutual TLS). Applies when TLS is enabled. |
| TLS Certificate Authority File    | String  |         | Path to the x509 PEM certificate authority file. Applies when TLS is enabled.            |

#### Retry on Failure

| Parameter               | Type    | Default | Description                                                                                                                              |
| ----------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Enable Retry on Failure | Boolean | `true`  | Attempt to resend logs that have failed to be transmitted to the destination.                                                            |
| Initial Interval        | Integer | `5`     | Time (in seconds) to wait after the first failure before retrying. Applies when retry is enabled.                                        |
| Max Interval            | Integer | `30`    | The upper bound (in seconds) on backoff. Applies when retry is enabled.                                                                  |
| Max Elapsed Time        | Integer | `300`   | The maximum amount of time (in seconds) spent trying to send a batch, to avoid a never-ending retry loop. Applies when retry is enabled. |

#### Sending Queue

| Parameter                 | Type      | Default                         | Description                                                                                                                                                      |
| ------------------------- | --------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable Sending Queue      | Boolean   | `true`                          | Buffer logs temporarily before sending to help ensure data is not lost during a temporary network outage.                                                        |
| Number of Consumers       | Integer   | `10`                            | Number of consumers that dequeue batches. Applies when the sending queue is enabled.                                                                             |
| Queue Size                | Integer   | `5000`                          | Maximum number of batches kept in memory before dropping. Applies when the sending queue is enabled.                                                             |
| Enable Persistent Queuing | Boolean   | `true`                          | Buffer telemetry to disk before sending to help ensure data is not lost during network outages or collector restarts. Applies when the sending queue is enabled. |
| Persistent Queue Storage  | Extension | `file_storage_persistent_queue` | Required. The storage to use for the persistent queue. Applies when the sending queue and persistent queuing are enabled.                                        |

### Example Configuration

#### Standalone Destination

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Destination
metadata:
  id: insightidr
  name: insightidr
spec:
  type: insightidr
  parameters:
    - name: raw_base
      value: 'Body'
    - name: insight_endpoint
      value: 'insight-collector.example.com:514'
    - name: insight_transport
      value: 'udp'
    - name: drop_raw_copy
      value: 'true'
```

A TCP example with TLS enabled:

```yaml
apiVersion: bindplane.observiq.com/v1
kind: Destination
metadata:
  id: insightidr
  name: insightidr
spec:
  type: insightidr
  parameters:
    - name: raw_base
      value: 'Body'
    - name: insight_endpoint
      value: 'insight-collector.example.com:6514'
    - name: insight_transport
      value: 'tcp'
    - name: enable_tls
      value: 'true'
    - name: ca_file
      value: '/opt/observiq-otel-collector/insightidr-ca.crt'
```

### Configuration Tips

#### Choosing the field to send

* `raw_base` controls which part of the log record is sent to InsightIDR. Set it to `Body` to forward the log body (the default) or `Attributes` to forward record attributes.
* When you only need a specific subfield, set `raw_body` (or `raw_attributes`) using bracket notation. Leave it empty to send the entire body or attribute map.

#### Transport and TLS

* `insight_transport` defaults to `udp`. Match it to the protocol configured on the InsightIDR Collector's syslog event source.
* TLS is available only with `tcp`. Configure the InsightIDR event source to accept TLS first, then set `enable_tls` and supply the certificate files. Use `insecure_skip_verify` only for testing against a non-trusted certificate.

#### Reducing payload size

* Leave `drop_raw_copy` enabled (the default) to drop the `log.record.original` field before sending. Disable it only if you need the original raw copy forwarded to InsightIDR.

### Troubleshooting

**Symptom:** No events arrive in InsightIDR. **Solution:** Confirm `insight_endpoint` points at the InsightIDR Collector's syslog listener (host and port) and that `insight_transport` matches the event source's protocol. Verify the Bindplane collector can reach that host and port over the network.

**Symptom:** TLS connection fails or certificates are rejected. **Solution:** TLS only applies to `tcp` transport. Confirm `enable_tls` is set, the InsightIDR event source accepts TLS, and the supplied `ca_file` (and `cert_file` / `key_file` for mutual TLS) are correct and readable on the collector host. For testing only, `insecure_skip_verify` bypasses verification.

**Symptom:** Events are larger than expected or contain a duplicated raw copy. **Solution:** Enable `drop_raw_copy` to remove the `log.record.original` field before the log is forwarded.

### Related Resources

* [Rapid7 InsightIDR documentation](https://docs.rapid7.com/insightidr/)
* [InsightIDR Collector](https://docs.rapid7.com/insightidr/the-insight-collector/)
* [Bindplane persistent queue configuration](https://docs.bindplane.com/configuration/bindplane-otel-collector/persistent-queue)

```
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bindplane.com/integrations/destinations/rapid7-insightidr.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.