SentriScope Connector Architecture

Governed connector ingestion lifecycle, idempotency model, supported integrations, trust tiers, and control effectiveness strategy.

Engineer · Intermediate · Architecture · 5 min read · Last updated: Jul 13, 2026 · Version 2.0

1. Overview

The connector architecture provides governed, idempotent, tenant-safe ingestion from all external security data sources. No ingestion may bypass canonical boundaries. Every connector follows the same lifecycle, validation, and audit pattern.

2. ConnectorSession Lifecycle

The CanonicalConnectorSession model manages connector state:

Field	Description
`id`	UUID primary key
`tenant`	FK to Tenant (always scoped)
`name`	Human-readable session name
`connector_type`	FK to `ConnectorType` registry
`connector_config`	JSON: api_base_url, sync_strategy, rate_limit_config
`credential secret reference`	Pointer to Secrets Manager — never plaintext
`health_status`	`Healthy`, `Degraded`, `Failed`
`last_sync_status`	`Success`, `Failed`, `Running`
`last_sync_at`	Timestamp of last successful sync
`last_error_message`	Sanitized error (no credentials, no raw tokens)
`is_enabled`	Boolean — disabled sessions do not run
`created_by`	FK to User (nullable for system-created)

3. Ingestion Flow

Every connector follows this pattern:

1. run_connector_with_tenant(session, fn)
   ├── Set tenant context from session
   ├── Open transaction
   ├── assert_tenant_context_set()
   └── fn()  (connector logic)
       │
2. validate_external_payload(payload, ...)
   ├── external_id required
   ├── source_system required
   ├── No tenant_id from payload (tenant from context only)
   ├── Reject if tenant context not set
   └── Severity normalization enforced when required
       │
3. upsert_by_external_id(model, ...)
   ├── Unique key: (tenant_id, source_system, external_id)
   ├── No overwrite of immutable fields (id, canonical_id, tenant_id, created_at)
   └── Audit: DATA_CREATED or DATA_UPDATED with connector_type, external_id

4. create_risk_snapshot(tenant, profile)  [after successful ingestion]

4. Canonical Write Constraints

All canonical writes must:

Constraint	Rule
`tenant_id` source	From execution context only — never from payload
`source_system`	Required — identifies the connector
`external_id`	Required — deduplication key per source
`source_updated_at`	Required — provenance timestamp
`severity_normalized`	Required for exposures/findings
Tenant context	Reject if `get_current_tenant()` is None

5. Idempotency Model

Idempotency prevents duplicate creation and enables safe re-sync:

Key: (tenant_id, source_system, external_id)
Behavior: get_or_create with that key; on match, update non-immutable fields only
Immutable fields: id, canonical_id, tenant_id, created_at — never overwritten
Same ingestion twice: produces identical content_hash (determinism guarantee)

6. Error Handling Model

Error Type	Behavior
Execution failure	Update session: `last_error_message` (sanitized), `last_sync_status=Failed`, `health_status=Degraded`; log warning; re-raise
Validation failure	`IngestionGuardrailError` raised; no write proceeds
Audit	`DATA_CREATED`/`DATA_UPDATED` with connector_type, external_id, canonical_id — no credentials

7. Supported Connectors

CMDB Connectors

Connector	Slug	Models Fed
ServiceNow CMDB	`SERVICENOW_CMDB`	`CanonicalAsset`, `CanonicalApplication`, `CanonicalAssetRelationship`
Jira Service Management Assets	`JSM_ASSETS_CMDB`	`CanonicalAsset`, `CanonicalApplication`, `CanonicalAssetRelationship`

Vulnerability Scanners

Connector	Slug	Models Fed
Tenable Vulnerability Scan	`TENABLE_VULNERABILITY`	`CanonicalAsset`, `CanonicalExposure`, `CanonicalVulnerability`
Qualys VMDR	`QUALYS_VM`	`CanonicalAsset`, `CanonicalExposure`, `CanonicalVulnerability`

