Usage

Commands (and subcommands) generally follow the model set by the OpenStackClient for its Command Structure. The general structure of a command is:

$ psec [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>]

Note

When originally written, python_secrets was the primary command name. And the Python secrets module did not yet exist. The name python_secrets is a little unwieldy to type on the command line, so a shorter script name psec was also included in the original release. The original python_secrets program name is now deprecated.

In this documentation and command line help, the program name psec is used. (The PyPi package may be renamed at a later date to avoid confusion between the package and the program.)

The actions are things like list, show, generate, set, etc.

Note

A proof-of-concept for using the python_secrets package in an open source project to eliminate default passwords and keep secrets out of the source code repository directory can be found here:

https://davedittrich.github.io/goSecure/documentation.html

Getting help

To get help information on global command arguments and options, use the help command or --help option flag. The usage documentation below will detail help output for each command.

Formatters

The cliff Command Line Formulation Framework provides a set of formatting options that facilitate accessing and using stored secrets in other applications. Data can be passed directly in a structured format like CSV, or passed directly to programs like Ansible using JSON.

Attention

The formatter options are shown in the --help output for individual commands (e.g., psec secrets show --help). For the purposes of this chapter, including the lengthy formatter options on every command would be quite repetitive and take up a lot of space. For this reason, the formatter options will be suppressed for commands as documented below. The difference (WITH and WITHOUT the formatting options) would look like this:

WITH formatting options

secrets show

List the contents of the secrets file or definitions.

The secrets show command is used to see variables, their values, and exported environment variables to help in using them in your code, shell scripts, etc. To see more metadata-ish information, such as their group, type, etc., use the secrets describe command instead.

To get show a subset of secrets, specify their names as arguments. If you instead want to show all secrets in one or more groups, use the --group option and specify the group names as arguments, or to show all secrets of one or more types, use the --type option:

$ psec secrets show
+------------------------+----------+------------------------+
| Variable               | Value    | Export                 |
+------------------------+----------+------------------------+
| jenkins_admin_password | REDACTED | jenkins_admin_password |
| myapp_app_password     | REDACTED | DEMO_app_password      |
| myapp_client_psk       | REDACTED | DEMO_client_ssid       |
| myapp_client_ssid      | REDACTED | DEMO_client_ssid       |
| myapp_pi_password      | REDACTED | DEMO_pi_password       |
| trident_db_pass        | REDACTED | trident_db_pass        |
| trident_sysadmin_pass  | REDACTED | trident_sysadmin_pass  |
+------------------------+----------+------------------------+

Visually finding undefined variables in a very long list can be difficult. You can show just undefined variables with the --undefined option.

psec secrets show
    [-f {csv,json,table,value,yaml}]
    [-c COLUMN]
    [--quote {all,minimal,none,nonnumeric}]
    [--noindent]
    [--max-width <integer>]
    [--fit-width]
    [--print-empty]
    [--sort-column SORT_COLUMN]
    [--sort-ascending | --sort-descending]
    [-C]
    [-p]
    [--undefined]
    [-g | -t]
    [arg [arg ...]]
-f <FORMATTER>, --format <FORMATTER>

the output format, defaults to table

-c COLUMN, --column COLUMN

specify the column(s) to include, can be repeated to show multiple columns

--quote <QUOTE_MODE>

when to include quotes, defaults to nonnumeric

--noindent

whether to disable indenting the JSON

--max-width <integer>

Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.

--fit-width

Fit the table to the display width. Implied if –max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable

--print-empty

Print empty table if there is no data to show.

--sort-column SORT_COLUMN

specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated

--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

-C, --no-redact

Do not redact values in output

-p, --prompts

Include prompts

--undefined

Only show variables that are not yet defined

-g, --group

Arguments are groups to show

-t, --type

Arguments are types to show

arg

This command is provided by the python-secrets plugin.

WITHOUT formatting options

secrets show

List the contents of the secrets file or definitions.

The secrets show command is used to see variables, their values, and exported environment variables to help in using them in your code, shell scripts, etc. To see more metadata-ish information, such as their group, type, etc., use the secrets describe command instead.

To get show a subset of secrets, specify their names as arguments. If you instead want to show all secrets in one or more groups, use the --group option and specify the group names as arguments, or to show all secrets of one or more types, use the --type option:

$ psec secrets show
+------------------------+----------+------------------------+
| Variable               | Value    | Export                 |
+------------------------+----------+------------------------+
| jenkins_admin_password | REDACTED | jenkins_admin_password |
| myapp_app_password     | REDACTED | DEMO_app_password      |
| myapp_client_psk       | REDACTED | DEMO_client_ssid       |
| myapp_client_ssid      | REDACTED | DEMO_client_ssid       |
| myapp_pi_password      | REDACTED | DEMO_pi_password       |
| trident_db_pass        | REDACTED | trident_db_pass        |
| trident_sysadmin_pass  | REDACTED | trident_sysadmin_pass  |
+------------------------+----------+------------------------+

Visually finding undefined variables in a very long list can be difficult. You can show just undefined variables with the --undefined option.

psec secrets show
    [--sort-ascending | --sort-descending]
    [-C]
    [-p]
    [--undefined]
    [-g | -t]
    [arg [arg ...]]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

-C, --no-redact

Do not redact values in output

-p, --prompts

Include prompts

--undefined

Only show variables that are not yet defined

-g, --group

Arguments are groups to show

-t, --type

Arguments are types to show

arg

This command is provided by the python-secrets plugin.

Formatting examples

CSV output (with header) can be produced like this:

$ psec secrets show -f csv --column Variable --column Value
"Variable","Value"
"trident_db_pass","gargle earlobe eggplant kissable"
"ca_rootca_password","gargle earlobe eggplant kissable"
"consul_key","HEvUAItLFZ0+GjxfwTxLDKq5Fbt86UtXrInzpf71GGY="
"jenkins_admin_password","gargle earlobe eggplant kissable"
"rabbitmq_default_user_pass","gargle earlobe eggplant kissable"
"rabbitmq_admin_user_pass","gargle earlobe eggplant kissable"
"trident_sysadmin_pass","gargle earlobe eggplant kissable"
"vncserver_password","gargle earlobe eggplant kissable"
"zookeeper_uuid4","769a77ad-b06f-4018-857e-23f970c777c2"

Or you can produce JSON and have structured data for consumption by other programs.

