Finding the Right Secret
Overview
Discovery is the half of Keeper work that involves no credential
material at all. list_secrets, search_secrets and list_folders
return metadata only — no passwords, no field values, nothing masked
because there is nothing sensitive to mask. Do all the narrowing here,
end up with one UID, and only then reach for a retrieval tool.
The three discovery tools
list_secrets
Every record in the application's scope, optionally filtered by folder.
{} // everything in scope
{ "folder_uid": "kJ3v9PqR2mXwL7nBcD4sTg" } // one folder
{ "folder_uids": ["uid1", "uid2"] } // several — preferred
folder_uids is the multi-folder form and is pushed down to Keeper's
folder filtering; folder_uid exists for backward compatibility. Passing
both ignores the singular one.
Response — count plus one entry per record:
{ "count": 2, "secrets": [
{ "uid": "NJ_xXSkk3xYI1h9ql5lAiQ", "title": "Contoso DC01 Local Admin",
"type": "serverCredentials", "folder": "kJ3v9PqR2mXwL7nBcD4sTg" },
{ "uid": "8fQ2wKmT5vXyL9pRnB3cAa", "title": "Contoso Firewall",
"type": "login", "folder": "kJ3v9PqR2mXwL7nBcD4sTg" }
] }
Four fields, and that is the whole surface: uid, title, type,
folder. type is the Keeper record type — it tells you which fields
the record can carry, and so which field names KSM notation is likely to
address. To see the actual names, read them off a masked get_secret.
list_folders
Every folder shared to the application, as a flat list of
uid / name / parent_uid. Nesting is expressed by parent_uid
pointers, not by structure, so build the tree yourself if you need one.
A folder whose parent_uid names a folder that is not in the list is a
subfolder of something outside the application's scope — normal, not an
error.
This is also the fastest honest answer to "what can this connection see?".
search_secrets
One required query string. Returns the same four metadata fields under
results, plus a count.
What it actually matches — verified against the upstream implementation, in this order, stopping at the first hit:
- Record title
- Record notes
- Record type (so
query: "login"matches every login record) - The values of four standard fields only:
login,url,hostname,address - Attachment filenames and titles
All matching is case-insensitive substring. It is not a Keeper-side search: the tool pulls every record in scope and filters locally, so there is no pagination, no ranking and no result cap — a broad query returns the whole scope.
Workflow: description to UID
list_folders— orient, and confirm the scope is what you expect.search_secretswith the most distinctive token you have (a hostname, a tenant name, a device name). Prefer one distinctive word over a long phrase; the match is a plain substring, so"Contoso DC01"fails against a record titled"DC01 (Contoso) Local Admin"while"DC01"succeeds.- If the result set is large, narrow with
list_secretson the folder the likely candidate sits in. - Confirm the choice by title and type, then hand the UID to
get_field— not toget_secret, unless the whole record is genuinely needed.
When two candidates look equally plausible, ask the user which record they mean. Do not disambiguate by fetching both and comparing credentials.
Gotchas
search_secrets does not search custom fields. The upstream code
carries an explicit TODO to that effect. A record whose only mention of
"Azure" is a custom field labelled Tenant ID will not be found by
searching Azure. Fall back to list_secrets over the likely folder and
read titles.
Some perfectly ordinary queries are rejected, and client names are the
usual casualty. The query validator refuses, case-insensitively, any
query containing union, select, insert, update, delete,
drop, xp_, sp_, --, /*, */, '; or "; — plus shell
metacharacters and queries over 256 characters. It is a SQL-injection
filter applied to a search that never touches SQL, and it matches on
substrings, so it catches real business names:
| Query | Rejected because it contains |
|---|---|
Union Bank |
union |
Updates Server |
update |
Select Insurance |
select |
Dropbox |
drop |
Insertech |
insert |
All of them fail with search query contains suspicious patterns. That
is input validation, not a permissions problem and not evidence the
record is missing — never report it as either. Search a different token
from the same record: a hostname, a login, part of a URL. Not a folder
name — search_secrets never matches those (see the match list above);
to narrow by folder use list_secrets with folder_uids.
A hit does not mean the title matched. Matching on notes and on
login / url / hostname / address values means a result can look
unrelated to the query. Read the returned title before acting, and say
which record you chose.
type matching makes generic queries useless. Searching login
matches every record of type login. Use the record type deliberately
(search_secrets with "pamMachine" is a legitimate way to enumerate
PAM machine records) or avoid type words entirely.
Empty results are usually scope, not absence. The application only
sees folders explicitly shared to it. Before telling a user their record
does not exist, check list_folders and say which folders the connection
can actually see — the record probably exists in a folder nobody shared.
See application-setup.
Titles are not unique and are not identifiers. Keeper permits duplicates. Anything that will be re-run — a runbook, a saved command, a scheduled job — should carry the UID, not the title.
Related Skills
- retrieving-credentials — what to do once you have the UID
- notation-queries — addressing one field on a found record
- api-patterns — tool tiers and the error vocabulary