Appearance
Integrations
Where to find it: Administration, then Integrations (/settings/integrations).
In OrviQ, integration capabilities are divided across distinct functional domains, each governed by dedicated tenant entitlements and permission scopes. The /settings/integrations screen administers API keys for inbound programmatic access and outbound webhooks for event delivery under the api_access entitlement.
It is architecturally distinct from operational ingestion engines such as Security Tool Integrations, Cloud & Identity Discovery, and the Integration Catalogue.
Integration Architecture & Domains
OrviQ separates administrative automation interfaces from technical telemetry ingestion and catalogue directories:
| Domain | Application Route | Entitlement Key | Primary Mechanism | Governing Permissions |
|---|---|---|---|---|
| API & Webhook Administration | /settings/integrations | api_access | Inbound REST API keys; outbound event webhooks | api.manage, webhook.manage (human session only) |
| Security Tool Integrations | /integrations/security-tools | integrations_security_tools | Direct adapters (Tenable SC, Nessus, Nipper, Qualys) ingesting vulnerability & config findings | integration.read, integration.manage, integration.import, integration.confirm |
| Cloud & Identity Discovery | /integrations/discovery | cloud_discovery | Discovery connectors (Entra ID, Azure, AWS, Prowler) ingesting assets, users, and posture | discovery.read, discovery.manage |
| Integration Catalogue | /integrations/catalogue | integrations_catalogue | Read-only directory disclosing status and adapter types for 22 catalogued integrations (20 available, 2 planned: Splunk and Microsoft Sentinel) | integration.read |
Key boundaries
- Administration (
/settings/integrations): Focuses exclusively on platform interoperability: granting external systems programmatic API access to OrviQ resources, or delivering OrviQ system events out to SIEM, ITSM, or webhook receivers. - Security Tool Integrations (
/integrations/security-tools): High-impact operational scanner ingestion engine. Ingests findings through automated adapter synchronization or governed manual report imports (.nessus, Tenable CSV, Nipper XML). Governed by strict maker-checker segregation of duties: an importer cannot confirm their own report import. Ships dark whenintegrations_security_toolsis disabled. - Cloud & Identity Discovery (
/integrations/discovery): Automated discovery pipelines that reconcile cloud infrastructure and enterprise directory accounts into tenant asset scopes. Ships dark whencloud_discoveryis disabled. - Integration Catalogue (
/integrations/catalogue): A read-only directory providing transparent disclosure of 22 catalogued integrations (20 available, 2 planned: Splunk and Microsoft Sentinel), connection methods, and lifecycle status (available,beta,planned) without configuring live credentials.
Semantic Doctrine
Semantic Doctrine: Integrations & Compliance
Enterprise governance in OrviQ enforces strict semantic boundaries between technical integration and regulatory status:
- Integration connection does not equal compliance: Successfully connecting an API key, cloud connector, or vulnerability scanner proves technical telemetry flow; it does not satisfy an obligation, establish policy adherence, or certify compliance with any regulatory standard.
- Scanner findings do not equal confirmed control failures: Ingested vulnerabilities or configuration deviations are raw technical observations. They require triage, risk contextualization, and review before they represent governed audit findings or control deficiencies.
- Evidence collection does not equal operating effectiveness: Automated evidence ingestion (via push API, collector, or scanner) delivers point-in-time observation records. Control effectiveness requires testing, threshold evaluation, and authoritative assessment by designated control owners and assessors.
API keys
An API key authenticates an external programmatic caller as a service principal within your tenant.
| Property | Behaviour |
|---|---|
| Token display | Shown once, at creation |
| Scopes | Narrow access; they never widen it |
| Rotation | Supported without losing the key's identity or audit trail |
| Revocation | Immediate across all active sessions |
Scopes only narrow
A key's scopes can only reduce what it can do
Scopes are a restriction applied on top of whatever access the key would otherwise inherit. They never grant access.
A key scoped to evidence submission cannot approve a policy or change disposition, whatever else is configured — and there is no scope value that would allow it to bypass governance checks.
The API key deny-list
Certain administrative actions can never be performed by an API key, regardless of assigned scope:
| Action | Permission | Rationale |
|---|---|---|
| Minting, rotating and revoking API keys | api.manage | Prevents a compromised key from creating persistent descendant keys |
| Creating and managing webhooks | webhook.manage | Prevents a compromised key from creating exfiltration channels |
These are human-session actions only. A key cannot mint another key, and a key cannot create the webhook that would exfiltrate what it reads.
Why this specific deny-list
A key that can mint keys is a key that survives its own revocation. A key that can create webhooks is a key that can establish a persistent outbound channel.
Both are standard escalation paths from a leaked credential, and both are closed in OrviQ by requiring an interactive, MFA-authenticated human session.
Webhooks
Webhooks deliver real-time platform events from OrviQ to an external HTTPS endpoint (such as an enterprise SIEM, SOAR, or ITSM tool).
| Concept | Meaning |
|---|---|
| Endpoint | Target URL where HTTPS POST payloads are delivered |
| Delivery | One individual delivery attempt, including response code and latency |
| Monitoring | Immutable audit log of delivery status, payload hashes, and retry history |
Endpoints can be created, disabled, secret-rotated, and monitored. Configuring webhooks requires webhook.manage within an active human session.
Evidence push
Separately from general tenant API access, external systems can submit evidence assertions directly through an authenticated push API or webhook gateway.
Requires evidence_push.submit and the Continuous Assurance (continuous_assurance) entitlement. See Evidence Assertions.
This mechanism allows CI/CD pipelines, container registries, or custom monitoring scripts to push structured observation records directly into OrviQ controls without deploying an outbound collector.
Choosing between a collector and a push
| Dimension | Collector | Push |
|---|---|---|
| Direction | OrviQ reads the source (inbound pull) | The source writes to OrviQ (outbound push) |
| Configured in | OrviQ | The source system |
| Scheduling | OrviQ's scheduled cadence | The source system's event timing |
| Best for | Systems with a queryable API (IdP, Cloud) | Systems that emit event streams (CI/CD, ITSM) |
| Requires | An evidence connection | An API key with evidence_push.submit |
Collectors are generally easier to govern because the connection definition, scheduled frequency, and observation mapping live entirely in OrviQ where they are visible to auditors.
Integration security
- Use a dedicated key per integration: A shared key cannot be revoked or rotated without disrupting multiple services.
- Apply least-privilege scoping: An unscoped key carries full tenant API privileges. Always restrict keys to the exact endpoints required.
- Rotate on a strict cadence: Rotation generates a new token while preserving the key's identifier, audit history, and configuration.
- Monitor webhook deliveries: A webhook failing silently is an observability gap. Monitor failure logs and implement endpoint alerts.
- Never store credentials in metadata: Never place API secrets, tokens, or passwords into connection names or description fields. See Secret Handling Principles.
Permissions & Entitlements
| Integration Area | Permission Key | Required Entitlement | Human Session Required? |
|---|---|---|---|
| Mint, rotate, and revoke API keys | api.manage | api_access | Yes |
| Create, update, and delete webhooks | webhook.manage | api_access | Yes |
| Submit evidence assertions via push API | evidence_push.submit | continuous_assurance | No (API key allowed) |
| View scanner integrations & findings | integration.read | integrations_security_tools | No |
| Configure scanner sync & connections | integration.manage | integrations_security_tools | Yes |
| Upload scanner report files | integration.import | integrations_security_tools | Yes |
| Confirm previewed scanner report import | integration.confirm | integrations_security_tools | Yes (Maker-Checker SoD) |
| View discovered cloud & identity assets | discovery.read | cloud_discovery | No |
| Configure cloud discovery pipelines | discovery.manage | cloud_discovery | Yes |
| View Integration Catalogue | integration.read | integrations_catalogue | No |
Example: A Bank's Integration Ecosystem
| Integration | Domain / Mechanism | Scope / Purpose |
|---|---|---|
| Identity Governance | Collector via Connection | Read-only polling of MFA status, privileged role assignments |
| Endpoint Security | Collector via Connection | Read-only polling of disk encryption and agent health |
| Vulnerability Scanner | Security Tool Integration (Tenable) | Scheduled ingestion of host vulnerabilities into Findings Inventory |
| Network Security Posture | Security Tool Integration (Nipper) | Governed XML import of firewall and router configuration audits |
| Cloud Infrastructure | Cloud Discovery (Azure / AWS) | Automated discovery of subscriptions, VMs, and S3/Storage buckets |
| Change Management | Push API (/settings/integrations) | CI/CD pipeline pushes deployment change record upon release |
| Enterprise ITSM | Webhook (/settings/integrations) | Dispatches real-time finding notifications to IT Service Desk |
Troubleshooting
"An API key stopped working."
Verify if the key was revoked, expired, or if its token was rotated without updating the calling system. Ensure the assigned scopes cover the specific API endpoint.
"An API key cannot create or modify a webhook."
This is expected behavior. Under the API key deny-list, webhook.manage is strictly reserved for authenticated human sessions to prevent exfiltration channel creation.
"I lost an API token."
API tokens are displayed exactly once at creation. If lost, perform a key rotation to generate a new active token.
"Webhook deliveries are failing."
Inspect the delivery log at /settings/integrations for the HTTP status code and response body. Ensure the receiving endpoint is publicly reachable and responds with an HTTP 2xx code within the timeout window.
"Integrations menu item is missing or locked."
/settings/integrationsrequires theapi_accessentitlement./integrations/security-toolsrequires theintegrations_security_toolsentitlement and ships dark (hidden) when unentitled./integrations/discoveryrequires thecloud_discoveryentitlement and ships dark (hidden) when unentitled./integrations/cataloguerequires theintegrations_catalogueentitlement.