Skip to main content

utility tool that load secret information safely.

Project description

Documentation Status!--None.svg?style=social

Welcome to pysecret Documentation

<nav class="contents this-will-duplicate-information-and-it-is-still-useful-here local" id="contents"> </nav>

pysecret is a library to ease your life dealing with secret information.

For example, if you have a database connection information, so you can’t include it in your source code, but you want to easily and securely access it, then pysecret is the library for you. It provides several options out of the box:


  1. access secret in environment variable from commandline, shell scripts, or Python.

  2. access secret in json file from Python.

  3. use AWS Key Management Service or AWS Secret Manager to access your secret info.

For large file or binary data encryption, I highly recommend you to use AWS Key Management Service and AWS Secret Manager to fetch your encryption key, then use windtalker library to encrypt it.

Load Data From Environment

The idea is: put your secret information in ~/.bashrc_pysecret file.

# content of ~/.bashrc_pysecret file
export DB_SECRET_MY_DB_PASSWORD="mypassword"

And put source ~/.bashrc_pysecret into your ~/.bashrc / ~/.bash_profile / .zshrc

Whenever you need your secret info:

  1. Your interactive command line interface gives you easy access to those secrets.

  2. You can put source ~/.bashrc_pysecret in your CI / CD scripts.

  3. pysecret allows you to load secret value in python code. By doing this:

>>> from pysecret import EnvSecret
>>> env = EnvSecret()
>>> env.load_pysecret_script()

You can write your secret to ~/.bashrc_pysecret file in a pythonic way:

from pysecret import EnvSecret

env = EnvSecret()

# will create ~/.bashrc_pysecret file if not exists
# will update ~/.bashrc_pysecret file too
# if you don't want to update ~/.bashrc_pysecret file, just set .set(..., temp=True)
env.set("DB_SECRET_MYDB_HOST", "123.456.789.000")
env.set("DB_SECRET_MYDB_USERNAME", "username")
env.set("DB_SECRET_MYDB_PASSWORD", "password")

Load Data From Json File

The idea is, put your secret info in a json file and load info from it. You can create it manually by your own, or do it in pythonic way:

from pysecret import JsonSecret, get_home_path

SECRET_FILE = get_home_path(".pysecret.json")
js =

# construct / update secret json file
js.set("": "123.456.789.000")
js.set("mydb.username": "username")
js.set("mydb.password": "password")

or you can just create $HOME/.pysecret.json includes:

    "mydb": {
        "host": "123.456.789.000",
        "username": "username",
        "password": "password

Load secret safely:

host = js.get("")
username = js.get("mydb.username")
password = js.get("mydb.password")

AWS Key Management Service and Secret Manager Integration

Encrypt your secret and Read secret value using AWS Secret Manager with ``pysecret`` is super easy.

First, let’s create a aws secret:

from pysecret import AWSSecret

aws_profile = "my_aws_profile"
aws = AWSSecret(profile_name=aws_profile)

secret_id = "my-example-secret"
secret_data = dict(
aws.deploy_secret(name=secret_id, secret_data=secret_data)

Now open your AWS Console (Replace us-east-1 to your region), you should be able to see the new AWS Secret has been created.

Now let’s retrive the secret value

>>> aws.get_secret_value(secret_id="my-example-secret", key="password")
>>> aws.get_secret_value(secret_id="my-example-secret", key="metadata.creator")

Use KMS Key to encrypt and decrypt text is easy

>>> from pysecret import AWSSecret
>>> aws_profile = "my_aws_profile"
>>> kms_key_id = "abcd1234-ab12-ab12-ab12-abcd1234abcd"

>>> aws = AWSSecret(profile_name=aws_profile)
>>> secret = "Hello World".encode("utf-8)
>>> encrypted_blob = aws.kms_encrypt(kms_key_id, secret)
>>> decrypted_blob = aws.kms_decrypt(encrypted_blob)
>>> assert secret != encrypted_blob
>>> assert secret == decrypted_blob
>>> decrypted_blob.decode("utf-8")
Hello World

AWS System Manager Parameter Store Integration

Parameter store is a Free service allows you to securely store parameters

First let’s create a parameter:

from pysecret import AWSSecret

aws_profile = "my_aws_profile"
aws = AWSSecret(profile_name=aws_profile)

parameter_name = "my-example-parameter"
parameter_data = dict(

    use_default_kms_key=True, # encrypt it with default kms key

Now open your AWS Console (Replace us-east-1 to your region), you should be able to see the new Parameter has been created.

Now let’s retrive the parameter value:

# read parameter from AWS
assert aws.get_parameter_value(parameter_name, "project_name") == parameter_data["project_name"]
assert aws.get_parameter_value(parameter_name, "metadata.creator") == parameter_data["metadata"]["creator"]

It also support complex parameter object TOO, with attrs python library:

import attr

class Credential:
    username = attr.ib()
    password = attr.ib()

class PasswordBook:
    amazon = attr.ib()
    google = attr.ib()
    facebook = attr.ib()

password_book = PasswordBook(
    amazon=Credential("", "amazonpassword"),
    google=Credential("", "googlepassword"),
    facebook=Credential("", "facebookpassword"),

parameter_name = "my-passwordbook"

    use_default_kms_key=True, # encrypt it with default kms key

Then you can read complex object from parameter store:

password_book = aws.get_parameter_object(name=parameter_name)
print(password_book.facebook.password) # should be "facebookpassword"


pysecret is released on PyPI, so all you need is:

$ pip install pysecret

To upgrade to latest version:

$ pip install --upgrade pysecret

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pysecret-1.0.3.tar.gz (18.5 kB view hashes)

Uploaded source

Built Distribution

pysecret-1.0.3-py2.py3-none-any.whl (15.7 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page