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
{ "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.
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:
notesis 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_secretfrequently discloses more through notes than through the field it carefully starred out.- Custom fields are masked by their label.
API Keymatches (key);Recovery Code,Service Account CredentialandBreak-glassmatch 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: trueon a record with MFA exposes the TOTP seed. TheoneTimeCode/otpfields hold the fullotpauth://URI. Masked, it is starred; unmasked, the record's permanent second factor is in the transcript. This is the strongest single reason to useget_totp_coderather 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.
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, folderContoso / Infrastructure" is usually the more useful answer and discloses nothing. - Re-read rather than remember. A second
get_fieldcall 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 — the single-field retrieval path this skill keeps pointing at
- finding-secrets — resolving a title to a UID without reading anything
- api-patterns — tool tiers, blocked tools, and error handling