$ psec secrets show -f json --column Variable --column Value
[
  {
    "Variable": "trident_db_pass",
    "Value": "gargle earlobe eggplant kissable"
  },
  {
    "Variable": "ca_rootca_password",
    "Value": "gargle earlobe eggplant kissable"
  },
  {
    "Variable": "consul_key",
    "Value": "HEvUAItLFZ0+GjxfwTxLDKq5Fbt86UtXrInzpf71GGY="
  },
  {
    "Variable": "jenkins_admin_password",
    "Value": "gargle earlobe eggplant kissable"
  },
  {
    "Variable": "rabbitmq_default_user_pass",
    "Value": "gargle earlobe eggplant kissable"
  },
  {
    "Variable": "rabbitmq_admin_user_pass",
    "Value": "gargle earlobe eggplant kissable"
  },
  {
    "Variable": "trident_sysadmin_pass",
    "Value": "gargle earlobe eggplant kissable"
  },
  {
    "Variable": "vncserver_password",
    "Value": "gargle earlobe eggplant kissable"
  },
  {
    "Variable": "zookeeper_uuid4",
    "Value": "769a77ad-b06f-4018-857e-23f970c777c2"
  }
]

The JSON can be manipulated, filtered, and restructured using a program like jq, for example:

$ psec secrets show -f json --column Variable --column Value |
> jq -r '.[] | { (.Variable): .Value } '
{
  "trident_db_pass": "gargle earlobe eggplant kissable"
}
{
  "ca_rootca_password": "gargle earlobe eggplant kissable"
}
{
  "consul_key": "HEvUAItLFZ0+GjxfwTxLDKq5Fbt86UtXrInzpf71GGY="
}
{
  "jenkins_admin_password": "gargle earlobe eggplant kissable"
}
{
  "rabbitmq_default_user_pass": "gargle earlobe eggplant kissable"
}
{
  "rabbitmq_admin_user_pass": "gargle earlobe eggplant kissable"
}
{
  "trident_sysadmin_pass": "gargle earlobe eggplant kissable"
}
{
  "vncserver_password": "gargle earlobe eggplant kissable"
}
{
  "zookeeper_uuid4": "769a77ad-b06f-4018-857e-23f970c777c2"
}
$ psec secrets show -f json --column Variable --column Value |
> jq -r '.[] | [ (.Variable), .Value ] '
[
  "trident_db_pass",
  "gargle earlobe eggplant kissable"
]
[
  "ca_rootca_password",
  "gargle earlobe eggplant kissable"
]
[
  "consul_key",
  "HEvUAItLFZ0+GjxfwTxLDKq5Fbt86UtXrInzpf71GGY="
]
[
  "jenkins_admin_password",
  "gargle earlobe eggplant kissable"
]
[
  "rabbitmq_default_user_pass",
  "gargle earlobe eggplant kissable"
]
[
  "rabbitmq_admin_user_pass",
  "gargle earlobe eggplant kissable"
]
[
  "trident_sysadmin_pass",
  "gargle earlobe eggplant kissable"
]
[
  "vncserver_password",
  "gargle earlobe eggplant kissable"
]
[
  "zookeeper_uuid4",
  "769a77ad-b06f-4018-857e-23f970c777c2"
]
$ psec secrets show -f json --column Variable --column Value |
> jq -r '.[] | [ (.Variable), .Value ] |@sh'
'trident_db_pass' 'gargle earlobe eggplant kissable'
'ca_rootca_password' 'gargle earlobe eggplant kissable'
'consul_key' 'HEvUAItLFZ0+GjxfwTxLDKq5Fbt86UtXrInzpf71GGY='
'jenkins_admin_password' 'gargle earlobe eggplant kissable'
'rabbitmq_default_user_pass' 'gargle earlobe eggplant kissable'
'rabbitmq_admin_user_pass' 'gargle earlobe eggplant kissable'
'trident_sysadmin_pass' 'gargle earlobe eggplant kissable'
'vncserver_password' 'gargle earlobe eggplant kissable'
'zookeeper_uuid4' '769a77ad-b06f-4018-857e-23f970c777c2'
$ psec secrets show -f json --column Variable --column Value |
> jq -r '.[] | [ (.Variable), .Value ] |@csv'
"trident_db_pass","gargle earlobe eggplant kissable"
"ca_rootca_password","gargle earlobe eggplant kissable"
"consul_key","HEvUAItLFZ0+GjxfwTxLDKq5Fbt86UtXrInzpf71GGY="
"jenkins_admin_password","gargle earlobe eggplant kissable"
"rabbitmq_default_user_pass","gargle earlobe eggplant kissable"
"rabbitmq_admin_user_pass","gargle earlobe eggplant kissable"
"trident_sysadmin_pass","gargle earlobe eggplant kissable"
"vncserver_password","gargle earlobe eggplant kissable"
"zookeeper_uuid4","769a77ad-b06f-4018-857e-23f970c777c2"

Commands

The following is reduced --help output for each subcommand supported by psec. See Formatting examples, or explicitly request --help output for the subcommand in question on the command line, to see the suppressed formatting options.

Environments

environments create

Create environment(s).

Empty environments can be created as needed, one at a time or several at once. Specify the names on the command line as arguments:

$ psec environments create development testing production
[+] environment directory /Users/dittrich/.secrets/development created
[+] environment directory /Users/dittrich/.secrets/testing created
[+] environment directory /Users/dittrich/.secrets/production created

In some special circumstances, it may be necessary to have one set of identical secrets that have different environment names. If this happens, you can create an alias (see also the environments list command):

$ psec environments create --alias evaluation testing

