Skip to main content

AWS Integration — Full Implementation Cycle Plan

Why this plan exists​

We already have solid AWS research, but it is split across multiple docs and PRs:

  • PR #56 — AWS connector coverage research
  • PR #127 — AWS integration comprehensive research and plan
  • PR #129 — AWS competitive analysis enrichment

Those docs are good enough to start implementation, but they do not yet give us one execution plan that ties together:

  1. connector delivery in sv0-connectors
  2. platform/data-model work in sv0-platform
  3. architecture + setup docs in sv0-documentation
  4. demo-lab/customer onboarding implications

This document is the execution bridge.

Source docs reviewed​

Existing implementation-relevant research​

Existing decisions already made​

Recent PRs this plan builds on​

  • PR #56 — research: AWS connector coverage — identity graph, ECR chain, authority paths
  • PR #127 — docs: AWS integration comprehensive research and plan
  • PR #129 — docs: enrich AWS competitive analysis with Veza platform architecture

What the research already tells us​

Main product call​

SecurityV0 should treat AWS primarily as a workload identity + authority path system, not as a generic CSPM inventory project.

That means the first shipped AWS wedge should optimize for:

  • runtime identities
  • cross-account trust
  • execution evidence
  • sensitive data reachability
  • cross-system story (GitHub / ServiceNow / Entra / Bedrock)

Main architecture call​

The best baseline pattern is:

  • AWS Organizations-aware by default
  • delegated admin / security account for centralized reads where possible
  • spoke read-only roles only where central services are insufficient
  • CloudTrail as execution evidence source
  • Config Aggregator / Organizations / Identity Center / Access Analyzer / Security Hub as high-leverage central control planes

Main competitive call​

The competitive research is pretty clear:

  • most vendors use the same multi-account trust pattern
  • our differentiator is execution-centric graphing, not generic AWS inventory
  • we should copy the good boring parts (cross-account onboarding, centralized readers, org trail ingestion)
  • we should avoid boiling the ocean in v1

Recommendation​

Do not start with a new round of AWS research.

The existing research is sufficient to move into implementation planning and phased execution.

What we need now is:

  1. one agreed implementation sequence
  2. explicit repo-by-repo deliverables
  3. a Phase 1 scope cut that is small enough to ship
  4. a follow-on sequence for Bedrock, containers, and richer cross-system paths

Automation requirement: no clickops​

AWS work for SecurityV0 must be 100% automation-first.

That means:

  • no AWS console-driven setup as the intended primary path
  • customer onboarding must be reproducible via Terraform and/or CloudFormation / StackSets
  • demo-lab environments must be reproducible via code
  • validation and teardown must also be scripted
  • any unavoidable manual bootstrap step must be treated as an exception, minimized, and documented explicitly

Applies to all AWS workstreams​

This requirement applies to:

  • customer onboarding
  • org-mode deployment
  • selected-account deployment
  • single-account deployment
  • demo environment provisioning
  • seeded-risk / demo scenario creation
  • teardown / cleanup

Required deliverables for implementation​

Any AWS implementation PR series should include, where applicable:

  • CloudFormation / StackSets templates for org-mode rollout
  • Terraform modules or equivalent IaC for reusable deployment patterns
  • scripted demo environment creation
  • scripted teardown
  • parameterized configuration for tenant/customer-specific values

Console verification can exist as a troubleshooting or audit aid, but console-click setup is not an acceptable primary workflow.

Phase 1 — Ship the first real AWS wedge​

Goal​

Make AWS appear in SecurityV0 as a first-class source of:

  • workload identities
  • cross-account trust chains
  • sensitive resource reachability
  • execution evidence

Phase 1 scope​

Connector scope (sv0-connectors)​

Ship one AWS connector package that supports:

  • Organizations account discovery
  • per-account role assumption
  • IAM roles
  • IAM managed + inline policies
  • Lambda
  • Step Functions
  • EventBridge rules
  • Bedrock agents / aliases / action groups / knowledge bases / flows
  • Secrets Manager
  • SSM Parameter Store / SecureString
  • S3 buckets
  • DynamoDB tables
  • CloudTrail evidence ingestion for core identity events
  • minimal Access Analyzer ingestion

Platform scope (sv0-platform)​

Ship the minimum platform changes required to materialize AWS paths correctly:

  • add permission_set support per ADR-014
  • support AWS account-scoped source_system semantics per ADR-015
  • materializer traversal for:
    • HAS_PERMISSION_SET
    • RUNS_AS
    • ASSUMES
    • TRIGGERED_BY
  • authority path explanation support for AWS caveat: conditions not evaluated
  • entity/finding UI support for AWS badges and account context

Documentation scope (sv0-documentation)​

