Orca Security

Purpose

To connect Orca Security to AirMDR using your regional API URL and an API token. This guide explains how to obtain the credentials, create the AirMDR connection, configure Remote Agent and Expiry, and troubleshoot common issues.The data and operations available through the connection depend on:

The Orca skills enabled in AirMDR.
The permissions assigned to the API token.
The accounts and resources included in the token’s scope.
The API capabilities available to your Orca tenant.

Supported Versions

Component	Compatibility requirement
Orca Security	Cloud-hosted Orca tenant with access to the APIs required by the selected AirMDR skills
Orca API	Endpoints supported by the deployed AirMDR Orca connector
AirMDR	Environment in which the Orca Security integration is available
Authentication	Orca API token
Network connection	HTTPS to the applicable regional API endpoint

Authentication

API token authenticationCreate an API token in Orca and enter its value in the AirMDR connection.Orca publishes token-based authentication examples using this header:

Authorization: Token <ORCA_API_TOKEN>

The Token prefix is part of the request header. Enter only the generated secret value in AirMDR’s API Token field unless its field instructions explicitly request a complete header.

Role-based access considerations

For an integration that only retrieves data, start with a read-only role such as Viewer, then verify that it permits every required AirMDR operation. Published Orca connector instructions use Viewer for read access; this does not establish the minimum role for every AirMDR skill.

Requirement	Access guidance
Create the token	Use an account authorized to manage API tokens
Retrieve information	Grant the read permissions required by the selected skills
Change information	Grant the specific write permissions only if an enabled skill requires them
Limit accessible resources	Restrict the token to the required accounts, business units, or other available scope options

Use a dedicated integration token. Avoid granting administrator-level access solely to resolve a connection error.

Pre-requisites

An active active Orca Security tenant with API access

An Orca user authorized to create, manage API tokens and confirmation of the region hosting your Orca tenant.

Permission to create an API token and permission to access data through that token are separate requirements.

Setup Steps

Open the Orca Security region-selection page.
Select the region in which your organization’s Orca tenant is hosted.
Sign in using your organization’s approved authentication method.
Confirm that you are accessing the correct organization before creating the token.
Select the tenant’s hosting region. Your physical location does not determine the tenant region.

Identify the API URL

The API URL is an existing regional endpoint; it is not generated when you create a token.

Confirm the hosting region selected during sign-in.
Open Settings → Users & Permissions → API.
Use any API documentation or endpoint information available to your tenant to confirm the regional API base URL.
If the endpoint is not displayed, obtain it from your Orca administrator or Orca Support.
Record the confirmed URL for the AirMDR connection.

Use the following regional API URLs as a reference and confirm the applicable host for your tenant.

Tenant region	API URL — host only
United States	`https://app.us.orcasecurity.io`
Europe	`https://app.eu.orcasecurity.io`
Australia	`https://app.au.orcasecurity.io`
India	`https://app.in.orcasecurity.io`
Israel	`https://api.il.orcasecurity.io`
Brazil	`https://api.sa.orcasecurity.io`

Published connector guides differ for some regions.
For example, Veracode lists https://api.eu.orcasecurity.io/api/
For Europe: Confirm the endpoint rather than replacing app with api yourself.

When entering the URL:

Use https://.
Do not enter the region-selection URL or a dashboard page.
Do not append an individual resource endpoint.
Follow the AirMDR field’s instructions for whether to include /api/. Some connectors expect the host only and add the API path themselves.

Open API token management

In Orca, select Settings.
Under Users & Permissions, select API.
Select Add API Token. Some documented UI versions label this action Create API Token.
If the API page or token-creation action is unavailable, ask your Orca administrator to review your access.

Configure the token

Complete the fields displayed in the token dialog.

Field	What to configure
Name	A descriptive name, such as `AirMDR-Production`
Description	The integration purpose and owner
Never Expire	Leave unselected when your policy requires time-limited credentials
Expiration	An approved expiry date
Service Token	Select when an organizational service token is appropriate and permitted
Role	The role required for the selected AirMDR operations
Scope access to specific resources	Restrict access to the necessary accounts, business units, or projects, where available

Example values:

Name: AirMDR-Production
Description: Orca integration for approved AirMDR investigation workflows
Role: Viewer, subject to required-skill validation
Expiration: Date approved by the organization
Scope: Required production accounts or business units

A narrowly scoped token can authenticate successfully while returning only part of the organization’s data.

Generate and securely copy the token

Review the role, scope, and expiration settings.
Click Add.
In the generated-token window, copy the token before selecting Continue.
Store it temporarily in an approved password manager or secret-management system.
Record its expiration date separately.

