Skip to content
VB-OSVB-OSVB-OS Docs

VB-OS Connectors: Evidence Acquisition Overview

Connectors bridge external systems and VB-OS boundaries. They acquire evidence from data sources, transform it into the format boundaries expect, and attach provenance metadata that records where each piece of evidence came from.

How Connectors Work

Section titled “How Connectors Work”
  1. Connect: configure a connector with credentials for an external system
  2. Map: define how source fields map to boundary evidence fields
  3. Gather: the connector queries the source and produces evidence
  4. Evaluate: the gathered evidence is submitted to a boundary for evaluation

Acquisition Classes

Section titled “Acquisition Classes”

Every piece of evidence has an acquisition class that describes how it entered VB-OS:

Class Description
active_provider The connector actively queried the external system
authenticated_provider_push The external system pushed data via a verified webhook
caller_supplied_payload The caller submitted evidence directly in the API request

Acquisition class is part of provenance: boundaries can require specific acquisition classes through provenance declarations.

Provider Categories

Section titled “Provider Categories”

VB-OS includes a registry of providers across domains:

  • Databases: PostgreSQL, MySQL, and other SQL databases
  • Payment: Stripe, payment processors
  • Identity: identity verification providers
  • AI/ML: AI inference and model deployment providers
  • DevOps: CI/CD, monitoring, deployment tools
  • Healthcare: FHIR-compatible health systems
  • Compliance: regulatory and compliance data sources
  • And more: security, analytics, CRM, ERP, cloud infrastructure

Each provider defines its authentication modes, evidence fields, and capabilities.

Authentication Modes

Section titled “Authentication Modes”

Connectors support multiple authentication patterns:

Mode Description
CREDENTIAL API keys, connection strings, or tokens stored encrypted
OAUTH_USER_CONSENT OAuth 2.0 authorization code flow with platform-managed tokens
NONE No authentication required (public endpoints)

Credentials are encrypted at rest. OAuth tokens are managed by the platform with automatic refresh.

Evidence Mapping

Section titled “Evidence Mapping”

Evidence mappings define how connector source data maps to boundary evidence fields:

  • evidence_field: the target field name in the boundary
  • source_path: dot-notation path into the provider’s response (e.g., data.status)
  • transform: optional transformation applied during mapping

Transforms

Section titled “Transforms”
Transform Description
identity Pass through unchanged
to_string Convert to string
to_integer Convert to integer
to_boolean Convert to boolean
categorical_map Map string categories to integers using a lookup table
to_timestamp Convert to a Unix timestamp
jsonpath Extract value using JSONPath
json_parse Parse a JSON string into a structured value

The categorical_map transform is particularly useful because VBL is integer-only. It maps string values (like "succeeded", "failed") to integers (like 1, 0). If a value does not match the mapping, the gather fails closed: no evidence is produced.

Webhook Ingestion

Section titled “Webhook Ingestion”

Connectors can receive evidence via inbound webhooks. Each webhook connector verifies the signature of incoming payloads using the provider’s signing method:

Method Description
STRIPE_V1 Stripe webhook signature verification
GITHUB_HMAC_SHA256 GitHub HMAC-SHA256 webhook signatures
VBOS_HMAC_SHA256 Platform HMAC for providers without a signing scheme

Verified webhooks produce evidence with authenticated_provider_push acquisition class.

Auto-Evaluate

Section titled “Auto-Evaluate”

Connectors can be configured to automatically evaluate gathered evidence against a boundary. When auto-evaluate is enabled, a successful gather immediately triggers an evaluation: no separate API call needed.

Next Steps

Section titled “Next Steps”