Skip to content
Back to search

guidance-for-claude-code-with-amazon-bedrock

This Guidance demonstrates how organizations can implement secure enterprise authentication for Amazon Bedrock using industry-standard protocols and AWS services

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aws-solutions-library-samples--guidance-for-claude-code-with-amazon-bedrock/badge.svg)](/listings/aws-solutions-library-samples--guidance-for-claude-code-with-amazon-bedrock)

HTML

<a href="/listings/aws-solutions-library-samples--guidance-for-claude-code-with-amazon-bedrock"><img src="/api/listings/aws-solutions-library-samples--guidance-for-claude-code-with-amazon-bedrock/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This guidance integrates Claude Code CLI and Claude Desktop with your existing OIDC identity provider (Okta, Entra ID, Auth0, Google, or Cognito User Pools) to provide federated access to Amazon Bedrock.

What You Need

- An OIDC identity provider (Okta, Entra ID, Auth0, Google, Cognito) OR AWS IAM Identity Center - AWS account with IAM and CloudFormation permissions - Amazon Bedrock activated in target regions - Python 3.10+ for deployment

What Gets Deployed

- Authentication infrastructure (IAM OIDC Provider or IDC auth stack) - Platform-specific installation packages (Windows, macOS, Linux) - Optional: OpenTelemetry monitoring + quota enforcement

**Deployment time:** 2-3 hours for initial setup. See [QUICK_START.md](QUICK_START.md) for step-by-step instructions.

Extend to Claude Cowork

If you've deployed this guidance for Claude Code, extend it to Claude Cowork (Claude Desktop) with one command:

poetry run ccwb cowork generate

This generates MDM configuration files (JSON, macOS .mobileconfig, Windows .reg) using your existing deployment profile. See the [CoWork 3P Guide](assets/docs/COWORK_3P.md) for setup and deployment details.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 109 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "aws-claude-code-plugins",
  4. "version": "1.0.0",
  5. "description": "Production-ready plugins for Claude Code: agents, hooks, and workflows",
  6. "owner": {
  7. "name": "AWS Solutions Library"
  8. },
  9. "plugins": [
  10. {
  11. "name": "epcc-workflow",
  12. "version": "3.1.0",
  13. "source": "./assets/claude-code-plugins/plugins/epcc-workflow",
  14. "description": "EPCC (Explore-Plan-Code-Commit) systematic development workflow with 12 specialized agents for exploration, planning, coding, and commit phases",
  15. "category": "workflow"
  16. },
  17. {
  18. "name": "frontend-design",
  19. "version": "1.0.0",
  20. "source": "./assets/claude-code-plugins/plugins/frontend-design",
  21. "description": "Frontend design skill for UI/UX implementation",
  22. "category": "skill"
  23. },
  24. {
  25. "name": "requirements",
  26. "version": "1.0.0",
  27. "source": "./assets/claude-code-plugins/plugins/requirements",
  28. "description": "PRD and TECH_REQ generating commands that can be used pre-EPCC workflow",
  29. "category": "workflow"
  30. },
  31. {
  32. "name": "troubleshooting",
  33. "version": "1.0.0",
  34. "source": "./assets/claude-code-plugins/plugins/troubleshooting",
  35. "description": "Troubleshooting command to assist with complex problems",
  36. "category": "troubleshooting"
  37. },
  38. {
  39. "name": "documentation",
  40. "version": "1.0.0",
  41. "source": "./assets/claude-code-plugins/plugins/documentation",
  42. "description": "Complete Diataxis documentation framework with 12 specialized agents for tutorials, how-tos, references, explanations, and analysis",
  43. "category": "documentation"
  44. },
  45. {
  46. "name": "architecture",
  47. "version": "1.0.0",
  48. "source": "./assets/claude-code-plugins/plugins/architecture",
  49. "description": "Architecture design, review, and documentation with 10 specialized agents for C4 diagrams, ADRs, and quality analysis",
  50. "category": "architecture"
  51. },
  52. {
  53. "name": "security",
  54. "version": "1.1.0",
  55. "source": "./assets/claude-code-plugins/plugins/security",
  56. "description": "Security scanning, auditing, and compliance validation with 4 specialized agents, plus fail-closed hooks: PII/secrets guard, HMAC-chained tamper-evident audit (CloudWatch dual-write), token-budget circuit breaker",
  57. "category": "security"
  58. },
  59. {
  60. "name": "testing",
  61. "version": "1.0.0",
  62. "source": "./assets/claude-code-plugins/plugins/testing",
  63. "description": "Testing, QA, and quality gates with 3 specialized agents for automated validation and code quality checks",
  64. "category": "testing"
  65. },
  66. {
  67. "name": "performance",
  68. "version": "1.0.0",
  69. "source": "./assets/claude-code-plugins/plugins/performance",
  70. "description": "Performance profiling, optimization, and monitoring with 5 specialized agents for comprehensive performance analysis",
  71. "category": "performance"
  72. },
  73. {
  74. "name": "tdd-workflow",
  75. "version": "1.0.0",
  76. "source": "./assets/claude-code-plugins/plugins/tdd-workflow",
  77. "description": "TDD workflow with 6 specialized agents for test-first development, red-green-refactor cycle, and comprehensive quality analysis",
  78. "category": "workflow"
  79. },
  80. {
  81. "name": "agile-tools",
  82. "version": "1.0.0",
  83. "source": "./assets/claude-code-plugins/plugins/agile-tools",
  84. "description": "Agile team roles: Scrum Master, Product Owner, Business Analyst, and Project Manager agents",
  85. "category": "agile"
  86. },
  87. {
  88. "name": "ux-design",
  89. "version": "1.0.0",
  90. "source": "./assets/claude-code-plugins/plugins/ux-design",
  91. "description": "UX optimization and UI design tools with accessibility validation and WCAG compliance",
  92. "category": "design"
  93. },
  94. {
  95. "name": "deployment",
  96. "version": "1.0.0",
  97. "source": "./assets/claude-code-plugins/plugins/deployment",
  98. "description": "Deployment orchestration and compliance automation with progressive rollout strategies",
  99. "category": "devops"
  100. },
  101. {
  102. "name": "code-analysis",
  103. "version": "1.0.0",
  104. "source": "./assets/claude-code-plugins/plugins/code-analysis",
  105. "description": "Code archaeology and technology evaluation for legacy systems and technical debt assessment",
  106. "category": "analysis"
  107. }
  108. ]
  109. }