To make it easier to bootstrap an open source project, where the use may not be intimately familiar with all necessary secrets and settings, you can make their life easier by preparing an empty set of secret descriptions that will help prompt the user to set them. You can do this following these steps:

  1. Create a template secrets environment directory that contains just the secrets definitions. This example uses the template found in the davedittrich/goSecure repository (directory https://github.com/davedittrich/goSecure/tree/master/secrets).

  2. Use this template to clone a secrets environment, which will initially be empty:

    $ psec environments create test --clone-from ~/git/goSecure/secrets
    [+] new password variable "gosecure_app_password" is unset
    [+] new string variable "gosecure_client_ssid" is unset
    [+] new string variable "gosecure_client_ssid" is unset
    [+] new string variable "gosecure_client_psk" is unset
    [+] new password variable "gosecure_pi_password" is unset
    [+] new string variable "gosecure_pi_pubkey" is unset
    [+] environment directory /Users/dittrich/.secrets/test created
    

Note: Directory and file permissions on cloned environments will prevent other from having read/write/execute permissions (i.e., o-rwx in terms of the chmod command.)

psec environments create
    [-A ALIAS | -C CLONE_FROM]
    [--force]
    [env [env ...]]
-A <ALIAS>, --alias <ALIAS>

Environment to alias

-C <CLONE_FROM>, --clone-from <CLONE_FROM>

Environment directory to clone from

--force

Create secrets base directory

env

This command is provided by the python-secrets plugin.

environments default

Manage default environment via file in cwd.

If no default is explicitly set, the default that would be applied is returned:

$ cd ~/git/psec
$ psec environments default
[+] default environment is "psec"

When listing environments, the default environment that would be implicitly used will be identified:

$ psec environments list
+-------------+---------+
| Environment | Default |
+-------------+---------+
| development | No      |
| testing     | No      |
| production  | No      |
+-------------+---------+

The following shows setting and unsetting the default:

$ psec environments default testing
[+] default environment set to "testing"
$ psec environments default
testing
$ psec environments list
+-------------+---------+
| Environment | Default |
+-------------+---------+
| development | No      |
| testing     | Yes     |
| production  | No      |
+-------------+---------+
$ psec environments default --unset-default
[+] default environment unset
psec environments default [--set | --unset] [environment]
--set

Set localized environment default

--unset

Unset localized environment default

environment

This command is provided by the python-secrets plugin.

environments delete

Delete environment.

Deleting an environment requires explicitly naming the environment to delete and confirmation from the user. This is done in one of two ways: by prompting the user to confirm the environment to delete, or by requiring the --force option flag be set along with the name.

When this command is run in a terminal shell (i.e., with a TTY), the user will be asked to type the name again to confirm the operation:

$ psec environments delete testenv
Type the name 'testenv' to confirm: testenv
[+] deleted directory path '/Users/dittrich/.secrets/testenv'

If no TTY is present (i.e., a shell script running in the background), an exception is raised that includes the files that will be deleted and explaining how to force the deletion:

$ psec environments delete testenv
[-] must use '--force' flag to delete an environment.
[-] the following will be deleted:
/Users/dittrich/.secrets/testenv
├── secrets.d
│   ├── ansible.json
│   ├── ca.json
│   ├── consul.json
│   ├── do.json
│   ├── jenkins.json
│   ├── opendkim.json
│   ├── rabbitmq.json
│   └── trident.json
└── token.json

The --force flag will allow deletion of the environment:

$ psec environments delete --force testenv
[+] deleted directory path /Users/dittrich/.secrets/testenv
psec environments delete [--force] [environment]
--force

Mandatory confirmation

environment

This command is provided by the python-secrets plugin.

environments list

List the current environments.

You can get a list of all available environments at any time, including which one would be the default used by sub-commands:

$ psec environments list
+-------------+---------+
| Environment | Default |
+-------------+---------+
| development | No      |
| testing     | No      |
| production  | No      |
+-------------+---------+

To see which environments are aliases, use the --aliasing option:

$ psec -v environments create --alias evaluation testing
$ psec environments list --aliasing
+-------------+---------+----------+
| Environment | Default | AliasFor |
+-------------+---------+----------+
| development | No      |          |
| evaluation  | No      | testing  |
| testing     | No      |          |
| production  | No      |          |
+-------------+---------+----------+

If there are any older environments that contain .yml files for storing secrets or definitions, they will be called out when you list environments. (Adding -v will explicitly list the names of files that are found if you wish to see them.):

$ psec environments list
[!] environment 'algo' needs conversion (see 'psec utils yaml-to-json --help')
[!] environment 'hypriot' needs conversion (see 'psec utils yaml-to-json --help')
[!] environment 'kali-packer' needs conversion (see 'psec utils yaml-to-json --help')
+-------------------------+---------+
| Environment             | Default |
+-------------------------+---------+
| attack_range            | No      |
| attack_range_local      | No      |
| flash                   | No      |
| python_secrets          | Yes     |
+-------------------------+---------+
psec environments list
    [--sort-ascending | --sort-descending]
    [--aliasing]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

--aliasing

Include aliasing

This command is provided by the python-secrets plugin.

environments path

Return path to files and directories for environment.

Provides the full absolute path to the environment directory for the environment and any specified subdirectories:

$ psec environments path
/Users/dittrich/.secrets/psec
$ psec environments path -e goSecure
/Users/dittrich/.secrets/goSecure

Using the --exists option will just exit with return code 0 when the environment directory exists, or 1 if it does not, and no path is printed on stdout.

To append subdirectory components, provide them as arguments and they will be concatenated with the appropriate OS path separator:

$ psec environments path -e goSecure configs
/Users/dittrich/.secrets/goSecure/configs

To ensure the directory path specified by command line arguments is present in the file system, use the --create option.

Using the --tmpdir option will return the path to the temporary directory for the environment. If the environment’s directory already exists, the temporary directory will be also be created so it is ready for use. If the environment directory does not already exist, the program will exit with an error message. Again, the --create changes this behavior and the missing directory path will be created.

psec environments path
    [--create]
    [--exists]
    [--json]
    [--tmpdir]
    [subdir [subdir ...]]
--create

Create the directory path if it does not yet exist

--exists

Check to see if environment exists and return exit code (0==exists, 1==not)

--json

Output in JSON (e.g., for Terraform external data source)

--tmpdir

Create and/or return tmpdir for this environment

subdir

This command is provided by the python-secrets plugin.

environments rename

Rename environment.

Just like mv, renames an environment from the name specified by the first argument to that of the second argument:

$ psec environments list
+----------------+---------+
| Environment    | Default |
+----------------+---------+
| old            | No      |
+----------------+---------+
$ psec environments rename new old
[-] source environment "new" does not exist
$ psec environments rename old new
[+] environment "old" renamed to "new"
$ psec environments list
+----------------+---------+
| Environment    | Default |
+----------------+---------+
| new            | No      |
+----------------+---------+
psec environments rename source dest
source

environment to rename

dest

new environment name

This command is provided by the python-secrets plugin.

environments tree

Output tree listing of files/directories in environment.

The environments tree command produces output similar to the Unix tree command:

$ psec -e d2 environments tree
/Users/dittrich/.secrets/d2
├── backups
│   ├── black.secretsmgmt.tk
│   │   ├── letsencrypt_2018-04-06T23:36:58PDT.tgz
│   │   └── letsencrypt_2018-04-25T16:32:20PDT.tgz
│   ├── green.secretsmgmt.tk
│   │   ├── letsencrypt_2018-04-06T23:45:49PDT.tgz
│   │   └── letsencrypt_2018-04-25T16:32:20PDT.tgz
│   ├── purple.secretsmgmt.tk
│   │   ├── letsencrypt_2018-04-25T16:32:20PDT.tgz
│   │   ├── trident_2018-01-31T23:38:48PST.tar.bz2
│   │   └── trident_2018-02-04T20:05:33PST.tar.bz2
│   └── red.secretsmgmt.tk
│       ├── letsencrypt_2018-04-06T23:45:49PDT.tgz
│       └── letsencrypt_2018-04-25T16:32:20PDT.tgz
├── dittrich.asc
├── keys
│   └── opendkim
│       └── secretsmgmt.tk
│           ├── 201801.private
│           ├── 201801.txt
│           ├── 201802.private
│           └── 201802.txt
├── secrets.d
│   ├── ca.json
│   ├── consul.json
│   ├── jenkins.json
│   ├── rabbitmq.json
│   ├── trident.json
│   ├── vncserver.json
│   └── zookeper.json
├── secrets.json
└── vault_password.txt

To just see the directory structure and not files, add the --no-files option:

$ psec -e d2 environments tree --no-files
/Users/dittrich/.secrets/d2
├── backups
│   ├── black.secretsmgmt.tk
│   ├── green.secretsmgmt.tk
│   ├── purple.secretsmgmt.tk
│   └── red.secretsmgmt.tk
├── keys
│   └── opendkim
│       └── secretsmgmt.tk
└── secrets.d
psec environments tree [--no-files] [environment]
--no-files

Do not include files in listing

environment

This command is provided by the python-secrets plugin.

Groups

groups create

Create a secrets descriptions group.

Secrets and variables are described in files in a drop-in style directory ending in .d. This forms ‘groups’ that organize secrets and variables by purpose, by open source tool, etc. This command creates a new group descriptions file in the selected environment.

When integrating a new open source tool or project with an existing tool or project, you can create a new group in the current environment and clone its secrets descriptions from pre-existing definitions. This does not copy any values, just the descriptions, allowing you to manage the values independently of other projects using a different environment:

$ psec groups create newgroup --clone-from ~/git/goSecure/secrets.d/gosecure.json
[+] created new group 'newgroup'
$ psec groups list
+----------+-------+
| Group    | Items |
+----------+-------+
| jenkins  |     1 |
| myapp    |     4 |
| newgroup |    12 |
| trident  |     2 |
+----------+-------+

Note: Directory and file permissions on cloned groups will prevent other from having read/write/execute permissions (i.e., o-rwx in terms of the chmod command.)

psec groups create [-C CLONE_FROM] [arg]
-C <CLONE_FROM>, --clone-from <CLONE_FROM>

Group descriptions file to clone from

arg

This command is provided by the python-secrets plugin.

groups delete

Delete a secrets descriptions group.

Deletes a group of secrets and variables by removing them from the secrets environment and deleting their descriptions file.

If the --force option is not specified, you will be prompted to confirm the group name before it is deleted.

psec groups delete [--force] [group]
--force

Mandatory confirmation

group

This command is provided by the python-secrets plugin.

groups list

Show a list of secrets groups.

The names of the groups and number of items are printed by default:

$ psec groups list
+---------+-------+
| Group   | Items |
+---------+-------+
| jenkins |     1 |
| myapp   |     4 |
| trident |     2 |
+---------+-------+
psec groups list [--sort-ascending | --sort-descending]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

This command is provided by the python-secrets plugin.

groups path

Return path to secrets descriptions (groups) directory.

$ psec groups path
/Users/dittrich/.secrets/psec/secrets.d
psec groups path [environment]
environment

This command is provided by the python-secrets plugin.

groups show

Show a list of secrets in a group.

Show the group name and number of items in the group for one or more groups:

$ psec groups show trident myapp
+---------+-----------------------+
| Group   | Variable              |
+---------+-----------------------+
| trident | trident_sysadmin_pass |
| trident | trident_db_pass       |
| myapp   | myapp_pi_password     |
| myapp   | myapp_app_password    |
| myapp   | myapp_client_psk      |
| myapp   | myapp_client_ssid     |
+---------+-----------------------+
psec groups show
    [--sort-ascending | --sort-descending]
    [group [group ...]]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

group

This command is provided by the python-secrets plugin.

Init

init

Initialize a psec secrets base directory.

The psec program stores secrets and variables for environments in their own subdirectory trees beneath a top level directory root referred to as the “secrets base directory” (secrets_basedir). This directory tree should not be a “normal” file system directory that includes arbitrary files and directories, but rather a special location dedicated to only storing secrets environments and related files.

For added security, you can root this directory tree within an encrypted USB-connected disk device, SD card, or other external or remote file system that is only mounted when needed. This ensures sensitive data that are not being actively used are left encrypted in storage. The D2_SECRETS_BASEDIR environment variable or -d option allow you to specify the directory to use.

To attempt to prevent accidentally storing secrets in directories that are already storing normal files or directories, a special marker file must be present. The init command ensures that this secrets base directory is created and marked by the presence of that special file. Until this is done, some psec commands may report the base directory is not found (if it does not exist) or is not valid (if it does exist, but does not contain the special marker file):

$ psec -d /tmp/foo/does/not/exist environments list
[-] directory '/tmp/foo/does/not/exist' does not exist
psec init [basedir]
basedir

This command is provided by the python-secrets plugin.

Run

run

Run a command line as a sub-shell.

The run subcommand is used to run a command line in a sub-shell similar to using bash -c.

When used with the --elapsed option, you get more readable elapsed time information than with the time command:

$ psec --elapsed run sleep 3
[+] elapsed time 00:00:03.01

When combined with the -E option to export a psec environment’s secrets and variables into the process environment, the command sub-shell (and every shell that is subsequently forked & exec’d) will inherit these environment variables. Programs like Ansible and Terraform can then access the values by reference rather than requiring hard-coding values or passing values on the command line. You can even run a shell program like bash or byobu in a nested shell to change default values for interactive sessions.

Secrets and variables may be exported with their name, or may have an additional environment variable name (for programs that expect a particular prefix, like TF_ for Terraform variables) as seen here:

$ psec secrets show myapp_pi_password --no-redact
+-------------------+---------------------------+------------------+
| Variable          | Value                     | Export           |
+-------------------+---------------------------+------------------+
| myapp_pi_password | GAINS.ranged.ENGULF.wound | DEMO_pi_password |
+-------------------+---------------------------+------------------+

Without the -E option the export variable is not set:

$ psec run -- bash -c 'env | grep DEMO_pi_password'
$ psec run -- bash -c 'echo The demo password is ${DEMO_pi_password:-not set}'
The demo password is not set

With the -E option it is set and the sub-shell can expand it:

$ psec -E run -- bash -c 'env | grep DEMO_pi_password'
DEMO_pi_password=GAINS.ranged.ENGULF.wound
$ psec run -- bash -c 'echo The demo password is ${DEMO_pi_password:-not set}'
The demo password is GAINS.ranged.ENGULF.wound

NOTE: The -- you see in these examples is necessary to ensure that command line parsing by the shell to construct the argument vector for passing to the psec program is stopped so that the options meant for the sub-command are passed to it properly for parsing. Failing to add the -- may result in a strange parsing error message, or unexpected behavior when the command line you typed is not parsed the way you assumed it would be:

$ psec run bash -c 'env | grep DEMO_pi_password'
usage: psec run [-h] [arg [arg ...]]
psec run: error: unrecognized arguments: -c env | grep DEMO_pi_password

You may use --elapsed without an environment if you do not need to export variables, but when the -e option is present an environment must exist or you will get an error.

If no arguments are specified, this --help text is output.

psec run [arg [arg ...]]
arg

Command arguments

This command is provided by the python-secrets plugin.

Secrets

secrets backup

Back up just secrets and descriptions.

Creates a backup (tar format) of the secrets.json file and all description files.

psec secrets backup

This command is provided by the python-secrets plugin.

secrets create

Create a new secret definition.

Defines one or more secrets in a specified group based on input from the user. Secret definitions are created in the user’s environments storage directory and a new variable with no value is created there, too.

If the environment and/or the group does not exist, you will be prompted to create them. Use the --force option to create them without asking.

To maintain a copy of the secrets descriptions in the source repository so they can be used to quickly configure a new deployment after cloning, use the --mirror-locally option when creating secrets from the root of the repository directory. A copy of each modified group description file will be mirrored into a subdirectory tree in the current working directory where you can commit it to the repository.

If no group is specified with the --group option, the environment identifier will be used as a default. This simplifies things for small projects that don’t need the drop-in style group partitioning that is more appropriate for multi-tool open source system integration where a single monolithic configuration file becomes unwieldy and inflexible. This feature can also be used for “global” variables that could apply across sub-components:

$ psec secrets create newsecret --force

KNOWN LIMITATION: This subcommand currently only works interactively and you will be prompted for all attributes. In future, this may be handled using key=value pairs for attributes, similar to the way the secrets set command works.

psec secrets create
    [--group GROUP]
    [--force]
    [--update]
    [--mirror-locally]
    [arg [arg ...]]
--group <GROUP>

Group in which to define the secret(s)

--force

Create missing environment and/or group

--update

Update the fields in an existing description

--mirror-locally

Mirror definitions locally

arg

This command is provided by the python-secrets plugin.

secrets delete

Delete secrets and their definitions.

Deletes one or more secrets and their definitions from an environment. Unless the --force flag is specified, you will be prompted to type in the variable name again to ensure you really want to remove all trace of it from the environment:

$ psec secrets delete --group myapp myapp_client_psk myapp_client_ssid
Type the name 'myapp_client_psk' to confirm: myapp_client_psk
Type the name 'myapp_client_ssid' to confirm: myapp_client_ssid

If you delete all of the variable descriptions remaining in a group, the group file will be deleted.

The --mirror-locally option will manage a local copy of the descriptions file. Use this if you are eliminating a variable from a project while editing files in the root of the source repository.

KNOWN LIMITATION: You must specify the group with the --group option currently and are restricted to deleting variables from one group at a time.

psec secrets delete
    [-g GROUP]
    [--force]
    [--mirror-locally]
    [arg [arg ...]]
-g <GROUP>, --group <GROUP>

Group from which to delete the secret(s)

--force

Mandatory confirmation

--mirror-locally

Mirror definitions locally

arg

This command is provided by the python-secrets plugin.

secrets describe

Describe supported secret types.

To get descriptions for a subset of secrets, specify their names as the arguments:

$ psec secrets describe jenkins_admin_password
+------------------------+---------+----------+--------------------------------------+---------+
| Variable               | Group   | Type     | Prompt                               | Options |
+------------------------+---------+----------+--------------------------------------+---------+
| jenkins_admin_password | jenkins | password | Password for Jenkins 'admin' account | *       |
+------------------------+---------+----------+--------------------------------------+---------+

If you instead want to get descriptions of all secrets in one or more groups, use the --group option and specify the group names as the arguments.

To instead see the values and exported environment variables associated with secrets, use the secrets show command instead.

psec secrets describe
    [--sort-ascending | --sort-descending]
    [--undefined]
    [-g | -t]
    [arg [arg ...]]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

--undefined

Only show variables that are not yet defined

-g, --group

Arguments are groups to list

-t, --types

Describe types

arg

This command is provided by the python-secrets plugin.

secrets find

Find defined secrets in environments.

Searches through all environments in the secrets base directory and lists those that contain the variable(s) with names matching the search terms. You can search for secrets by value instead using the –value option flag. Example:

$ psec secrets find tanzanite_admin
[+] searching secrets base directory /Users/dittrich/.secrets
+-------------+-----------+----------------------------+
| Environment | Group     | Variable                   |
+-------------+-----------+----------------------------+
| tanzanite   | tanzanite | tanzanite_admin_user_email |
| tanzanite   | tanzanite | tanzanite_admin_password   |
| tzdocker    | tanzanite | tanzanite_admin_user_email |
| tzdocker    | tanzanite | tanzanite_admin_password   |
| tztest      | tanzanite | tanzanite_admin_user_email |
| tztest      | tanzanite | tanzanite_admin_password   |
+-------------+-----------+----------------------------+
psec secrets find
    [--sort-ascending | --sort-descending]
    [--group GROUP]
    [--value]
    [arg [arg ...]]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

--group <GROUP>

Limit searches to this specific group

--value

The search term is the value to find (not the variable name)

arg

This command is provided by the python-secrets plugin.

secrets generate

Generate values for secrets.

Sets variables by generating values according to the Type definition for each variable.

If you include the --from-options flag, string variables will also be set according to their default value as described in the help output for the secrets set command. This allows as many variables as possible to be set with a single command (rather than requiring the user to do both secrets set and secrets generate as two separate steps.

To affect only a subset of secrets, specify their names as the arguments to this command. If no secrets are specified, all secrets will be affected.

psec secrets generate
    [--from-options]
    [-U]
    [--min-words-length MIN_WORDS_LENGTH]
    [--max-words-length MAX_WORDS_LENGTH]
    [--min-acrostic-length MIN_ACROSTIC_LENGTH]
    [--max-acrostic-length MAX_ACROSTIC_LENGTH]
    [--acrostic ACROSTIC]
    [--delimiter DELIMITER]
    [-C CASE]
    [arg [arg ...]]
--from-options

Set variables from first available option

-U, --unique

Generate unique values for each type of secret

--min-words-length <MIN_WORDS_LENGTH>

Minimum word length for XKCD words list

--max-words-length <MAX_WORDS_LENGTH>

Maximum word length for XKCD words list

--min-acrostic-length <MIN_ACROSTIC_LENGTH>

Minimum length of acrostic word for XKCD password

--max-acrostic-length <MAX_ACROSTIC_LENGTH>

Maximum length of acrostic word for XKCD password

--acrostic <ACROSTIC>

Acrostic word for XKCD password

--delimiter <DELIMITER>

Delimiter for XKCD password

-C CASE, --case CASE

Choose the method for setting the case of each word in the passphrase. Choices: [‘alternating’, ‘upper’, ‘lower’, ‘random’, ‘first’, ‘capitalize’]

arg

This command is provided by the python-secrets plugin.

secrets get

Gets the value associated with a secret and returns it on standard output. This is used for inline command substitution in cases where a single value is needed:

$ echo "Jenkins admin password: $(psec secrets get jenkins_admin_password)"
Jenkins admin password: OZONE.negate.TIPTOP.ocean

To get values for more than one secret, use secrets show with one of the formatting options allowing you to parse the results or otherwise use them as a group.

psec secrets get [-C] secret
-C, --content

Get content if secret is a file path

secret

This command is provided by the python-secrets plugin.

secrets path

Return path to secrets file.

If no arguments are present, the path to the secrets for the default environment is returned. If you want to get the secrets path for a specific environment, specify it as the argument to this command.

psec secrets path [environment]
environment

This command is provided by the python-secrets plugin.

secrets restore

Restore secrets and descriptions from a backup file.

psec secrets restore [backup]
backup

This command is provided by the python-secrets plugin.

secrets send

Send secrets using GPG encrypted email.

Recipients for the secrets are specified as USERNAME@EMAIL.ADDRESS strings and/or VARIABLE references.

psec secrets send
    [-T]
    [--test-smtp]
    [-H SMTP_HOST]
    [-U SMTP_USERNAME]
    [-F SMTP_SENDER]
    [-S SMTP_SUBJECT]
    [arg [arg ...]]
-T, --refresh-token

Refresh Google API Oauth2 token and exit

--test-smtp

Test Oauth2 SMTP authentication and exit

-H <SMTP_HOST>, --smtp-host <SMTP_HOST>

SMTP host

-U <SMTP_USERNAME>, --smtp-username <SMTP_USERNAME>

SMTP authentication username

-F <SMTP_SENDER>, --from <SMTP_SENDER>

Sender address

-S <SMTP_SUBJECT>, --subject <SMTP_SUBJECT>

Subject line

arg

This command is provided by the python-secrets plugin.

secrets set

Set values manually for secrets.

One or more secrets can be set directly by specifying them as variable=value pairs as the arguments to this command:

$ psec secrets set trident_db_pass="rural coffee purple sedan"

Adding the --undefined flag will limit the secrets being set to only those that are currently not set. If values are not set, you are prompted for the value.

When cloning an environment from definitions in a source repository or an existing environment, you can set secrets by copying them from another existing environment using the --from-environment option:

$ psec secrets set gosecure_pi_password --from-environment goSecure

When you are doing this immediately after cloning (when all variables are undefined) you can set all undefined variables at once from another environment this way:

$ psec environments create --clone-from goSecure
$ psec secrets set --undefined --from-environment goSecure

To facilitate setting variables from another environment where the variable names may differ, use the assignment style syntax for arguments along with the --from-environment option, like this:

$ psec secrets set hypriot_client_psk=gosecure_client_psk \
> hypriot_client_ssid=gosecure_client_ssid \
> --from-environment goSecure

If you do not provide values for variables using assignment syntax and you are not copying values from another environment, you will be prompted for values according to how the options field is defined.

  • If the only option is * (meaning “any string”), you will be prompted to enter a value. When prompted this way, you can cancel setting the variable by entering an empty string. If you really want the value to be an empty string, you must use the assignment syntax with an empty string like this: variable=''
  • An options list that does not contain a * defines a finite set of options. This means you are resticted to only choosing from the list. This is similar to the Boolean type, which can only have a value of true or false.
  • If one or more options are listed along with *, you can either choose from one of the listed values or select * to manually enter a value not in the list.
  • You can back out of making a change by selecting <CANCEL> from the list.
psec secrets set
    [--undefined]
    [--ignore-missing]
    [--from-environment <environment> | --from-options]
    [arg [arg ...]]
--undefined

Set values for undefined variables

--ignore-missing

Skip setting variables that are not defined

--from-environment <environment>

Environment from which to copy secret value(s)

--from-options

Set from first available option

arg

This command is provided by the python-secrets plugin.

secrets show

List the contents of the secrets file or definitions.

The secrets show command is used to see variables, their values, and exported environment variables to help in using them in your code, shell scripts, etc. To see more metadata-ish information, such as their group, type, etc., use the secrets describe command instead.

To get show a subset of secrets, specify their names as arguments. If you instead want to show all secrets in one or more groups, use the --group option and specify the group names as arguments, or to show all secrets of one or more types, use the --type option:

$ psec secrets show
+------------------------+----------+------------------------+
| Variable               | Value    | Export                 |
+------------------------+----------+------------------------+
| jenkins_admin_password | REDACTED | jenkins_admin_password |
| myapp_app_password     | REDACTED | DEMO_app_password      |
| myapp_client_psk       | REDACTED | DEMO_client_ssid       |
| myapp_client_ssid      | REDACTED | DEMO_client_ssid       |
| myapp_pi_password      | REDACTED | DEMO_pi_password       |
| trident_db_pass        | REDACTED | trident_db_pass        |
| trident_sysadmin_pass  | REDACTED | trident_sysadmin_pass  |
+------------------------+----------+------------------------+

Visually finding undefined variables in a very long list can be difficult. You can show just undefined variables with the --undefined option.

psec secrets show
    [--sort-ascending | --sort-descending]
    [-C]
    [-p]
    [--undefined]
    [-g | -t]
    [arg [arg ...]]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

-C, --no-redact

Do not redact values in output

-p, --prompts

Include prompts

--undefined

Only show variables that are not yet defined

-g, --group

Arguments are groups to show

-t, --type

Arguments are types to show

arg

This command is provided by the python-secrets plugin.

secrets tree

Output tree listing of groups and secrets in environment.

The secrets tree command produces output similar to the Unix tree command. This gives you a visual overview of the groupings of secrets in the target environment:

$ psec secrets tree my_environment
my_environment
├── myapp
│   ├── myapp_app_password
│   ├── myapp_client_psk
│   ├── myapp_client_ssid
│   ├── myapp_ondemand_wifi
│   └── myapp_pi_password
└── oauth
    ├── google_oauth_client_id
    ├── google_oauth_client_secret
    ├── google_oauth_refresh_token
    └── google_oauth_username
psec secrets tree [environment]
environment

This command is provided by the python-secrets plugin.

SSH

ssh config

Create SSH configuration snippets for use by update-dotdee.

Names of the snippets will start with psec_ followed by the environment name and host name (separated by _) in order to support global removal of existing snippets for a given environment, while avoiding name clashes with other environments.

These configuration snippets will reside in the directory ~/.ssh/config.d/ and update-dotdee will be run after creating them to apply the new configuration(s) for immediate use.

To ensure that no inactive instances still have configurations, the --clean option will delete all existing snippets with the prefix for this environment prior to creating new files.

Use -vvv to see the configuration file in the terminal command line output.

psec ssh config
    [--clean]
    [--public-ip PUBLIC_IP]
    [--known-hosts-root KNOWN_HOSTS_ROOT]
    [--ssh-user SSH_USER]
    [--public-dns PUBLIC_DNS]
    [--show-config]
--clean

Clean out all existing snippets before writing new files

--public-ip <PUBLIC_IP>

IP address of host

--known-hosts-root <KNOWN_HOSTS_ROOT>

Root for extracted known_hosts files

--ssh-user <SSH_USER>

SSH user account

--public-dns <PUBLIC_DNS>

Public DNS name of host

--show-config

Show the SSH configuration on standard output and exit

This command is provided by the python-secrets plugin.

ssh known-hosts add

Add public SSH keys to known_hosts file(s).

This command will either extract SSH public host keys and fingerprints from a cloud service console output (either directly via an API or or from saved output from instantiation of the cloud instance.)

By default, the public keys are added to the system known_hosts file (/etc/ssh/ssh_known_hosts, which is not writeable by normal users) for added security. The file is manipulated indirectly using an embedded Ansible playbook.

Use --show-playbook to just see the Ansible playbook without running it. Use -vvv to see the Ansible playbook while it is being applied.

The Ansible playbook uses become to elevate privileges. On Linux systems, this usually relies on sudo. If plays in the playbook fail with "module_stderr": "sudo: a password is required" in the message, you will need to use the --ask-become-pass option to be prompted for your password.

NOTE: Because of the use of Ansible, with the potential need for using sudo, you cannot pipe console-output text into psec using I/O redirection or piping. The following exception will be thrown:

...
File "[...]/site-packages/pexpect/pty_spawn.py", line 783, in interact
  mode = tty.tcgetattr(self.STDIN_FILENO)
termios.error: (25, 'Inappropriate ioctl for device')
...

If this happens, save the console output to a file and pass its name as a command line argument.

psec ssh known-hosts add
    [--known-hosts-root KNOWN_HOSTS_ROOT]
    [--public-ip PUBLIC_IP]
    [--public-dns PUBLIC_DNS]
    [--instance-id INSTANCE_ID]
    [--ask-become-pass]
    [--show-playbook]
    [--save-to-files]
    [source]
--known-hosts-root <KNOWN_HOSTS_ROOT>

Root for extracted known_hosts files

--public-ip <PUBLIC_IP>

IP address of host

--public-dns <PUBLIC_DNS>

Public DNS name of host

--instance-id <INSTANCE_ID>

instance ID for getting direct AWS console output

--ask-become-pass

Ask for sudo password for Ansible privilege escalation

--show-playbook

Show the playbook on standard output and exit

--save-to-files

Write extracted fingerprints and public keys out to files

source

console output to process

This command is provided by the python-secrets plugin.

ssh known-hosts extract

Extract SSH keys from cloud provider console logs.

Log output may come from stdout (as it does with Terraform), or it may need to be extracted (e.g., after Pulumi creates AWS instances, you need to manually extract the instance log(s) in order to post-process them.

psec ssh known-hosts extract
    [--known-hosts-root KNOWN_HOSTS_ROOT]
    [source]
--known-hosts-root <KNOWN_HOSTS_ROOT>

Root for extracted known_hosts files

source

console output to process

This command is provided by the python-secrets plugin.

ssh known-hosts remove

Remove SSH keys from known_hosts file(s).

This command indirectly manipulates the known hosts file using an embedded Ansible playbook.

Use --show-playbook to just see the Ansible playbook without running it. Use -vvv to see the Ansible playbook while it is being applied.

The Ansible playbook uses become to elevate privileges. On Linux systems, this usually relies on sudo. If plays in the playbook fail with "module_stderr": "sudo: a password is required" in the message, you will need to use the --ask-become-pass option to be prompted for your password.

NOTE: Because of the use of Ansible, with the potential need for using sudo, you cannot pipe console-output text into psec using I/O redirection or piping. The following exception will be thrown:

...
File "[...]/site-packages/pexpect/pty_spawn.py", line 783, in interact
  mode = tty.tcgetattr(self.STDIN_FILENO)
termios.error: (25, 'Inappropriate ioctl for device')
...

If this happens, save the console output to a file and pass its name as a command line argument.

psec ssh known-hosts remove
    [--known-hosts-root KNOWN_HOSTS_ROOT]
    [--ask-become-pass]
    [--show-playbook]
    [source]
--known-hosts-root <KNOWN_HOSTS_ROOT>

Root for extracted known_hosts files

--ask-become-pass

Ask for sudo password for Ansible privilege escalation

--show-playbook

Show the playbook on standard output and exit

source

console output to process

This command is provided by the python-secrets plugin.

Template

template

Template file(s).

For information on the Jinja2 template engine and how to use it, see http://jinja.pocoo.org

To assist debugging, use --check-defined to check that all required variables are defined.

psec template [--check-defined] [--no-env] [source] [dest]
--check-defined

Just check for undefined variables

--no-env

Do not require and load an environment

source

input Jinja2 template source

dest

templated output destination (‘-’ for stdout)

This command is provided by the python-secrets plugin.

Utils

utils myip

Get currently active internet routable IPv4 address.

Return the routable IP address of the host running this script using one of several publicly available free methods typically using HTTPS or DNS.

The --cidr option expresses the IP address as a CIDR block to use in setting up firewall rules for this specific IP address.

The --netblock option follows this lookup with another lookup using WHOIS to get the network provider’s address range(s), in CIDR notation, to help with creating firewall rules that can work around dynamic addressing. This is not the most secure way to grant network access as it allows any customer using the same provider to also communicate through the firewall, but you have to admit that it is better than allow ANY! ¯_(ツ)_/¯

To see a table of the methods, use utils myip methods.

KNOWN LIMITATION: Some of the methods may not fully support IPv6 at this point. If you find one that doesn’t work, try a different one.

See also:
https://linuxize.com/post/how-to-find-ip-address-linux/ https://dev.to/adityathebe/a-handy-way-to-know-your-public-ip-address-with-dns-servers-4nmn
psec utils myip
    [-M {akamai,amazon,google,opendns_h,opendns_r,icanhazip,infoip,tnx,random}]
    [-C | -N]
-M <METHOD>, --method <METHOD>

Method to use for determining IP address

-C, --cidr

Express the IP address as a CIDR block

-N, --netblock

Return network CIDR block(s) for IP from WHOIS

WARNING: Any of the sites used by this command may limit the number of queries allowed from a given source in a given period of time and may temporarily block or reject attempts to use their service beyond the quota limit.

utils myip methods

Show methods for obtaining routable IP address.

Provides the details of the methods coded into this app for obtaining this host’s routable IP address:

$ psec utils myip methods
+-----------+-------+--------------------------------------------------------+
| Method    | Type  | Source                                                 |
+-----------+-------+--------------------------------------------------------+
| akamai    | dns   | dig +short @ns1-1.akamaitech.net ANY whoami.akamai.net |
| amazon    | https | https://checkip.amazonaws.com                          |
| google    | dns   | dig +short @ns1.google.com TXT o-o.myaddr.l.google.com |
| icanhazip | https | https://icanhazip.com/                                 |
| infoip    | https | https://api.infoip.io/ip                               |
| opendns_h | https | https://diagnostic.opendns.com/myip                    |
| opendns_r | dns   | dig +short @resolver1.opendns.com myip.opendns.com -4  |
| tnx       | https | https://tnx.nl/ip                                      |
+-----------+-------+--------------------------------------------------------+

It can be used for looping in tests, etc. like this:

$ for method in $(psec utils myip methods -f value -c Method)
> do
>   echo "$method: $(psec utils myip --method $method)"
> done
akamai: 93.184.216.34
amazon: 93.184.216.34
google: 93.184.216.34
icanhazip: 93.184.216.34
infoip: 93.184.216.34
opendns_h: 93.184.216.34
opendns_r: 93.184.216.34
tnx: 93.184.216.34
psec utils myip methods
    [--sort-ascending | --sort-descending]
    [method [method ...]]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

method

WARNING: Any of the sites used by this command may limit the number of queries allowed from a given source in a given period of time and may temporarily block or reject attempts to use their service beyond the quota limit.

utils netblock

Get network CIDR block(s) for IP from WHOIS lookup.

Look up the network address blocks serving the specified IP address(es) using the Python IPWhois module.

https://pypi.org/project/ipwhois/

If no arguments are given, the routable address of the host on which psec is being run will be determined and used as the default.

psec utils netblock [ip [ip ...]]
ip

IP address to use

This command is provided by the python-secrets plugin.

utils set-aws-credentials

Set credentials from saved secrets for use by AWS CLI.

This command directly manipulates the AWS CLI “credentials” INI-style file. The AWS CLI does not support non-interactive manipulation of the credentials file, so this hack is used to do this. Be aware that this might cause some problems (though it shouldn’t, since the file is so simple):

[default]
aws_access_key_id = [ Harm to Ongoing Matter ]
aws_secret_access_key = [        HOM           ]

For simple use cases, you will not need to switch between different users. The default is to use the AWS convention of default as seen in the example above. If you do need to support multiple users, the --user option will allow you to specify the user.

See also:

psec utils set-aws-credentials [-U USER]
-U <USER>, --user <USER>

IAM User who owns credentials

This command is provided by the python-secrets plugin.

utils tfstate backend

Enable Terraform backend support.

Enables the Terraform “backend support” option to move the file terraform.tfstate (which can contain many secrets) out of the current working directory and into the current environment directory path.

psec utils tfstate backend [--path]
--path

Print path and exit

This command is provided by the python-secrets plugin.

utils tfstate output

Retrieve current terraform output results.

If the tfstate argument is not provided, this command will attempt to search for a terraform.tfstate file in (1) the active environment’s secrets storage directory (see environments path), or (2) the current working directory. The former is documented preferred location for storing this file, since it will contain secrets that should not be stored in a source repository directory to avoid potential leaking of those secrets:

$ psec environments path
/Users/dittrich/.secrets/psec
psec utils tfstate output
    [--sort-ascending | --sort-descending]
    [tfstate]
--sort-ascending

sort the column(s) in ascending order

--sort-descending

sort the column(s) in descending order

tfstate

Path to Terraform state file

This command is provided by the python-secrets plugin.

utils yaml-to-json

Convert YAML file(s) to JSON file(s).

You can specify one or more files or directories to convert (including ‘-’ for standard input).

By default the JSON format data will be written to standard output. This is useful for one-off conversion of YAML content to see the resulting JSON, or to produce a file with a different name by redirecting into a new file.

The --convert option writes the JSON to a file with the same base name, but with a .json extension, then deletes the original YAML file unless the --keep-original option is specified. When a directory is passed as an argument with the --convert option, all files ending in .yml in the directory will be processed.

Note

The original format for secrets files and secrets description files was YAML. The format was changed to JSON in a recent release, necessitating that existing secrets descriptions in repositories and/or existing secrets environments be converted. As of now, this utility subcommand provides a mechanism for you to use in making this change. Future releases may include a more user-friendly upgrade mechanism.

Here is a demonstration using an old YAML-style secrets descriptions directory used by tests in the tests/ subdirectory:

$ cp -r tests/secrets /tmp
$ tree /tmp/secrets/
/tmp/secrets/
└── secrets.d
    ├── jenkins.yml
    ├── myapp.yml
    ├── oauth.yml
    └── trident.yml

1 directory, 4 files
$ psec utils yaml-to-json --convert /tmp/secrets/secrets.d
[+] converting '/tmp/secrets/secrets.d/jenkins.yml' to JSON
[+] removing '/tmp/secrets/secrets.d/jenkins.yml'
[+] converting '/tmp/secrets/secrets.d/myapp.yml' to JSON
[+] removing '/tmp/secrets/secrets.d/myapp.yml'
[+] converting '/tmp/secrets/secrets.d/trident.yml' to JSON
[+] removing '/tmp/secrets/secrets.d/trident.yml'
[+] converting '/tmp/secrets/secrets.d/oauth.yml' to JSON
[+] removing '/tmp/secrets/secrets.d/oauth.yml'
$ tree /tmp/secrets/
/tmp/secrets/
└── secrets.d
    ├── jenkins.json
    ├── myapp.json
    ├── oauth.json
    └── trident.json

1 directory, 4 files
psec utils yaml-to-json [--convert] [--keep-original] [arg [arg ...]]
--convert

Convert file(s) in place

--keep-original

Keep original YAML file after conversion

arg

Files and/or directories convert

This command is provided by the python-secrets plugin.