diff --git a/docs/assets/bitwarden/ui_get_id.png b/docs/assets/bitwarden/ui_get_id.png new file mode 100644 index 00000000..50d522fc Binary files /dev/null and b/docs/assets/bitwarden/ui_get_id.png differ diff --git a/docs/assets/github/ui_get_org_id.png b/docs/assets/github/ui_get_org_id.png new file mode 100644 index 00000000..ef858631 Binary files /dev/null and b/docs/assets/github/ui_get_org_id.png differ diff --git a/docs/assets/otterdog/dashboard.png b/docs/assets/otterdog/dashboard.png new file mode 100644 index 00000000..2df16b7d Binary files /dev/null and b/docs/assets/otterdog/dashboard.png differ diff --git a/docs/assets/otterdog/otterdog_sample_pr.png b/docs/assets/otterdog/otterdog_sample_pr.png new file mode 100644 index 00000000..18e52d94 Binary files /dev/null and b/docs/assets/otterdog/otterdog_sample_pr.png differ diff --git a/docs/assets/otterdog/playground.png b/docs/assets/otterdog/playground.png new file mode 100644 index 00000000..471fb038 Binary files /dev/null and b/docs/assets/otterdog/playground.png differ diff --git a/docs/infra/bitwarden.md b/docs/infra/bitwarden.md index 175a8963..8355ba8a 100644 --- a/docs/infra/bitwarden.md +++ b/docs/infra/bitwarden.md @@ -1,6 +1,7 @@ # Bitwarden A [password tool](https://bitwarden.com) to help us manage our [organizations secrets](https://vault.bitwarden.com/#/vault?organizationId=e429b264-5b49-4794-be50-b0660125456a). +Another potential tool is the [pass CLI](https://www.passwordstore.org) where `pass` is for password not _our_ Open Access PASS. Here is an outline of passwords we are tracking (duplicating here as can better document the integrations with other services @@ -8,6 +9,99 @@ like [Otterdog](/docs/infra/otterdog.md) and Github Actions). ![Bitwarden Secrets User Interface](/docs/assets/bitwarden/ui.png) -| Secret | Description | -| --- | --- | -| HELLO_WORLD | A test secret for demontsrating how secrets are managed | +| Item Name | Item Id | Field | Description | +| --- | --- | --- | --- | +| HELLO_WORLD | 23801ca4-fd27-446c-b5af-b07b0108f443 | quest | A test secret of `holy_grail` for demontsrating how secrets are managed | +| HELLO_WORLD | 23801ca4-fd27-446c-b5af-b07b0108f443 | color | Another test secret of `blue_no_ahh` | + +## Installing CLI + +Some instructions for installing the [bitwarden cli are here](https://github.com/bitwarden/clients). +The tools command line name is `bw` and you can see which version you are running with + +```bash +bw -v +``` + +To install it via [homebrew](https://brew.sh) you can run + +```bash +brew install bitwarden-cli +``` + +You can log into the account with + +```bash +bw login +``` + +And then you can list the passwords (in plain text, be careful). + +```bash +bw list items --search HELLO_WORLD +``` + +Note these are NOT sensitive passwords so it's OK to be shown + +```bash +[ + { + "passwordHistory": + [ + { + "lastUsedDate": "2023-09-26T17:32:20.947Z", + "password": "HELLO_WORLD" + } + ], + "revisionDate": "2023-09-26T17:39:02.833Z", + "creationDate": "2023-09-12T16:04:39.793Z", + "deletedDate": null, + "object": "item", + "id": "23801ca4-fd27-446c-b5af-b07b0108f443", + "organizationId": "e429b264-5b49-4794-be50-b0660125456a", + "folderId": null, + "type": 1, + "reprompt": 0, + "name": "HELLO_WORLD", + "notes": null, + "favorite": false, + "fields": + [ + { + "name": "quest", + "value": "holy_grail", + "type": 1, + "linkedId": null + }, + { + "name": "color", + "value": "blue_no_ahh", + "type": 1, + "linkedId": null + } + ], + "login": + { + "username": null, + "password": "WORLD_HELLO", + "totp": null, + "passwordRevisionDate": "2023-09-26T17:32:20.947Z" + }, + "collectionIds": + [ + "af5a75d8-8762-4cec-8d96-b06601263cf1" + ] + } +] +``` + + +## Troubleshooting + +### How do I get the ID of an item from the UI + +You will need to **Inspect** the page and watch for the network traffic +after you edit the item. + +![Bitwarden Secrets User Interface](/docs/assets/bitwarden/ui_get_id.png) + diff --git a/docs/infra/otterdog.md b/docs/infra/otterdog.md index ad6564f7..a766d9af 100644 --- a/docs/infra/otterdog.md +++ b/docs/infra/otterdog.md @@ -5,3 +5,153 @@ using the [Otterdog tool](https://gitlab.eclipse.org/eclipsefdn/security/otterdo Our first project will be to manage secrets via [bitwarden](/docs/infra/bitwarden.md). +## Pushing GitHub Infra Changes + +To make changes, you must push a [forked PR like this one](https://github.com/eclipse-pass/.eclipsefdn/pull/1). + +![Sample PR](/docs/assets/otterdog/otterdog_sample_pr.png) + + +## Configurations + +The base configuration is [eclipse-pass.jsonnet](https://github.com/eclipse-pass/.eclipsefdn/blob/main/otterdog/eclipse-pass.jsonnet), +and can be monitored at [eclipse-pass.org/.eclipsefdn](https://eclipse-pass.org/.eclipsefdn/) + +![Otterdog Config Monitoring](/docs/assets/otterdog/dashboard.png) + +The base entry for jsonnett configs is via + +```javascript +local orgs = import 'otterdog-defaults.libsonnet'; +``` + +### Bitwarden Configs + +To integrate [bitwarden into otterdog configs](https://gitlab.eclipse.org/eclipsefdn/security/otterdog#bitwarden) +the request is to add an _"organization"_ directly to the JSON, but instead lets use the jsonnett based +on the outputs from the [otterdog playground](http://eclipse-pass.org/.eclipsefdn/playground/). + +```javascript +orgs.newOrg('eclipse-pass') { + credentials+: [{ + "provider": "bitwarden", + "item_id" : "23801ca4-fd27-446c-b5af-b07b0108f443" + }, + ], +} +``` + +And then we can specify secrets based on the structure of `bitwarden:@`. + +### Organizational Secrets + +Here is documentation on managing [organization secrets](https://otterdog.readthedocs.io/en/latest/reference/organization/secret/) + +```javascript +orgs.newOrg('eclipse-pass') { + secrets+: [ + orgs.newOrgSecret('HELLO_WORLD_QUEST') { + value: "bitwarden:23801ca4-fd27-446c-b5af-b07b0108f443@quest", + }, + orgs.newOrgSecret('HELLO_WORLD_COLOR') { + value: "bitwarden:23801ca4-fd27-446c-b5af-b07b0108f443@color", + }, + ], +} +``` + +Please refer to [bitwarden for specifics on password management](/docs/infra/bitwarden.md) + +## Playground (Online Editor) + +From the [monitoring application]((https://eclipse-pass.org/.eclipsefdn/)) you can access a [otterdog playground](http://eclipse-pass.org/.eclipsefdn/playground/) + +![Otterdog Playground](/docs/assets/otterdog/playground.png) + +## Installing Locally + +If you are testing github integrations, you will need to [install Otterdog locally](https://otterdog.readthedocs.io/en/latest/install/) + +Below is a summary of the [installation guide above](https://otterdog.readthedocs.io/en/latest/install/). +If you run into problems, then please read the source installation guide and update these docs. + +You will need the following tools + +```bash +python3 --version # 3.10+, tested on 3.11.4 +pip --version # any, tested on 23.2 +poetry --version # any, tested on 1.4.2 +go version # 1.13+, tested on 1.20.5 +jb --version # any, tested on 'dev' (aka 0.5.1 as shown in troubleshooting below) +bw -v # any, tested on 2023.9.0 +``` + +Now you can clone the [Otterdog repo](https://gitlab.eclipse.org/eclipsefdn/security/otterdog/) +and build it locally + +```bash +# Somewhere outside of the eclipse-pass repos +git clone git@gitlab.eclipse.org:eclipsefdn/security/otterdog.git +cd otterdog +make init +``` + +You now have `otterdog` installed locally. + +```bash +otterdog --version +# otterdog.sh, version 0.3.0.dev0 +``` + +### Troubleshooting + +#### jb / jsonnet-bundler not found + +Here's how you install [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler) (aka `jb`) + +``` +go install -a github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb@v0.5.1 +``` + +Note that [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler) was installed to a `$HOME/go/bin` which was NOT +on our path, so I had to add that to ensure `jb` was accessible. + +```bash +# in your ~/.bash_profile or similar +PATH="$HOME/go/bin:$PATH" +``` + +#### bw / bitwarden not found + +Here's how you install [bitwarden](https://github.com/bitwarden/clients) (aka `bw`). + +The installation uses `snap`, but (home)`brew` also works + +```bash +brew install bitwarden-cli +``` + +#### .local/bin/otterdog: No such file or directory + +If you see something like + +```bash +test -f ~/.local/bin/otterdog || ln -s /Users/aforward/sin/projects/eclipse-pass/otterdog/otterdog.sh ~/.local/bin/otterdog +ln: /Users/aforward/.local/bin/otterdog: No such file or directory +make: *** [init] Error 1 +``` + +Then ensure that you have a `~/.local/bin` to receive the file, and that is also on your path + +```bash +mkdir -p ~/.local/bin + +# in your ~/.bash_profile or similar +PATH="$HOME/.local/bin:$PATH" +``` + +#### How do I get the github organization ID from the UI + +You will need to **Inpsect** the org page and look for `organization:` + +![GitHub Organization ID](/docs/assets/github/ui_get_org_id.png)