Vault Custom Plugin scalesecSecretStore is an example Hashicorp custom secret engine plugin based off the Hashicorp vault-guides. This version helps illustrate how to create a custom secret store backend and provides a starting point to help jump start your own custom plugin develoment.It does this by providing:
- Comments in the code explaining what the sections of code are doing
- Logging in all the defined functions so you can see the plugin life cycle at work.
- Providing a unified development; testing and debugging experience under one single project
Setup:
- Installation of Go Lang is required to build the plugin. A fundamental knowledge of go is not required but is recommended.
- Installation of Hashicorp Vault is required. It is recommend you use the ScaleSec Vault Assistant project: https://github.com/ScaleSec/vault-assistant to install vault. This helps provide the unified experience.
- VSCode is recommended for an IDE and is what we base our examples on.
- Checkout the scalesec-secret-store project from GitHub.
Useage:
make-scalesec-secret-store-plugin.sh
: command script to help you build and deploy the plugin code. It takes in the following arguments in sequence you wish executed:
- debug - Set the debug flags for the a build
- build - Build the plugin
- deploy - Deploy and Register the plugin to vault. Handles removing prior installs
- test - Run all the test functions listed below
- test_list - Test/Run just the vault list function
- test_read - Test/Run just the vault read function
- test_write - Test/Run just the vault write function
- test_delete - Test/Run just the vault delete function
Example Usage:
make-scalesec-secret-store-plugin.sh build deploy
There are two options using the interactive debugger in VSCode.
- Command Line
- VSCode Debugger GUI
Setup:
- Install of "Delve" is required. The most common way to install is running the command:
go install github.com/go-delve/delve/cmd/dlv@latest
For more detailed install information visit the Delve web site: https://github.com/go-delve/delve
- Compile for debugging. Compile with the flags: -gcflags "all=-N -l". Run:
make-scalesec-secret-store-plugin.sh debug build
Command Line
- Install and register your plugin.
make-scalesec-secret-store-plugin.sh deploy
- Run a vault command to start the plugin backend.
vault list scalesecsecrets/test
- Locate the process that above step created.
ps -ef | grep scalesecSecretStorePlugin
orpgrep scalesecSecretStorePlugin
- Run dlv to attach to the process
$HOME/go/bin/dlv attach 56135
You should now have a (dlv) command line. - Set some breakpoins and now your ready to invoke your plugin to debug
-
export VAULT_CLIENT_TIMEOUT=300
To extend the CLI timeout to give you time to debug -
vault list scalesecsecrets/test
Run the command you want to debug
-
Delve Commands: Enter help to learn the commands to use dlv. Hear are some to help
- b = set break point
- n = next line
- c = continue to next break point
- args = show values of arguments passed to current function
- locals = show values of local function variables
- exit = exit
VSCode Debugger GUI
- Install and register your plugin.
make-scalesec-secret-store-plugin.sh deploy
- Run a vault command to start the plugin backend.
vault list scalesecsecrets/test
- Locate the process that above step created.
ps -ef | grep scalesecSecretStorePlugin
orpgrep scalesecSecretStorePlugin
- Create a debug "launch.json" file: https://code.visualstudio.com/docs/editor/debugging
- Your launch.json should contain the following block of code. #### should be replaced with the process number you located in step 3
{ "name": "Attach to local process", "type": "go", "request": "attach", "mode": "local", "processId": #### }
- Run this launch config from the debugger.
- Set some breakpoints and now your ready to invoke your plugin to debug
-
export VAULT_CLIENT_TIMEOUT=300
To extend the CLI timeout to give you time to debug -
vault list scalesecsecrets/test
Run the command you want to debug
-
Developing this example the following references were very helpful.
- https://learn.hashicorp.com/tutorials/vault/getting-started-secrets-engines
- https://learn.hashicorp.com/tutorials/vault/plugin-backends
- https://discuss.hashicorp.com/t/debug-vault-plugin-with-vs-code/14806/2
- https://groups.google.com/g/vault-tool/c/oV5bi1ls76s
- https://github.com/golang/vscode-go/blob/master/docs/debugging.md
- https://github.com/golang/vscode-go/blob/master/docs/debugging-legacy.md#selecting-legacy-debug-adapter