> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gravwell

> The Gravwell integration enables AirMDR to connect to a Gravwell instance, authenticate using an API token, and retrieve searchable security/log telemetry for investigation and automation workflows.

## Purpose

This guide explains how to generate the required Gravwell credentials for configuring the integration in AirMDR:

| Required Field | Description                                           |
| :------------- | :---------------------------------------------------- |
| `Instance_url` | Base URL of the Gravwell web instance.                |
| `Token`        | Gravwell API token used to authenticate API requests. |

<Note>
  Gravwell API tokens allow external tools to access selected Gravwell APIs without requiring a full login flow. Tokens can be restricted by permission and expiration.
</Note>

## Supported Versions

| Component             | Supported/Recommended                                   |
| :-------------------- | :------------------------------------------------------ |
| Gravwell              | Gravwell versions that support API Tokens and REST APIs |
| Authentication Method | Gravwell API Token                                      |
| Protocol              | HTTPS recommended                                       |
| Integration Type      | SIEM / Data Lake / Log Search integration               |

<Note>
  Gravwell’s Direct Query API is designed for REST-based access to Gravwell search and requires a valid Gravwell account or token with search access.
</Note>

## Authentication

Gravwell uses API tokens for external integrations.

### Authentication Fields

| Field          | Description                       |
| :------------- | :-------------------------------- |
| `Instance_url` | Reachable Gravwell base URL or IP |
| `Token`        | Gravwell API Token                |

**Example:** `https://gravwell.company.com `**or** `http://199.244.253.132`

<Note>
  Users only need to provide the `Instance_url` and `Token` in the AirMDR integration UI.
</Note>

<Tip>
  The `Gravwell-Token` HTTP header is automatically handled internally by the AirMDR integration. Users do NOT need to manually configure headers.
</Tip>

### Role-Based Access Recommendations

| Permission        | Purpose                            |
| :---------------- | :--------------------------------- |
| Search Access     | Required for executing queries     |
| Tag Access        | Required for reading Gravwell tags |
| Alert Read Access | Required if alerts are queried     |
| Admin Access      | Not recommended                    |

> **Best Practice:** Create a dedicated low-privilege token specifically for AirMDR integration usage.

### Pre-requisites

> <Check>
>   Users must have Administrator access to the **Gravwell**  UI with sufficient privileges to create or manage users and verify firewall settings.
> </Check>
>
> <Check>
>   Permission to create API tokens in Gravwell.
> </Check>

<Note>
  Gravwell admins can restrict token creation for non-admin users using CBAC controls.
</Note>

### Setup Steps

