Skip to content

Feature Spec - Discovery & Onboarding (v0.2)

Date: 2026-02-06

Summary

Enable a Director of IAM to connect AWS, Azure, and CyberArk Identity, run discovery, and obtain <5-minute insight through an Access Explorer visualization grounded in normalized entities, relationships, and provenance.

Persona

Director of IAM

Scope

In scope: - Integrations: AWS, Azure, CyberArk Identity - Connector Type: Discovery - Connections: create/test/run/schedule - Discovery runs: status/history/partial failures - Normalization: canonical entities + relationships + provenance - Visualization: Access Explorer (principal-centric + resource-centric)

Out of scope (v0): - Credentials as first-class entities (v1) - Control/JIT/Rotation/Session connector types (future) - Marketplace/public connector store (future)

Design Principles & Constraints

  • Connector boundary = extensibility boundary
  • API-first
  • Tenant-isolated data planes with workspace-scoped access
  • RBAC: Admin, Connector Builder, Viewer/Auditor
  • Auditability for connector lifecycle and runs
  • Microservices orientation (independent services adhere to contracts)

Tenancy & Isolation Requirements

  • All connection, run, and result records are scoped by tenant_id and workspace_id.
  • Discovery and visualization endpoints must derive scope from authenticated context.
  • Cross-tenant data access is out of scope for v0 product flows.
  • Cross-workspace reads are not supported in v0 except explicit audited admin operations.
  • Audit events must include tenant/workspace scope for each action.

Canonical Model

See: - 04-contracts/canonical-model.md - 06-decisions/0001-canonical-entities-and-relationships.md - 06-decisions/0004-discovery-execution-architecture.md

Terminology

See: - 02-domain/glossary.md - 06-decisions/0002-integration-vs-connector-terminology.md

User Journeys

Happy path (single system)

  1. User opens Integrations catalog
  2. Selects AWS (Discovery)
  3. Creates a Connection (credentials + scope)
  4. Tests Connection (actionable success/fail)
  5. Runs discovery
  6. Sees Results Overview + Access Explorer
  7. Drills into an access path with provenance

Expand to multi-system

  1. Adds Azure connection
  2. Adds CyberArk Identity connection
  3. Re-runs discovery
  4. Identity mapping confidence improves; Access Explorer shows richer paths

Failure paths (must support)

  • Insufficient permissions: show what's missing and how to fix
  • Partial run: show partial results + what failed
  • Empty result: clear message + suggestions
  • Throttling/rate limits: show retry behavior and schedule guidance

Functional Requirements

Integrations & Connections

MUST: - List integrations (AWS/Azure/CyberArk Identity) - Create/edit/delete connection - Securely store connection secrets (never re-display) - Test connection with actionable remediation - Run discovery now - Schedule discovery daily/weekly - View connection status + last run + run history

SHOULD: - Scope selection (AWS accounts / Azure subscriptions / Identity tenants) - Permissions checklist per integration

Discovery Runs

MUST: - statuses: queued/running/succeeded/partial/failed - store run summary (counts/duration/errors) - emit normalized entities + relationships + provenance - identity resolution best-effort where deterministic joins exist - execute runs asynchronously via a queue-backed worker plane (no secrets in queue)

SHOULD: - confidence scoring for mappings - show partial results and errors clearly

Visualization (Moment of Value)

MUST: - Results Overview with high-signal summary cards - Access Explorer: - resource-centric: "Who has access to this?" - principal-centric: "What access does this principal have?" - Drilldown shows access paths and provenance per hop - Filters: system, cloud boundary, orphaned accounts

SHOULD: - Export entities/relationships (CSV/JSON) - "Explain this path" panel

UX Requirements

Screens (v0)

  • Workspace Selector
  • Integrations Catalog
  • Connection Setup Wizard
  • Connection Detail (status/test/run/schedule)
  • Discovery Runs History
  • Results Overview
  • Access Explorer

States

  • No connections
  • No runs
  • Running/Queued
  • Partial/Failed
  • Empty discovery
  • Permission errors

Audit Narrative

Audit events: - connection created/edited/deleted - test attempted (success/fail + reason) - run started/completed/partial/failed - export generated

Acceptance Criteria (examples)

  • Viewer cannot edit secrets
  • Test connection returns specific remediation guidance
  • Run outputs comply with canonical contract and include provenance
  • Access Explorer supports both modes and shows path drilldown

Telemetry

Funnel: catalog -> create connection -> test -> run -> results -> drilldown Events: connection_created, connection_tested, discovery_run_completed, explorer_opened, path_drilled, export_generated

Audit Platform (Foundational)

See 05-specs/slices/slice-000-audit-platform.md and ADR 0005 for centralized audit ingestion, action inventory, and SIEM streaming.

Open Questions

  • identity resolution rules across the three systems
  • v0 admin-like entitlement heuristics per provider
  • retention policy for run history and evidence references