Managing secrets

Adding a secret via CLI (imperative)

If you have a secret at path/to/secret, then having it managed by sesam is only a matter of this command:

$ sesam add path/to/secret --group deploy

This will:

1. Record that this file is now managed by sesam by adding it to the audit log.
2. Encrypt the file and place it in .sesam/objects. This is what is being pushed in the end.

If you omit the --group parameter then only the admin group will have access to the file. You can change this at any point by just re-running the add command with any groups you want to set.

Adding a secret via config (declarative)

Adding secrets via CLI is nice for scripts. sesam also supports describing the desired state in a declarative way via sesam.yml. If you executed the above command you will notice the secret was added already to the config:

secrets:
  - path: path/to/secret
    access: [deploy]
    description: Where it used, who owns it, Contact...

If you did not run the add command above, then you can also add the entry manually and then run:

$ sesam apply

This will automatically check what the state is in the repo and how it differs from the state in the config. The changes are then resolved by adding/removing secrets or adding/removing users.

Adding multiple secrets

You can also add whole directories, if you need to:

$ tree dir/of/secrets
.
├── some_file
└── sub
    └── another_file
$ sesam add dir/of/secrets
$ tree dir/of/secrets
.
├── sesam.yml
├── some_file
└── sub
    ├── another_file
    └── sesam.yml

This will create a config hierarchy of sesam.yml files in the config:

# Main sesam.yml:
config:
  secrets:
    - include: dir/of/secrets

# dir/of/secrets sesam.yml:
config:
  secrets:
    - include: sub
    - path: some_file

# sub sesam.yml:
config:
  secrets:
    - path: another_file

Once done you can also add descriptions to the files in the config or do more fine-tuning with the available config keys.

Modifying secrets

Running sesam add will work here too, similar to git add. By default this will also re-seal the secrets, except if you pass --no-seal.

If you want to change the access groups of a user, then just pass a different set of --group flags.

Getting an overview

If you need to see which files were modified but not yet sealed you can use sesam status:

# without --all you will only see the modified files:
$ sesam status --all
.
├─ M README.md (admin)
├─ ✓ bg.png (admin)
╰─ services/
   ├─ ✓ gateway.env (admin)
   ╰─ ✓ registry.env (admin)
  1 out of sync · 3 in sync

This will show you files you edited directly without calling sesam add on them.

Removing secrets

If you have deleted files you can run this:

$ sesam rm files/ dir/

Moving secrets

Probably not very surprising by now, but we have a mv command as well:

$ sesam mv old_name new_name

Listing secrets

$ sesam ls
├── README.sesam
└── dir
    └── of
        └── secrets
            ├── some_file
            └── sub
                └── another_file

You can also use the --json switch to print it in a more scriptable way.