<Steps>
  <Step title="Generate the Instance URL">
    1. Log in to the Gravwell web UI.
    2. Identify the Gravwell server IP address or hostname that is reachable from the AirMDR platform or configured remote agent.
    3. Use the Gravwell base URL in one of the following formats: Using IP Address: `http://199.244.253.132`\
       or, if SSL/TLS is enabled: `https://199.244.253.132`\
       Using Hostname: `https://gravwell.company.com`
    4. Remove any additional paths after the hostname or IP address.\
       Use this: `http://199.244.253.132 `or `https://gravwell.company.com`\
       Avoid this:\
       `http://199.244.253.132/api/search/direct`\
       `https://gravwell.company.com/search/history`
    5. Save this value as `Instance_url`.
           <Note>
             The `Instance_url` must contain only the Gravwell base URL or reachable IP address. API paths such as `/api/parse` and `/api/search/direct` are automatically appended by the integration during API requests.
           </Note>
           <Check>
             Ensure the Gravwell IP address or hostname is reachable from the AirMDR platform or the configured remote agent.
           </Check>
  </Step>

  <Step title="Generate the API Token in Gravwell UI">
    1. Log in to the Gravwell web UI.
    2. From the left navigation menu, go to: **Tools & Resources → API Tokens**.
           <Info>
             The Gravwell API Token interface is located under **Tools & Resources**.
           </Info>
           <Frame>
             <img src="https://mintcdn.com/airmdr/RXlunQlSCsOi3j7m/images/Gravwell1.png?fit=max&auto=format&n=RXlunQlSCsOi3j7m&q=85&s=796842e3d31e63054a4f519ef478a628" alt="Gravwell1" width="582" height="586" data-path="images/Gravwell1.png" />
           </Frame>
    3. Click **Create Token** or **New Token**.
    4. Enter a clear token name. Example: `AirMDR Integration Token`
    5. Add a description.\
       Example: `Token used by AirMDR to query Gravwell alerts and telemetry.`
    6. Select the required permissions. Recommended minimum permissions:
       | Permission Area | Purpose                                                   |
       | :-------------- | :-------------------------------------------------------- |
       | Search          | Allows AirMDR to run Gravwell searches.                   |
       | Search and Data | Allows access to search-related APIs.                     |
       | Alert Read      | Allows AirMDR to retrieve alert information, if required. |
       | Tag Access      | Allows access to required Gravwell tags.                  |
           <Info>
             Gravwell supports selecting permissions as grouped permissions or fine-grained controls.
           </Info>
    7. Set an expiration date, if required.
           <Frame>
             <img src="https://mintcdn.com/airmdr/RXlunQlSCsOi3j7m/images/Gravwell2.png?fit=max&auto=format&n=RXlunQlSCsOi3j7m&q=85&s=ce1bc3053c4b55d545b851343e59f2a6" alt="Gravwell2" width="496" height="568" data-path="images/Gravwell2.png" />
           </Frame>
    8. Click **Generate**.
    9. Copy the generated token immediately.
           <Frame>
             <img src="https://mintcdn.com/airmdr/atbUpYTeHQGcYWGq/images/Screenshot-2026-05-27-at-17.11.07.png?fit=max&auto=format&n=atbUpYTeHQGcYWGq&q=85&s=9b525d304d1cdd349d68080162d521f6" alt="Screenshot 2026 05 27 At 17 11 07" width="1526" height="244" data-path="images/Screenshot-2026-05-27-at-17.11.07.png" />
           </Frame>
    10. Store the token securely.
            <Warning>
              Gravwell displays the token only once. Make sure to record the token, Gravwell will never again provide that token to you, this is your one and only chance to record it. \
              \
              **If it is lost, generate a new token.**
            </Warning>
  </Step>

  <Step title="Generate the API Token in Gravwell UI">
    1. Log in to the Gravwell web UI.
    2. From the left navigation menu, go to: **Tools & Resources → API Tokens**.
           <Info>
             The Gravwell API Token interface is located under **Tools & Resources**.
           </Info>
           <Frame>
             <img src="https://mintcdn.com/airmdr/RXlunQlSCsOi3j7m/images/Gravwell1.png?fit=max&auto=format&n=RXlunQlSCsOi3j7m&q=85&s=796842e3d31e63054a4f519ef478a628" alt="Gravwell1" width="582" height="586" data-path="images/Gravwell1.png" />
           </Frame>
    3. Click **Create Token** or **New Token**.
    4. Enter a clear token name. Example: `AirMDR Integration Token`
    5. Add a description.\
       Example: `Token used by AirMDR to query Gravwell alerts and telemetry.`
    6. Select the required permissions. Recommended minimum permissions:
       | Permission Area | Purpose                                                   |
       | :-------------- | :-------------------------------------------------------- |
       | Search          | Allows AirMDR to run Gravwell searches.                   |
       | Search and Data | Allows access to search-related APIs.                     |
       | Alert Read      | Allows AirMDR to retrieve alert information, if required. |
       | Tag Access      | Allows access to required Gravwell tags.                  |
           <Info>
             Gravwell supports selecting permissions as grouped permissions or fine-grained controls.
           </Info>
    7. Set an expiration date, if required.
           <Frame>
             <img src="https://mintcdn.com/airmdr/RXlunQlSCsOi3j7m/images/Gravwell2.png?fit=max&auto=format&n=RXlunQlSCsOi3j7m&q=85&s=ce1bc3053c4b55d545b851343e59f2a6" alt="Gravwell2" width="496" height="568" data-path="images/Gravwell2.png" />
           </Frame>
    8. Click **Generate**.
    9. Copy the generated token immediately.
           <Frame>
             <img src="https://mintcdn.com/airmdr/atbUpYTeHQGcYWGq/images/Screenshot-2026-05-27-at-17.11.07.png?fit=max&auto=format&n=atbUpYTeHQGcYWGq&q=85&s=9b525d304d1cdd349d68080162d521f6" alt="Screenshot 2026 05 27 At 17 11 07" width="1526" height="244" data-path="images/Screenshot-2026-05-27-at-17.11.07.png" />
           </Frame>
    10. Store the token securely.
            <Warning>
              Gravwell displays the token only once. Make sure to record the token, Gravwell will never again provide that token to you, this is your one and only chance to record it. \
              \
              **If it is lost, generate a new token.**
            </Warning>
  </Step>
</Steps>

### Integration Credential Requirements

Use the following values in the AirMDR integration configuration screen:

