secret

mcp
Guvenlik Denetimi
Basarisiz
Health Uyari
  • License — License: GPL-3.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 9 GitHub stars
Code Basarisiz
  • rm -rf — Recursive force deletion command in .github/workflows/ci.yml
  • rm -rf — Recursive force deletion command in .github/workflows/host-hooks.yml
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Let coding agents use your credentials without reading them

README.md


Secret

Let coding agents use your credentials without reading them.

Release CI License MCP: stdio Platforms: macOS, Linux, Windows

Secret lets a coding agent run commands that need your credentials while the
values stay out of the conversation.
The agent works with key names; the
secret CLI puts the selected value into the child program's environment and
replaces it with <redacted> in that program's output.

$ secret show ~/.secrets.env
API_TOKEN=<40 bytes>
$ secret run -f ~/.secrets.env --key API_TOKEN -- ./deploy.sh
deploying with token <redacted> ... ok    (illustrative deploy output)

It is three parts that work together:

Part What it does
secret CLI Stores values (hidden prompt, private atomic writes), shows names with masked lengths, runs a program with selected keys and redacts loaded literal values from its stdout and stderr.
Names-only MCP server secret mcp --store REF exposes four read-only tools (list, show, diff, health) over stdio for explicitly allowlisted stores. It never returns values, value hashes or lengths.
Guard hook and agent skill A Claude Code and Codex plugin that denies known secret-reading tool calls (store and credential files, environment dumps, credential printers, clipboard reads, secret get and secret exec) and teaches the agent the safe workflow.

Accident prevention, not a sandbox: see Security limits.

Install

Install or update the Secret CLI to the latest release.

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/avhn/secret/v0.6.1/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/avhn/secret/v0.6.1/install.ps1 | iex

No GitHub account or gh is needed; rerunning updates the installation.
See pins, paths and verification.

Quick start

In your own terminal, stash a value at the hidden prompt. These are illustrative paths:

secret stash ~/.secrets.env API_TOKEN                       # you: hidden prompt, never argv or chat
secret list                                                 # store paths, never contents
secret show ~/.secrets.env                                  # API_TOKEN=<40 bytes>
secret run -f ~/.secrets.env --key API_TOKEN -- ./deploy.sh # child gets the value, output is redacted

Then ask your agent to "deploy with API_TOKEN from ~/.secrets.env". It needs only
the store reference and the key name.

More that run and its siblings can do, all in usage:

  • Select precisely: --key (required), --optional-key, several -f stores
    (later wins). Only selected keys reach the child.
  • Environments and labels: [env=dev] sections in a store, selected with
    --env dev or --label name=value.
  • Private templates: --template-file renders {{KEY}} placeholders into a
    private 0600 file and passes its path in SECRET_TEMPLATE_FILE.
  • Clipboard: secret clip FILE KEY [SECONDS] copies a value and clears it
    after 45 seconds unless you copied something else.

Where values can live