README.md · README · 319 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Guidance for Claude Code and Cowork on Amazon Bedrock
  2. [![Stable Release](https://img.shields.io/github/v/release/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock?style=for-the-badge&label=stable&filter=v*.*.*)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/releases/latest)
  3. [![Beta Release](https://img.shields.io/github/v/release/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock?style=for-the-badge&include_prereleases&label=beta)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/tree/beta)
  4. This guidance enables enterprise deployment of Claude Code and Claude Cowork on Amazon Bedrock across command-line (CLI) and desktop surfaces — with secure single sign-on (SSO), usage monitoring, and cost controls.
  5. ## ℹ️ Maintenance Mode
  6. **This repository is now in maintenance mode on a best-efforts basis.** It remains available as a reference implementation. New contributions without GitHub issues approved by maintainers will not be accepted.
  7. For new deployments of Claude Apps on Amazon Bedrock, we recommend [Claude Apps Gateway](https://code.claude.com/docs/en/claude-apps-gateway) — a self-hosted service that sits between your Claude clients and your model provider. It is included in the `claude` binary, so the same executable that runs Claude Code also runs the gateway. It provides:
  8. - Corporate SSO (OIDC) with centralized policy enforcement
  9. - Per-user cost attribution and spend caps
  10. - Managed settings delivery
  11. - OTLP telemetry routing
  12. - Single stateless container deployment
  13. **👉 [Get started with Claude Apps Gateway on AWS](https://github.com/aws-samples/anthropic-on-aws/tree/main/claude-apps-gateway)**
  14. **💻 [Deploying both Claude Code CLI and Claude Desktop? Add the Bootstrap Server](https://github.com/aws-samples/anthropic-on-aws/tree/main/claude-apps-gateway-bootstrap)** — delivers managed settings, organization plugins, and per-user configuration to Claude Desktop at sign-in.
  15. <details>
  16. <summary><strong>Areas where this reference solution complements Claude Apps Gateway today</strong></summary>
  17. The following capabilities are not yet available in Claude Apps Gateway but may appear on its future roadmap. This solution provides reference patterns in the meantime:
  18. - **Claude Desktop** — spend controls and model discovery may be functional, however configuration and managed settings delivery requires MDM or per-user bootstrap server.
  19. - **AWS IAM Identity Center** — native IDC authentication without external OIDC
  20. - **Historical usage analytics** — S3 + Athena for long-term usage queries
  21. - **Multi-platform packaging** — automated installers for Windows, macOS, Linux (note: Claude Apps Gateway is native to Claude Code and requires no additional client-side packages)
  22. - **Cost tracking via IAM principal-based cost allocation** — Gateway spend controls are based on cost estimates
  23. As Claude Apps Gateway evolves, check Anthropic's documentation for the latest capabilities.
  24. </details>
  25. ---
  26. ## Key Features
  27. - **Secure Access**: Secure single sign-on (SSO) with enterprise identity providers such as Okta, Entra ID, Auth0, Google, Cognito, or AWS IAM Identity Center — temporary credentials, automatic refresh, no API keys to manage
  28. - **Usage Monitoring**: CloudWatch dashboards with per-user cost attribution, plus S3 + Athena for historical analytics
  29. - **Quota Enforcement**: Per-user and per-team token limits with configurable thresholds, warnings, and block modes
  30. - **Multi-Platform**: Windows, macOS, Linux — Go or Python binaries, pre-built from GitHub Releases
  31. - **One Deployment, Two Surfaces**: Same infrastructure powers both Claude Code CLI and Claude Desktop (which features Chat, Cowork and Code)
  32. - **Model Flexibility**: Choose from Opus, Sonnet, Haiku with model aliases (e.g. `opusplan` for Opus planning + Sonnet execution)
  33. - **Native Desktop Experience**: Deploy and manage Claude Desktop via MDM (Jamf, Intune, Group Policy)
  34. - **Dynamic Config Delivery**: Deliver per-user settings and [organization plugins](assets/docs/PLUGINS.md#bootstrap-server-delivery-dynamic) to Claude Desktop at sign-in via a bootstrap server — no MDM re-push needed for config changes
  35. - **Data Residency**: Select your cross-region inference profile (US, EU, AU) to keep data within your compliance boundary
  36. - **AWS-Native**: Your data, your AWS account, your compliance controls — no Anthropic licensing required
  37. ## Table of Contents
  38. 1. [Quick Start](#quick-start)
  39. 2. [Architecture Overview](#architecture-overview)
  40. - [Authentication Modes](#authentication-modes)
  41. - [Per-User Attribution](#per-user-attribution)
  42. 3. [How It Works](#how-it-works)
  43. - [Usage Monitoring](#usage-monitoring)
  44. - [Quota Enforcement and Cost Controls](#quota-enforcement-and-cost-controls)
  45. 4. [Deployment](#deployment)
  46. 5. [Additional Resources](#additional-resources)
  47. ## Quick Start
  48. This guidance integrates Claude Code CLI and Claude Desktop with your existing OIDC identity provider (Okta, Entra ID, Auth0, Google, or Cognito User Pools) to provide federated access to Amazon Bedrock.
  49. ### What You Need
  50. - An OIDC identity provider (Okta, Entra ID, Auth0, Google, Cognito) OR AWS IAM Identity Center
  51. - AWS account with IAM and CloudFormation permissions
  52. - Amazon Bedrock activated in target regions
  53. - Python 3.10+ for deployment
  54. ### What Gets Deployed
  55. - Authentication infrastructure (IAM OIDC Provider or IDC auth stack)
  56. - Platform-specific installation packages (Windows, macOS, Linux)
  57. - Optional: OpenTelemetry monitoring + quota enforcement
  58. **Deployment time:** 2-3 hours for initial setup. See [QUICK_START.md](QUICK_START.md) for step-by-step instructions.
  59. ### Extend to Claude Cowork
  60. If you've deployed this guidance for Claude Code, extend it to Claude Cowork (Claude Desktop) with one command:
  61. ```bash
  62. poetry run ccwb cowork generate
  63. ```
  64. This generates MDM configuration files (JSON, macOS .mobileconfig, Windows .reg) using your existing deployment profile. See the [CoWork 3P Guide](assets/docs/COWORK_3P.md) for setup and deployment details.
  65. ## Architecture Overview
  66. The architecture is modular — start with authentication, then optionally add [monitoring, quota enforcement, analytics, or distribution](#what-gets-deployed) independently as requirements grow. This guidance supports three authentication paths (see [Authentication Modes](#authentication-modes) for details). The recommended path is Direct IAM Federation:
  67. ### Recommended: Direct IAM Federation
  68. ![Architecture Diagram](assets/images/credential-flow-direct-diagram.png)
  69. 1. **User initiates authentication**: User requests access to Amazon Bedrock through Claude Code or Claude Cowork
  70. 2. **OIDC authentication**: User authenticates with their OIDC provider and receives an ID token
  71. 3. **Token exchange with AWS STS**: Application calls `AssumeRoleWithWebIdentity` with the OIDC ID token
  72. 4. **STS returns credentials**: AWS STS validates the token against the registered IAM OIDC provider and returns temporary AWS credentials (scoped to Bedrock access)
  73. 5. **Access Amazon Bedrock**: Application uses the temporary credentials to call Amazon Bedrock
  74. 6. **Bedrock response**: Amazon Bedrock processes the request and returns the response
  75. ### What Gets Deployed
  76. `ccwb init` creates a profile that selects which stacks to enable. Deploy all at once with `ccwb deploy`, or individually with `--stack <name>`:
  77. | Component | What | Deployed via |
  78. |-----------|------|-------------|
  79. | **Authentication** | IAM OIDC Provider + federated role, or IDC auth stack | `ccwb deploy --stack auth` |
  80. | **User packages** | Platform-specific binaries (credential-process, otel-helper) + install scripts | `ccwb package` |
  81. | **Monitoring** (optional) | Central mode: ECS Fargate OTEL collector + ALB. Sidecar mode: local collector on each machine. Both export to CloudWatch dashboards. | `ccwb deploy --stack monitoring` |
  82. | **Quota enforcement** (optional) | Quota check API + DynamoDB policies + per-user/team limits | `ccwb deploy --stack quota` |
  83. | **Analytics** (optional) | S3 data lake + Athena for historical SQL queries on usage data | `ccwb deploy --stack analytics` |
  84. | **Distribution** (optional) | S3 presigned URLs or self-service landing page with IdP auth | `ccwb deploy --stack distribution` |
  85. | **Diagnostics** | Installation health checks + resolved config dump | `ccwb doctor` |
  86. See [Monitoring Guide](assets/docs/MONITORING.md), [Quota Guide](assets/docs/QUOTA_MONITORING.md), [Analytics Guide](assets/docs/ANALYTICS.md), and [Distribution Comparison](assets/docs/distribution/comparison.md) for detailed setup.
  87. ### Authentication Modes
  88. This guidance supports three identity paths. Each path provides usage monitoring and audit trails. Per-user identity resolution and quota enforcement depend on the authentication mode chosen.
  89. | Mode | `ccwb init` choice | Identity Source | Session Length | Quota Enforcement | Best For |
  90. |------|--------------------|----------------|----------------|-------------------|----------|
  91. | **External IdP (OIDC)** | `OIDC / Direct IdP` | Okta, Entra ID, Auth0, Google, Cognito User Pools JWT claims | Refresh token lifetime | ✅ Full | Orgs with an existing enterprise IdP |
  92. | **AWS IAM Identity Center** | `AWS IAM Identity Center` | `AWSReservedSSO_*` IAM role ARN (email in session name) | Up to 90 days (recommended: 7 days) | ✅ Via SigV4 | Orgs on native AWS identity, or where OIDC localhost callback is blocked |
  93. | **None** | `None` | IAM user ARN or hashed role principal | AWS credential TTL | ❌ Not available | Internal tools / analytics-only deployments |
  94. For deployment patterns and best practices, see the [Claude Code deployment patterns and best practices with Amazon Bedrock](https://aws.amazon.com/blogs/machine-learning/claude-code-deployment-patterns-and-best-practices-with-amazon-bedrock/) blog post.
  95. ### Optional: Deploy Without SSO Authentication
  96. You can deploy the observability/analytics stack without configuring an identity provider. Select **"None"** during `ccwb init`.
  97. - No OIDC provider or IdP configuration required
  98. - Uses AWS IAM for access control directly
  99. - Identity detection is automatic (IDC users: email from ARN, IAM users: username, other roles: hashed identifier)
  100. - Best for: internal tools, analytics-only deployments, or orgs where users already have IAM access to Bedrock
  101. ### Per-User Attribution
  102. Per-user usage attribution works across all authentication modes and Claude Code CLI and Claude Desktop (Cowork):
  103. | Auth Mode | Identity Source | Telemetry Attribution | Quota Enforcement | CUR 2.0 Cost Visibility |
  104. |-----------|----------------|----------------------|-------------------|-------------------------|
  105. | **OIDC** | JWT email claim | Per-user (email, team, department) | ✅ | ✅ Per-user via STS session tags |
  106. | **IAM Identity Center** | IAM ARN session name | Per-user (email only) | ✅ | ✅ Per-user if [ABAC attributes](https://docs.aws.amazon.com/singlesignon/latest/userguide/abac.html) configured in IDC |
  107. | **None** | Hashed IAM principal | Anonymous | ❌ | ✅ Per-IAM-role |
  108. Usage from both Claude Code CLI and Claude Desktop (Cowork) counts toward the same per-user limit — a single quota applies regardless of which surface consumed the tokens.
  109. See [Quota Monitoring Guide](assets/docs/QUOTA_MONITORING.md) for enforcement details and [CoWork 3P Guide](assets/docs/COWORK_3P.md#quota-enforcement) for Desktop-specific behavior.
  110. ## How It Works
  111. Once distributed, the **credential-process** binary runs on each user's machine:
  112. - **Claude Code:** configured via `credential_process` in `~/.aws/config` (AWS SDK calls it automatically)
  113. - **Claude Desktop (Cowork):** configured via `inferenceBedrockProfile` MDM key pointing to the AWS profile that has `credential_process` set
  114. ```mermaid
  115. flowchart LR
  116. CC1[Claude Code CLI] -->|needs credentials| CP[credential-process binary]
  117. CC2[Claude Desktop] -->|needs credentials| CP
  118. CP --> AUTH{Auth Mode}
  119. AUTH -->|OIDC| OIDC[IdP → STS]
  120. AUTH -->|IDC| IDC[SSO → STS]
  121. OIDC --> OUT[Temporary AWS credentials]
  122. IDC --> OUT
  123. ```
  124. The **otel-helper** binary attaches per-user identity to telemetry:
  125. - **Header mode** (Claude Code CLI): Called once per OTLP export as a header provider. Returns JSON headers containing user identity (email, team, department) extracted from the cached JWT.
  126. - **Bootstrap mode** (Claude Desktop, recommended): The [bootstrap server](assets/docs/PLUGINS.md#bootstrap-server-delivery-dynamic) delivers per-user `otlpHeaders` at sign-in. Claude Desktop applies these natively — no proxy or helper needed.
  127. - **Static MDM** (Claude Desktop, basic): Set `otlpHeaders` in MDM config for device-level identity (not per-user unless you create per-device profiles).
  128. ```mermaid
  129. flowchart LR
  130. CC1[Claude Code CLI] -->|telemetry| OH[otel-helper]
  131. CC2[Claude Desktop] -->|telemetry| OH
  132. OH -->|adds user identity| COLL[Collector] --> CW[CloudWatch]
  133. ```
  134. ### Usage Monitoring
  135. Both Claude Code (CLI) and Claude Desktop emit OpenTelemetry (OTLP) telemetry. For Claude Code, otel-helper provides per-user identity headers. For Claude Desktop, the bootstrap server delivers per-user `otlpHeaders` at sign-in — no local proxy needed. See [Monitoring Guide](assets/docs/MONITORING.md) for detailed configuration.
  136. ```mermaid
  137. flowchart LR
  138. CC[Claude Code CLI] -->|OTLP| OH1[otel-helper<br/>header mode]
  139. CW[Claude Desktop] -->|OTLP with otlpHeaders| COLL[Collector]
  140. OH1 -->|"user identity + Bearer JWT"| COLL
  141. COLL --> DASH[CloudWatch Dashboards]
  142. ```
  143. | Surface | Per-user identity | How | Collector mode |
  144. |---------|------------------|-----|----------------|
  145. | **Claude Code (CLI)** | otel-helper (header mode) | Returns identity headers per export | Central or Sidecar |
  146. | **Claude Desktop (bootstrap)** | Bootstrap server delivers `otlpHeaders` | Per-user from OIDC token at sign-in | Central |
  147. | **Claude Desktop (static MDM)** | `otlpHeaders` in MDM config | Device-level (not per-user) | Central or Sidecar |
  148. > **Recommended:** Use the [bootstrap server](assets/docs/PLUGINS.md#bootstrap-server-delivery-dynamic) for per-user Claude Desktop telemetry. It delivers `otlpHeaders` with user identity at sign-in — no local proxy or helper binary needed on the Desktop machine.
  149. **Cost attribution:** Since April 2026, Amazon Bedrock supports [IAM principal cost tracking via CUR 2.0](assets/docs/COST_ATTRIBUTION.md) — per-user costs appear in Cost Explorer automatically from the STS session tags set by credential-process. Note: real-time quota enforcement relies on telemetry emitted from the client rather than actual costs metered by AWS, so figures may differ from CUR.
  150. **Dashboards:** Pre-built CloudWatch dashboards for [Claude Code](assets/images/ClaudeCodeDashboard.png) and [Claude Desktop (Cowork)](assets/images/ClaudeCoworkDashboard.png). See [Monitoring Guide](assets/docs/MONITORING.md) for setup.
  151. ### Quota Enforcement and Cost Controls
  152. Quota is enforced at the **credential layer** — before any Bedrock call is made:
  153. ```mermaid
  154. flowchart LR
  155. CP[credential-process binary] -->|"am I allowed?"| API[Quota API]
  156. API --> Lambda[Lambda]
  157. Lambda -->|check limits| DDB[(DynamoDB Policies)]
  158. Lambda -->|check usage| CW[CloudWatch Metrics]
  159. Lambda -->|allowed| OUT[✅ Credentials issued]
  160. Lambda -->|blocked| STOP[❌ Credentials denied]
  161. ```
  162. How it works:
  163. - **Policies** (DynamoDB): Admins set per-user or per-team monthly/daily token limits via `ccwb quota` commands
  164. - **Usage** (CloudWatch): The OTEL collector aggregates token consumption metrics per user
  165. - **Check** (Lambda): On each credential request, compares current usage against the policy limit
  166. - **Enforcement**: If over limit, credentials are withheld and the user sees a quota exceeded message
  167. If a user exceeds their quota, access to Bedrock is denied until usage resets or an admin unblocks them. See [Quota Guide](assets/docs/QUOTA_MONITORING.md) for configuration details.
  168. ## Deployment
  169. ### Requirements
  170. - Python 3.10+, Poetry, AWS CLI v2, Git
  171. - AWS account with Bedrock activated and IAM/CloudFormation permissions
  172. - OIDC identity provider (Okta, Entra ID, Auth0, Google, Cognito) or AWS IAM Identity Center
  173. - Go 1.24+ (optional — only for local builds; [pre-built binaries](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/releases) available from v2.4.0+)
  174. **End users need only:** Claude Code or Claude Desktop installed. No Python, AWS account, or build tools required — IT distributes pre-built packages.
  175. See [QUICK_START.md](QUICK_START.md) for the full step-by-step walkthrough.
  176. ### Supported Regions
  177. Deploys to any AWS region with Bedrock support, across both AWS Commercial and AWS GovCloud (US) partitions. During `ccwb init`, select your region and the wizard auto-configures partition-appropriate models and endpoints.
  178. ### Cross-Region Inference
  179. Select your preferred model (Opus, Sonnet, Haiku) and cross-region inference profile (US, EU, AU) for optimal routing and data residency. Modern Claude models (3.7+) require cross-region inference.
  180. See [Model Configuration](https://code.claude.com/docs/en/model-config) for model aliases (including `opusplan` for Opus planning + Sonnet execution).
  181. ### Platform Support
  182. | Platform | Architecture | Build Methods |
  183. |----------|-------------|---------------|
  184. | Windows | x64 | Go (recommended) or Nuitka via CodeBuild |
  185. | macOS | ARM64 / Intel / Universal | Go or PyInstaller |
  186. | Linux | x86_64 / ARM64 | Go or PyInstaller (Docker) |
  187. **Pre-built binaries:** From v2.4.0+, [GitHub Releases](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/releases) include binaries for all platforms — no local build tools needed.
  188. See [QUICK_START.md](QUICK_START.md#platform-builds) for build configuration.
  189. ## Additional Resources
  190. ### Getting Started
  191. - [Quick Start Guide](QUICK_START.md) - Step-by-step deployment walkthrough
  192. - [CLI Reference](assets/docs/CLI_REFERENCE.md) - Complete command reference for the `ccwb` tool
  193. - [Troubleshooting](assets/docs/TROUBLESHOOTING.md) - Common issues, `ccwb doctor`, and how to file bugs
  194. - [Workshop: Claude Code on Amazon Bedrock](https://catalog.workshops.aws/claude-code-on-amazon-bedrock/en-US) - Companion hands-on workshop
  195. - [Claude Code deployment patterns and best practices with Amazon Bedrock](https://aws.amazon.com/blogs/machine-learning/claude-code-deployment-patterns-and-best-practices-with-amazon-bedrock/) - Blog post covering deployment patterns and best practices
  196. ### Architecture & Deployment
  197. - [Architecture Guide](assets/docs/ARCHITECTURE.md) - System architecture and design decisions
  198. - [Deployment Guide](assets/docs/DEPLOYMENT.md) - Advanced deployment options
  199. - [Distribution Comparison](assets/docs/distribution/comparison.md) - Presigned URLs vs Landing Page
  200. - [Local Testing Guide](assets/docs/LOCAL_TESTING.md) - Testing before deployment
  201. ### Monitoring & Analytics
  202. - [Monitoring Guide](assets/docs/MONITORING.md) - OpenTelemetry setup and dashboards
  203. - [Analytics Guide](assets/docs/ANALYTICS.md) - S3 data lake and Athena SQL queries
  204. ### Cost Management
  205. - [Cost Estimates](assets/docs/COST_ESTIMATES.md) - High-level monthly cost estimates by deployment tier and team size
  206. - [Cost Attribution](assets/docs/COST_ATTRIBUTION.md) - Per-user and per-team cost tracking via CUR 2.0 and Cost Explorer
  207. ### Plugins
  208. - [Example Plugins](assets/claude-code-plugins/) - Example plugins for Claude Code and Cowork 3P ([distribution guide](assets/docs/PLUGINS.md))
  209. ### Claude Cowork (Desktop)
  210. - [CoWork 3P Guide](assets/docs/COWORK_3P.md) - Setup and deployment for Claude Desktop with Bedrock
  211. - [AWS Blog: Running Claude Cowork in Amazon Bedrock](https://aws.amazon.com/blogs/machine-learning/from-developer-desks-to-the-whole-organization-running-claude-cowork-in-amazon-bedrock/)
  212. ### Identity Provider Setup
  213. - [Okta](assets/docs/providers/okta-setup.md)
  214. - [Microsoft Entra ID](assets/docs/providers/microsoft-entra-id-setup.md)
  215. - [Auth0](assets/docs/providers/auth0-setup.md)
  216. - [Google](assets/docs/providers/google-oidc-setup.md)
  217. - [AWS Cognito User Pool](assets/docs/providers/cognito-user-pool-setup.md)
  218. - [Generic OIDC (PingFederate, Keycloak, ForgeRock, etc.)](assets/docs/providers/generic-oidc-setup.md)
  219. ## License
  220. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
assets/claude-code-plugins/plugins/security/hooks/command_security_check.sh · Bundled script · 279 lines · 2 findings marked
  1. #!/bin/bash
  2. # Command Security Check Hook
  3. #
  4. # This hook validates Bash commands for security compliance:
  5. # - Blocks destructive commands (rm -rf /, chmod 777, etc.)
  6. # - Flags suspicious operations (curl | sh, eval, etc.)
  7. # - Requires confirmation for sensitive operations
  8. # - Blocks sudo operations entirely
  9. #
  10. # Exit codes:
  11. # 0 - Command passes all security checks
  12. # 1 - Warning issued but command continues
  13. # 2 - Security violation, command blocked (Claude will correct)
  14. #
  15. # Author: Claude Code Advanced Patterns
  16. # Version: 1.0.0
  17. set -euo pipefail
  18. # Read Claude Code hook input from stdin
  19. INPUT_JSON=$(cat)
  20. # Extract command from hook input
  21. COMMAND=$(echo "$INPUT_JSON" | jq -r '.tool_input.command // empty')
  22. PROJECT_ROOT=${CLAUDE_PROJECT_DIR:-$(pwd)}
  23. if [ -z "$COMMAND" ]; then
  24. # No command to validate
  25. exit 0
  26. fi
  27. # Function to log security events
  28. log_security_event() {
  29. local event_type="$1"
  30. local command="$2"
  31. local result="$3"
  32. local log_dir="$PROJECT_ROOT/.claude"
  33. mkdir -p "$log_dir"
  34. local log_file="$log_dir/security-audit.log"
  35. local timestamp=$(date '+%Y-%m-%d %H:%M:%S')
  36. echo "$timestamp COMMAND_SECURITY_CHECK $event_type \"$command\" $result" >> "$log_file"
  37. }
  38. # Function to block dangerous commands
  39. check_dangerous_commands() {
  40. local cmd="$1"
  41. # Extremely dangerous commands that should never be allowed
  42. local dangerous_patterns=(
  43. "rm -rf /"
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 52 on GitHub
  44. "rm -rf \*"
  45. "> /dev/sda"
  46. "dd if=/dev/zero"
  47. "mkfs\."
  48. "fdisk /dev/"
  49. "parted /dev/"
  50. ":(){ :|:& };:" # Fork bomb
    • Note: Quoted as data in code: Matches a classic shell fork-bomb pattern
    • Line 59 on GitHub
  51. )
  52. for pattern in "${dangerous_patterns[@]}"; do
  53. if [[ "$cmd" == *"$pattern"* ]]; then
  54. echo "❌ SECURITY VIOLATION: Dangerous command blocked" >&2
  55. echo "Command: $cmd" >&2
  56. echo "" >&2
  57. echo "This command could cause system damage or data loss." >&2
  58. echo "Operation blocked for security reasons." >&2
  59. log_security_event "DANGEROUS_COMMAND" "$cmd" "BLOCKED"
  60. exit 2
  61. fi
  62. done
  63. }
  64. # Function to check for suspicious operations
  65. check_suspicious_operations() {
  66. local cmd="$1"
  67. # More precise patterns to avoid false positives
  68. # These patterns specifically target download-and-execute scenarios
  69. local suspicious_patterns=(
  70. "curl\s+[^|]*\|\s*(sh|bash)\s*$"
  71. "wget\s+[^|]*\|\s*(sh|bash)\s*$"
  72. "curl\s+.*\s+\|\s+sh\s+"
  73. "wget\s+.*\s+\|\s+bash\s+"
  74. "(curl|wget)\s+.*\s*\|\s*(sh|bash)\s*$"
  75. )
  76. for pattern in "${suspicious_patterns[@]}"; do
  77. if echo "$cmd" | grep -qE "$pattern"; then
  78. # Additional validation to reduce false positives
  79. # Allow common legitimate patterns like "git diff | grep" or "cat file | head"
  80. if echo "$cmd" | grep -qE "^(git|cat|ls|find|grep|awk|sed|head|tail|sort|uniq)\s+.*\|" && ! echo "$cmd" | grep -qE "(curl|wget)\s+.*\|\s+(sh|bash)"; then
  81. log_security_event "LEGITIMATE_PIPE" "$cmd" "ALLOWED"
  82. continue
  83. fi
  84. echo "❌ SECURITY VIOLATION: Suspicious download and execute pattern" >&2
  85. echo "Command: $cmd" >&2
  86. echo "" >&2
  87. echo "Downloading and executing scripts from the internet is dangerous." >&2
  88. echo "" >&2
  89. echo "Safer alternatives:" >&2
  90. echo " 1. Download first: curl -o script.sh https://example.com/script.sh" >&2
  91. echo " 2. Review the script: cat script.sh" >&2
  92. echo " 3. Execute if safe: bash script.sh" >&2
  93. log_security_event "SUSPICIOUS_DOWNLOAD" "$cmd" "BLOCKED"
  94. exit 2
  95. fi
  96. done
  97. }
  98. # Function to check for command injection risks
  99. check_command_injection() {
  100. local cmd="$1"
  101. # Check for eval usage
  102. if echo "$cmd" | grep -qE "\beval\b"; then
  103. echo "⚠️ SECURITY WARNING: eval usage detected" >&2
  104. echo "Command: $cmd" >&2
  105. echo "" >&2
  106. echo "The 'eval' command can be dangerous as it executes arbitrary code." >&2
  107. echo "Please ensure the evaluated string is properly sanitized." >&2
  108. log_security_event "EVAL_USAGE" "$cmd" "WARNING"
  109. # Continue with warning (exit 0)
  110. fi
  111. # Check for exec usage
  112. if echo "$cmd" | grep -qE "\bexec\b.*\$"; then
  113. echo "⚠️ SECURITY WARNING: exec with variable detected" >&2
  114. echo "Command: $cmd" >&2
  115. echo "" >&2
  116. echo "Using 'exec' with variables can be risky." >&2
  117. echo "Ensure variables are properly validated." >&2
  118. log_security_event "EXEC_VARIABLE" "$cmd" "WARNING"
  119. # Continue with warning
  120. fi
  121. }
  122. # Function to check for destructive file operations
  123. check_destructive_operations() {
  124. local cmd="$1"
  125. # Check for dangerous rm operations
  126. if echo "$cmd" | grep -qE "rm\s+.*-r.*-f|rm\s+.*-rf|rm\s+.*-fr"; then
  127. # Allow common safe patterns
  128. if echo "$cmd" | grep -qE "rm\s+-rf?\s+(\.pytest_cache|\*\.pyc|__pycache__|node_modules|\.git|build|dist|\.venv)"; then
  129. log_security_event "RM_RF_SAFE" "$cmd" "ALLOWED"
  130. return 0
  131. fi
  132. echo "⚠️ SECURITY WARNING: Recursive force delete detected" >&2
  133. echo "Command: $cmd" >&2
  134. echo "" >&2
  135. echo "The 'rm -rf' command permanently deletes files and directories." >&2
  136. echo "Please double-check the target path is correct." >&2
  137. log_security_event "RM_RF_WARNING" "$cmd" "WARNING"
  138. # Continue with warning
  139. fi
  140. # Check for dangerous chmod operations
  141. if echo "$cmd" | grep -qE "chmod\s+(777|666)"; then
  142. echo "❌ SECURITY VIOLATION: Dangerous permissions detected" >&2
  143. echo "Command: $cmd" >&2
  144. echo "" >&2
  145. echo "Setting permissions to 777 or 666 makes files world-writable." >&2
  146. echo "This is a security risk." >&2
  147. echo "" >&2
  148. echo "Safer alternatives:" >&2
  149. echo " chmod 755 file # Executable files" >&2
  150. echo " chmod 644 file # Regular files" >&2
  151. echo " chmod 600 file # Private files" >&2
  152. log_security_event "DANGEROUS_CHMOD" "$cmd" "BLOCKED"
  153. exit 2
  154. fi
  155. }
  156. # Function to check operations requiring confirmation
  157. check_confirmation_required() {
  158. local cmd="$1"
  159. local confirmation_patterns=(
  160. "git push.*--force"
  161. "git push.*-f\b"
  162. "git reset.*--hard"
  163. "npm publish"
  164. "pip upload"
  165. "pypi upload"
  166. "docker push.*:latest"
  167. "kubectl delete"
  168. "terraform destroy"
  169. "aws.*delete"
  170. "gcloud.*delete"
  171. )
  172. for pattern in "${confirmation_patterns[@]}"; do
  173. if echo "$cmd" | grep -qE "$pattern"; then
  174. echo "⚠️ SECURITY WARNING: Potentially destructive operation" >&2
  175. echo "Command: $cmd" >&2
  176. echo "" >&2
  177. echo "This command could have significant impact." >&2
  178. echo "Please ensure you want to proceed with this operation." >&2
  179. log_security_event "CONFIRMATION_REQUIRED" "$cmd" "WARNING"
  180. # Continue with warning, don't block
  181. return 0
  182. fi
  183. done
  184. }
  185. # Function to block sudo operations
  186. check_sudo_usage() {
  187. local cmd="$1"
  188. if echo "$cmd" | grep -qE "^\s*sudo\b"; then
  189. echo "❌ SECURITY VIOLATION: sudo operations not permitted" >&2
  190. echo "Command: $cmd" >&2
  191. echo "" >&2
  192. echo "Claude Code hooks should not use sudo for security reasons." >&2
  193. echo "" >&2
  194. echo "If elevated privileges are needed:" >&2
  195. echo " 1. Run the command manually outside Claude Code" >&2
  196. echo " 2. Use user-level alternatives (e.g., --user flag for pip)" >&2
  197. echo " 3. Configure system permissions appropriately" >&2
  198. log_security_event "SUDO_BLOCKED" "$cmd" "BLOCKED"
  199. exit 2
  200. fi
  201. }
  202. # Function to check for network security issues
  203. check_network_security() {
  204. local cmd="$1"
  205. # Check for connections to suspicious domains
  206. if echo "$cmd" | grep -qE "(localhost|127\.0\.0\.1).*\|.*sh"; then
  207. echo "❌ SECURITY VIOLATION: Local network execution detected" >&2
  208. echo "Command: $cmd" >&2
  209. echo "" >&2
  210. echo "Connecting to localhost and executing commands is suspicious." >&2
  211. log_security_event "LOCALHOST_EXEC" "$cmd" "BLOCKED"
  212. exit 2
  213. fi
  214. # Check for unencrypted downloads of executables
  215. if echo "$cmd" | grep -qE "http://.*\.(sh|py|pl|rb|exe|bin)"; then
  216. echo "⚠️ SECURITY WARNING: Unencrypted download of executable" >&2
  217. echo "Command: $cmd" >&2
  218. echo "" >&2
  219. echo "Downloading executables over HTTP is insecure." >&2
  220. echo "Consider using HTTPS instead." >&2
  221. log_security_event "HTTP_EXECUTABLE" "$cmd" "WARNING"
  222. # Continue with warning
  223. fi
  224. }
  225. # Main security validation
  226. main() {
  227. echo "Checking command security: $COMMAND" >&2
  228. # Run all security checks
  229. check_dangerous_commands "$COMMAND"
  230. check_suspicious_operations "$COMMAND"
  231. check_command_injection "$COMMAND"
  232. check_destructive_operations "$COMMAND"
  233. check_confirmation_required "$COMMAND"
  234. check_sudo_usage "$COMMAND"
  235. check_network_security "$COMMAND"
  236. # Log successful validation
  237. log_security_event "COMMAND_CHECK" "$COMMAND" "PASSED"
  238. echo "Command security check passed" >&2
  239. exit 0
  240. }
  241. # Error handling
  242. trap 'echo "Security hook error on line $LINENO" >&2; exit 0' ERR
  243. # Run main function
  244. main

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.