The Orca Security token may be visible only once.
If it is lost, generate a new token and update the AirMDR integration.

Do not include the token in screenshots, email, chat, Jira tickets, or documentation examples.

Orca Security Credential Reference Table

Credential / Field	Required	Where to obtain	Description
API URL	Yes	Orca tenant API documentation or your Orca administrator	Regional HTTPS host used to connect to Orca Security. Enter the host only, without `/api/` or any other path. AirMDR appends the API path automatically.
API Token	Yes	Orca Security → Settings → Users & Permissions → API → Add API Token / Create API Token	Token used to authenticate API requests. Enter only the generated token value, without the `Token` prefix. Assign the access required by the selected skills.

Copy the generated Orca token before closing the token window; the published workflow states that it cannot be retrieved again after continuing.

Validate Connectivity

You can optionally validate the Orca API URL and token before adding them to AirMDR. The following request queries up to one open alert through the Serving Layer API. Although it uses POST, it retrieves information without changing alerts. The endpoint uses Authorization: Token <API_TOKEN>.

Prerequisite: The token must have alert-read permission and access to the required accounts or business units.

Sample Request

Replace <ORCA_API_TOKEN> with your generated token. The example uses the default US API host; replace it with your confirmed regional host when applicable.This example adapts the published Serving Layer alert-query format by limiting the result to one record.

A manual cURL request includes the complete endpoint path. The AirMDR API URL field contains only the host because AirMDR appends that path.

curl --request POST \
  --url 'https://app.us.orcasecurity.io/api/serving-layer/query' \
  --header 'Authorization: Token <ORCA_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --connect-timeout 10 \
  --max-time 30 \
  --include \
  --data '{
    "query": {
      "models": ["Alert"],
      "type": "object_set",
      "with": {
        "operator": "and",
        "type": "operation",
        "values": [
          {
            "key": "Status",
            "operator": "in",
            "type": "str",
            "values": ["open"]
          }
        ]
      }
    },
    "select": [
      "AlertId",
      "Title",
      "Status",
      "OrcaScore"
    ],
    "limit": 1,
    "start_at_index": 0
  }'

Sample Response

A successful request should return **HTTP **200 OK and a JSON response. Review the body for any application-level error.

HTTP/2 200
content-type: application/json

Troubleshooting

Result	What to check
`400 Bad Request`	Query format and field names
`401 Unauthorized`	Token value, expiration, or revocation
`403 Forbidden`	Alert-read permission and resource scope
`404 Not Found`	Regional host and endpoint path
`429 Too Many Requests`	Request frequency and retry guidance
Timeout or TLS error	DNS, firewall, proxy, and certificate trust

This test validates alert retrieval from the machine running the command. Validate the AirMDR connection separately, and test status changes, snoozing, comments, and score updates to confirm their write permissions.

Configure Orca Security in AirMDR Integrations Dashboard

Navigate to AirMDR, provide the credentials and click Login
Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
Use the search option, enter the keyword “Orca Security”, select the Connections tab, and click + New Connection button.

Use the following values in the AirMDR integration configuration screen:

AirMDR field	What to enter	Example
Instance	A unique connection name	`Orca-Security-Production`
Organization, if displayed	The AirMDR organization owning the connection	Select the appropriate organization
Description, if displayed	A brief connection purpose	`Production Orca investigation connection`
API URL	The confirmed regional URL in the format required by the connector	`<CONFIRMED_ORCA_API_URL>`
API Token	The generated token value	`<ORCA_API_TOKEN>`

Expand Advanced Configuration if required. (Optional)

In Remote Agent, select an AirMDR Remote Agent when Orca API requests must run through an approved network route. Ensure the selected agent can resolve and reach the regional Orca API host over HTTPS. For direct connectivity from AirMDR, leave this field unselected.
In Expiry, select the Orca token’s expiration date or an earlier date required by your organization’s credential-rotation policy.

Expiry controls credential validity in AirMDR. It does not automatically rotate, extend, or revoke the token in Orca Security. Create a replacement token, update API Token and Expiry, save and validate the connection, and then revoke the previous token when it is no longer required.

Click Save.

Skills provided by this Integration

Alert Investigation

Skill	Purpose	Access type	Required permission
Fetch Orca Security Alerts	Retrieves alerts through the Serving Layer API. Supports filters including alert ID, type, category, risk level, status, source, minimum Orca score, and a relative time window.	Read	Alert-read access to the selected resources

Alert Lifecycle Management