EDR / Endpoint Security

Connector	Slug	Models Fed
Microsoft Defender for Endpoint	`MICROSOFT_DEFENDER_ENDPOINT`	`CanonicalAsset`, `CanonicalExposure`, `CanonicalIncident`
SentinelOne Singularity	`SENTINELONE_SINGULARITY`	`CanonicalAsset`, `CanonicalIncident`
CrowdStrike Falcon	`CROWDSTRIKE_FALCON`	`CanonicalAsset`, `CanonicalIncident`
Palo Alto Cortex XDR	`PALOALTO_CORTEX_XDR`	`CanonicalAsset`, `CanonicalIncident`
Trellix ENS / ePO	`TRELLIX_ENS`	`CanonicalAsset`, `CanonicalIncident`

Network / OT / Cloud

Connector	Slug	Models Fed
Akamai Guardicore Segmentation	`AKAMAI_GUARDICORE`	`CanonicalAsset`, `CanonicalAssetNetworkFlow`, `CanonicalSegmentationPolicy`
Nozomi Vantage	`NOZOMI_VANTAGE`	`CanonicalAsset` (OT assets)
Palo Alto Cortex Cloud (Prisma)	`PALOALTO_CORTEX_CLOUD`	`CanonicalAsset`, `CanonicalExposure`, `CanonicalVulnerability`

Identity

Connector	Slug	Models Fed
Microsoft Entra ID	`ENTRA_ID`	`CanonicalIdentity`, `CanonicalIdentityCredential`, `CanonicalIdentityAuthEvent`

Security Ratings and DRP

Connector	Slug	Models Fed
SecurityScorecard	`SECURITY_SCORECARD`	`CanonicalAsset`, `CanonicalExposure`
Tempest Prospero DRP	`TEMPEST_PROSPERO_DRP`	`CanonicalExposure`, `CanonicalAsset`, `CanonicalIdentity`, `CanonicalCredentialLeak`

8. Connector Trust Levels

Trust Tier	Auth Method	Payload Validation
Tier 1	API key / OAuth2	Standard guardrails
Tier 2	OAuth2 + token refresh	Standard guardrails + replay protection
Tier 3	Webhook (push)	Full payload signature verification + timestamp check + nonce

All connectors enforce rate limits per tenant. Retry strategy: MAX_RETRIES=5, exponential backoff + jitter, cap 120s. No retry on 401/403.

9. Sync Modes

Mode	Description
`FULL`	Fetch all records from source (default)
`SINCE_LAST_SYNC`	Fetch only records updated since `session.last_sync_at`

last_sync_at is updated only on successful run. Partial or failed runs do not advance the watermark.

10. Severity Normalization in Connectors

All connectors must use:

normalize_severity(
    value,
    source_system="CONNECTOR_SLUG",
    source_scale=SOURCE_SCALE_0_10 | SOURCE_SCALE_0_100
)

source_scale must be explicit — inference is forbidden. Categorical severity (critical/high/medium/low/info) is mapped to numeric before normalization.

11. Control Effectiveness Strategy

Security controls are assessed against assets using SecurityCoverage:

Control coverage: Which controls are deployed on which assets/segments
Effectiveness score: 0–100 based on deployment quality, configuration, and gap analysis
Risk influence: Coverage effectiveness reduces residual_risk_score in RiskSnapshotItem

Coverage Quality	Effectiveness Score	Risk Reduction
Full, well-configured	80–100	High reduction
Partial or degraded	40–79	Medium reduction
Missing or failed	0–39	No reduction

Control effectiveness feeds the risk scoring engine after canonical ingestion.

12. Run ID and Traceability

Every connector run generates a run_id (UUID):
- Included in all audit events for this run
- Stored in session.connector_config["last_run_id"]
- Returned in API response for correlation
- Audit metadata: run_id, connector_type, session_id, asset_count, exposure_count, duration_ms

SentriScope Intelligence Architecture

Tags Connectors · Idempotency · Ingestion · Integrations