Document credential access in execute_bash tool #1005
+142
−8
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Document how the secret manager works with execute_bash tool to help agents understand how to access registered credentials in bash commands. The new section explains: - Automatic secret injection mechanism - How to reference secrets in commands (using environment variable syntax) - Case-insensitive secret detection - Automatic output masking for security Co-authored-by: openhands <openhands@all-hands.dev>
xingyaoww
commented
Nov 3, 2025
This change enhances the execute_bash tool to show agents which secrets are available for use in bash commands. The available secret names are now populated in CmdOutputMetadata and displayed in the LLM-facing observation output. Changes: - Add available_secrets field to CmdOutputMetadata - Populate available_secrets from conversation's secret_registry - Display available secrets in ExecuteBashObservation.to_llm_content - Add test to verify the new functionality This helps agents discover what credentials they can access without having to guess or try different secret names. Co-authored-by: openhands <openhands@all-hands.dev>
Contributor
Coverage Report •
|
||||||||||||||||||||||||||||||
Collaborator
Author
|
@OpenHands merge from main and resolve all conflicts for this pr |
|
I'm on it! xingyaoww can track my progress at all-hands.dev |
Resolved conflicts: - openhands-tools/openhands/tools/terminal/impl.py: * Combined available_secrets population logic from feature branch * Updated to use observation.text instead of observation.output (API change in main) * Maintained proper secret masking with ExecuteBashObservation.from_text() - tests/tools/terminal/test_secrets_masking.py: * Updated test to use from_text() instead of output parameter Co-authored-by: openhands <openhands@all-hands.dev>
SummaryI have successfully merged the What Was DoneMerge Conflict Resolution:
Verification✅ All pre-commit hooks pass (Ruff format, Ruff lint, pycodestyle, pyright) The PR #1005 is now fully up-to-date with the latest changes from main (v1.1.0 release) and ready for review! |
enyst
reviewed
Nov 11, 2025
enyst
reviewed
Nov 11, 2025
Test verifies that shell parameter expansion syntax like ${GITHUB_TOKEN:0:8}
is properly detected by the secret manager's find_secrets_in_text method.
The test covers various parameter expansion forms:
- ${var:offset:length} - substring expansion
- ${var:-default} - default value if unset
- ${var:?error} - error if unset
- ${var#pattern} - remove shortest prefix match
- ${var%pattern} - remove shortest suffix match
This ensures agents can safely use these bash features with secrets.
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Engel Nyst <engel.nyst@gmail.com>
Add documentation explaining that secrets like GITHUB_TOKEN may be updated periodically or expire over time. When authentication failures occur, agents should try using the secret again in a new command to pick up the refreshed value. Include specific example of updating git remote URLs with refreshed GITHUB_TOKEN. Co-authored-by: openhands <openhands@all-hands.dev>
enyst
reviewed
Nov 11, 2025
| * How to use secrets: Simply reference the secret key in your command (e.g., `echo ${GITHUB_TOKEN:0:8}` or `curl -H "Authorization: Bearer $API_KEY" https://api.example.com`). The system will detect the key name in your command text and export it as environment variable before it executes your command. | ||
| * Secret detection: The system performs case-insensitive matching to find secret keys in your command text. If a registered secret key appears anywhere in your command, its value will be made available as an environment variable. | ||
| * Security: Secret values are automatically masked in command output to prevent accidental exposure. You will see `<secret-hidden>` instead of the actual secret value in the output. | ||
| * Refreshing expired secrets: Some secrets (like GITHUB_TOKEN) may be updated periodically or expire over time. If a secret stops working (e.g., authentication failures), try using it again in a new command - the system will automatically use the refreshed value. For example, if GITHUB_TOKEN was used in a git remote URL and later expired, you can update the remote URL with the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git` to pick up the refreshed token value. |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Refreshing expired secrets: Some secrets (like GITHUB_TOKEN) may be updated periodically or expire over time. If a secret stops working (e.g., authentication failures), try using it again in a new command - the system will automatically use the refreshed value. For example, if GITHUB_TOKEN was used in a git remote URL and later expired, you can update the remote URL with the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git` to pick up the refreshed token value. | |
| * Refreshing expired secrets: Some secrets (like GITHUB_TOKEN) may be updated periodically or expire over time. If a secret stops working (e.g., authentication failures), try using it again in a new command - the system should automatically use the refreshed value. For example, if GITHUB_TOKEN was used in a git remote URL and later expired, you can update the remote URL with the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git` to pick up the refreshed token value. | |
| * If it still fails, report it to the user. |
OK! Looks good. Verbose, but these LLMs will deal with it.
This is not always true, though: this happens on the Cloud, and I don't think, as of now, anywhere else in the project. So how about we add an escape hatch, maybe, for the LLM to not assume it will always happen?
Collaborator
There was a problem hiding this comment.
e.g.
"* If it still fails, report it to the user."
or "you can ask the user about it"
Contributor
|
[Automatic Post]: This PR seems to be currently waiting for review. @malhotra5, could you please take a look when you have a chance? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR enhances the
execute_bashtool to help agents understand and use the secret manager system effectively.Changes
1. Documentation (Initial Commit)
Added a new "Credential Access" section to the
TOOL_DESCRIPTIONinopenhands-tools/openhands/tools/execute_bash/definition.pythat documents:$GITHUB_TOKEN,$API_KEY)2. Available Secrets in Metadata (New Feature)
Enhanced
ExecuteBashObservationto show agents which secrets are available:available_secretsfield toCmdOutputMetadatato store list of available secret namesconversation.state.secret_registry.secret_sources.keys()in the executorExecuteBashObservation.to_llm_content()showing format:[Available secrets: $SECRET1, $SECRET2, $SECRET3]test_bash_executor_metadata_available_secrets()to verify the functionalityThis helps agents discover what credentials they can access without having to guess or try different secret names.
Implementation Details
The implementation reflects the actual secret manager behavior in
openhands-tools/openhands/tools/execute_bash/impl.py:_export_envs()method callssecret_registry.get_secrets_as_env_vars(action.command)export KEY="value"before the actual command runs<secret-hidden>insteadTesting
tests/tools/execute_bash/test_secrets_masking.py(3 tests)test_bash_executor_metadata_available_secrets()verifies:metadata.available_secrets$prefixExample Output
When an agent executes a bash command with secrets available, they'll now see:
Why This Matters
This enhancement helps agents:
Co-authored-by: openhands openhands@all-hands.dev
Agent Server images for this PR
• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server
Variants & Base Images
eclipse-temurin:17-jdknikolaik/python-nodejs:python3.12-nodejs22golang:1.21-bookwormPull (multi-arch manifest)
# Each variant is a multi-arch manifest supporting both amd64 and arm64 docker pull ghcr.io/openhands/agent-server:f90c770-pythonRun
All tags pushed for this build
About Multi-Architecture Support
f90c770-python) is a multi-arch manifest supporting both amd64 and arm64f90c770-python-amd64) are also available if needed