Orca Security Configuration#

Configure a read-only Orca API token and the API origin for your Orca region.

Authentication#

Create an API token by following the instructions for your Orca tenant. Orca role names can vary by tenant, so grant the organization-wide read access listed below.

Required Permissions#

The token must authorize these operations:

Operation

Required access

GET /api/user/action

Read the organization’s ID and name.

POST /api/serving-layer/query

Query Alert and VulnerabilityV2, including related Inventory context.

The token must cover the entire organization. Partial account, business-unit, or asset access isn’t supported because cleanup requires a complete snapshot. VulnerabilityV2 results must include Inventory.AssetUniqueId.

Configure Cartography#

Set --orca-api-endpoint to your regional HTTPS API origin without /api or a route. Cartography reads the token from ORCASECURITY_API_TOKEN by default.

Option

Default

Required

Description

--orca-api-endpoint

Yes

Regional Orca API origin.

--orca-api-token-env-var

ORCASECURITY_API_TOKEN

No

Environment variable that contains the Orca API token.

Run Cartography#

export ORCASECURITY_API_TOKEN="..."

cartography \
  --selected-modules orca \
  --orca-api-endpoint https://api.orcasecurity.io

Troubleshooting#

  • HTTP 401: Check whether the token is valid and unexpired.

  • HTTP 403 or missing findings: Check the token’s organization-wide read access.

  • Missing Inventory.AssetUniqueId: Check the response in Orca’s authenticated Serving Layer Request Builder.

References#