keycmd

在任意命令前加上 keycmd，以安全地从操作系统密钥链中提取您的机密和凭据，而不是使用风险较大的 .env 文件（或者更糟糕 🙈）。常见应用包括npm、pip、poetry、docker、docker compose 和 kubectl！

支持Windows、macOS 和 Linux。

关于

keycmd 的主要功能是从您的操作系统密钥链中加载机密，并在单个shell命令的持续时间或子shell的生命周期内将其暴露为环境变量。

这使得您可以将如身份验证令牌和密码等敏感数据存储在您的操作系统密钥链中，因此您不再需要依赖如 .env 文件或将在终端中粘贴机密等不安全做法。😱

最常见的情况是在使用私有包索引（如Azure Artifact Feeds）时加载包管理器（如pip和npm）的凭据。另一个常见用例是docker构建机密。

安装

注意 如果您打算在WSL或pyenv环境中安装 keycmd，您将不得不跳转到这些环境特定的安装说明。

全局安装

使用 pip install keycmd 从pypi安装 keycmd，或您喜欢的任何替代Python包管理器。

请注意，必须将可执行文件 keycmd 安装到您的 PATH 环境变量所在的文件夹，否则该命令将不可用全局。假设您刚才能够运行 pip，则 keycmd 可执行文件应位于完全相同的位置，一切应该正常。

要验证是否已安装并可用 keycmd，请运行 keycmd --version。

pyenv安装

现在，如果您使用pyenv，您将不得不跳过一些步骤，因为keycmd需要全局安装，这与pyenv试图达成的目标背道而驰。

本指南假设您已安装pyenv-virtualenv，以便为您提供一个最干净的设置。✨

注意 这些pyenv说明适用于Linux和MacOS上的pyenv。如果您正在使用Windows上的pyenv-win，这些说明可能与您的设置不兼容。

逐个运行以下命令，将keycmd安装到其独立的独立环境中

# run the following commands one by one
pyenv virtualenv 3.9 keycmd
pyenv activate keycmd
pip install keycmd
pathToKeycmd=$(python -c 'import sys; from pathlib import Path; print(Path(sys.executable).parent / "keycmd")')
pyenv deactivate
mkdir -p $HOME/.local/bin
ln -s $pathToKeycmd $HOME/.local/bin/keycmd

最后，编辑您的~/.bashrc文件（或您使用的任何shell配置文件），以便将~/.local/bin添加到您的PATH变量中

export PATH="$HOME/.local/bin:$PATH"

注意 这一行可能已经存在于您的~/.bashrc中，例如，如果您安装了poetry！这是一个常用的技巧，用于在包含应该不暴露在PATH中的二进制文件的文件夹中暴露特定的二进制文件。

要验证是否已安装并可用 keycmd，请运行 keycmd --version。

WSL安装

如果您使用WSL，在第一次尝试使用keycmd时可能会遇到障碍。这是因为keycmd使用keyring库连接到OS密钥环，而keyring将尝试连接到您的linux发行版（可能是Ubuntu）的密钥环后台服务，该服务默认情况下实际上并未在WSL环境中运行！

如果您确实已设置您的linux发行版的密钥环后台服务，那很好，您可以继续使用它，无需执行任何其他步骤。

注意 只因您在系统上安装了WSL，并不意味着您实际上正在使用WSL。稍加思考；您是从Windows还是从WSL中使用Python？这里提供的说明仅在您实际上在WSL中工作时才是必要的。

因此，如果您希望keyring从WSL环境连接到Windows凭据管理器，请继续执行以下步骤。

您必须在Windows上根据上述说明安装keycmd（全局或使用pyenv），而不是在WSL中安装。然后，假设keycmd已添加到您的WindowsPATH，现在它也应该在WSL中可用！

升级和降级

如果您稍后想安装keycmd的不同版本，只需再次使用pip即可。

注意 如果您使用pyenv，请确保首先使用pyenv activate keycmd激活虚拟环境。不要忘记之后执行pyenv deactivate。

• 升级到最新版本：pip install -U keycmd
• 安装特定版本：pip install keycmd==0.6.0

快速入门

现在keycmd已安装，我们可以进行快速测试，看看它如何工作！

让我们向我们的OS密钥环添加一个新的密钥，然后看看我们如何使用keycmd来暴露它。

为了本示例的目的，使用my-secret作为凭据名称，使用my-username作为...用户名。我使用了foobar作为密码。

在Windows上，这意味着点击开始并输入“凭据管理器”以找到应用程序。点击“Windows凭据”选项卡，然后点击“添加通用凭据”。请参阅下面的截图。

在macOS上，打开密钥链访问（命令-空格栏，输入keychain access），然后按Command-N添加一个新的密码项。请注意，账户名称包含用户名。

注意 欢迎提交添加linux密钥环视觉指南的拉取请求！

