Shielda Enterprise Onboarding Guide
This document explains how to onboard an enterprise customer onto Shielda's enterprise-grade features: air-gapped deployment, FedRAMP boundary enforcement, advanced RBAC, Bring-You...
This document explains how to onboard an enterprise customer onto Shielda's enterprise-grade features: air-gapped deployment, FedRAMP boundary enforcement, advanced RBAC, Bring-Your-Own-Key (BYOK), customer-managed keys (CMK), external audit-log streaming, and dedicated single-tenant infrastructure.
Every feature below is backed by a pure-core library under control-plane/src/lib/ with full unit coverage, plus pluggable adapter modules for real cloud integrations.
---
Deployment models
Model When to pick it Module Shared SaaS Commercial customers, no compliance constraints default control-plane Single-tenant dedicated FedRAMP Moderate, IL4, PCI-DSS, HIPAA, or customer demand infra/modules/single-tenant/ Air-gapped on-prem Classified networks, no outbound connectivity airgap bundle manifest
---
FedRAMP / sovereignty boundary selection
Every tenant is assigned a boundary at onboarding — this determines which AWS regions they may store data in and which data classifications are permitted.
const decision = canStore({ boundary: 'fedramp-moderate', region: 'us-gov-west-1', classification: 'cui', }); // → { ok: true }
Available boundaries:
Boundary Allowed regions Max classification commercial any gdpr fedramp-moderate us-gov- cui il4 us-gov- classified eu-sovereign eu- phi, gdpr
Writes that violate the boundary throw BoundaryViolationError → HTTP 451 (Unavailable For Legal Reasons).
---
Advanced RBAC & approval chains
Custom roles with wildcard () grants, row-level tag constraints UNION'd across roles, and ordered multi-approver chains for sensitive actions.
const result = checkAccess({ principal: { id: 'alice', roles: ['security-engineer'] }, permission: 'findings:read', resource: { tags: { severity: 'high' } }, });
Approval chains enforce: ordered required roles (each slot = one approver) requester self-exclusion (you cannot approve your own request) requireDistinctApprovers prevents one principal filling two slots
---
BYOK / CMK envelope
Customers bring their own KMS key; the platform wraps a per-record DEK via KMS.Encrypt and never sees the CMK.
Provision (AWS example)
Customer creates a symmetric CMK in their AWS account. Customer grants shielda-kms-access IAM role kms:Encrypt, kms:Decrypt, kms:DescribeKey on that CMK. Operator registers the CMK ARN in the tenant settings — this instantiates an AwsKmsProvider:
const client = new KMSClient({ region }); const transport = { encrypt: (i) = client.send(new EncryptCommand(i)).then((o) = ({ CiphertextBlob: o.CiphertextBlob, KeyId: o.KeyId, })), decrypt: (i) = client.send(new DecryptCommand(i)).then((o) = ({ Plaintext: o.Plaintext, KeyId: o.KeyId, })), };
const provider = new AwsKmsProvider({ cmkArn: 'arn:aws:kms:eu-west-1:123:key/abc', transport, encryptionContext: { tenantId, purpose: 'shielda-dek' }, });
Rotation
Call provider.rotate() at your cadence (AWS KMS annual rotation is auto-applied at the CMK level; the envelope key-version byte is bumped manually for re-wrap campaigns). Existing envelopes with older keyVersion remain decryptable.
Envelope wire format (v1)
---
Audit-log streaming
Every audit event is fanned out to zero or more customer-owned sinks via AuditStreamer. Sinks retry independently with per-sink high-water cursors; buffer trims only to the slowest sink (at-least-once).
Splunk HEC
new SplunkHecSink({ url: 'https://splunk.customer.com:8088', token: process.env.SPLUNKHECTOKEN!, index: 'shielda', sourcetype: 'shielda:audit', });
S3 (Athena / Glue friendly)
const s3 = new S3Client({ region }); new S3NdjsonSink({ bucket: 'shielda-acme-audit', prefix: 'audit', transport: { putObject: async (i) = { await s3.send(new PutObjectCommand(i)); } }, serverSideEncryption: 'aws:kms', });
Key layout: audit/YYYY/MM/DD/HH/{ms}-{seqStart}-{seqEnd}.ndjson.
CloudWatch Logs
OTLP (any OpenTelemetry collector)
new OtlpSink({ url: 'https://otel.customer.com:4318/v1/logs', headers: { 'X-API-Key': process.env.OTLPKEY! }, resource: { 'service.name': 'shielda-control-plane' }, });
---