Skill	Purpose	Access type	Required permission
Update Orca Security Alert Status	Changes the status of a single alert. Accepts `open`, `in_progress`, `dismiss`, `dismissed`, `close`, or `closed`, with an optional reason and justification.	Write	Status-change access; closing/verifying access when closing
Snooze Orca Security Alert	Snoozes a single alert for a specified number of days. The alert reappears when the snooze period expires.	Write	Alert-snooze access
Update Orca Security Alert Score	Changes the score or severity of a single alert. Supports `score`, `orca_score` from `0` to `10`, or both, with an optional reason and justification.	Write	Risk-score update access

Changing an alert’s status, snooze period, or score manages the alert record. It does not demonstrate that the underlying cloud risk has been remediated.

Investigation Notes and Evidence

Skill	Purpose	Access type	Required permission
Add Comment to Orca Security Alert	Adds a comment to an alert identified by `AlertId`. Use it to record investigation notes, triage findings, or remediation evidence in Orca.	Write	Comment-creation access; exact Orca permission mapping pending validation

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

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

Permissions and Roles by Skill

AirMDR skill	Required access	Applicable role	Required permissions
Fetch Orca Security Alerts	Query and read alerts through the Serving Layer API	Viewer, or a custom read-only role	Risks → Alerts → Alerts Read for Serving Layer alert queries
Update Orca Security Alert Status	Change alert status, including closing or verifying alerts when those actions are used	Custom role with alert-management access	Alert-read access plus Alerts status change. Include Alerts Close/Verifywhen using `close` or `closed`.
Snooze Orca Security Alert	Snooze alerts	Custom role with snooze access	Alert-read access plus Alerts snooze
Add Comment to Orca Security Alert	Add comments to alerts	Custom role with comment-creation access	Alert-read access plus permission to add alert comments. The exact permission label, including whether Alerts Write covers it, requires confirmation.
Update Orca Security Alert Score	Change alert score or severity	Custom role with score-update access	Alert-read access plus Updating Risk Score

Read-only access is sufficient for alert retrieval. Alert-management skills require the corresponding write access. Resource scope controls which alerts the token can access; it does not grant permission to modify them.

Alert-read access is documented for Serving Layer retrieval. The granular action labels above appear in a published Orca UI walkthrough; their mapping to the exact API calls used by AirMDR must be validated before documenting them as the verified minimum.

Confirm the exact built-in role or custom permission labels against a live tenant, especially comment creation. Remove research notes from customer content, but do not replace them with an unsupported claim that Viewer, Alerts Write, or a particular custom role supports every operation.

Recommended Configuration for All Five Skills

Create a custom role named, for example, AirMDR Orca Alert Management, with:

Alert-read access.
Alert status-change access.
Alert closing/verifying access.
Alert snooze access.
Alert score-update access.
Alert comment-creation access, once its permission mapping is confirmed.

If your tenant exposes a broader Alerts Write permission instead of separate action controls, validate it against all four write skills. It is a candidate configuration, not a confirmed minimum permission set.

Resource Scope

Assign the API token access to the cloud accounts or business units containing the alerts that AirMDR will retrieve or manage. Orca’s token configuration supports resource scoping.

Setting	Requirement
Role / Permissions	Allows the required read or write operation
Resource Scope	Allows access to the account or business unit associated with the alert

Important: The user creating the token needs token-management privileges. The integration token itself should receive only the operational permissions above; administrator access is not established as a requirement for these skills.

Additional Information

🧰 Error Handling

The following describes common HTTP and connection symptoms. The returned error details should guide the final diagnosis.

Symptom	Possible cause	Recovery steps
Cannot access API token settings	Insufficient Orca permissions	Ask the administrator to review token-management access
Required AirMDR field rejected	Missing value or incorrect URL format	Check the connector’s field instructions
`400 Bad Request`	Invalid input, query, or request format	Review the skill inputs and endpoint requirements
`401 Unauthorized`	Incorrect, expired, or revoked token	Verify token validity and replace the stored value when necessary
`403 Forbidden`	Missing permission or restricted resource access	Review the role, scope, and any applicable access policy
`404 Not Found`	Incorrect host/path or unavailable endpoint	Confirm the regional URL and check for a duplicated `/api/` path
`429 Too Many Requests`	Request rate exceeded	Reduce concurrency and follow any supplied retry guidance
`5xx` response	Service-side or upstream failure	Check availability and retry with a bounded delay
DNS or connection timeout	DNS, firewall, proxy, or routing issue	Test from the actual AirMDR execution route
TLS certificate error	Certificate trust or proxy inspection issue	Correct the trust configuration; retain certificate validation
Successful request with missing data	Scope restrictions, filters, or unavailable records	Check the token’s resource scope and skill inputs
Remote Agent execution fails	Agent unavailable or unable to reach Orca	Check agent health and outbound connectivity
Connection credentials marked expired	AirMDR Expiry reached	Replace or verify the credentials and update Expiry appropriately

