This document provides a security overview of the Claude Code Multi-Agent Development Sample, including a threat model, AI security controls, and risk assessment.

Note: This repository is a sample configuration — not a production application. The security analysis below documents risks inherent in multi-agent AI workflows and the mitigations built into this configuration.

Threat: Agents execute in the same Claude Code session with shared file system access. An agent operating outside defined scope due to configuration error or logic fault may perform unauthorized file system modifications beyond its assigned scope.

Mitigations (require user configuration and ongoing verification):

• Agent team protocol (rules/agent-team-protocol.md) restricts each agent to files listed in its task assignment — users must define and maintain these restrictions
• Verification gate requires agents to confirm they only modified assigned files before marking tasks complete — users must enforce this gate in their workflow
• review-agent independently verifies changes match task scope — users must include review-agent in their team composition
• Claude Code's permission system prompts the user before executing potentially dangerous operations — users must review and respond to these prompts

Threat: Agents interacting with AWS services may perform unauthorized privilege escalation through IAM policy exploitation, access resources outside authorized scope, or execute unauthorized modifications to production infrastructure.

Mitigations (require user configuration and ongoing verification):

• Production safety rules (rules/amazon-builder-production-safety.md) mandate ReadOnly/least-privilege credentials for read operations — users must configure appropriate AWS profiles and IAM policies
• Agents must assume resources are production unless proven otherwise — users must verify agents follow this convention
• Destructive operations (delete, terminate, modify) require explicit user confirmation — users must not grant blanket approval
• AWS Security Token Service (AWS STS) identity verification via aws sts get-caller-identity is required before any AWS operation — users must ensure credentials are correctly scoped
• Safety controls (termination protection, deletion protection, MFA delete) must never be disabled without user confirmation — users must review all safety control changes

Threat: Agents have read/write access to the local file system and may perform unauthorized file system modifications to system configuration files, overwrite uncommitted work, or access sensitive data outside authorized scope.

Mitigations (require user configuration and ongoing verification):

• Claude Code's built-in permission system gates file operations — users must review permission prompts and not grant overly broad access
• Spec-driven workflow constrains agents to spec-defined file paths — users must define accurate file paths in specs
• Agent team protocol requires agents to stay within task scope — users must verify compliance during review
• Non-interactive execution rules prevent agents from bypassing confirmation prompts — users must maintain these rules in their configuration

Threat: MCP servers are external services that agents communicate with. MCP server compromise may result in data manipulation, prompt injection attacks, or unauthorized data exfiltration.

Mitigations (require user configuration and ongoing verification):

• All configured MCP servers are either official AWS services or well-known public services — users must vet any additional MCP servers before adding them
• MCP servers are used for documentation lookup and diagram generation — not for executing privileged operations — users must verify new servers do not require privileged access
• Claude Code flags suspected prompt injection in tool results — users must review flagged results and act accordingly
• Users can review and approve/deny MCP server tool calls via the permission system — users must actively monitor and respond to these prompts

Threat: Plugins execute code within the Claude Code session and may access data outside authorized scope boundaries.

Mitigations (require user configuration and ongoing verification):

• All configured plugins are from the official Claude Code marketplace — users must review plugin permissions before enabling
• Plugins operate within Claude Code's permission framework — users must maintain appropriate permission settings
• The security-guidance plugin specifically reviews for security best practices — users must include this plugin in their configuration and act on its findings