Ship customer/operator docs for:

  • AWS onboarding modes (single account / selected accounts / org mode)
  • required IAM role templates
  • ExternalId setup
  • security-account / delegated-admin architecture
  • caveats: conditions not evaluated, Config delay, CloudTrail coverage limits
  • explicit automation-first setup guidance covering Terraform and/or CloudFormation / StackSets as the required primary path

Explicit non-goals for Phase 1​

Do not block Phase 1 on:

  • ECS / EKS deep coverage
  • full KMS policy reasoning
  • full SCP effective evaluation
  • all AWS services
  • perfect IAM condition evaluation
  • deep ECS / EKS coverage

Phase 2 — Bedrock + container identity expansion​

Goal​

Expand from serverless-first AWS coverage into the modern workload identity surfaces buyers actually care about.

Scope​

Connector additions​

  • Bedrock agents / aliases / action groups / knowledge bases / flows
  • ECS task definitions / services / task roles / execution roles
  • ECR repositories and repository policies
  • GitHub OIDC trust pattern capture
  • EKS IRSA / Pod Identity discovery where practical

Platform additions​

  • supply-chain-to-runtime path rendering
  • richer egress_category support for Bedrock and AI-linked flows
  • policy/resource visualization for ECR injection and CI/CD-to-runtime chains

Documentation additions​

  • Bedrock integration guide
  • ECS/ECR pathing examples
  • GitHub OIDC to AWS trust narrative
  • cross-cloud story: GitHub → AWS → data / ServiceNow

Phase 3 — Enterprise hardening and full operations story​

Goal​

Make AWS integration enterprise-ready for larger, multi-account environments.

Scope​

  • IAM Identity Center correlation
  • richer Access Analyzer and Security Hub ingestion
  • Config Aggregator-backed resource inventory enrichment
  • selected SCP interpretation
  • KMS / resource-policy depth where it materially changes path accuracy
  • demo-lab live AWS scenario updates
  • ServiceNow <-> AWS operational workflows

Repo-by-repo implementation plan​

1. sv0-connectors​

1.1 Create connector package​

Create a new connector package/module for AWS with:

  • boto3 session bootstrap
  • AssumeRole per target account
  • account iteration and retry boundaries
  • normalized emitters that match existing connector contracts

1.2 Phase 1 collectors​

Implement collectors in this order:

  1. Organizations / account inventory
  2. IAM roles + trust policies
  3. IAM policies (managed + inline)
  4. Lambda
  5. Step Functions
  6. EventBridge
  7. Secrets Manager
  8. S3 / DynamoDB
  9. CloudTrail evidence
  10. Access Analyzer findings

1.3 Connector-side output contract​

Emit:

  • entities
  • relationships
  • execution evidence
  • provenance / caveat metadata

Required metadata from day one:

  • account_id
  • account_name when known
  • organization_id when known
  • ou_id when known
  • ou_path when known
  • account_purpose when known
  • is_management_account
  • is_delegated_admin
  • region
  • source_system=aws_{service}:{account_id}
  • conditions_not_evaluated=true where appropriate

1.4 Connector test plan​

Need fixtures for:

  • single-account role assumption
  • multi-account trust chain
  • Lambda → role → S3 path
  • Step Functions → Lambda chain
  • resource-based policy cross-account path
  • CloudTrail AssumeRole evidence mapping

2. sv0-platform​

2.1 Data model / enums / schemas​

Implement the model changes already implied by ADR-014 and ADR-015:

  • permission_set node/entity type
  • HAS_PERMISSION_SET
  • SUBJECT_TO for permission boundaries / SCPs
  • prefix-aware filtering for AWS source_system
  • the underlying API/index support for source_system prefix queries (or an equivalent source_system_prefix field), as called out by ADR-015

2.2 Materializer changes​

Extend path materialization to understand:

  • IAM trust edges
  • policy-document-based grants
  • cross-account account transitions
  • trigger edges such as TRIGGERED_BY
  • invocation edges such as INVOKES
  • workload → runtime role → permission_set → permission → resource

2.3 Evidence ingestion​

Add ingestion and UI surfacing for:

  • sts:AssumeRole
  • AssumeRoleWithWebIdentity
  • high-value Lambda / Step Functions execution evidence
  • CloudTrail-linked timestamps and lineage

2.4 UI work​

Need at least:

  • AWS account-aware source badges
  • entity detail support for AWS subtypes
  • explanation caveat for IAM condition non-evaluation
  • finding copy for cross-account and dormant-but-powerful runtime roles

3. sv0-documentation​

3.1 Architecture docs to add/update​

