Metadata-Version: 2.1
Name: pass-operator
Version: 0.3.0
Summary: A kubernetes operator that syncs and decrypts secrets from pass git repositories
License: GPL-3.0-or-later
Keywords: python,kubernetes,secrets,operator,pass
Author: Emma Doyle
Author-email: emma@premiscale.com
Maintainer: Emma Doyle
Maintainer-email: emma@premiscale.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: gitpython (>=3.1.41,<4.0.0)
Requires-Dist: kopf (>=1.36.2,<2.0.0)
Requires-Dist: kubernetes (>=29.0.0,<30.0.0)
Requires-Dist: python-gnupg (>=0.5.2,<0.6.0)
Description-Content-Type: text/markdown

# `pass` secrets operator

This Kubernetes operator can be used to sync and decrypt secrets from a password store ([pass](https://www.passwordstore.org/)) Git repository. It is proposed as a proof-of-concept and shouldn't be used in any production capacity.

While this approach to secrets management on Kubernetes is more technically challenging, the advantage is that we don't have to rely on a 3rd party SaaS platform, such as Vault or Doppler, to hold our secrets (the obvious benefits these platforms do provide, however, are better user and access management). We may also use this operator in an airgapped environment with a self-hosted git repository.

<!--
I also acknowledge that this approach swims against the DevSecOps tide in that it requires you to store your secrets (albeit encrypted)
in Git, a practice that is often discouraged and typically forbidden at most organizations.
-->

## How it works

From a high level, this operator runs `git pull` on an interval to grab updates from a git repository populated with encrypted
secrets by `pass`. It maps secrets' paths to key values through the application of a [`PassSecret`](helm/operator/crds/PassSecret.yaml), a [CRD](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/),
such as the following.

```yaml
apiVersion: secrets.premiscale.com/v1alpha1
kind: PassSecret
metadata:
  name: mysecret
  namespace: pass-operator-test
spec:
  encryptedData:
    mykey: premiscale/mydata
  managedSecret:
    name: mysecret
    namespace: pass-operator-test
    type: Opaque
    immutable: false
```

The above `PassSecret` manifest translates to the following `Secret`.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
  namespace: pass-operator-test
stringData:
  mykey: <decrypted contents of premiscale/mydata>
immutable: false
type: Opaque
```

## Use

This operator requires the following items to start successfully.

- private GPG key to decrypt the secrets that have been encrypted with a public key, locally
- local pass store (on your local development machine)
- git repository populated by the local password store
- private SSH key to clone the Git repository

I will go more in-depth and explain these requirements in the following sections.

### Private GPG key

The private GPG key is used by `pass` to decrypt your secrets that were encrypted on your local machine.

<details>
  <summary><b>Generating GPG keys</b></summary>

  You can find a lot of explanation about how to generate keys with GPG online, but I'll write down my process below for generating keys to use with this operator.

  1. First, generate a key.

      ```shell
      $ gpg --generate-key
      gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc.
      This is free software: you are free to change and redistribute it.
      There is NO WARRANTY, to the extent permitted by law.

      Note: Use "gpg --full-generate-key" for a full featured key generation dialog.

      GnuPG needs to construct a user ID to identify your key.

      Real name: Emma Doyle
      Email address: emma@premiscale.com
      You selected this USER-ID:
      "Emma Doyle <emma@premiscale.com>"

      Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
      We need to generate a lot of random bytes. It is a good idea to perform
      some other action (type on the keyboard, move the mouse, utilize the
      disks) during the prime generation; this gives the random number
      generator a better chance to gain enough entropy.
      We need to generate a lot of random bytes. It is a good idea to perform
      some other action (type on the keyboard, move the mouse, utilize the
      disks) during the prime generation; this gives the random number
      generator a better chance to gain enough entropy.
      gpg: key 4B90DE5D5BF143B8 marked as ultimately trusted
      gpg: revocation certificate stored as '/home/emmadoyle/.gnupg/openpgp-revocs.d/51924ADAFC92656FAFEB672D4B90DE5D5BF143B8.rev'
      public and secret key created and signed.

      pub   rsa3072 2024-01-12 [SC] [expires: 2026-01-11]
            51924ADAFC92656FAFEB672D4B90DE5D5BF143B8
      uid                      Emma Doyle <emma@premiscale.com>
      sub   rsa3072 2024-01-12 [E] [expires: 2026-01-11]

      ```

      > **Important:** be sure not to specify a password to use your keys.

      You'll now see your key on your keyring.

      ```shell
      $ gpg --list-keys 51924ADAFC92656FAFEB672D4B90DE5D5BF143B8
      pub   rsa3072 2024-01-12 [SC] [expires: 2026-01-11]
            51924ADAFC92656FAFEB672D4B90DE5D5BF143B8
      uid           [ultimate] Emma Doyle <emma@premiscale.com>
      sub   rsa3072 2024-01-12 [E] [expires: 2026-01-11]
      ```

  2. Export your private key and b64 encode it (otherwise it will dump a bunch of binary data to your shell).

      ```shell
      $ gpg --armor --export-secret-keys 51924ADAFC92656FAFEB672D4B90DE5D5BF143B8 | base64
      ...
      ```

      Copy this value and update your [Helm values](/helm/operator/).

</details>

### Password store

Install [`pass`](https://www.passwordstore.org/) and initialize a local store using the GPG keys you generated in the last step.

```shell
pass init "$GPG_KEY_ID" --path <subpath of ~/.password-store/>
```

Now, on your local machine,

```shell
$ ls -lash ~/.password-store/repo/
total 12K
4.0K drwx------  2 emmadoyle emmadoyle 4.0K Jan 15 13:36 .
4.0K drwxrwxr-x 13 emmadoyle emmadoyle 4.0K Jan 15 13:36 ..
4.0K -rw-------  1 emmadoyle emmadoyle   41 Jan 15 13:36 .gpg-id
```

### Git repository

From the `pass` [man page](https://git.zx2c4.com/password-store/about/),

```text
...
pass git git-command-args...
        If the password store is a git repository, execute a git command
        specified by git-command-args.
...
```

we may easily link our local password store to a remote Git repository. This operator uses `git` alongside `pass` to pull secret updates.

```shell
$ git init ~/.password-store/repo/
$ ls -lash ~/.password-store/repo/
total 16K
4.0K drwx------  3 emmadoyle emmadoyle 4.0K Jan 15 13:38 .
4.0K drwxrwxr-x 13 emmadoyle emmadoyle 4.0K Jan 15 13:36 ..
4.0K drwxrwxr-x  7 emmadoyle emmadoyle 4.0K Jan 15 13:38 .git
4.0K -rw-------  1 emmadoyle emmadoyle   41 Jan 15 13:36 .gpg-id
```

### Private SSH key

Now add a remote git repository and watch as `pass insert`-commands create local commits automatically. Sync your local password store with the remote repo via `pass git push`.

## Development

### Testing

Run unit tests with

```shell
poetry run pytest tests/unit
```

e2e tests against a live environment with

```shell
poetry run pytest tests/e2e
```

And coverage against the codebase with

```shell
poetry run coverage run -m pytest
poetry run coverage report -m pytest
```
