Skip to main content

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.

​
Purpose

This guide explains how to generate the required Gravwell credentials for configuring the integration in AirMDR:
Required FieldDescription
Instance_urlBase URL of the Gravwell web instance.
TokenGravwell 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

ComponentSupported/Recommended
GravwellGravwell versions that support API Tokens and REST APIs
Authentication MethodGravwell API Token
ProtocolHTTPS recommended
Integration TypeSIEM / 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

FieldValue
Instance URLhttps://<gravwell-hostname>
TokenAPI token generated from Gravwell UI
Header UsedGravwell-Token
Example authentication header: Gravwell-Token: <token>

​
Role-Based Access Considerations

AreaRecommendation
Token PermissionsGrant only the permissions required by AirMDR.
Search AccessEnable search-related permissions if AirMDR needs to run queries.
Alert AccessEnable alert/read permissions if alert retrieval is required.
Admin APIsDo not expect tokens to perform admin-level actions.
ExpirationSet an expiration date where possible.
Gravwell tokens can only restrict access. They cannot grant permissions that the user does not already have.

​
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. Copy the base URL from the browser address bar.
    Example: https://gravwell.company.com
  3. Remove any extra paths after the hostname. Use this: https://gravwell.company.com
  4. Avoid this: https://gravwell.company.com/search/history
  5. Save this value as Instance_url.
    The Instance URL must be reachable from the AirMDR platform or 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 AreaPurpose
    SearchAllows AirMDR to run Gravwell searches.
    Search and DataAllows access to search-related APIs.
    Alert ReadAllows AirMDR to retrieve alert information, if required.
    Tag AccessAllows 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. If it is lost, generate a new token.

​
Integration Credential Requirements

Use the following values in the AirMDR integration configuration screen:
AirMDR FieldValue
Instance URLhttps://<gravwell-hostname>
Token<generated-gravwell-api-token>
Verify SSL CertificateEnabled, unless using a trusted internal exception
Remote AgentSelect if Gravwell is accessible only through an internal network

​
Gravwell Credential Reference Table

CredentialDescriptionWhere to Get in Gravwell UIExample
Instance_urlBase URL of the Gravwell instance used by AirMDR to connect to the APICopy directly from the browser address bar after logging into Gravwellhttps://gravwell.company.com
TokenAPI authentication token used for secure API accessNavigate to Tools & Resources → API Tokens and generate a new tokenAPITOKEN_xxxxxxxxx

​
Validate Connectivity

Use the following command to verify connectivity and token authentication: 
curl --request GET \
  --url "https://<gravwell-hostname>/api/tags" \
  --header "Gravwell-Token: <token>"
Sample successful response: 
[
  "default",
  "gravwell",
  "syslog",
  "apache",
  "netflow"
]

​
Configure Salesforce 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 IDPurpose
Get Gravwell Ingesters stateGet the state of ingesters in gravwell instance.
Gravwell Execute Query for DetectionsThis 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 QueryExecute 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

ErrorPossible CauseResolution
401 UnauthorizedInvalid, expired, or copied incorrectly tokenGenerate a new token and update AirMDR.
403 ForbiddenToken does not have required permissionsAdd required search/read permissions.
404 Not FoundIncorrect Instance URL or API pathVerify the base URL and endpoint.
TLS certificate errorSelf-signed or untrusted certificateUse a trusted certificate or configure certificate validation as per internal policy.
Connection timeoutNetwork/firewall issueCheck connectivity from AirMDR or remote agent.
Query parse failedInvalid Gravwell query syntaxValidate query in Gravwell UI first.
No data returnedIncorrect tag, time range, or permission issueConfirm tag access and query scope.

​
Where to Check

LocationPurpose
AirMDR Integration StatusValidate connection status and integration health.
AirMDR Playbook Execution LogsReview API call failures or query errors.
Gravwell API Token PageCheck token status and expiration.
Gravwell Webserver LogsTroubleshoot authentication or API errors.
Sample Success Log
INFO Gravwell integration validation completed successfully.INFO Tags retrieved from Gravwell instance.Sample Failure LogERROR Gravwell API request failed.ERROR Status Code: 401 Unauthorized.ERROR Reason: Invalid or expired token.\Recommended Log Levels
Log LevelUsage
INFOSuccessful connection, validation, and query execution.
WARNSlow response, partial data, or expiring token.
ERRORAuthentication failure, timeout, SSL failure, or invalid endpoint.
DEBUGUse temporarily during troubleshooting only.

​
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.
  • 📧 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.
ActivityRecommended Frequency
Review token permissionsQuarterly
Rotate API tokenAs per company security policy
Check token expirationMonthly
Validate integration healthAfter Gravwell upgrades
Review AirMDR execution logsDuring incident or integration failures

​
Data Exchanged

Data TypeDirectionDescription
API TokenAirMDR → GravwellUsed for authentication.
Search QueryAirMDR → GravwellUsed to retrieve required telemetry.
AlertsGravwell → AirMDRReturned if alert read access is configured.
Tags / Telemetry MetadataGravwell → AirMDRUsed to identify available data sources.
Search ResultsGravwell → AirMDRUsed for enrichment and investigation.

​
Ports and Endpoints\

ItemValue
ProtocolHTTPS
Default Port443
Instance URL Formathttps://<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.

\