[](https://pepy.tech/project/whispr)
[](https://coveralls.io/github/narenaryan/whispr)
# Whispr
Whispr (Pronounced as whisper) is a CLI tool to safely inject secrets from your favorite secret vault (Ex: AWS Secrets Manager, Azure Key Vault etc.) into your app's environment. This is very useful for enabling secure local software development.
Whispr uses keys (with empty values) specified in a `.env` file and fetches respective secrets from a vault, and sets them as environment variables before launching an application.
Install whispr easily with pip!
```bash
pip install whispr
```
Key Features of Whispr:
* **Safe Secret Injection**: Fetch and inject secrets from your desired vault using HTTPS, SSL encryption, strict CERT validation.
* **Just In Time (JIT) Privilege**: Set environment variables for developers only when they're needed.
* **Secure Development**: Eliminate plain-text secret storage and ensure a secure development process.
* **Customizable Configurations**: Configure project-level settings to manage multiple secrets for multiple projects.
* **No Custom Scripts Required**: Whispr eliminates the need for custom bash scripts or cloud CLI tools to manage secrets, making it easy to get started.
* **Easy Installation**: Cross-platform installation with PyPi.
* **Generate Random Sequences for key rotation**: Whispr can generate crypto-safe random sequences with a given length. Great for secret rotation.
Supported Vault Technologies:
# Why use Whispr ?
The MITRE ATT&CK Framework Tactic 8 (Credential Access) suggests that adversaries can exploit plain-text secrets and sensitive information stored in files like `.env`. It is essential to avoid storing
sensitive information in unencrypted files. To help developers, Whispr can safely fetch and inject secrets from a vault into the app environment or pass them as standard input just in time. This enables developers to securely manage
credentials and mitigate advisory exploitation tactics.
Whispr can also comes with handy utilities like:
1. Audit a secret from vault
```sh
whispr secret get --vault=aws --secret-name=my_secret --region=us-east-1
```
2. Generate a crypto-safe random sequences for rotated secrets
```sh
whispr secret gen-random --length=16 --exclude='*/^'
```
# Getting Started
## Installing Whispr
To get started with Whispr, simply run:
```bash
pip install whispr
```
## Configuring Your Project
**Step 1: Initialize Whispr**
Run `whispr init <vault_type>` in your terminal to create a `whispr.yaml` file in your project root. This file will store your configuration settings.
The available vault types are: `aws`, `azure`, and `gcp`.
**Example whispr.yaml contents (For: AWS):**
```yaml
env_file: '.env'
secret_name: <your_secret>
vault: aws
```
This default configuration will inject fetched secrets into `os.environ` of main process. If your app instead want to receive secrets as STDIN arguments, use `no_env: true` field.
This is a secure way than default control but app now should parse arguments itself.
```yaml
env_file: '.env'
secret_name: <your_secret>
vault: aws
no_env: true # Setting true will send KEY1=VAL1 secret pairs as command args
```
## Setting Up Your Injectable Secrets
**Step 2: Create or Configure a Secret File**
Create a new `.env` file with empty values for your secret keys. For example:
```bash
POSTGRES_USERNAME=
POSTGRES_PASSWORD=
```
**Note**: You can also control filename with `env_file` key in your `whispr.yaml`.
**Step 3: Authenticating to Your Vault (Ex:AWS)**
* Authenticate to AWS using Short-term credentials.
* Alternatively, set temporary AWS credentials using a config file or environment variables.
**Note**: Use respective authentication methods for other vaults.
## Launch any Application using Whispr (Requires a configuration file: `whispr.yaml`)
In contrary to programmatic access, if you want to run a script/program do: `whispr run '<your_app_command_with_args>'` (mind the single quotes around command) to inject your secrets before starting the subprocess.
Examples:
```bash
whispr run 'python main.py' # Inject secrets and run a Python program
whispr run 'node server.js --threads 4' # Inject secrets and run a Node.js express server
whispr run 'django manage.py runserver' # Inject secrets and start a Django server
whispr run '/bin/sh ./script.sh' # Inject secrets and run a custom bash script. Script should be permitted to execute
whispr run 'semgrep scan --pro' # Inject Semgrep App Token and scan current directory with Semgrep SAST tool.
```
## Programmatic access of Whispr (Doesn't require a configuration file)
Instead of using Whispr as an execution tool, a Python program can leverage core utility functions like this:
```bash
pip install whispr
```
Then from Python code you can import important functions like this:
```py
from whispr.utils.vault import fetch_secrets
from whispr.utils.process import execute_command
config = {
"vault": "aws",
"secret_name": "<your_secret_name>",
"region": "us-west-2"
}
secrets = fetch_secrets(config)
# Now, inject secrets into your command's environment
command = "ls -l"
cp = execute_command(command.split(), no_env=False, secrets=secrets) #cp is CompletedProcess object.
```
That's it. This is a programmatic equivalent to the tool usage which allows programs to fetch secrets from vault at run time.
## TODO
Support:
* HashiCorp Vault
* 1Password Vault
* K8s secret patching
* Container patching (docker)
* Increase test coverage
Raw data
{
"_id": null,
"home_page": null,
"name": "whispr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "code-security, cybersecurity, devsecops, mitre-attack-framework, no-plain-secrets, whispr",
"author": null,
"author_email": "Naren Yellavula <naren.yellavula@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/33/ae/9a6ade50b7e4fe6ec89ffcd90ef6a138932aff5137728ca3d8c4719fb981/whispr-0.6.0.tar.gz",
"platform": null,
"description": "[](https://pepy.tech/project/whispr)\n[](https://coveralls.io/github/narenaryan/whispr)\n\n# Whispr\n\n\n\nWhispr (Pronounced as whisper) is a CLI tool to safely inject secrets from your favorite secret vault (Ex: AWS Secrets Manager, Azure Key Vault etc.) into your app's environment. This is very useful for enabling secure local software development.\n\nWhispr uses keys (with empty values) specified in a `.env` file and fetches respective secrets from a vault, and sets them as environment variables before launching an application.\n\nInstall whispr easily with pip!\n\n```bash\npip install whispr\n```\n\nKey Features of Whispr:\n\n* **Safe Secret Injection**: Fetch and inject secrets from your desired vault using HTTPS, SSL encryption, strict CERT validation.\n* **Just In Time (JIT) Privilege**: Set environment variables for developers only when they're needed.\n* **Secure Development**: Eliminate plain-text secret storage and ensure a secure development process.\n* **Customizable Configurations**: Configure project-level settings to manage multiple secrets for multiple projects.\n* **No Custom Scripts Required**: Whispr eliminates the need for custom bash scripts or cloud CLI tools to manage secrets, making it easy to get started.\n* **Easy Installation**: Cross-platform installation with PyPi.\n* **Generate Random Sequences for key rotation**: Whispr can generate crypto-safe random sequences with a given length. Great for secret rotation.\n\nSupported Vault Technologies:\n\n\n\n\n# Why use Whispr ?\n\nThe MITRE ATT&CK Framework Tactic 8 (Credential Access) suggests that adversaries can exploit plain-text secrets and sensitive information stored in files like `.env`. It is essential to avoid storing\nsensitive information in unencrypted files. To help developers, Whispr can safely fetch and inject secrets from a vault into the app environment or pass them as standard input just in time. This enables developers to securely manage\ncredentials and mitigate advisory exploitation tactics.\n\nWhispr can also comes with handy utilities like:\n\n1. Audit a secret from vault\n\n```sh\nwhispr secret get --vault=aws --secret-name=my_secret --region=us-east-1\n```\n\n2. Generate a crypto-safe random sequences for rotated secrets\n\n```sh\nwhispr secret gen-random --length=16 --exclude='*/^'\n```\n\n# Getting Started\n\n## Installing Whispr\n\nTo get started with Whispr, simply run:\n\n```bash\npip install whispr\n```\n\n## Configuring Your Project\n\n**Step 1: Initialize Whispr**\n\nRun `whispr init <vault_type>` in your terminal to create a `whispr.yaml` file in your project root. This file will store your configuration settings.\n\nThe available vault types are: `aws`, `azure`, and `gcp`.\n\n**Example whispr.yaml contents (For: AWS):**\n```yaml\nenv_file: '.env'\nsecret_name: <your_secret>\nvault: aws\n```\nThis default configuration will inject fetched secrets into `os.environ` of main process. If your app instead want to receive secrets as STDIN arguments, use `no_env: true` field.\nThis is a secure way than default control but app now should parse arguments itself.\n\n```yaml\nenv_file: '.env'\nsecret_name: <your_secret>\nvault: aws\nno_env: true # Setting true will send KEY1=VAL1 secret pairs as command args\n```\n\n## Setting Up Your Injectable Secrets\n\n**Step 2: Create or Configure a Secret File**\n\nCreate a new `.env` file with empty values for your secret keys. For example:\n\n```bash\nPOSTGRES_USERNAME=\nPOSTGRES_PASSWORD=\n```\n\n**Note**: You can also control filename with `env_file` key in your `whispr.yaml`.\n\n**Step 3: Authenticating to Your Vault (Ex:AWS)**\n\n* Authenticate to AWS using Short-term credentials.\n* Alternatively, set temporary AWS credentials using a config file or environment variables.\n\n**Note**: Use respective authentication methods for other vaults.\n\n## Launch any Application using Whispr (Requires a configuration file: `whispr.yaml`)\nIn contrary to programmatic access, if you want to run a script/program do: `whispr run '<your_app_command_with_args>'` (mind the single quotes around command) to inject your secrets before starting the subprocess.\n\nExamples:\n```bash\nwhispr run 'python main.py' # Inject secrets and run a Python program\nwhispr run 'node server.js --threads 4' # Inject secrets and run a Node.js express server\nwhispr run 'django manage.py runserver' # Inject secrets and start a Django server\nwhispr run '/bin/sh ./script.sh' # Inject secrets and run a custom bash script. Script should be permitted to execute\nwhispr run 'semgrep scan --pro' # Inject Semgrep App Token and scan current directory with Semgrep SAST tool.\n```\n\n## Programmatic access of Whispr (Doesn't require a configuration file)\n\nInstead of using Whispr as an execution tool, a Python program can leverage core utility functions like this:\n\n```bash\npip install whispr\n```\n\nThen from Python code you can import important functions like this:\n\n```py\nfrom whispr.utils.vault import fetch_secrets\nfrom whispr.utils.process import execute_command\n\nconfig = {\n \"vault\": \"aws\",\n \"secret_name\": \"<your_secret_name>\",\n \"region\": \"us-west-2\"\n}\n\nsecrets = fetch_secrets(config)\n\n# Now, inject secrets into your command's environment\ncommand = \"ls -l\"\ncp = execute_command(command.split(), no_env=False, secrets=secrets) #cp is CompletedProcess object.\n```\n\nThat's it. This is a programmatic equivalent to the tool usage which allows programs to fetch secrets from vault at run time.\n\n## TODO\n\nSupport:\n\n* HashiCorp Vault\n* 1Password Vault\n* K8s secret patching\n* Container patching (docker)\n* Increase test coverage\n",
"bugtrack_url": null,
"license": null,
"summary": "A CLI tool to whisper your secrets between secure vault and your local environment",
"version": "0.6.0",
"project_urls": {
"Documentation": "https://github.com/cybrota/whispr/blob/main/README.md",
"Issues": "https://github.com/cybrota/whispr/issues",
"Source": "https://github.com/cybrota/whispr"
},
"split_keywords": [
"code-security",
" cybersecurity",
" devsecops",
" mitre-attack-framework",
" no-plain-secrets",
" whispr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5ca1b06b127fb55d74084c78f6c53bc04b07ff626f9a6216dda17c5dd5c6f6c8",
"md5": "5e05a4e3e81c22975698896fcbf1bf54",
"sha256": "6cecabd3b2daa561ba2f90b0d41b50e88fe2e6f6229d92790ba60455bb949337"
},
"downloads": -1,
"filename": "whispr-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e05a4e3e81c22975698896fcbf1bf54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15408,
"upload_time": "2025-01-15T04:40:00",
"upload_time_iso_8601": "2025-01-15T04:40:00.487503Z",
"url": "https://files.pythonhosted.org/packages/5c/a1/b06b127fb55d74084c78f6c53bc04b07ff626f9a6216dda17c5dd5c6f6c8/whispr-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "33ae9a6ade50b7e4fe6ec89ffcd90ef6a138932aff5137728ca3d8c4719fb981",
"md5": "6c4abdde8a51395381a69d6e2cc060f8",
"sha256": "d0da154b1288c9a0901a22be6a9ab57e93e90367cc995ae981f421c6d5b4ebae"
},
"downloads": -1,
"filename": "whispr-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "6c4abdde8a51395381a69d6e2cc060f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 170815,
"upload_time": "2025-01-15T04:40:03",
"upload_time_iso_8601": "2025-01-15T04:40:03.218200Z",
"url": "https://files.pythonhosted.org/packages/33/ae/9a6ade50b7e4fe6ec89ffcd90ef6a138932aff5137728ca3d8c4719fb981/whispr-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-15 04:40:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cybrota",
"github_project": "whispr",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "boto3",
"specs": [
[
"==",
"1.35.42"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "google-cloud-secret-manager",
"specs": [
[
"==",
"2.20.2"
]
]
},
{
"name": "structlog",
"specs": [
[
"==",
"24.4.0"
]
]
},
{
"name": "azure-keyvault",
"specs": [
[
"==",
"4.2.0"
]
]
},
{
"name": "azure-identity",
"specs": [
[
"==",
"1.19.0"
]
]
},
{
"name": "hvac",
"specs": [
[
"==",
"2.3.0"
]
]
}
],
"lcname": "whispr"
}
JSON
