Skip to content

Latest commit

 

History

History
96 lines (74 loc) · 4.86 KB

README.md

File metadata and controls

96 lines (74 loc) · 4.86 KB
Raw

scalesec-secret-store:

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

Debugging

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

  1. Install and register your plugin. make-scalesec-secret-store-plugin.sh deploy
  2. Run a vault command to start the plugin backend. vault list scalesecsecrets/test
  3. Locate the process that above step created. ps -ef | grep scalesecSecretStorePlugin or pgrep scalesecSecretStorePlugin
  4. Run dlv to attach to the process $HOME/go/bin/dlv attach 56135 You should now have a (dlv) command line.
  5. 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

  1. Install and register your plugin. make-scalesec-secret-store-plugin.sh deploy
  2. Run a vault command to start the plugin backend. vault list scalesecsecrets/test
  3. Locate the process that above step created. ps -ef | grep scalesecSecretStorePlugin or pgrep scalesecSecretStorePlugin
  4. Create a debug "launch.json" file: https://code.visualstudio.com/docs/editor/debugging
  5. 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": ####
 }
  6. Run this launch config from the debugger.
  7. 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

References

Developing this example the following references were very helpful.