# Threat Detections

Streams runtime threat detections from Upwind, including network, process, and cloud-logs detections enriched with MITRE ATT&CK metadata.

**Sync Type: Incremental**

## Prerequisites

Before connecting Monad to Upwind, you need:

1. An active Upwind account with at least one organization.
2. An **API application** configured in the Upwind console with the client credentials grant enabled. This provides the OAuth2 Client ID and Client Secret used to authenticate API requests.
3. Your **Organization ID** — found in the Upwind console under Organization Settings. It follows the format `org_<alphanumeric>`.
4. Knowledge of your **deployment region** (United States, Europe, or Middle East) so Monad can target the correct API endpoint.

## Authentication

Upwind uses the **OAuth2 client credentials** grant. Monad exchanges the Client ID and Client Secret for a short-lived access token at `https://auth.upwind.io/oauth/token` before each request. Token refresh is handled automatically.

### Generating API Credentials

1. Log in to the [Upwind console](https://console.upwind.io).
2. Navigate to **Settings** > **Credentials**.
3. Click **Generate Credentials**.
4. Select **API** as the credential type.
5. Define the **Scope**: choose **Global Scope** for full read access, or **Custom** and grant read access to threat detections.
6. Provide a descriptive name (e.g., `monad-threat-detections`).
7. Click **Generate New Credentials**.
8. Copy the **Client ID** and **Client Secret** — the secret is shown only once, so store it securely.

### Finding your Organization ID

1. In the Upwind console, open **Organization Settings**.
2. Copy the **Organization ID** value. It begins with `org_` followed by alphanumeric characters.

## Configuration

### Settings

| Setting | Type | Required | Description |
| ------- | ---- | -------- | ----------- |
| Region | string | Yes | Your Upwind deployment region. Determines which API and authentication endpoints are used. Options: **United States**, **Europe**, **Middle East**. Defaults to United States. |
| Organization ID | string | Yes | Your Upwind organization identifier. Format: `org_<alphanumeric>`. Found in Organization Settings in the Upwind console. |
| Severity Filter | array of strings | No | Restrict returned detections to the specified severity levels. Leave empty to receive all severities. Options: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. |
| Backfill Start Time | string | No | The date (RFC3339) to start fetching threat detections from. If not specified, no historical records will be fetched — only new detections from the time the connector first runs. |

### Secrets

| Secret | Type | Required | Description |
| ------ | ---- | -------- | ----------- |
| Client ID | string | Yes | OAuth2 Client ID from your Upwind API application. Used to obtain access tokens via the client credentials grant. |
| Client Secret | string | Yes | OAuth2 Client Secret from your Upwind API application. Used alongside the Client ID to obtain access tokens. |

## Setup Walk-through

1. **Create an API application** — follow the Authentication section above to create a client-credentials application in the Upwind console and note the Client ID and Client Secret.

2. **Find your Organization ID** — in the Upwind console navigate to **Organization Settings** and copy the ID (format: `org_xxxxxxxx`).

3. **Create the input in Monad**:
   - Open your Monad workspace and navigate to **Inputs**.
   - Click **Add Input** and select **Upwind — Threat Detections**.

4. **Fill in the configuration**:
   - Select your **Region** (United States, Europe, or Middle East).
   - Paste your **Organization ID** into the *Organization ID* field.
   - Optionally select one or more values in **Severity Filter** to limit detections to specific severity levels.
   - Optionally set a **Backfill Start Time** (RFC3339, e.g. `2025-01-01T00:00:00Z`) to load historical detections from that date onward.
   - Enter the **Client ID** and **Client Secret** from your Upwind API application.

5. **Save and test** — click **Test Connection**. Monad will authenticate against the Upwind token endpoint and query the threat detections API to confirm the credentials are valid.

6. **Activate** — once the connection test passes, enable the input. Monad will incrementally sync threat detections, advancing its cursor after each run so only new detections are fetched on subsequent runs.

## Troubleshooting

### Common Issues

1. **Authentication Errors (401 / 403)**
   - Confirm the Client ID and Client Secret are correct and belong to the same API application.
   - Verify the application has the client credentials grant type enabled in Upwind.
   - Regenerate the Client Secret if you suspect it may have been compromised.

2. **Organization Not Found / 404 on Detections Endpoint**
   - Check that the Organization ID begins with `org_` and contains no extra whitespace or characters.
   - Confirm the API application has access to the target organization in your Upwind account.

3. **Wrong Region**
   - If authentication succeeds but no detections are returned, verify the selected region matches the region where your Upwind organization is deployed.
   - The three regional API base URLs are `https://api.upwind.io` (US), `https://api.eu.upwind.io` (EU), and `https://api.me.upwind.io` (ME).

4. **No Results Returned**
   - If **Severity Filter** is set, relax or clear the filter to ensure detections at other severity levels are not excluded.
   - If **Backfill Start Time** is set far in the future, no historical detections will fall within the window.
   - Confirm your Upwind organization has active threat detections by checking the Upwind console directly.

5. **Empty Incremental Syncs**
   - The connector uses `last_seen_time` as its incremental cursor. If no new detections have been seen since the last run, no records will be emitted — this is expected behavior.

## Related Articles

- [Upwind Documentation](https://docs.upwind.io)
- [Upwind API Reference](https://docs.upwind.io/restapi/v1/introduction)