keeper-credential-retrieval

# Retrieving Credentials Safely ## Overview Four of the nine served tools return credential material. Everything in this skill follows from one property of the environment: **a secret read into an agent transcript has been disclosed**, to the transcript, to whatever stores it, and to anything downstream the transcript reaches. Masking narrows that; it does not undo it. So the discipline is to read the least, as late as possible, and to move it onward without copying it. ## Prefer the narrowest tool | Need | Use | Why | |------|-----|-----| | One value | `get_field` with notation | Returns exactly that value | | A live second factor | `get_totp_code` | Returns a code, not the seed | | Field names / record shape | `get_secret` **masked** | The response keys *are* the field names, read from the real record | | A genuinely whole record | `get_secret` with `unmask: true` | Last resort — see below | Reaching for `get_secret` because it is fewer keystrokes than composing notation is the common failure. One record can carry a password, an API secret, recovery codes, and notes containing a second credential; all of it lands in context at once. ## `get_secret` ```jsonc { "uid": "NJ_xXSkk3xYI1h9ql5lAiQ" } // masked { "uid": "NJ_xXSkk3xYI1h9ql5lAiQ", "fields": ["login", "url"] } // subset { "uid": "NJ_xXSkk3xYI1h9ql5lAiQ", "unmask": true } // full reveal ``` `uid` must be a real UID — 16 to 32 characters — and a title fails with `invalid UID: UID must be between 16 and 32 characters`. Resolve titles first; see [finding-secrets](../finding-secrets/SKILL.md). With no `fields`, the response carries `uid`, `title`, `type`, `notes` if present, one key per standard field the record type is expected to have, `custom_fields` keyed by label, and `files` (name, title, size, type — metadata, never content). With `fields`, you get `uid`, `title`, `type` and only the named fields; `notes`, `custom_fields` and `files` are dropped entirely unless you name `"notes"` explicitly. Naming the one or two fields you need is the cheap way to cut exposure when notation does not fit — and, as a side effect, the surest way to keep unread notes out of the transcript. ### What masking actually covers With `unmask` unset, a value is masked only when its **name** matches a fixed sensitive-word list by case-insensitive substring — `password`, `secret`, `key`, `token`, `privateKey`, `cardNumber`, `cardSecurityCode`, `accountNumber`, `pin`, `passphrase`, `auth`, `routingNumber`, `licenseNumber`, `oneTimeCode`, `otp`, `answer`, `paymentCard`, `bankAccount`, `keyPair`. For standard fields the name tested is the field type; for custom fields it is the label the user typed. Masked output is `first3 + "***" + last3`, or `******` for values of six characters or fewer. A few sub-values inside composite fields are masked by explicit rule instead: `paymentCard.cardNumber` and `.cardSecurityCode`, `bankAccount.routingNumber` and `.accountNumber`, `keyPair.privateKey`, `securityQuestion.answer`, `script.command`, `appFiller.macroSequence`, and `passkey.privateKey` (replaced outright with `***MASKED***`). Their siblings are not — `cardExpirationDate`, `publicKey`, `accountType`, every `address`, `phone` and `name` sub-value, and the whole `pam*` settings family come back in clear. Four consequences: - **`notes` is never masked.** Notes are returned verbatim whenever present. In real MSP vaults notes routinely hold a second password, a recovery phrase, or a PIN. A "masked" `get_secret` frequently discloses more through notes than through the field it carefully starred out. - **Custom fields are masked by their label.** `API Key` matches (`key`); `Recovery Code`, `Service Account Credential` and `Break-glass` match nothing and come back in clear. - **The masked form leaks six real characters.** A masked value is not a redacted value. Do not paste one into a ticket on the assumption that it is safe. - **`unmask: true` on a record with MFA exposes the TOTP seed.** The `oneTimeCode` / `otp` fields hold the full `otpauth://` URI. Masked, it is starred; unmasked, the record's permanent second factor is in the transcript. This is the strongest single reason to use `get_totp_code` rather than unmasking a record to read a code off it. ### `unmask` in this deployment Upstream ksm-mcp is built to stop here and ask a human, over a terminal, with the warning *"This will expose all requested fields of the secret, including the password if present, directly TO THE AI MODEL and its context."* There is no terminal in a container, so that prompt is never shown and `unmask: true` executes directly. Treat the warning as addressed to you instead. Before setting `unmask`, have an answer to: which field is needed, what is it for, and does the person who asked have a use for it right now. If the answer is "so I can show them the record", that is not a use — offer the masked view plus the record's title and location. ### Completeness is not guaranteed With no `fields` argument, `get_secret` iterates a **hard-coded list of field types per record type** — for a `login` record that is `login`, `password`, `url`, `oneTimeCode`, `otp`, and nothing else. A standard field outside its type's list is simply absent from the response, and a record type the list does not recognise falls back to a broad generic sweep instead. If a field you can see in the vault UI does not appear, it was not omitted for security; address it directly with `get_field` notation or name it in `fields`. So do not tell a user "that record has no such field" on the strength of a `get_secret` response. Say the field did not come back, and query it by name. ## `get_totp_code` Takes a `uid` only — no title, no notation — and returns `{ "code": "123456", "time_left": 21 }`, where `time_left` is seconds until the code rotates. The seed never leaves Keeper, which makes this strictly safer than reading the `oneTimeCode` field: a code is useless in about half a minute, a seed is a permanent second factor. The record must carry a TOTP field (an `otpauth://` URL, either as the password field or as a `oneTimeCode` field); otherwise the call fails with `no TOTP field found in secret`. That is a record-content answer, not a permissions answer. Deliver a code, its `time_left`, and stop. Do not cache it, restate it later in the conversation, or write it anywhere — by the time it is read twice it is usually expired anyway. **Never substitute an unmasked record read for this.** `get_secret` with `unmask: true` on an MFA record returns the `oneTimeCode` / `otp` field, and that field holds the full `otpauth://` URI — the seed, not a code. A code expires in seconds; a seed is the account's permanent second factor, and putting one in a transcript is a materially different incident. If someone asks for "the MFA code", `get_totp_code` is the answer and unmasking is not. ## Attachments cannot be retrieved `download_file` is not served — it is blocked, because upstream writes attachment bytes to a path on the server's filesystem and returns only a status, so no argument makes it hand a file to the caller. See [api-patterns](../api-patterns/SKILL.md). `get_secret` still lists a record's attachments (`name`, `title`, `size`, `type` — metadata, never content). So the correct answer to "send me the VPN profile off that record" is to confirm the attachment exists, name it and its size, say which record holds it, and send the user to the Keeper vault. Do not promise a download, and do not look for another tool that might do it; there isn't one. ## `generate_password` Returns `{ "password": "…", "length": 32, "warning": "Password is exposed to AI model. Consider using save_to_secret parameter." }`. Defaults to 32 characters with no per-class minimums unless `lowercase` / `uppercase` / `digits` / `special` are set. The warning is not actionable here: `save_to_secret` and `folder_uid` are stripped because they write, so Keeper's "generate straight into a new record without showing the AI" flow is unavailable and anything generated is disclosed by definition. Do not relay the warning as advice — treat the output as secret material and hand it over the same way as any other. ## Handling rules These apply to every value returned by the four tools above. - **Do not echo a secret you were not asked to produce.** Confirming "retrieved the password for DC01" is the report; repeating the value back in a summary, a recap, or a status line is a second disclosure. - **Never write secret material into durable artifacts** — ticket notes, commit messages, PR descriptions, code comments, config files, scratch files, or logs. This includes masked values. - **Never move a secret between systems on your own initiative.** If a workflow seems to call for pasting a credential into another tool, say what is needed and let the human do it. - **Prefer a pointer to a payload.** "The credential is in Keeper record `Contoso DC01 Local Admin`, folder `Contoso / Infrastructure`" is usually the more useful answer and discloses nothing. - **Re-read rather than remember.** A second `get_field` call is cheaper than a transcript that carries a credential through a long session. - **Report what you read.** Keeper audits the application's access, but the person in the conversation should be told which records were opened, which is also how an unnecessary read gets caught. ## Related Skills - [notation-queries](../notation-queries/SKILL.md) — the single-field retrieval path this skill keeps pointing at - [finding-secrets](../finding-secrets/SKILL.md) — resolving a title to a UID without reading anything - [api-patterns](../api-patterns/SKILL.md) — tool tiers, blocked tools, and error handling