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

# Orca Security

> The Orca Security integration enables AirMDR to access Orca data through supported integration skills. Security teams can use the available skills to add cloud-security context to investigations and automate applicable playbook tasks.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="Authentication">
    **API token authentication**

    Create an API token in Orca and enter its value in the AirMDR connection.

    Orca publishes token-based authentication examples using this header:

    ```text theme={null}
    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. 

    <Accordion title="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 |

      <Warning>
        Use a dedicated integration token. Avoid granting administrator-level access solely to resolve a connection error.
      </Warning>
    </Accordion>
  </Accordion>
</AccordionGroup>

## Pre-requisites

> <Check>
>   An active Orca Security tenant with API access.
> </Check>
>
> <Check>
>   An Orca user authorized to create and manage API tokens.
> </Check>
>
> <Check>
>   Confirmation of the region hosting your Orca tenant.
> </Check>
>
> <Check>
>   Permission to create an API token and permission to access data through that token are separate requirements.
> </Check>

## Setup Steps

<Steps>
  <Step title="Sign in to the correct Orca region">
    1. Open the [Orca Security region-selection page](https://region-selection.orcasecurity.io/).
    2. Select the region in which your organization’s Orca tenant is hosted.
    3. Sign in using your organization’s approved authentication method.
    4. Confirm that you are accessing the correct organization before creating the token.
           <Note>
             Select the tenant’s hosting region. Your physical location does not determine the tenant region.
           </Note>
  </Step>

  <Step title="Identify the API URL">
    The API URL is an existing regional endpoint; it is not generated when you create a token.

    1. Confirm the hosting region selected during sign-in.
    2. Open **Settings → Users & Permissions → API**.
    3. Use any API documentation or endpoint information available to your tenant to confirm the regional API base URL.
    4. If the endpoint is not displayed, obtain it from your Orca administrator or Orca Support.
    5. 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` |

    <Tip>
      When entering the URL:

      * Use `https://`.
      * Do not enter the region-selection URL or a dashboard page.
      * Do not append an individual resource endpoint.
      * Enter the regional HTTPS host only, without `/api/`, a resource endpoint, query parameters, or any other path. AirMDR automatically appends the API path when sending requests.
    </Tip>
  </Step>

  <Step title="Open API token management">
    1. In Orca, select **Settings**.
    2. Under **Users & Permissions**, select **API**.
    3. Select **Add API Token**. Some documented UI versions label this action **Create API Token**.
           <Note>
             If the API page or token-creation action is unavailable, ask your Orca administrator to review your access.
           </Note>
  </Step>

  <Step title="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:

    ```text theme={null}
    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
    ```

    <Note>
      A narrowly scoped token can authenticate successfully while returning only part of the organization’s data.
    </Note>
  </Step>

  <Step title="Generate and securely copy the token">
    1. Review the role, scope, and expiration settings.
    2. Click **Add**.
    3. In the generated-token window, copy the token before selecting **Continue**.
    4. Store it temporarily in an approved password manager or secret-management system.
    5. Record its expiration date separately.

    <Warning>
      **The Orca Security token may be visible only once.** <br />**If it is lost, generate a new token and update the AirMDR integration.**
    </Warning>

    <Warning>
      **Do not include the token in screenshots, email, chat, Jira tickets, or documentation examples.**
    </Warning>
  </Step>
</Steps>

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

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

### 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>`. 

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

<Accordion title="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.

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

  ```text theme={null}
  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
    }'
  ```
</Accordion>

<Accordion title="Sample Response">
  A successful request should return \*\*HTTP \*\*`200 OK` and a JSON response. Review the body for any application-level error.

  ```http theme={null}
  HTTP/2 200
  content-type: application/json
  ```
</Accordion>

<Accordion title="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 |

  <Note>
    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.
  </Note>
</Accordion>

## Configure Orca Security 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 **ADMIN → Integrations**.
3. Use the search option, enter the keyword "**Orca Security**", select the **Connections** tab, and click **+ New Connection** button.
4. 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** | Regional HTTPS host only, without `/api/` or any other path | `https://app.us.orcasecurity.io` |
   | **API Token** | The generated token value | `<ORCA_API_TOKEN>` |

   <Accordion title="Expand Advanced Configuration if required. (Optional)">
     1. 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.
     2. In **Expiry**, select the Orca token’s expiration date or an earlier date required by your organization’s credential-rotation policy.

     <Note>
       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.
     </Note>
   </Accordion>
5. Click **Save**.

## Skills provided by this Integration

<AccordionGroup>
  <Accordion title="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 |
  </Accordion>

  <Accordion title="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 |

    <Note>
      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.
    </Note>
  </Accordion>

  <Accordion title="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 |
  </Accordion>
</AccordionGroup>

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

  * Go to [AirMDR → Orca Security](https://app.airmdr.com/integrationsv2/4ec06f1a-09f2-40c0-89cf-831682ecc587/skills?search=orca) Integration page.
  * Select the **Skills** tab and click on the required listed skills.
</Tip>

### 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/Verify** when 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** | Changes the score or severity of a single Orca Security alert. Set `score` as an integer with no range limit imposed by the skill, `orca_score` as a floating-point value between `0` and `10`, or both | Read-only access for alert retrieval; corresponding alert-management access for write skills | Alert-read access plus **Updating Risk Score** |

<Note>
  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.
</Note>

<Info>
  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.
</Info>

<Check>
  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.
</Check>

<AccordionGroup>
  <Accordion title="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**.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Additional Information

<AccordionGroup>
  <Accordion title="🧰 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 |

    <Note>
      Do not repeatedly retry authentication or permission failures without correcting their cause.
    </Note>
  </Accordion>

  <Accordion title="🔄 Monitoring & Logs">
    **Review execution results in AirMDR**

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

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

    **Review the token in Orca**

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

    **Recommended diagnostic information**

    Record:

    * 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 entries**

    These examples show useful diagnostic fields; they are not the native AirMDR or Orca log format.

    ```text theme={null}
    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.
  </Accordion>

  <Accordion title="🛑 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.
  </Accordion>

  <Accordion title="👉 Support & Maintenance">
    * 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) 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.
             <Warning>
               If compromise is suspected, revoke the affected token promptly and follow your incident-response process.
             </Warning>
  </Accordion>

  <Accordion title="🛑 Data Flow & Security">
    **Data exchanged**

    AirMDR 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**

    <img src="https://mintcdn.com/airmdr/1FGkbbt5A_OPbw8d/images/mermaid-diagram-2.png?fit=max&auto=format&n=1FGkbbt5A_OPbw8d&q=85&s=199303fe896befb7544baad364d67594" alt="Mermaid Diagram 2" width="974" height="952" data-path="images/mermaid-diagram-2.png" />

    **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 |

    <Note>
      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.
    </Note>
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.