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.

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.

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

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.

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

Users only need to provide the Instance_url and Token in the AirMDR integration UI.

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

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

Users must have Administrator access to the Gravwell UI with sufficient privileges to create or manage users and verify firewall settings.

Permission to create API tokens in Gravwell.

Gravwell admins can restrict token creation for non-admin users using CBAC controls.

Setup Steps

1. 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.
      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.

      Ensure the Gravwell IP address or hostname is reachable from the AirMDR platform or the configured remote agent.

2. 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.
      The Gravwell API Token interface is located under Tools & Resources.

      
   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.

      Gravwell supports selecting permissions as grouped permissions or fine-grained controls.

   7. Set an expiration date, if required.
      
   8. Click Generate.
   9. Copy the generated token immediately.
      
   10. Store the token securely.
       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.

3. 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.
      The Gravwell API Token interface is located under Tools & Resources.

      
   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.

      Gravwell supports selecting permissions as grouped permissions or fine-grained controls.

   7. Set an expiration date, if required.
      
   8. Click Generate.
   9. Copy the generated token immediately.
      
   10. Store the token securely.
       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.

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:

Sample Request & Response – /api/parse

Request:

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

Sample successful response:

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

Sample Failure Response:

{
  "GoodQuery": false,
  "Error": "Invalid query syntax"
}

Sample Request & Response – /api/search/direct

Request:

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:

{
  "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:

{
  "Error": "Unauthorized"
}

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

The token used must have Search permission enabled; otherwise the API returns authorization failures.

Configure Gravwell in AirMDR Integrations Dashboard

1. Navigate to AirMDR, 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.

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

• Go to AirMDR → Gravwell Integration page.
• Select the Skills tab and click on the required listed skills.

Additional Information

🧰 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.

🔄 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.

🛑 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.

👉 Support & Maintenance

• 📧 Contact AirMDR Support 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

🛑 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.