| AirMDR Field           | Value                                                             |
| :--------------------- | :---------------------------------------------------------------- |
| Instance URL           | `https://<gravwell-hostname>`                                     |
| Token                  | `<generated-gravwell-api-token>`                                  |
| Verify SSL Certificate | Enabled, unless using a trusted internal exception                |
| Remote Agent           | Select if Gravwell is accessible only through an internal network |

### Gravwell Credential Reference Table

| AirMDR Field   | What to Enter                                     | Where to Get It                                                            | Example                                               |
| :------------- | :------------------------------------------------ | :------------------------------------------------------------------------- | :---------------------------------------------------- |
| `Instance_url` | Gravwell API base URL using the reachable IP/host | Use the Gravwell server IP or hostname that AirMDR/remote agent can access | `http://199.244.253.132` or `https://199.244.253.132` |
| `Token`        | Gravwell API token                                | Gravwell UI → **Tools & Resources → API Tokens**                           | `<generated-gravwell-token>`                          |

### Validate Connectivity

Use the following command to verify connectivity and token authentication:

<AccordionGroup>
  <Accordion title="Sample Request & Response – /api/parse">
    **Request:**

    ```text theme={null}
    curl -X POST \
      -H "Gravwell-Token: <token>" \
      -H "query: tag=gravwell limit 10" \
      http://199.244.253.132/api/parse
    ```

    **Sample successful response:**

    ```text theme={null}

      "GoodQuery": true,
      "ParsedQuery": "tag=gravwell limit 10",
      "RawQuery": "tag=gravwell limit 10"

    ```

    **Sample Failure Response:**

    ```text theme={null}
    {
      "GoodQuery": false,
      "Error": "Invalid query syntax"
    }
    ```
  </Accordion>

  <Accordion title="Sample Request & Response – /api/search/direct">
    **Request:**

    ```text theme={null}
    curl -X POST \
      -H "Gravwell-Token: <token>" \
      -H "query: tag=gravwell limit 5" \
      -H "duration: 1h" \
      -H "format: json" \
      http://199.244.253.132/api/search/direct
    ```

    **Sample Successful Response:**

    ```text theme={null}
    {
      "Entries": [
        {
          "TS": "2026-05-25T10:15:30Z",
          "Tag": "gravwell",
          "Data": "User login successful from 10.10.1.15"
        },
        {
          "TS": "2026-05-25T10:16:02Z",
          "Tag": "gravwell",
          "Data": "Firewall connection allowed to 172.16.1.10"
        }
      ]
    }
    ```

    **Sample Failure Response:**

    ```text theme={null}
    {
      "Error": "Unauthorized"
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  The `/api/parse` endpoint validates query syntax, while `/api/search/direct` executes the actual Gravwell search query and returns results.
</Note>

<Check>
  The token used must have `Search` permission enabled; otherwise the API returns authorization failures.
</Check>

### Configure Gravwell in AirMDR Integrations Dashboard

1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login**
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **Integrations**.
3. Use the search option, enter the keyword "**Gravwell**", select the **Connections** tab, and click **+ Create** button.
4. Enter an unique name to the Instance (e.g., `your org name-Gravwell`) to easily identify the user connection by AirMDR.
5. Enter the application credentials like **Instance URL** and **Token** in the Authentication Details field params, and click **Save**.

### Skills provided by this Integration

| **Skill ID**                          | **Purpose**                                                                                                                                                                              |
| :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get Gravwell Ingesters state          | Get the state of ingesters in gravwell instance.                                                                                                                                         |
| Gravwell Execute Query for Detections | This skill executes queries on Gravwell instances for detection purposes. It supports custom search strings and time duration filters to retrieve security logs and events for analysis. |
| Execute Gravwell Query                | Execute a query in Gravwell.                                                                                                                                                             |

<Tip>
  To view the details of Input Parameters and Output for the respective skills

  * Go to [AirMDR → Gravwell](https://app.airmdr.com/integrationsv2/f04273b1-318e-48db-ad9e-c18f4c158a38/skills?search=grav) Integration page.
  * Select the **Skills** tab and click on the required listed skills.
</Tip>

## Additional Information

<AccordionGroup>
  <Accordion title="🧰 Error Handling">
    | Error                   | Possible Cause                                 | Resolution                                                                            |
    | :---------------------- | :--------------------------------------------- | :------------------------------------------------------------------------------------ |
    | `401 Unauthorized`      | Invalid, expired, or copied incorrectly token  | Generate a new token and update AirMDR.                                               |
    | `403 Forbidden`         | Token does not have required permissions       | Add required search/read permissions.                                                 |
    | `404 Not Found`         | Incorrect Instance URL or API path             | Verify the base URL and endpoint.                                                     |
    | `TLS certificate error` | Self-signed or untrusted certificate           | Use a trusted certificate or configure certificate validation as per internal policy. |
    | `Connection timeout`    | Network/firewall issue                         | Check connectivity from AirMDR or remote agent.                                       |
    | `Query parse failed`    | Invalid Gravwell query syntax                  | Validate query in Gravwell UI first.                                                  |
    | `No data returned`      | Incorrect tag, time range, or permission issue | Confirm tag access and query scope.                                                   |
  </Accordion>

  <Accordion title="🔄 Monitoring & Logs">
    ### Where to Check

    | Location                       | Purpose                                            |
    | :----------------------------- | :------------------------------------------------- |
    | AirMDR Integration Status      | Validate connection status and integration health. |
    | AirMDR Playbook Execution Logs | Review API call failures or query errors.          |
    | Gravwell API Token Page        | Check token status and expiration.                 |
    | Gravwell Webserver Logs        | Troubleshoot authentication or API errors.         |

    **Sample Success Log**\
    `INFO Gravwell integration validation completed successfully.`

    `INFO Tags retrieved from Gravwell instance.`

    **Sample Failure Log**

    `ERROR Gravwell API request failed.`

    `ERROR Status Code: 401 Unauthorized.`

    `ERROR Reason: Invalid or expired token.`\\

    **Recommended Log Levels**

    | Log Level | Usage                                                              |
    | :-------- | :----------------------------------------------------------------- |
    | INFO      | Successful connection, validation, and query execution.            |
    | WARN      | Slow response, partial data, or expiring token.                    |
    | ERROR     | Authentication failure, timeout, SSL failure, or invalid endpoint. |
    | DEBUG     | Use temporarily during troubleshooting only.                       |
  </Accordion>

  <Accordion title="🛑 Security & Access Best Practices">
    ### Do

    1. Use a dedicated Gravwell token for AirMDR.
    2. Grant only required permissions.
    3. Set token expiration where possible.
    4. Store the token in a secure vault.
    5. Use HTTPS with valid TLS certificates.
    6. Rotate tokens periodically.
    7. Disable or delete unused tokens.
    8. Use a remote agent when Gravwell is not publicly reachable.

    ### Avoid

    1. Do not use personal admin tokens for integrations.
    2. Do not share tokens over email or chat.
    3. Do not disable SSL verification unless approved internally.
    4. Do not grant token write permissions unless absolutely required.
    5. Do not reuse the same token across multiple tools.
  </Accordion>

  <Accordion title="👉 Support & Maintenance">
    * 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel.
    * 🔁 Rotate credentials regularly. Recommended cadence: Every 90 days or as per internal security policy
    * 🔄 Reconnect in AirMDR when secrets are changed.

    | Activity                     | Recommended Frequency                   |
    | :--------------------------- | :-------------------------------------- |
    | Review token permissions     | Quarterly                               |
    | Rotate API token             | As per company security policy          |
    | Check token expiration       | Monthly                                 |
    | Validate integration health  | After Gravwell upgrades                 |
    | Review AirMDR execution logs | During incident or integration failures |
  </Accordion>

  <Accordion title="🛑 Data Flow & Security">
    ### Data Exchanged

    | Data Type                 | Direction         | Description                                  |
    | :------------------------ | :---------------- | :------------------------------------------- |
    | API Token                 | AirMDR → Gravwell | Used for authentication.                     |
    | Search Query              | AirMDR → Gravwell | Used to retrieve required telemetry.         |
    | Alerts                    | Gravwell → AirMDR | Returned if alert read access is configured. |
    | Tags / Telemetry Metadata | Gravwell → AirMDR | Used to identify available data sources.     |
    | Search Results            | Gravwell → AirMDR | Used for enrichment and investigation.       |

    ### Ports and Endpoints\\

    | Item                   | Value                         |
    | :--------------------- | :---------------------------- |
    | Protocol               | HTTPS                         |
    | Default Port           | 443                           |
    | Instance URL Format    | `https://<gravwell-hostname>` |
    | Example API Endpoint   | `/api/tags`                   |
    | Search Parse Endpoint  | `/api/parse`                  |
    | Direct Search Endpoint | `/api/search/direct`          |

    Use HTTPS with a valid TLS certificate wherever possible.
  </Accordion>
</AccordionGroup>

###