现在，在您的用户主目录中创建一个.keycmd配置文件。将以下配置放入文件并保存

[keys]
SECRET = { credential = "my-secret", username = "my-username" }

最后，打开一个终端并运行一个命令来打印秘密，这样我们就可以看到是否成功。这取决于您使用的shell，所以这里有一些示例

• Cmd: keycmd echo %SECRET%
• Powershell: keycmd 'echo $env:SECRET'
• Bash: keycmd 'echo $SECRET'

你应该看到文本 foobar 被打印到终端。

你已经成功设置了 keycmd! 👏

下面是高级配置示例，其中展示了如何将 poetry、npm 和 docker-compose 结合起来使用 keycmd。

使用方法

CLI 有以下选项

❯ keycmd --help
usage: keycmd [-h] [-v] [--version] [--shell] ...

positional arguments:
  command        command to run

optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  enable verbose output, useful for configuration debugging
  --version      print version info
  --shell        spawn a subshell instead of running a command

使用 CLI 有两种主要方式

• keycmd '你的命令'
• keycmd --shell

第一种是最受欢迎的方法，因为你的秘密信息只会在一次性命令期间以环境变量的形式暴露。后者不太受欢迎，但如果你正在调试依赖于你所暴露的凭证的一些进程，它可能更方便。

配置

注意 如果你遇到 keycmd 配置问题，请参阅调试配置部分。

位置

配置可以存储在三个地方（其中 ~ 是用户主目录，. 是调用 keycmd 时的当前工作目录）

• ~/.keycmd
• 从 . 向文件系统向上遍历时找到的所有 .keycmd
• 从 . 向文件系统向上遍历时找到的第一个 pyproject.toml

注意： 搜索 .keycmd 和 pyproject.toml 将在 git 仓库的根目录处停止，并在用户主目录之前停止，以确保你的配置可以应用于文件系统的子树。

配置文件按列表顺序加载和合并。

选项

选项模式定义如下

• keys: dict
  • {key_name}: dict
    • credential: str
    • username: str
    • b64: bool, optional
    • format: str, optional
• aliases: dict
  • {alias_name}: dict
    • key: str
    • b64: bool, optional
    • format: str, optional

你可以定义任意数量的密钥。对于每个密钥，你需要定义以下内容

• key_name，这是凭证将暴露的环境变量的名称
• credential，这是你操作系统密钥环中凭证的名称
• username，这是在操作系统密钥环中拥有凭证的用户名称

可选字段

• b64，将其设置为 true 以对密码应用 base64 编码
• format，应用格式化字符串（在可选地应用 base64 编码之前）
  • 你可以访问 credential、username 和 password
  • 例如，你可以组合一个基本的认证头，如下所示： "{username}:{password}"

别名使得以另一种方式暴露相同的凭证成为可能，字段工作方式相同。

示例

此配置将特定的凭证以明文形式在环境变量 MY_TOKEN 下暴露，并且再次以 base64 编码的形式作为 MY_TOKEN_B64 暴露

[keys]
MY_TOKEN = { credential = "MY_TOKEN", username = "azure" }

[aliases]
MY_TOKEN_B64 = { key = "MY_TOKEN", b64 = true }

pyproject.toml 示例

你还可以通过在键前加上 tool.keycmd 前缀来在 pyproject.toml 中存储你的配置。所以如果我们把之前的例子转换一下，它看起来会是这样

[tool.keycmd.keys]
MY_TOKEN = { credential = "MY_TOKEN", username = "azure" }

[tool.keycmd.aliases]
MY_TOKEN_B64 = { key = "MY_TOKEN", b64 = true }

OpenAI 示例

对于 OpenAI，你被指导使用 API 密钥来认证他们的 API。当你将这个字符串放入 .env 文件，或者直接放入你的代码中时，你可能会将你的 API 密钥与全世界分享！🙅‍♂️

相反，只需将其放入你的操作系统密钥环中，然后在运行你的 Python 脚本或 Jupyter 笔记本时使用 keycmd 来暴露它。

例如，如果你将其添加到操作系统密钥环中的 my-openai-token 和 your-username 下，你将使用以下 .keycmd 配置

[keys]
OPENAI_API_KEY = { credential = "my-openai-token", username = "your-username" }

现在你只需在命令前加上 keycmd 即可运行任何 OpenAI 脚本。例如

keycmd 'python my_openai_script.py'

或者一个 jupyter 笔记本

keycmd 'jupyter notebook'

这就完了！🤘 现在，你可以安心休息，知道你的令牌是安全的。🛌💤

高级示例

这是一个用于 Poetry、npm 和 docker-compose 的示例配置。它应该能够激发你看到 keycmd 通过其配置系统提供的可能性。

