About this document
This document provides step-by-step instructions to configure the Orca Security integration in SAFE.
Introduction
This integration enables you to seamlessly onboard assets and import vulnerability findings from Orca Security into SAFE. SAFE Admins can configure the integration using the “Orca Security” card available on the Integrations page.
Prerequisites
An Orca Security user with the Viewer role (no Admin or custom role required unless specified by your organization’s policy or for token creation).
SAFE access with an Administrator role.
Generate Orca API Token
To integrate SAFE with Orca Security, you need an API token with the Viewer role. Follow these steps:
Log in to your organization’s Orca account as an administrator or a user with permission to create API tokens.
Click Settings from the navigation menu.
Navigate to Users & Permissions > API.
.png)
Click API Tokens, then click Add API Token.
In the Add API Token dialog, enter the details:
Name: Give your API token a name.
Description: (Optional) Add a description.
Never Expire: (Optional) Select if you want the token to never expire.
Service Token: (Optional) Enable if you want a service token.
Role: Select Viewer from the Role drop-down.
Note: The Viewer role is the minimum required to read and retrieve data. For more, see https://docs.orcasecurity.io/v1/docs/default-roles-and-permissions.
Scope: Select the accounts or business units the token should access, or leave blank for all.
Click Add.
Copy and securely store the generated API token. You will not be able to view it again.
You now have the API token required for integration.
Configure Orca Security in SAFE
Navigate to the Integrations page in SAFE and click the Add icon.
Search for Orca Security and select the integration card to open the configuration page.
On the configuration page, provide the following details:
Orca API URL: Enter the base URL for your Orca Security instance.
API Token: Enter the API Key generated in Section 3.
Exclude Asset Types - Optionally specify asset types to exclude from syncing. If left blank, all asset types accessible via the provided credentials will be synced.|
This field allows you to prevent specific asset types from being pulled into SAFE from Orca Security. This is useful if you want to limit the integration to only certain types of assets relevant to your organization’s risk analysis or reporting needs.If needed, uncheck the Update Existing Assets Metadata checkbox.
If checked, asset metadata (such as asset name, etc.) will be updated based on data pulled from Orca Security.
If needed, check the Auto Onboard New Assets checkbox.
By default, any assets in Orca Security not found in SAFE will be onboarded. Uncheck to limit the integration to findings for assets already present in SAFE.
Click the Test Connection button.
Once validated, click the Save button.
Click the Sync Now button to trigger an on-demand sync.
Exclude Asset Types
The Exclude Asset Types feature allows you to prevent specific asset types from being pulled into SAFE from Orca Security. This is useful if you want to limit the integration to only certain types of assets relevant to your organization’s risk analysis or reporting needs.
If you do not specify any asset types to exclude, SAFE will, by default, pull all asset types available to your Orca Security credentials.
Identify Asset Types in Orca Security
Log in to your Orca Security account.
Navigate to the Inventory section from the main menu.
Browse the list of assets displayed on the page.
Click on an asset you are considering for exclusion.
In the asset details pane, click on Additional Details.
Locate the Asset Type field, this value represents the asset type as recognized by Orca Security.
Note down the exact asset type names you wish to exclude.
When configuring the integration in SAFE, enter the names of these asset types in the Exclude Asset Types field, separated by commas.
Example:If you want to exclude “Container” and “GcpGcrImage” asset types, enter: Container, GcpGcrImage.
This approach ensures only the desired asset types are onboarded into SAFE, giving you precise control over your asset inventory and vulnerability management.
View Result
From the Integrations page, click on the Orca Security card.
A page with “Finding View” and “Asset View” will open.
Finding View: Contains all findings pulled from Orca Security.
Asset View: Lists all assets pulled/updated from Orca Security.
Alternatively, navigate to Technology and filter the asset list for Finding source equals Orca Security.
FAQs
Why are there more assets in Orca Security than what is onboarded in SAFE?
SAFE only ingests assets from Orca Security that have a unique global identifier, such as an AWS ARN, GCP Self Link, or Azure ID. Assets in Orca Security that do not have one of these identifiers are not ingested into SAFE and are therefore excluded from your SAFE asset inventory. This ensures that only assets with a verifiable and trackable identity are onboarded into SAFE for accurate risk analysis and reporting.
I have fixed a vulnerability for an asset, however that fix doesn’t reflect in SAFE?
SAFE updates the vulnerability status for your assets during a full sync with Orca Security, which occurs every 7 days. Only during a full sync does SAFE refresh the vulnerability data to reflect the current state in Orca Security, including any vulnerabilities you have fixed. Incremental (auto) syncs, which happen more frequently, only fetch new or updated active vulnerabilities and do not update the status of vulnerabilities that have been fixed. Therefore, you may not see the fix reflected in SAFE until the next full sync.
What permissions are required for the Orca Security API token?
The API token used for integration must have the Viewer role in Orca Security. This role is sufficient to read and retrieve asset and vulnerability data. No Admin or custom role is required unless mandated by your organization’s policy or for token creation.
How does SAFE sync data from Orca Security? What is the difference between Full Sync and Incremental Sync?
SAFE uses two types of synchronisation with Orca Security to ensure your asset and vulnerability data remains up to date:
Full Sync: SAFE performs a comprehensive full sync with Orca Security every 7 days. During a full sync, SAFE fetches all eligible assets and findings from Orca Security, ensuring that your SAFE environment reflects the complete and current state of your Orca Security inventory.
Auto Sync (Incremental Sync): In addition to the scheduled full sync, SAFE also performs automatic incremental syncs based on the auto sync frequency you configure during integration setup. Auto syncs are designed to fetch only the new or updated assets and findings since the last sync, allowing for more frequent updates and minimizing data transfer.
How often does SAFE sync data from Orca Security?
SAFE performs a full sync with Orca Security every 7 days to ensure all assets and findings are comprehensively updated. In addition, SAFE performs automatic incremental syncs based on the configured auto sync frequency, allowing for more frequent updates between full syncs.
Can I trigger a manual sync with Orca Security?
Yes, you can trigger an on-demand sync at any time by clicking the Sync Now button on the Orca Security integration configuration page in SAFE. This will immediately fetch the latest assets and findings from Orca Security.
Why do I see new asset types in SAFE’s Attack Surface field?
With Orca Security integration, new asset types may be introduced based on Orca’s classification.
What happens if I exclude certain asset types during integration?
If you specify asset types to exclude in the integration settings, SAFE will not pull those asset types from Orca Security. Only the asset types not listed in the exclusion field will be onboarded and synced with SAFE. If you do not specify any asset types to exclude, all asset types accessible via your Orca Security credentials will be synced by default.
Will existing asset metadata in SAFE be overwritten during sync?
If the “Update Existing Assets Metadata” option is checked, SAFE will update asset metadata (such as asset name and other details) based on the latest data from Orca Security. If unchecked, existing metadata in SAFE will remain unchanged.
Can I limit the integration to findings for assets already present in SAFE?
Yes. If you uncheck the Auto Onboard New Assets option during configuration, SAFE will only pull findings for assets that are already onboarded in SAFE. New assets from Orca Security will not be automatically added.
What should I do if the integration test connection fails?
If the “Test Connection” step fails, please verify that:
The API token is correct and has the necessary Viewer permissions.
The Orca API URL is accurate.
Network connectivity between SAFE and Orca Security is not blocked by firewalls or other restrictions.
If issues persist, consult your network administrator or refer to SAFE support documentation.