• Claude Code's built-in safety system validates user prompts and agent communications
• The system flags suspected prompt injection attempts in tool results and MCP responses
• Agent instructions include explicit constraints on scope and behavior (each agent's markdown definition)

• Claude Code applies content safety measures to all generated output
• review-agent independently verifies implementation correctness and security
• The spec-driven workflow requires explicit PASS from review-agent before work is accepted

• Claude Code sessions are governed by Anthropic's API rate limits and usage policies
• Agent team protocol limits review cycles to 3 per group before escalating to the user
• Same-blocker-twice rule forces escalation rather than infinite retry loops

• All agent interactions occur within the Claude Code session and are visible to the user
• Task coordination (TaskCreate/TaskUpdate/TaskList) provides an audit trail of agent actions
• decisions.md logs mid-flight architectural decisions
• review.md documents review findings per cycle

1. Suspicious agent behavior: User can deny any tool call via Claude Code's permission system
2. Unexpected AWS changes: Production safety rules require confirmation for destructive operations; use aws cloudformation describe-stack-events to audit
3. Compromised MCP server: Remove the server entry from .mcp.json and restart the session
4. Review failure loop: After 3 cycles, the system escalates to the user for manual intervention

This section addresses bias and fairness considerations for the multi-agent system. Because this repository is a sample configuration — not a production application that processes user data or makes consequential decisions — many traditional bias concerns do not directly apply. The agents generate infrastructure code and review it; they do not make decisions about people.

The agents rely on Claude models, which may reflect biases present in their training data. In practice, this could surface as:

• Defaulting to specific AWS services, patterns, or regions without considering alternatives
• Over-engineering or under-engineering based on patterns seen in training data

Mitigation: The spec-driven workflow requires explicit architectural decisions documented in design.md and decisions.md. The sa-agent provides Well-Architected reviews that challenge assumptions. All decisions are visible to the user for override.

Task delegation is deterministic — tasks are assigned by role prefix ([coding], [devops], [sa]) defined in tasks.md by the team lead. The review-agent applies the same review criteria to all code regardless of which agent produced it. There is no adaptive or learned behavior that could develop bias over time.

• All agent outputs are visible in the Claude Code session
• review-agent independently evaluates all implementations against the same criteria
• decisions.md provides an audit trail of architectural choices for human review
• The max-3-review-cycles rule with user escalation ensures a human reviews persistent disagreements

• Claude Code's permission system requires user approval for potentially impactful operations
• The spec-driven workflow has explicit human review points (spec approval, diff review, deployment approval)
• Production safety rules gate all destructive AWS operations behind user confirmation
• Users can deny any tool call and override any agent decision

The Claude models used by these agents have known limitations regarding bias:

• Training data biases may influence code style, library choices, and architectural preferences
• Models may not equally represent all programming paradigms, languages, or cloud providers
• Generated code patterns may reflect biases toward certain community conventions over others
• Models have a knowledge cutoff and may not reflect the latest best practices

Users should treat agent outputs as recommendations subject to human judgment, not as authoritative decisions.

Important: The security controls described in this document are required controls that users must actively implement, configure, and maintain. Failure to implement these controls may result in unauthorized access, data exposure, or unintended infrastructure modifications.

Anthropic is responsible for the following platform-level security controls:

• Claude Code platform security and infrastructure
• API authentication and authorization
• Model safety controls and content filtering
• Rate limiting and abuse prevention
• Prompt injection detection in tool results

Users MUST implement and maintain the following security controls. Failure to implement these controls may result in unauthorized access, data exposure, or unintended infrastructure modifications:

• Secure agent configuration and rule definitions — users must define and maintain agent scope restrictions
• AWS credential management and least-privilege IAM policies — users must configure appropriate IAM roles and rotate credentials
• MCP server security review and approval — users must vet all MCP servers before adding them to .mcp.json
• File system access controls and sensitive data protection — users must review and respond to Claude Code permission prompts
• Production safety rule enforcement — users must not grant blanket approval for destructive operations
• Ongoing verification that security controls remain correctly configured — users must periodically audit agent configurations and access policies

When agents interact with AWS services via MCP servers or CLI commands, the standard AWS Shared Responsibility Model applies.

Core Principle: AWS is responsible for security OF the cloud (physical infrastructure, compute, storage, networking, and managed service infrastructure). Users are responsible for security IN the cloud (customer data, IAM policies, OS patching, network configuration, and encryption).

• Physical security of data centers and global infrastructure
• Managed service infrastructure (compute, storage, networking, databases)
• Hypervisor and host OS security for managed services
• Service availability and durability guarantees

• Identity and access management: Least-privilege IAM policies, credential rotation, MFA enforcement
• Data protection: Encryption key management, data classification, retention policies
• OS and application patching: EC2 instance OS updates, security groups, instance metadata controls
• Network configuration: VPC design, subnet isolation, security group rules, NACLs
• Service-specific configuration: S3 encryption and public access blocks, database authentication and audit logging
• Monitoring and compliance: AWS CloudTrail, AWS Config rules, Amazon GuardDuty, AWS Security Hub

Implement security controls in phased priority order. See agents/devops-agent.md Data Security section for the detailed S3 implementation pattern.

Configure least-privilege IAM for agent operations:

aws iam create-policy --policy-name claude-code-readonly --policy-document file://readonly-policy.json
aws iam attach-user-policy --user-name claude-code-user --policy-arn arn:aws:iam::<account>:policy/claude-code-readonly

Verify: aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::<account>:user/claude-code-user --action-names s3:DeleteBucket ec2:TerminateInstances --resource-arns "*" (expect: Deny for all write/delete operations)

Configure Claude Code permission settings to restrict file operations:

• Review and set permission mode to limit automatic file access: claude config set --project permissions.mode restricted
• Define allowed paths in agent task assignments via tasks.md file path column
• Verify: git diff --name-only lists only files assigned in the agent's task scope (expect: 100% match with task assignments)
• Audit: review-agent checks modified files against task scope each review cycle

Vet all MCP servers before adding to .mcp.json:

• Review server source code or documentation for data handling practices
• Verify servers do not require privileged AWS credentials: cat .mcp.json | jq '.mcpServers[] | .command, .args' (expect: no credential flags or secret references)
• Remove any unreviewed third-party servers: cat .mcp.json | jq '.mcpServers | keys' (expect: only approved servers from the MCP Server Legal Approval table)
• Validate server integrity: npx @anthropic/mcp-validator <server-name> (expect: PASS for all security checks)

Each phase must be verified before proceeding to the next:

• Phase 1: aws sts get-caller-identity returns a least-privilege role; aws iam simulate-principal-policy returns Deny for unused actions
• Phase 2: review-agent confirms all file modifications are within task scope
• Phase 3: All MCP servers in .mcp.json have completed security review