在这种情况下，我们使用 Azure DevOps 个人访问令牌对 Azure Artifacts Feed 进行身份验证，该 Feed 供 python 和 node.js 包使用。

让我们从在 Azure DevOps 中创建打包（读取）令牌开始。

请确保检查打包（读取）权限，这是我们在此示例中需要的唯一权限。

在这种情况下，我们不会手动将其输入到操作系统密钥环中。我们将让 Poetry 处理它。让我们查看我们的 pyproject.toml 文件

[tool.poetry]
name = "my-project"
version = "1.0.0"
description = ""
authors = ["My Name <my-name@my-organization.com>"]

[[tool.poetry.source]]
name = "main"
url = "https://pkgs.dev.azure.com/my-organization/_packaging/main/pypi/simple/"
priority = "default"

[tool.poetry.dependencies]
python = "~3.9"

[build-system]
requires = ["poetry>=1.0.0"]
build-backend = "poetry.core.masonry.api"

看起来我们的 poetry 源命名为 main，所以让我们运行相应的命令

poetry config http-basic.main <username> <personal-access-token>

Poetry 将在操作系统密钥环中创建一个条目，当您运行 poetry install 时，它将自动使用该凭据进行身份验证。这里不需要 keycmd！

接下来，我们将使用 keycmd 依赖此凭据，以便将其用于 npm 和 docker-compose。这样，我们只需要管理一个凭据（这意味着当它到期时更新它）。

在您的操作系统密钥环中查找新的凭据，并将以下配置存储在 .keycmd 文件中。当然，请检查您的操作系统密钥环，并根据凭据名称和用户名调整您的配置！

[keys]
PAT = { credential = "credential-name", username = "your-username" }
PAT_B64 = { credential = "credential-name", username = "your-username", b64 = true }

在此示例中，我们将相同的凭据暴露两次

• 作为环境变量 PAT
• 再次，但以 base64 编码的形式作为环境变量 PAT_B64

这很重要，因为 npm 需要我们以 base64 编码的形式提供令牌，但其他工具不需要。

对于我的 npm 项目，我有一个.npmrc 文件，内容如下

registry=https://pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/
always-auth=true
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/:username=dev
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/:_password=${PAT_B64}
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/registry/:email=email
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/:username=dev
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/:_password=${PAT_B64}
//pkgs.dev.azure.com/my_organization/_packaging/main/npm/:email=email

现在，我可以通过调用 keycmd 'npm install' 来设置我的 node_modules！🚀

注意 如果您不设置环境变量并尝试调用类似 npm run [...] 的任何调用，npm 将会抱怨。🙄 您可以将它们设置为空字符串，这样 npm 就会闭嘴。我在 Linux 上使用 export PAT_B64=（或在 Windows 上使用 setx PAT_B64=）。

此外，我还有一个配置如下所示的 docker-compose 文件

secrets:
  token:
    environment: PAT
  token_b64:
    environment: PAT_B64

当我调用 keycmd 'docker compose build' 时，这两个变量将通过 keycmd 暴露，随后它们将作为docker compose 构建密钥可用。👌

调试配置

如果您没有得到预期的结果，请使用 -v 标志来调试您的配置。Keycmd 将详尽地告诉您它正在执行的所有步骤。

以下是一个使用 cmd.exe 的示例，否则命令将是 poetry run keycmd -v 'echo $ARTIFACTS_TOKEN_B64'

❯ poetry run keycmd -v echo %ARTIFACTS_TOKEN_B64%
keycmd: loading config file C:\Users\kvang\.keycmd
keycmd: loading config file C:\Users\kvang\dev\keycmd\pyproject.toml
keycmd: merged config:
{'keys': {'ARTIFACTS_TOKEN': {'credential': 'korijn@poetry-repository-main',
                              'username': 'korijn'},
          'ARTIFACTS_TOKEN_B64': {'b64': True,
                                  'credential': 'korijn@poetry-repository-main',
                                  'username': 'korijn'}}}
keycmd: exposing credential korijn@poetry-repository-main belonging to user korijn as environment variable ARTIFACTS_TOKEN (b64: False)
keycmd: exposing credential korijn@poetry-repository-main belonging to user korijn as environment variable ARTIFACTS_TOKEN_B64 (b64: True)
keycmd: detected shell: C:\Windows\System32\cmd.exe
keycmd: running command: ['C:\\Windows\\System32\\cmd.exe', '/C', 'echo', '%ARTIFACTS_TOKEN_B64%']
aSdtIG5vdCB0aGF0IHN0dXBpZCA6KQ==

关于密钥库后端的说明

由于 keycmd 使用 keyring 作为其后端，您不仅限于仅与操作系统密钥环一起工作。🤯 任何密钥库后端都可以与 keycmd 一起工作。无需特殊配置！

有关所有选项的列表，请参阅第三方后端。