AWS amazonq high security documentation change
Summary
Complete restructuring of documentation with new sections about chat commands, tool permissions management, security risks, and safety recommendations. Added detailed explanations of security controls and warnings about trusting tools.
Security assessment
Added explicit 'Security risks' section warning about '/tools trustall' risks including unintended system changes, AWS resource modifications, data loss, and security vulnerabilities. Introduces security documentation for granular tool permissions management.
Diff
diff --git a/amazonq/latest/qdeveloper-ug/command-line-chat.md b/amazonq/latest/qdeveloper-ug/command-line-chat.md index ae69c58b2..db72e3467 100644 --- a//amazonq/latest/qdeveloper-ug/command-line-chat.md +++ b//amazonq/latest/qdeveloper-ug/command-line-chat.md @@ -5 +5 @@ -Context integrationPrompt for actionsUsage +Starting a chat sessionChat commandsEntering multiline inputManaging tool permissionsSummarizing conversationsSecurity risksSafety recommendations @@ -7 +7 @@ Context integrationPrompt for actionsUsage -# Chatting with Amazon Q in the command line +# Using chat on the command line @@ -9 +9 @@ Context integrationPrompt for actionsUsage -The Amazon Q command-line interface (CLI) allows you to interact with Amazon Q. With Amazon Q for command line, you can engage in natural language conversations, ask questions, and receive responses from Amazon Q within your terminal environment. +The Amazon Q Developer CLI provides an interactive chat experience directly in your terminal. You can ask questions, get help with AWS services, troubleshoot issues, and generate code snippets without leaving your command line environment. @@ -11 +11 @@ The Amazon Q command-line interface (CLI) allows you to interact with Amazon Q. -## Context integration +## Starting a chat session @@ -13 +13 @@ The Amazon Q command-line interface (CLI) allows you to interact with Amazon Q. -Amazon Q for command line integrates contextual information from your local development environment. This context integration enhances the Amazon Q with understanding of your specific use case, enabling it to provide more relevant and context-aware responses. +To start a chat session with Amazon Q, use the `chat` subcommand: @@ -15 +14,0 @@ Amazon Q for command line integrates contextual information from your local deve -## Prompt for actions @@ -17 +16 @@ Amazon Q for command line integrates contextual information from your local deve -Amazon Q for command line allows you to interact with Amazon Q and grant it permission to perform tasks on your behalf. You can ask Amazon Q complex questions, and it provides feedback or potential solutions using the conversation as context, as well as information and context outside of the conversation by leveraging tools. These tools can read and write files, execute code, and query AWS resources. When performing operations using the tools, Amazon Q generally prompts you to confirm that you want to allow it to perform those actions. Amazon Q doesn’t seek permission for the following readonly commands: `ls`, `cat`, `echo`, `pwd`, `which`, `head`, and `tail`. Also, Amazon Q doesn’t seek permissions for querying AWS resources or to read files. + $ q chat @@ -19 +18 @@ Amazon Q for command line allows you to interact with Amazon Q and grant it perm -## Usage +This opens an interactive chat session where you can type questions or commands. @@ -21 +20 @@ Amazon Q for command line allows you to interact with Amazon Q and grant it perm -**To start using Amazon Q for command line** +To exit the chat session, type `/quit` or press **Ctrl** **+D** . @@ -23 +22 @@ Amazon Q for command line allows you to interact with Amazon Q and grant it perm - 1. [Install the Amazon Q command line.](./command-line-installing.html) +## Chat commands @@ -25 +24 @@ Amazon Q for command line allows you to interact with Amazon Q and grant it perm - 2. Open your terminal or command prompt. +Amazon Q supports several commands that you can use during a chat session. These commands start with a forward slash (`/`). @@ -27 +26,14 @@ Amazon Q for command line allows you to interact with Amazon Q and grant it perm - 3. Initiate a conversation with Amazon Q using the the following chat command: `q chat`. +Chat commands Command | Description +---|--- +`!` | Executes a shell command from inside an Amazon Q CLI session. +`/editor` | Uses the configured editor to compose prompts. +`/help` | Displays a list of available commands. +`/issue` | Reports an issue or make a feature request. +`/quit` | Exits the chat session. +`/clear` | Clears the chat history from the current session. +`/reset` | Resets the conversation context, clearing all previous messages. +`/tools` | Manages tools and permissions for tools that Amazon Q can use. +`/acceptall` | Deprecated. Disables confirmation prompts when Amazon Q performs actions on your system. +`/profile` | Manages AWS profiles for AWS CLI commands. +`/context` | Manages the context information available to Amazon Q. +`/compact` | Compacts the conversation history and shows the output of the compacted conversation history. @@ -29 +41 @@ Amazon Q for command line allows you to interact with Amazon Q and grant it perm -If you didn't log into Amazon Q, you will be directed to the [AWS Build ID login page](https://docs.aws.amazon.com/signin/latest/userguide/sign-in-aws_builder_id.html) to allow permission to Amazon Q for command line. +## Entering multiline input @@ -31 +43 @@ If you didn't log into Amazon Q, you will be directed to the [AWS Build ID login - 4. Type your query or input, and then enter your query or input. +To enter multiple lines of text in a single message, use triple backticks (`````) to start and end a multiline block: @@ -33 +44,0 @@ If you didn't log into Amazon Q, you will be directed to the [AWS Build ID login -Amazon Q processes your input, considering any provided context, and responds with its output. You can request assistance with coding, development, or technical questions. @@ -35 +46,119 @@ Amazon Q processes your input, considering any provided context, and responds wi - 5. Continue the conversation by providing additional input or asking follow-up questions. + Amazon Q> ``` + def hello_world(): + print("Hello, world!") + + hello_world() + ``` + +This is particularly useful when sharing code snippets or configuration files with Amazon Q. + +## Managing tool permissions + +You can use the `/tools` command to manage permissions for tools that Amazon Q uses to perform actions on your system. This provides granular control over what actions Amazon Q can perform. + +Tools commands Command | Description +---|--- +`help` | Shows help related to tools. +`trust` | Trusts a specific tool for the session. +`untrust` | Reverts a tool to per-request confirmation. +`trustall` | Trusts all tools (equivalent to deprecated /acceptall). +`reset` | Resets all tools to default permission levels. + +To view the current permission settings for all tools: + + + $ q chat + Amazon Q> /tools + +This displays a list of all available tools and their current permission status (trusted or per-request). + +To trust or untrust a specific tool for the current session: + + + Amazon Q> /tools trust fs_read + Amazon Q> /tools untrust execute_bash + + + +You can also trust all tools at once with `/tools trustall`(equivalent to the deprecated `/acceptall` command): + + + Amazon Q> /tools trustall + +###### Warning + +Using `/tools trustall` carries risks. For more information, see Security risks. + + + +The following image shows the status of the CLI tools when they are all in the trusted status. + + + +The following tools are natively available for Amazon Q to use: + +Available tools Tool | Description +---|--- +`fs_read` | Reads files and directories on your system. +`fs_write` | Creates and modifies files on your system. +`execute_bash` | Executes bash commands on your system. +`use_aws` | Makes AWS CLI calls to interact with AWS services. +`report_issue` | Opens a browser to report an issue with the chat to AWS. +`reset` | Reset all tools to default permission levels. + +When Amazon Q attempts to use a tool that doesn't have explicit permission, it will ask for your approval before proceeding. You can choose to allow or deny the action, or trust the tool for the remainder of your session. + + + +Each tool has a default trust behavior. `fs_read` is the only tool that is trusted by default. + +When Amazon Q uses a tool, it shows you the trust permission being used. + + + +You can also specify trust permissions as part of starting a `q chat` session. + + + +## Summarizing conversations + +The `/compact` command compacts the conversation history and shows the output of the compacted conversation history. + +When the length of characters in your conversation history approaches the limit, Amazon Q provides a warning message, indicating that you should `/compact` your conversation history + + + + + +## Security risks + +Using `/tools trustall` or `/acceptall` introduces significant security risks: + + * _Unintended system changes_ : Amazon Q may interpret your requests in unexpected ways, leading to unintended modifications + + * _AWS resource modifications_ : Resources could be created, modified, or deleted without confirmation, potentially affecting production environments or incurring costs + + * _Data loss_ : Commands that delete or overwrite files will execute without confirmation + + * _Security vulnerabilities_ : Commands that could compromise system security will execute without review + + + + +###### Warning + +AWS recommends against using `/tools trustall` or `/acceptall` mode in production environments or when working with sensitive data or resources. You are responsible for all actions performed by Amazon Q when `/acceptall` mode is enabled. + +## Safety recommendations + +If you must use `/tools trustall` or `/acceptall`, follow these safety practices: + + * Only use in development or testing environments, never in production + + * Enable `/acceptall` only for specific tasks, then immediately disable it + + * Back up important data before enabling `/acceptall` + + * Use AWS credentials with minimal permissions when `/acceptall` is enabled + + * Carefully monitor all actions Amazon Q takes while `/acceptall` is enabled @@ -46 +175 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Uninstalling +Installing @@ -48 +177 @@ Uninstalling -Command line completions +Context Management