RFC: on-boot materialization of _-prefixed SSM secrets into $HERMES_HOME/.env - #24
Closed
capotej wants to merge 1 commit into
Closed
RFC: on-boot materialization of _-prefixed SSM secrets into $HERMES_HOME/.env#24capotej wants to merge 1 commit into
capotej wants to merge 1 commit into
Conversation
…ES_HOME/.env Propose an on-boot, in-container mechanism: any SSM SecureString under /bclaw/ whose leaf starts with _ (e.g. /bclaw/_MY_API_KEY) is fetched inside the container via the task role, decrypted, and written to $HERMES_HOME/.env on every boot. Hermes' existing env_loader.load_hermes_dotenv already sources that file, so the values reach the gateway with no task-def secrets[] entry, no template edit, and no per-secret redeploy. SSM edit + task restart auto-rotates. Doing the fetch in-container (vs. deployer-side) keeps secret plaintext off the deployer host and out of the agent's context -- the agent only ever sees exit codes. Adds a scoped task-role ssm:GetParameter(s)+kms:Decrypt grant and a non-fatal boot-time SSM step (mirrors the gh-auth block posture). BLOCKING DEPENDENCY: the harness image (ghcr.io/boldblackai/harness) does not ship the aws CLI today, and the boot Command calls aws ssm inside the container. The Command guards on 'command -v aws' and silently no-ops without it, so this RFC cannot land until aws is added to the image. Flagged as the first checklist item and the first integration-cycle gate.
Contributor
Author
|
closing in favor of a native hermes aws ssm plugin |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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
Proposes a template-free escape hatch for forwarding operator-specific env vars into the running claw: any SSM SecureString under
/bclaw/whose leaf name starts with_(e.g./bclaw/_MY_API_KEY) is fetched inside the container via the task role, decrypted, and written to$HERMES_HOME/.envon every boot. Hermes already sources that file (env_loader.load_hermes_dotenv), so the values reach the gateway with no task-defsecrets[]entry, notemplate.yamledit, and no per-secret redeploy. Editing the SSM param + restarting the task auto-rotates the value.This is
Status: Proposed— doc-only (a new RFC underrfcs/). Notemplate/orsrc/changes in this PR.Why in-container (not deployer-side)
An earlier draft materialized
.envfrom the deployer shell duringsetup-bclaw. That design was rejected because it routes secret plaintext through the deployer host and the agent's context:get-parameters --with-decryption --query '...Value]'prints values the agent captures, and themanage-bclawtransfer transport (CHUNK=$(cat "$f")+--commandembedding) would flow the base64 of a secret-laden.envthrough the agent's tool calls. Decoding base64 is trivial, so that's plaintext-in-context in practice.Doing the fetch inside the container under the task role removes that exposure entirely — the agent only ever sees exit codes. As a bonus, running it on every boot makes rotation automatic.
awsThe boot
Commandcallsaws ssminside the container, butghcr.io/boldblackai/harnessdoes not ship theawsCLI today (it shipsghandhermes; everyawscall in the shipped skills runs on the deployer host or the EC2 instance, never in the container). TheCommandguards oncommand -v awsand degrades gracefully (non-fatal no-op), so the gateway never crashes — but the feature is inert on every claw untilawsis added to the image.That image change is a blocking upstream prerequisite, called out as the RFC's first
## Dependenciesbullet, the firstEdge cases & risksbullet, the first implementation-checklist item, and the first integration-cycle gate. If shippingawsproves undesirable, the RFC lists fallbacks (root-stage image fixup,boto3, or revert to the deployer-side design) — none chosen; in-imageawsis preferred.Decisions worth a glance on review
/bclaw/_*only — deeper nesting (/bclaw/sub/_BAR) is ignored (path filter is non-recursive/bclaw).DescribeParametersonResource: "*". List-style SSM actions can't be ARN-scoped; mirrors the deployer policy's existing grant. Values stay pinned toparameter/bclaw/*..envon every boot —$HERMES_HOME/.envis no longer operator-editable inside the container (a hand-edit is clobbered on restart). Merge semantics deferred pending confirmation of thehermes config/.envwrite interaction in cloud mode.gh-authblock) — operator extras must never take down the Slack bot.See
rfcs/2026-07-16_underscore-ssm-secrets-to-hermes-env.mdfor the full design, the IAM grant shape, the bootCommandsketch, alternatives considered, and the integration-cycle plan.