After Phase 1 coding begins, update:

  • docs/architecture/05-connectors.md
  • docs/architecture/10-access-paths.md
  • docs/architecture/01-data-model.md
  • setup / onboarding docs for AWS connector

3.2 Operator docs to add​

We should expect to need:

  • docs/integrations/aws/index.md
  • docs/integrations/aws/authentication.md
  • docs/integrations/aws/permissions.md
  • docs/integrations/aws/onboarding-modes.md
  • docs/integrations/aws/known-caveats.md
  • org-mode onboarding templates (CloudFormation / StackSets baseline) for delegated-admin + spoke-role rollout
  • reusable Terraform modules where they provide a better operator workflow than raw templates

3.3 Demo-lab docs​

Update the demo-lab plan to move the AWS scenario from “blocked until connector ships” to a real execution plan with:

  • org-mode demo account topology
  • serverless + Bedrock sample workloads
  • one cross-account trust misconfiguration
  • one orphaned runtime role
  • one GitHub OIDC deployment path

Decision: what should be first PRs?​

PR A — platform prerequisites​

Repo: sv0-platform

Ship the smallest platform-enabling changes first:

  • permission_set support
  • HAS_PERMISSION_SET / SUBJECT_TO
  • source_system prefix filtering or equivalent support
  • path materializer prep for AWS entities

Why first: the connector should not get too far ahead of the platform model.

PR B — connector skeleton + IAM/Lambda wedge​

Repo: sv0-connectors

Ship:

  • AWS connector scaffolding
  • account iteration + AssumeRole
  • IAM role/policy ingestion
  • Lambda ingestion
  • S3 / Secrets / DynamoDB basics
  • first path fixtures

Why second: this gets the smallest end-to-end AWS story live.

PR C — CloudTrail evidence + cross-account findings​

Repos: sv0-connectors, sv0-platform

Ship:

  • CloudTrail evidence mapping
  • cross-account path visibility
  • findings that use evidence + structural reachability together

Why third: this is where SecurityV0 becomes differentiated, not just inventory-capable.

PR D — docs + onboarding package​

Repo: sv0-documentation

Ship customer-facing docs once the actual connector shape is real.

PR E — Bedrock / Step Functions / EventBridge expansion​

Repos: sv0-connectors, sv0-platform, docs as needed

Proposed work breakdown by sprint​

Sprint 1 — prerequisites​

  • sv0-platform: permission_set + path model prep
  • sv0-connectors: AWS connector skeleton, auth/session/bootstrap
  • docs: onboarding draft skeleton

Sprint 2 — first working wedge​

  • IAM roles + policies
  • Lambda
  • S3 / DynamoDB / Secrets
  • first end-to-end path materialization

Sprint 3 — evidence + trust chains​

  • CloudTrail
  • cross-account AssumeRole paths
  • first AWS-specific findings

Sprint 4 — orchestration and AI surface​

  • Step Functions
  • EventBridge
  • Bedrock agent/action-group support

Sprint 5 — expansion + demo lab​

  • ECS / ECR
  • GitHub OIDC
  • demo-lab AWS scenario
  • docs hardening

Risks and blockers​

1. Platform model drift​

The biggest implementation risk is not AWS API complexity. It is connector output diverging from platform semantics.

Mitigation: do PR A first.

2. IAM conditions false positives​

If we present structural reachability as fully effective reachability, we will overstate risk.

Mitigation: explicit caveat in API + UI + docs for Phase 1.

3. Multi-account onboarding complexity​

Customers will want org mode; many will only be able to start with selected accounts.

Mitigation: document 3 onboarding modes from day one.

4. Over-scoping AWS services​

Trying to cover ECS, EKS, Bedrock, IAM Identity Center, Config, Security Hub, and every resource policy in the first implementation cycle will slow shipping dramatically.

Mitigation: keep Phase 1 to IAM + Lambda + trust + evidence + sensitive stores.

Success criteria​

This implementation cycle is successful when SecurityV0 can show, for a real AWS environment:

  1. a Lambda or Step Functions workload
  2. the IAM role it runs as
  3. the policy documents that grant access
  4. the destination data resources it can reach
  5. whether it crosses account boundaries
  6. at least one CloudTrail-backed proof that the path was exercised
  7. ownership/account context that makes the result actionable

If we can do that well, we have a credible AWS wedge.

Bottom line​

The existing AWS research is good enough. We do not need another discovery phase before coding.

The right next move is:

  1. platform prerequisite PR in sv0-platform
  2. connector wedge PR in sv0-connectors
  3. then evidence + docs hardening

All AWS rollout and demo work under that sequence must follow the automation-first rule above: no clickops, reproducible IaC, scripted validation, scripted teardown.

This document should be treated as the working execution plan for that sequence.