Default stores are plain KEY=VALUE files: ~/.secrets.env and
~/.secrets/*.secret. A bare NAME means ~/.secrets/NAME.secret. Other
backends are selected explicitly by reference and work with the same commands.

Reference Backend Linux macOS Windows Notes
path, NAME, file:PATH dotenv-style file, private permissions yes yes yes Default; the only kind list discovers by default. usage
keychain:NAME macOS Keychain no yes no SECRET_KEYCHAIN selects a keychain path. usage
libsecret:NAME Secret Service through secret-tool yes no no Needs an unlocked session. usage
wincred:NAME Windows Credential Manager no no yes 2560-byte value limit. windows
pass:NAME pass 1.7.4 with your GnuPG setup yes yes no You initialize the password store. pass
age:NAME age-encrypted file, X25519 keys yes yes no Explicit --age-identity; create with age-init. age

Keystore backends keep a names-only manifest under ~/.secrets, so list and
show read names without fetching a value.

1Password and Bitwarden. Copy items into a store with a human-run,
insert-only import through the vendor CLI (op or bw) that you have already
signed in. Explicit field mappings are required:

secret import --from op:ITEM_ID --into file:/absolute/team.secret --map password=API_TOKEN
secret import --from bw:ITEM_ID --into file:/absolute/team.secret --map login.password=API_TOKEN
secret import --from dotenv:/absolute/old.env --into file:/absolute/team.secret

Reading op:// references live, without importing, is planned: the
onepassword: backend exists in the source but is switched off with no runtime
override until a licensing review and isolated provider testing pass; see
its status. secret export copies records from one store
to a keystore or age store (for example file to Keychain); plaintext export
targets are refused.

For agents

If you are a coding agent reading this, the rules are short. The full version is
the agent skill; setup is in docs/setup.md.

You may run Purpose
secret list Default store paths, without opening them.
secret show FILE Key names, masked lengths and labels.
secret run -f FILE --key KEY -- CMD Run a command with the value in its environment and redacted output.
secret clip FILE KEY Only when the user explicitly asks for the clipboard.
MCP tools list, show, diff, health Names-only metadata for stores the human allowlisted.
Human only: never run it Why
secret get Prints a value to a terminal.
secret exec Unfiltered run, for human-configured launchers.
secret stash The human types the value at a hidden prompt.
import, export, rotate, rename, delete, age-init, age-rekey Operator commands; require real terminals and hidden confirmation.
  • Use the exact store reference the human gave you. Do not search for, open,
    cat, grep or patch store files, and do not print or transform values
    (no echo $KEY, env, base64).
  • Prefer stdin or header files over arguments, so a value does not appear in
    the child's argv:
    secret run -f FILE --key API_TOKEN -- bash -c 'printf "Authorization: Bearer %s\n" "$API_TOKEN" | curl -fsS -H @- URL'
  • Missing key: ask the human to run secret stash FILE KEY in their own
    terminal. Never ask for a value in chat.
  • Denied by the guard: narrow the request or follow its hint. Do not disguise the
    command, disable the hook or change permissions. The installed hooks also deny
    newer subcommands such as diff, doctor, audit and mcp from the shell.

Connect your agent

Names-only MCP server. Register it with the installed executable's concrete
absolute path and an exact human-approved store reference. Do not discover or
read stores:

claude mcp add --transport stdio --scope user secret -- "/ABSOLUTE/INSTALL DIR/secret" mcp --store "file:/ABSOLUTE/STORE DIR/STORE.secret"

Reconnect the client and verify list/show/diff/health. The server is off without
--store, has no network listener and cannot be widened by a request.
Setup covers Claude Code, Claude Desktop (MCPB bundle
or JSON), Codex, ChatGPT desktop, OpenCode, Cursor and VS Code, Windows
equivalents, and the MCP Registry name io.github.avhn/secret (see the
release status for the currently published record).

Guard hook and skill. Optional plugin for Claude Code:

/plugin marketplace add avhn/secret
/plugin install secret@secret

and for Codex:

codex plugin marketplace add avhn/secret
codex plugin add secret@secret

The plugin installs the Bash guard and the agent skill,
not an MCP registration. Codex requires explicit hook trust in /hooks,
including re-trust after changes. Also install the protective ripgrep config;
see plugin and manual-hook instructions.
Go hooks remain inactive; installation and synthetic tests do not prove host
fail-closed protection.

Launching other MCP servers with a credential. For a launcher you configure
yourself, exec supplies selected values without filtering the server's stdio.
It works on macOS, Linux and Windows. -f takes a plain store path, not file::

"/ABSOLUTE/INSTALL DIR/secret" exec -f "/ABSOLUTE/STORE DIR/.secrets.env" --key OPENPROJECT_API_TOKEN -- uvx [email protected]

This is not the names-only server or an agent retrieval route. Output is
unfiltered and can disclose values. Review the server first; see
client JSON, Windows paths and shutdown limits.

Command overview

Command Who What
list, show agent or human Store paths; key names with masked lengths (<stored> for keystores). --format=json is names-only.
run agent or human Child with selected keys, redacted stdout and stderr, optional --template-file.
clip on human request Clipboard copy with timed conditional clear.
stash human Hidden prompt or stdin; private atomic write.
get, exec human Print one value to a terminal; unfiltered child.
import, export human operator Insert-only transfer from dotenv, op, bw, or between stores; --dry-run.
rotate, rename, delete human operator Lifecycle of one exact record.
age-init, age-rekey human operator Create or rekey an encrypted store.
diff, doctor, audit, completion human Names-only comparison, diagnostics, opt-in audit log queries, completion candidates.
mcp client launcher Names-only stdio server.

secret help prints the full reference. The site lists the same
tools and commands.

Security limits

  • The CLI supplies selected values to a child and redacts literal output.
    Redaction does not catch base64, URL encoding, substrings or other transformations.
  • The guard is heuristic. It denies known secret-reading operations but cannot
    contain a determined agent, arbitrary child behavior or tools it never sees,
    including MCP search tools.
  • Metadata can reveal key names, labels, paths and provider account IDs.
  • Default file stores are plaintext at rest with private permissions; choose a
    keystore or age: store for encryption at rest.
  • No fail-closed host protection is claimed.

Treat this as one layer, not the boundary. Read the
full threat model.

More

License

GPL-3.0-or-later, copyright Mert Dede.

Yorumlar (0)

Sonuc bulunamadi