Do not repeatedly retry authentication or permission failures without correcting their cause.

🔄 Monitoring & Logs

Review execution results in AirMDR

Open the playbook or skill execution that used the Orca connection.
Review its status, inputs, outputs, and error details.
Identify whether the failure concerns connectivity, authentication, authorization, or request parameters.
Record the execution ID and timestamp for troubleshooting.

Use the execution-history controls available in your AirMDR environment.Review the token in Orca

Navigate to Settings → Users & Permissions → API.
Locate the integration token.
Review its expiration, role, and resource scope.
Check relevant audit information if it is available to your tenant.

Recommended diagnostic informationRecord:

Connection name.
Execution ID and timestamp.
API host and requested operation.
HTTP status code and sanitized error.
Remote Agent identity, when applicable.

Do not record authorization headers or token values.Illustrative log entriesThese examples show useful diagnostic fields; they are not the native AirMDR or Orca log format.

INFO integration=orca_security connection=Orca-Security-Production
operation=read_only_query http_status=200 result=success

ERROR integration=orca_security connection=Orca-Security-Production
operation=read_only_query http_status=401 result=authentication_failed

Use INFO for routine operation and WARN/ERROR for failures. Enable DEBUG temporarily only when needed, with secrets and sensitive response data redacted.

🛑 Security & Access Best Practices

✅ Do

Create a dedicated token for the AirMDR connection.
Grant only the permissions required by enabled skills.
Restrict access to the necessary resources.
Use an approved expiration date and rotate credentials in advance.
Confirm the regional endpoint before entering credentials.
Keep TLS certificate validation enabled.
Store credentials in approved secret-management systems.
Mask secrets in screenshots, recordings, and support evidence.

❌ Don’t

Sharing tokens through email, chat, or tickets.
Granting administrator access as a general troubleshooting measure.
Using non-expiring tokens without policy approval.
Entering a dashboard or region-selection URL as the API URL.
Assuming every regional API host follows the same naming pattern.
Assuming AirMDR Expiry changes the token in Orca.
Assuming a Remote Agent expands the token’s access.

👉 Support & Maintenance

📧 Contact AirMDR Support through your designated support channel.
🔁 Rotate credentials regularly. Recommended cadence: As per your internal security policy
🔄 Replace a token before expiration
1. Create a replacement token in Orca with the approved role and scope.
2. Copy and securely store the new value.
3. Edit the existing Orca connection in AirMDR.
4. Replace API Token.
5. Update Expiry.
6. Save and validate a read-only skill.
7. After successful validation, revoke or delete the previous token in Orca using the available token-management controls.
8. Update the credential inventory and remove obsolete secret copies.
  If compromise is suspected, revoke the affected token promptly and follow your incident-response process.

🛑 Data Flow & Security

Data exchangedAirMDR retrieves Orca alerts through the Serving Layer API. Alert results can include associated context, such as Inventory.Name and CloudAccount.* fields.The other supported skills update an alert’s status, snooze period, comments, or score. These five skills do not perform standalone asset queries.Requests are sent to the regional Orca API, either directly from AirMDR or through a selected Remote Agent.Connection flow

Network and security requirements

Area	Requirement
Transport	Use HTTPS with certificate validation
Destination	Confirmed regional Orca API hostname
API port	TCP 443 for standard HTTPS endpoints
Request authentication	API token in the authorization header
Resource access	Restricted by the token’s role and scope
Network allowlisting	Permit the required destination from the actual execution environment
Credentials and retained results	Follow the applicable AirMDR, Orca, and organizational storage controls

HTTPS protects traffic in transit. Specific encryption-at-rest algorithms, retention periods, and regional-storage guarantees must be taken from the applicable vendor security documentation.

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Pre-requisites

Setup Steps

Orca Security Credential Reference Table

Validate Connectivity

Configure Orca Security in AirMDR Integrations Dashboard

Skills provided by this Integration

Permissions and Roles by Skill

Additional Information

​Pre-requisites

​Setup Steps

​Orca Security Credential Reference Table

​Validate Connectivity

​Configure Orca Security in AirMDR Integrations Dashboard

​Skills provided by this Integration

​Permissions and Roles by Skill

​Additional Information

Pre-requisites

Setup Steps

Orca Security Credential Reference Table

Validate Connectivity

Configure Orca Security in AirMDR Integrations Dashboard

Skills provided by this Integration

Permissions and Roles by Skill

Additional Information