How-to

Integrating with existing infrastructure

You don't need a greenfield AWS organization to use the Provabl suite. ground can add compliance foundations to an existing org, and attest can manage an org that ground didn't create.

Three integration scenarios

1. Greenfield

New AWS organization with no existing workloads. Run ground deploy in full — all four stacks, all OUs. Then hand off to attest.

Easiest. Recommended for new SRE deployments.

2. Brownfield — add ground to existing org

Existing AWS organization with accounts and workloads. Deploy ground stacks alongside — they create new OUs and security services without touching existing accounts.

Most common for R1 institutions.

3. Attest-only

Skip ground entirely. Run attest init against an existing org. attest inventories what's there, identifies gaps, and enforces frameworks — it doesn't require ground.

Use when the org already has a managed foundation (LZA, Control Tower, etc.).

Brownfield: adding ground to an existing org

If your organization already has accounts and SCPs, ground can be deployed incrementally. The key is that ground stacks are additive — they create new resources, they don't modify or delete existing ones.

Step 1: Deploy the logging stack only

Start with logging — it's non-destructive and gives attest what it needs to assess your existing org.

# Only deploy the logging foundation — no OU changes yet
ground deploy --dry-run    # review what will be created
ground deploy              # creates ground-logging and ground-security stacks

# Now attest can assess your existing org
attest init --region us-east-1
attest frameworks add nist-800-171-r2
attest scan    # see gaps in your existing setup

Step 2: Move accounts to ground OUs (optional)

Once the logging and security stacks are in place, deploy the accounts stack to create ground OUs. Then move existing accounts into them at your own pace — accounts inherit SCPs on move, so test with non-production accounts first.

# Deploy accounts stack to create OUs (no accounts moved yet)
ground status   # see what's deployed: ground-accounts stack

# Move an account into a ground OU using the AWS CLI
aws organizations move-account \
  --account-id 123456789012 \
  --source-parent-id r-xxxx \
  --destination-parent-id ou-xxxx-yyyyyyyy   # ground OU ID from stack output

# Verify SCPs inherited correctly
attest scan    # posture should improve as accounts move into correct OUs

What to watch for in brownfield deployments

  • Existing SCPs — ground SCPs will coexist with your existing ones. The 5-SCP-per-target limit applies to the sum of all SCPs on a target. Check attest preflight before applying compiled SCPs.
  • Existing CloudTrail — ground creates a new org-wide trail. If you already have one, configure logging.bucket_name to use the existing audit bucket instead of creating a new one.
  • Identity Center — if IAM Identity Center is already configured, set identity.instance_arn in ground.yaml to deploy permission sets into your existing instance.
  • SCP conflicts — run attest compile --dry-run and review the conflict report before attest apply on a brownfield org.

Attest-only: skip ground entirely

attest doesn't require ground. If your org was set up with AWS Control Tower, Landing Zone Accelerator, or another managed foundation, you can run attest directly against it.

# Skip ground — run attest directly against your existing org
attest init --region us-east-1

# attest will check prerequisites and warn about any gaps:
#   ✓ CloudTrail org-wide trail: active
#   ✓ AWS Config: active
#   ⚠ GuardDuty: not enabled in all accounts
#   ✓ IAM Identity Center: detected (added to SSP boundary)

attest frameworks add nist-800-171-r2 hipaa
attest compile --scp-strategy merged
attest apply --approve
attest scan

The attest prerequisite validation report tells you exactly what's missing and how to fix it — either manually or by deploying the relevant ground stack.

Alongside AWS Control Tower or LZA

ground and attest are designed to work alongside AWS managed foundations. The key principle: ground doesn't touch resources it didn't create.

AWS Control Tower

Control Tower manages the OU hierarchy and baseline guardrails. Use ground only for the stacks Control Tower doesn't cover — typically logging augmentation and the Sensitive Research / DoD OUs.

Set org.management_account_id and skip ground deploy accounts if Control Tower owns the OU structure.

Landing Zone Accelerator (LZA)

LZA is more customizable than Control Tower. ground can complement it by adding the Sensitive Research and DoD/CMMC OU tiers that LZA's research configurations don't include by default.

Use ground deploy --output terraform and merge the HCL into your LZA pipeline.

Existing Terraform / CDK

Export ground as Terraform or CDK and import the resources into your existing state. Ground's IaC output is standard — aws_organizations_organizational_unit, aws_ssoadmin_permission_set, etc.

ground deploy --output terraform
# merge ground-terraform/main.tf into your IaC

Handing off to attest

After ground deploy, export metadata for attest to consume. This allows attest init to skip live AWS prerequisite checks — useful in CI/CD pipelines where ground and attest run in separate stages.

# Export ground deployment metadata
ground export-metadata --output ground-meta.json

# ground-meta.json (current schema):
# {
#   "ground_version": "0.3.0",
#   "region": "us-east-1",
#   "cloudtrail_enabled": true,
#   "config_enabled": true,
#   "identity_center_instance_arn": "arn:aws:sso:::instance/ssoins-xxxx",
#   "external_services": [
#     { "name": "globus", "vendor": "Globus", "category": "data-transfer",
#       "features": ["baa","high-assurance"] }
#   ],
#   "probe_results": {}
# }
# Note: guardduty_enabled and security_hub_enabled are NOT present —
# ground does not deploy detection services. Run 'attest apply' to enable them.

# Pass to attest in the next pipeline stage
attest init --region us-east-1 --ground-meta ground-meta.json