docs: add least-privilege deployment roles and deployment guide

[scottschreckengaust]

Summary

• Validated least-privilege IAM policies for the CloudFormation execution role through end-to-end deployment testing on a clean AWS account (us-east-1). The original single monolithic policy was replaced with a 3-way split to stay under the IAM managed policy 6,144-character limit:
  • IaCRole-ABCA-Infrastructure — CloudFormation, IAM, VPC, Route 53 Resolver DNS Firewall
  • IaCRole-ABCA-Application — DynamoDB, Lambda, API Gateway, Cognito, WAFv2, EventBridge, Secrets Manager (+ optional ECS)
  • IaCRole-ABCA-Observability — Bedrock AgentCore, Bedrock Guardrails, CloudWatch, X-Ray, S3, KMS, ECR, SSM, STS
• Fixed Quick Start deployment blockers found during end-to-end walkthrough:
  • X-Ray update-trace-segment-destination fails on fresh accounts without a CloudWatch Logs resource policy — added prerequisite aws logs put-resource-policy command
  • mise run build fails without AWS credentials (CDK synth does AZ lookups) — added note and common error entry
  • Added common error entries for non-TTY deploy approval and build credential issues
  • Added AWS_PROFILE guidance for multi-profile users
• Fixed abca-plugin gaps discovered during deep review:
  • /setup skill Phase 3 was missing the logs put-resource-policy prerequisite (same X-Ray bug)
  • /deploy skill had no least-privilege guidance — added section with re-bootstrap command and reference to DEPLOYMENT_ROLES.md
  • CLAUDE.md had no reference to the plugin — added pointer so sessions discover guided workflows
• Add docs/guides/DEPLOYMENT_GUIDE.md covering architecture, scale-to-zero analysis (~$140-150/month idle), and complete AWS services inventory
• Update docs/design/COST_MODEL.md with corrected baseline, scale-to-zero section, and updated references
• Add .gitignore entries for Claude Code plugin artifacts (.mcp.json, .remember/)
• Add docs-sync pre-commit hook to auto-regenerate Starlight mirrors

Review feedback addressed

Changes made after code review:

#	Issue	Resolution
1	SecretsManager Resource: "*"	Split GetRandomPassword into own statement; all other actions scoped to backgroundagent-*
2	Deploy SKILL.md references non-existent IaCRole-ABCA-Policy	Updated to reference all three policy names
3	DEPLOYMENT_GUIDE.md has no Starlight mirror	Added route mapping, mirror, and sidebar entry
4	iam:PassRole without conditions	Added IAMPassRole statement with iam:PassedToService condition (7 services); AttachRolePolicy restriction added as iterative tightening item
5	aws-service-role/* allows any service-linked role	Added iam:AWSServiceName as iterative tightening item
6	KMS kms:CreateGrant on Resource: "*"	Added kms:ResourceAliases as iterative tightening item
7	X-Ray resource policy grants Resource: "*"	Scoped to arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans
8	Inconsistent placeholder names	Unified to ACCOUNT_ID with substitution note
9	ACCOUNT_ID captured but never used	Now used by scoped X-Ray resource policy (item 7)
10	Session timeout "8 hours" vs "9 hours"	Clarified: 8h = AgentCore service limit, 9h = orchestrator executionTimeout
11	VPC endpoint cost underestimated	Corrected from ~$50/mo to ~$102/mo (7×2 AZs×$0.01/hr×730hrs); baseline updated to ~$140-150/mo
12	Region wildcards	Kept as iterative tightening item #3 (users deploy to different regions)

Deployment validation test matrix

Four configurations are tested across the full stack lifecycle (create → task → update → destroy):

#	IAM Policy	ECS Compute	Purpose
V1	AdministratorAccess (default bootstrap)	Off (AgentCore only)	Baseline — confirms stack works with default permissions
V2	AdministratorAccess	On (ECS Fargate)	Baseline with ECS — confirms ECS compute path works
V3	Least-privilege (3-way split)	Off (AgentCore only)	Primary validation — confirms scoped policies are sufficient
V4	Least-privilege (3-way split)	On (ECS Fargate)	Confirms ECS statement + scoped policies work together

Lifecycle steps per variation

Each variation runs through:

1. Create — Fresh cdk deploy from clean state (no existing stack). Validates all resource creation permissions.
2. Task — Submit a coding task via CLI, wait for agent to complete and open a PR. Validates runtime permissions (Secrets Manager read, DynamoDB, AgentCore/ECS invocation).
3. Update — Modify a Blueprint parameter and redeploy. Validates stack update permissions (resource modifications, not just creation).
4. Destroy — cdk destroy to tear down all resources. Validates deletion permissions.

Pre-test setup (once per account)

• CDK bootstrap (default for V1/V2, re-bootstrap with --cloudformation-execution-policies for V3/V4)
• X-Ray resource policy (aws logs put-resource-policy)
• GitHub PAT stored in Secrets Manager (post first deploy)
• Cognito user created (post first deploy)

Pass criteria

• Create: Stack reaches CREATE_COMPLETE with no permission errors in CloudFormation events
• Task: Task reaches COMPLETED status with a PR URL in the output
• Update: Stack reaches UPDATE_COMPLETE
• Destroy: Stack reaches DELETE_COMPLETE (AgentCore ENI timing retries are acceptable)

Progress is reported as individual PR comments (one per lifecycle step per variation, ~16 total).

Files changed

File	What Changed
docs/design/DEPLOYMENT_ROLES.md	3-way policy split; IAMPassRole with PassedToService condition; split SecretsManager; iterative tightening items for AttachRolePolicy, CreateServiceLinkedRole, KMS; unified ACCOUNT_ID placeholder
docs/guides/DEPLOYMENT_GUIDE.md	New: architecture, scale-to-zero (~$140-150/mo), AWS services inventory; corrected VPC endpoint cost; clarified session timeouts
docs/guides/QUICK_START.md	X-Ray resource policy scoped to aws/spans; build credential note; AWS_PROFILE guidance; 4 new common errors
docs/design/COST_MODEL.md	Corrected VPC endpoint cost (~$102/mo); baseline updated to ~$140-150/mo; clarified session timeouts; scale-to-zero section
docs/abca-plugin/skills/setup/SKILL.md	Scoped X-Ray resource policy
docs/abca-plugin/skills/deploy/SKILL.md	Updated to 3-way policy split
docs/scripts/sync-starlight.mjs	Added DEPLOYMENT_GUIDE route mapping and mirror
docs/astro.config.mjs	Added Deployment Guide sidebar entry
CLAUDE.md	Added plugin reference
AGENTS.md	Strengthened docs-sync instructions
.gitignore	Added .mcp.json, .remember/
.pre-commit-config.yaml	Added docs-sync pre-commit hook

Test plan

• Deploy with AdministratorAccess on clean account — passed (initial validation)
• CloudTrail analysis of all CFN execution role actions — 36 gaps identified
• Deploy with scoped 3-way policy split — passed after 7 iterations (initial validation)
• Stack update with scoped policies — passed (initial validation)
• Smoke test (task submission, PR creation) — passed (initial validation)
• Stack destroy with scoped policies — passed with AgentCore ENI retry (initial validation)
• ECS statement fits in Application policy under size limit — verified (4,110 / 6,144 chars with ECS + split SM)
• Verify all markdown links resolve between new and existing docs
• Starlight mirrors regenerated and astro check passed
• V1: Admin / No ECS — create → task → update → destroy
• V2: Admin / ECS — create → task → update → destroy
• V3: Least-priv / No ECS — create → task → update → destroy
• V4: Least-priv / ECS — create → task → update → destroy

🤖 Generated with Claude Code

[krokoko]

Overall this is a high-quality, deployment-validated PR that replaces AdministratorAccess with scoped IAM policies — a significant security improvement. However, all three reviewers flagged issues
that should be addressed before merge.

---

Critical (must fix)

1. SecretsManager Resource includes bare "*" — grants full account access to all secrets

File: docs/design/DEPLOYMENT_ROLES.md (and Starlight mirror)

The SecretsManager statement lists "*" as a second resource alongside the scoped ARN, completely negating least-privilege. Actions like GetSecretValue, DeleteSecret, and PutSecretValue become
account-wide.

Fix: Split GetRandomPassword (the only action that requires "") into its own statement:
{
"Sid": "SecretsManager",
"Action": ["secretsmanager:CreateSecret", "...all others except GetRandomPassword..."],
"Resource": "arn:aws:secretsmanager::㊙️backgroundagent-"
},
{
"Sid": "SecretsManagerAccountLevel",
"Action": "secretsmanager:GetRandomPassword",
"Resource": "*"
}

2. Deploy SKILL.md references non-existent policy name IaCRole-ABCA-Policy

File: docs/abca-plugin/skills/deploy/SKILL.md

The skill tells users to bootstrap with a single IaCRole-ABCA-Policy, but DEPLOYMENT_ROLES.md defines three policies (-Infrastructure, -Application, -Observability). Users following this skill will
get a deployment failure.

Fix: Update to reference all three --cloudformation-execution-policies flags, matching DEPLOYMENT_ROLES.md.

3. DEPLOYMENT_GUIDE.md has no Starlight mirror — broken link on docs site

File: docs/src/content/docs/architecture/Cost-model.md

The Starlight mirror of COST_MODEL.md contains Deployment guide as a raw relative path because the sync script has no route mapping for it. This is a broken link on
the deployed Starlight site.

Fix: Either add DEPLOYMENT_GUIDE to explicitGuideRoutes in sync-starlight.mjs and create a mirror, or remove the link from content that gets mirrored.

---

High (strongly recommend fixing)

4. iam:PassRole and iam:AttachRolePolicy without conditions — privilege escalation path

File: docs/design/DEPLOYMENT_ROLES.md, IAMRolesAndPolicies statement

Without an iam:PassedToService condition on PassRole and no policy restriction on AttachRolePolicy, the execution role could create a backgroundagent-dev-* role, attach AdministratorAccess to it, pass
it to Lambda, and invoke it — full account compromise.

Fix: Add iam:PassedToService condition limiting to lambda.amazonaws.com, ecs-tasks.amazonaws.com, apigateway.amazonaws.com, logs.amazonaws.com, bedrock.amazonaws.com.

5. aws-service-role/* allows creating any service-linked role

File: docs/design/DEPLOYMENT_ROLES.md, IAMRolesAndPolicies statement

Combined with iam:CreateServiceLinkedRole, the resource arn:aws:iam:::role/aws-service-role/ allows creating service-linked roles for any AWS service.

Fix: Add an iam:AWSServiceName condition scoped to only the services ABCA actually uses.

6. KMS kms:CreateGrant on Resource: "*" — can delegate key access across account

The CDK bootstrap key alias (alias/cdk-hnb659fds-*) is deterministic. Consider adding a kms:ResourceAliases condition to scope this.

7. X-Ray resource policy in QUICK_START.md grants Resource: "*" to xray.amazonaws.com

Fix: Scope to arn:aws:logs::ACCOUNT_ID:log-group:aws/spans and arn:aws:logs::ACCOUNT_ID:log-group:aws/spans:*.

8. Inconsistent placeholder names (ACCOUNT vs ACCOUNT_ID)

The bootstrap command uses ACCOUNT, the trust policy uses ACCOUNT_ID, and the IAM ARNs use * for the account field. Should be unified with a single ACCOUNT_ID placeholder and a note at the top
explaining substitution.

---

Medium (should fix)

9. ACCOUNT_ID variable captured but never used

Files: QUICK_START.md, setup/SKILL.md (and Starlight mirror)

ACCOUNT_ID=$(aws sts get-caller-identity ...) is set but never referenced. Either remove it or use it to scope the resource policy ARN.

10. Session timeout inconsistency: "8 hours" vs "9 hours"

• DEPLOYMENT_GUIDE.md says "8 hours (AgentCore session)"
• COST_MODEL.md (updated in this PR) says "9 hours"
• Code: executionTimeout: Duration.hours(9) at task-orchestrator.ts:173
• Pre-existing COST_MODEL.md line 46 still says "8-hour max session timeout" (not updated)

These are actually two different limits (AgentCore service limit vs. orchestrator timeout), but this needs explicit clarification.

11. VPC endpoint cost may be underestimated

The PR claims ~$50/month for 7 endpoints across 2 AZs. AWS pricing: 7 x 2 AZs x $0.01/hr x 730 hrs = ~$102/month. This would push the total baseline to ~$135-145/month. (Pre-existing issue in
COST_MODEL.md, perpetuated in the new DEPLOYMENT_GUIDE.md.)

12. Region wildcards throughout all policies

All ARNs use * for region despite ABCA deploying to a single region. The "Iterative tightening" section mentions this but it could be a stronger recommendation.

[scottschreckengaust]

1. SecretsManager Resource includes bare "*"

The "*" is intentional — secretsmanager:GetRandomPassword is an account-level API that does not support resource-level permissions (it generates a random string without referencing any secret). Splitting it into its own statement would push the Application policy over the IAM 6,144-character limit (the 3-way split was specifically sized to stay under this). Added an entry to the Resource-level permission constraints table documenting this, with a pointer to the Iterative tightening section for post-deployment refinement.

2. Deploy SKILL.md references non-existent policy name IaCRole-ABCA-Policy

Fixed — updated to reference all three policies (IaCRole-ABCA-Infrastructure, -Application, -Observability) with the three --cloudformation-execution-policies flags matching DEPLOYMENT_ROLES.md.

3. DEPLOYMENT_GUIDE.md has no Starlight mirror — broken link on docs site

Fixed — added DEPLOYMENT_GUIDE to explicitGuideRoutes in sync-starlight.mjs, added a mirrorMarkdownFile() call to generate the mirror at getting-started/Deployment-guide.md, and added a sidebar entry in astro.config.mjs. The COST_MODEL.md links now rewrite to /getting-started/deployment-guide instead of the raw relative path.

[scottschreckengaust]

4. iam:PassRole and iam:AttachRolePolicy without conditions — privilege escalation path

Separated iam:PassRole into its own IAMPassRole statement with an iam:PassedToService condition scoped to the 7 services ABCA passes roles to: lambda.amazonaws.com, ecs-tasks.amazonaws.com, ecs.amazonaws.com, apigateway.amazonaws.com, logs.amazonaws.com, bedrock.amazonaws.com, events.amazonaws.com.

For iam:AttachRolePolicy: restricting with iam:PolicyARN requires enumerating every AWS managed policy CDK attaches (e.g., service-role/AWSLambdaBasicExecutionRole), which is brittle across CDK versions. Added this as Iterative tightening item #4 with guidance to enumerate from a synthesized template post-deployment.

5. aws-service-role/* allows creating any service-linked role

Added as Iterative tightening item #5 — recommending iam:AWSServiceName condition scoped after first deploy using CloudTrail to identify which service-linked roles were actually created.

6. KMS kms:CreateGrant on Resource: "*"

Added as Iterative tightening item #6 — recommending kms:ResourceAliases condition scoped to alias/cdk-hnb659fds-* (the deterministic CDK bootstrap key alias).

7. X-Ray resource policy in QUICK_START.md grants Resource: "*"

Fixed — scoped to arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans and arn:aws:logs:*:${ACCOUNT_ID}:log-group:aws/spans:* in both QUICK_START.md and the setup SKILL.md. The ACCOUNT_ID variable (item 9) is now used by this resource policy.

8. Inconsistent placeholder names (ACCOUNT vs ACCOUNT_ID)

Unified to ACCOUNT_ID throughout DEPLOYMENT_ROLES.md (bootstrap command, policy ARNs). Added a substitution note at the top of the "Using these policies" section explaining the two placeholders (ACCOUNT_ID and REGION).

9. ACCOUNT_ID variable captured but never used

Keeping as-is — the variable is now used by the scoped X-Ray resource policy (item 7 fix).

10. Session timeout inconsistency: "8 hours" vs "9 hours"

Clarified that these are two distinct limits:

• 8 hours: AgentCore service limit (max session duration)
• 9 hours: Orchestrator executionTimeout (Duration.hours(9) in task-orchestrator.ts:173)

Updated both DEPLOYMENT_GUIDE.md and COST_MODEL.md to distinguish the two explicitly.

11. VPC endpoint cost may be underestimated

Fixed — the ~$50/month figure was calculated for 1 AZ. Corrected to ~$102/month (7 × 2 AZs × $0.01/hr × 730 hrs) in both COST_MODEL.md and DEPLOYMENT_GUIDE.md. Updated the total baseline from ~$85–95/month to ~$140–150/month and adjusted the cost-at-scale table accordingly.

12. Region wildcards throughout all policies

Agree this could be stronger. All policy ARNs use * for region despite ABCA deploying to a single region. The Iterative tightening section already has item #3 recommending "aws:RequestedRegion" conditions. Recommend keeping this as a post-deployment tightening step rather than hardcoding a region in the docs — users deploy to different regions, and a hardcoded region in the policy template would cause confusion. The tightening guidance is clear about what to do.

[scottschreckengaust]

V1: Admin / No ECS — Create

⏳ In progress — CDK bootstrap complete, cdk deploy running (~10 min for 189 resources).

Pre-deploy setup:

• ✅ X-Ray resource policy created and destination set
• ✅ CDK bootstrapped with default AdministratorAccess
• ✅ Full build passed (721 CDK tests, 70 CLI tests)

Note: The scoped X-Ray resource policy (aws/spans log group ARN) fails at update-trace-segment-destination time because the log group doesn't exist yet. Workaround: set with Resource: "*" first, then tighten after. Will document this in Quick Start.

[scottschreckengaust]

V1: Admin / No ECS — Create

✅ Passed — Stack backgroundagent-dev reached CREATE_COMPLETE (189 resources).

Note: Had to delete an orphaned AWS::XRay::ResourcePolicy from a previous test deployment — this is an account-level resource that survives cdk destroy. Added to cleanup checklist.

Now running smoke test task (CODEOWNERS file creation).

[scottschreckengaust]

V1: Admin / No ECS — Task

✅ Passed — Task 01KQ0VB0GSYS245NH2Q4ZGN41K completed in 124s, $0.14.

• PR: chore(github): add CODEOWNERS file with default owner scottschreckengaust/agent-plugins#3
• Status: COMPLETED
• Agent created CODEOWNERS file and opened PR successfully.

[scottschreckengaust]

V1: Admin / No ECS — Update

✅ Passed — Stack reached UPDATE_COMPLETE. Added systemPromptOverrides to Blueprint and redeployed successfully.

[scottschreckengaust]

V1: Admin / No ECS — Destroy

⏳ In progress (retry) — First delete attempt hit the known AgentCore ENI cleanup timing issue (security group + 2 subnets retained by ela-attach managed ENIs). Retrying delete — ENIs typically release within 10-30 min after runtime deletion. This is a known operational note, not a permissions issue.

[scottschreckengaust]

V1: Admin / No ECS — Destroy

✅ Passed (with known ENI retry) — Stack deleted. AgentCore-managed ENIs (ela-attach) held references to the security group and subnets, requiring --retain-resources on the VPC, 2 subnets, and 1 SG. These orphaned resources will be cleaned up once ENIs release (~10-30 min). This is a known operational characteristic, not a permissions issue.

V1 Summary: All 4 lifecycle steps passed (Create ✅ → Task ✅ → Update ✅ → Destroy ✅).

[scottschreckengaust]

V2: Admin / ECS — Create

✅ Passed — Stack reached CREATE_COMPLETE with ECS Fargate cluster, task definition, and Docker image asset. Submitting smoke test task now.

[scottschreckengaust]

V2: Admin / ECS — Task

✅ Passed — Task completed in 130s, $0.16.

• PR: chore(config): add .editorconfig with standard formatting settings scottschreckengaust/agent-plugins#4
• Status: COMPLETED
• Agent created .editorconfig and opened PR (routes to AgentCore; ECS cluster deployed but not task-routed).

[scottschreckengaust]

V2: Admin / ECS — Update

✅ Passed — Stack reached UPDATE_COMPLETE. Removed systemPromptOverrides from Blueprint and redeployed with ECS cluster intact.