Skip to content
VB-OSVB-OSVB-OS Docs

Connectors in VB-OS

Connectors bridge external data sources and VB-OS boundaries. They acquire evidence from systems outside VB-OS and deliver it to the evaluation pipeline with provenance metadata.

How Connectors Work

Section titled “How Connectors Work”

Instead of your application gathering all evidence and submitting it in one API call, connectors let VB-OS acquire evidence directly from the source:

┌──────────────┐     ┌────────────────┐     ┌──────────────┐
│  Your App    │────▶│  VB-OS Cloud   │────▶│  External    │
│              │     │  (Connector)   │◀────│  System      │
│  workload={  │     │                │     │  (Database,  │
│   user_id:1  │     │  Evidence      │     │   API, IdP)  │
│  }           │     │  acquired +    │     └──────────────┘
└──────────────┘     │  mapped to     │
                     │  boundary      │
                     │  fields        │
                     └────────────────┘

Your application submits a minimal workload (e.g., a user ID). The connector fetches the remaining evidence (e.g., account balance, risk score) from the configured source and maps it to boundary fields.

Connector Components

Section titled “Connector Components”

Provider

Section titled “Provider”

The integration type: what kind of system the connector talks to. Providers include database connectors, REST API connectors, and identity provider connectors.

Configuration

Section titled “Configuration”

Connection details for the external system: endpoints, credentials (encrypted at rest), timeouts, retry policies.

Field Mapping

Section titled “Field Mapping”

Maps the external system’s response fields to boundary evidence fields. Each mapping declares:

  • source_path: the field path in the external system’s response
  • evidence_field: the boundary evidence field it maps to

Security

Section titled “Security”

Connector credentials are encrypted at rest. The platform sanitizes connector configurations to prevent credential leakage in logs, error messages, and API responses. OAuth-based connectors support token refresh and rotation.

Evidence Provenance

Section titled “Evidence Provenance”

When a connector acquires evidence, it attaches evaluation-level provenance metadata (a single acquisition_provenance dictionary) recording:

  • The acquisition_class: classification of how evidence was acquired
  • The connector_id: which connector instance provided the evidence
  • The acquired_at: timestamp of evidence acquisition

Boundaries can require specific provenance:

require_provenance: risk_score: internal_risk_engine

This ensures the risk_score field came from the declared source, not from direct submission or a different connector.

Auto-Evaluation

Section titled “Auto-Evaluation”

Connectors can trigger automatic evaluation when evidence changes in the source system. The connector polls or receives webhooks from the external system, acquires updated evidence, and submits it for evaluation. This enables continuous verification without your application initiating each check.

Next Steps

Section titled “Next Steps”