[![Build][build-shield]][build-url] [![Contributors][contributors-shield]][contributors-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url]

<a href="https://github.com/sebastiean/volt"> <img src="images/logo.jpg" alt="Logo" width="100"> </a>  An open source Azure Key Vault API compatible server (emulator). <a href="https://github.com/sebastiean/volt/issues">Report Bug</a> · <a href="https://github.com/sebastiean/volt/issues">Request Feature</a>

🚨 This project is in alpha status. This means that bugs are extremely likely and no assurances are made about compatability with the Key Vault REST API.

<details open="open"> <summary>Table of Contents</summary> <ol> <li><a href="#about-the-project">About The Project</a></li> <li><a href="#getting-started">Getting Started</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#roadmap">Roadmap</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> <li><a href="#acknowledgements">Acknowledgements</a></li> </ol> </details>

About The Project

Volt is an open source Azure Key Vault API compatible server (emulator) based on Node.js and written in Typescript.

Volt is inspired by and heavily based on Azurite, an Azure Storage API emulator. Volt uses (pretty much) the same architecture and patterns that are found in the Azurite project.

Built With

Supported Features

Secrets API
- Set Secret
- Update Secret
- Get Secret
- Get Secret Versions
- Get Secrets
- Delete Secret
- Get Deleted Secret
- ~~Get Deleted Secrets~~ *Not yet supported
- ~~Backup Secret~~ *Not yet supported
- ~~Purge Deleted Secret~~ *Not yet supported
- ~~Recover Deleted Secret~~ *Not yet supported
- ~~Restore Secret~~ *Not yet supported

Getting Started

Install / run using one of the following options:

Clone this repo

After cloning source code, execute following commands to install and start Volt.

npm ci
npm run build
npm install -g
volt [options]

DockerHub

Run Volt docker image

docker run -p 13000:13000 sebastiean/volt

-p 13000:13000 will expose secrets service default listening port.

Run Volt docker image with customized persisted data location

docker run -p 13000:13000 -v ~/volt:/data sebastiean/volt

-v ~/volt:/data will use and map host path ~/volt as Volt's workspace location.

Customize other Volt supported parameters for docker image

docker run -p 8888:8888 -v ~/volt:/data sebastiean/volt volt -l --secretsPort 8888 --secretsHost 0.0.0.0 --loose --skipApiVersionCheck --cert ./localhost.cert --key ./localhost.key --oauth basic

When running via Docker with HTTPS enabled, you must use --secretsHost 0.0.0.0 to correctly bind to the correct hostname.

Usage

SDK

To use Volt with the Azure Key Vault SDKs, you <ins>must</ins> enable HTTPS and OAuth.

volt --oauth basic --cert certname.pem --key certname-key.pem

Example (JavaScript SDK):

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();
         
const url = `https://127.0.0.1:13000`;

const client = new SecretClient(url, credential);

Command line options

Standard options

| Option | Example | Description | |----------------------------- |------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --secretsHost <host> | --secretsHost 127.0.0.1 | Listening host. By default Volt secrets will listen on 127.0.0.1 Use 0.0.0.0 to accept requests from remote addresses (unsafe). | | ---secretsPort <port> | --secretsPort 8888 | Listening port. By default, Volt will listen on port 13000 for secrets. Customize the listening port per your requirements. | | -s ---silent | | Disable access logs. By default Volt will display access logs in the console. | | -d <path> --debug <path> | -d ./debug.log | Debug log includes detailed information on every request and exception stack traces. Enable it by providing a valid local file path for the debug log destination. | | -L --loose | | By default Volt will apply strict mode. Strict mode will block unsupported request headers or parameters. Disable it by enabling loose mode. |

Certificate options (HTTPS)

Please see HTTPS Setup section for help with creating self-signed certificates to use with Volt.

OAuth options

Currently, Volt supports following OAuth authentication levels:

Basic

In basic level, --oauth basic, Volt will do basic authentication, such as validating incoming bearer token, checking issuer, audience, expiry.
<ins>Volt will NOT verify the token signature or permission</ins>.

Key Vault specific options

These options can be used to change the soft-delete behaviour of Volt. Please see the linked official documentation to understand this feature.

| Option | Example | Description | |------------------------- |---------------------- |------------------------------------------------------------------------------------------------------------------------------- | | --disableSoftDelete | | Disable the soft-delete feature entirely. See https://docs.microsoft.com/en-us/azure/key-vault/general/soft-delete-change | | --recoverableDays | --recoverableDays 10 | Number of calendar days deleted vault objects remain in a recoverable state. Should be between 7 and 90. Default is 90. | | --purgeProtection | | If enabled, deleted vault objects cannot be purged during the retention period. | | --protectedSubscription | | If enabled, Volt will behave as if part of a subscription that cannot be cancelled. |

HTTPS Setup

This section is borrowed almost directly from Azurite

Volt natively supports HTTPS with self-signed certificates via the --cert and --key/--pwd options. You have two certificate type options: PEM or PFX. PEM certificates are split into "cert" and "key" files. A PFX certificate is a single file that can be assigned a password.

PEM

Generate PEM Certificate and Key

You have a few options to generate PEM certificate and key files. We'll show you how to use mkcert and OpenSSL.

mkcert

[mkcert](https://github.

Volt

Install / Use

README