Package: secrets-helper
secrets-helperhelps you use credentials stored in AWS Secrets Manager
with tools that accept credentials and other configuration
through environment variables.Getting StartedRequired PrerequisitesSuported Python versions3.73.8Installation$ pip install secrets-helperUsageHow it worksTo usesecrets-helper,
simply identify the ARN of your Secrets Manager secret,
the command profile that you want to use,
and the command that you want to run along with any desired arguments.$secrets-helperrun\--secretarn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecret\--profiletwine\--command"twine upload --skip-existing dist/*"Value Injectionsecrets-helpergets your credentials from Secrets Manager
and injects them into the appropriate environment variables
when it runs the command.For example, if you were to have it run theenvcommand
to print out all of your environment variables,
you would see:$secrets-helperrun\--secretarn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecret\--profiletwine\--commandenvTWINE_USERNAME=my-awesome-usernameTWINE_PASSWORD=my-secret-passwordTWINE_REPOSITORY_URL=https://test.pypi.org/legacy/ImportantStoring secrets in environment variables carries risks
because anything running in that environment has access
to those secret values.For example, if your testing infrastructure logs all environment variables
(something that is perfectly reasonable to do in a testing environment)
then if you store secrets in your environment variables
those secrets are leaked into your testing logs.secrets-helperrunhelps you work around this
by running your requested command in an isolated subprocess.
Your secret environment variables are ONLY injected
into this isolated subprocess,
so anything running outside of that process does NOT
have access to your secrets.ConfigurationIn order forsecrets-helperto correctly load your credentials,
your secret needs to be JSON-formatted with expected field names.
It uses these names to map your secret values to the correct environment variables.
This means you can use a single Secrets Manager secret to store multiple secret values.You can either format your secret plaintext like this manually
or you can create key-value pairs in your secret through the
Secrets Manager console.$awssecretsmanagerget-secret-value\--secret-idarn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecret{"username":"my-awesome-username","password":"my-secret-password","url":"https://test.pypi.org/legacy/"}secrets-helpercomes pre-loaded
with some known environment variable mappings for common tools.
You can use those as-is or you can provide an ini-style config file
that defines a custom mapping.$secrets-helperrun\--secretarn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecret\--configtwine-config.cfg\--command"twine upload --skip-existing dist/*"A mapping fortwinemight looks like this:[secrets-helper.env]username:TWINE_USERNAMEpassword:TWINE_PASSWORDurl:TWINE_REPOSITORY_URLWarningEach identifier to environment variable mapping MUST be 1:1.
No environment variable may have more than one identifier
that maps to it.Additional ConfigurationYou can also define secret IDs and a command profile in the config file.[secrets-helper.settings]secrets:arn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecretarn:aws:secretsmanager:us-west-2:111222333444:secret:AnotherSecretprofile:twineMultiple SecretsYou might need to load secret values from multiple Secrets Manager secrets.
In this case, simply provide multiple--secretoptions!WarningWARNING: If you usesecrets-helperwith multiple secrets,
those secrets MUST NOT have any repeating keys.$secrets-helperrun\--secretarn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecret\--secretarn:aws:secretsmanager:us-west-2:111222333444:secret:AnotherSecret\--profiletwine\--command"twine upload --skip-existing dist/*"Secrets as Command Line ParametersSome commands need secret values to be passed in as command line parameters.
If you need to do this, add a reference in your--commandparameter
using the{env:NAME}syntax to identify where you need
environment variable values to be injected.ImportantProviding secrets as command line arguments should generally be avoided
because anything monitoring your shell activity (such ashistory)
will collect your secret values.secrets-helperrunhelps with this too!
Because it executes the command you request in an isolated subprocess,
the command arguments are not exposed to external processes.$secrets-helperrun\--secretarn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecret\--profiletwine\--command"twine upload --skip-existing {env:DIST_DIRECTORY}"Passing toenvIn some advanced use cases, you might not be able to use therunoperating mode.
If you find yourself in this situation,
you can use theenvoperating mode
and makesecrets-helperprint out the resulting environment variable assignments
in a format that theenvcommand can understand.$secrets-helperenv\--secretarn:aws:secretsmanager:us-west-2:111222333444:secret:MyAwesomeSecret\--profiletwineDevelopmentPrerequisitesRequiredPython 3.7+tox: We use tox to drive all of our testing and package management behavior.
Any tests that you want to run should be run using tox.Optionalpyenv: If you want to test against multiple versions of Python and are on Linux or MacOS,
we recommend using pyenv to manage your Python runtimes.tox-pyenv: Plugin for tox that enables it to use pyenv runtimes.detox: Parallel plugin for tox. Useful for running a lot of test environments quickly.Setting up pyenvIf you are using pyenv, make sure that you have set up all desired runtimes and configured the environment
before attempting to run any tests.Install all desired runtimes.ex:pyenv install 3.7.0NOTE:You can only install one runtime at a time with thepyenv installcommand.In the root of the checked out repository for this package, set the runtimes that pyenv should use.ex:pyenv local 2.7.14 3.4.6 3.5.3 3.6.4 3.7.0NOTE:This creates the.python-versionfile that pyenv will use. Pyenv treats the first
version in that file as the default Python version.Running testsThere are two criteria to consider when running our tests:
what version of Python do you want to use and what type of tests do you want to run?For a full listing of the available types of tests available,
see the[testenv]commandssection of thetox.inifile.All tests should be run using tox.
To do this, identify the test environment that you want tox to run using the-eENV_NAMEflag.
The standard test environments are named as a combination of the Python version
and the test type in the formVERSION-TYPE.
For example, to run thelocaltests against CPython 3.7:tox-epy37-localIf you want to provide custom parameters to pytest to manually identify what tests you want to run,
use themanualtest type. Any arguments you want to pass to pytest must follow the--argument.
Anything before that argument is passed to tox. Everything after that argument is passed to pytest.tox-epy37-manual--test/unit/test_example_file.pyBefore submitting a pull requestBefore submitting a pull request, please run thelinttox environment.
This will ensure that your submission meets our code formatting requirements
and will pass our continous integration code formatting tests.