Contract: Connector Specification (v0)

Connector (Packaged Module)

A Connector is a versioned package that implements one or more Connector Types.

Required metadata: - connector_id - name - version - connector_type: discovery (v0) - provider_system: aws|azure|cyberark_identity - required_permissions (human-readable) - emits_entities (subset of Principal/Account/Entitlement/Resource/CloudAccountBoundary) - emits_relationships (subset of relationship types) - limits/blind_spots (notes)

Connector Interface (Discovery SDK)

Discovery connectors implement a simple interface with: - testConnection(context, inputs) -> success/failure + remediation - run(context, inputs) -> discovery output

Inputs: - context: run_id, connection_id, tenant_id, workspace_id, started_at - inputs: configuration (secrets/credentials), scope (accounts/subscriptions), both opaque to core

Run output formats: - Full result: entities + relationships + counts + errors - Streaming: async generator yielding batches of entities/relationships; generator return value is a summary with final status, counts, and errors

Connection (Configured Instance)

A tenant/workspace configured instance of a Connector.

Required attributes: - connection_id - tenant_id / workspace_id - connector_id + version - configuration (secure) - scope (e.g., accounts/subscriptions) - schedule (optional) - status/health

Discovery Run Semantics

A run produces: - run_id - started_at / ended_at - status: queued|running|succeeded|partial|failed - counts: entities + relationships - errors: list of {category, message, remediation} - normalized outputs complying with 04-contracts/canonical-model.md

Directionality Rule

Discovery connectors submit facts (entities + relationships + provenance). They do not directly mutate core canonical objects without normalization safeguards.