diff --git a/config/config.yaml b/config/config.yaml index 730cd6e..33853e7 100644 --- a/config/config.yaml +++ b/config/config.yaml @@ -3,13 +3,10 @@ bootstrap: url: https://api.venafi.cloud auth: privateKeyFile: /etc/firefly/private-key.pem - clientID: d2170df3-c468-11ee-88fe-72744281ddfc + clientID: f531953f-c51c-11ee-aa38-62722f50b33a csr: instanceNaming: Demo server: - rest: - port: 8281 - tls: - dnsNames: - - firefly.venafi.example - ipAddress: 127.0.0.1 + grpc: + uds: + socketPath: /opt/firefly/grpc.sock diff --git a/config/general-config.yaml b/config/general-config.yaml index b99acd2..4b6a3a4 100644 --- a/config/general-config.yaml +++ b/config/general-config.yaml @@ -1,86 +1,86 @@ -bootstrap: - selfSigned: - csr: - commonName: Demo - privateKey: - algorithm: ECDSA - size: 256 - duration: 8760h # one year - trustRootDirectory: /etc/firefly/trust -signer: - inMemory: true -server: - rest: - port: 8281 - tls: - dnsNames: - - firefly.venafi.example - ipAddress: 127.0.0.1 - authentication: - jwt: -# oidc: -# baseUrl: http://superfuzz.venafi.example:8000 -# audience: firefly - jwks: - urls: - - http://jwt-this.example:8000/.well-known/jwks.json - authorization: - configuration: Basic Demo -policies: -- name: Basic Demo - subject: - commonName: - type: OPTIONAL - allowedValues: - - ^.*\.vena\.fi - maxOccurrences: 1 - organization: - type: LOCKED - defaultValues: - - Venafi, Inc. - organizationalUnit: - type: IGNORED - locality: - type: OPTIONAL - allowedValues: - - Sofia - - London - defaultValues: - - Sofia - maxOccurrences: 1 - stateOrProvince: - type: IGNORED - country: - type: REQUIRED - allowedValues: - - BG - - GB - minOccurrences: 1 - maxOccurrences: 1 - sans: - dnsNames: - type: REQUIRED - allowedValues: - - ^.*\.vena\.fi - minOccurrences: 1 - maxOccurrences: 10 - ipAddresses: - type: FORBIDDEN - rfc822Names: - type: IGNORED - uniformResourceIdentifiers: - type: FORBIDDEN - keyUsages: - - digitalSignature - - keyEncipherment - extendedKeyUsages: - - SERVER_AUTH - - CLIENT_AUTH - keyAlgorithm: - allowedValues: - - EC_P256 - - EC_P384 - - EC_P521 - defaultValue: EC_P256 - signatureAlgorithm: EC_DSA_WITH_SHA256 +bootstrap: + selfSigned: + csr: + commonName: Demo + privateKey: + algorithm: ECDSA + size: 256 + duration: 8760h # one year + trustRootDirectory: /etc/firefly/trust +signer: + inMemory: true +server: + rest: + port: 8281 + tls: + dnsNames: + - firefly.venafi.example + ipAddress: 127.0.0.1 + authentication: + jwt: +# oidc: +# baseUrl: http://superfuzz.venafi.example:8000 +# audience: firefly + jwks: + urls: + - http://jwt-this.example:8000/.well-known/jwks.json + authorization: + configuration: Basic Demo +policies: +- name: Basic Demo + subject: + commonName: + type: OPTIONAL + allowedValues: + - ^.*\.vena\.fi + maxOccurrences: 1 + organization: + type: LOCKED + defaultValues: + - Venafi, Inc. + organizationalUnit: + type: IGNORED + locality: + type: OPTIONAL + allowedValues: + - Sofia + - London + defaultValues: + - Sofia + maxOccurrences: 1 + stateOrProvince: + type: IGNORED + country: + type: REQUIRED + allowedValues: + - BG + - GB + minOccurrences: 1 + maxOccurrences: 1 + sans: + dnsNames: + type: REQUIRED + allowedValues: + - ^.*\.vena\.fi + minOccurrences: 1 + maxOccurrences: 10 + ipAddresses: + type: FORBIDDEN + rfc822Names: + type: IGNORED + uniformResourceIdentifiers: + type: FORBIDDEN + keyUsages: + - digitalSignature + - keyEncipherment + extendedKeyUsages: + - SERVER_AUTH + - CLIENT_AUTH + keyAlgorithm: + allowedValues: + - EC_P256 + - EC_P384 + - EC_P521 + defaultValue: EC_P256 + signatureAlgorithm: EC_DSA_WITH_SHA256 validityPeriod: P90D \ No newline at end of file diff --git a/config/private-key.pem b/config/private-key.pem index 1add331..9ffdfb2 100644 --- a/config/private-key.pem +++ b/config/private-key.pem @@ -1,5 +1,5 @@ -----BEGIN PRIVATE KEY----- -MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgPpjorEmk7gkhEFwI -NONJPX+80LO47pUCNJ1Q5R6ELOmhRANCAAT9DcVHN4G96CBfw1SmJvd1R6wKezsm -EJ8vCz8KOT6/40QCvs3wQsI5k/nylERWLOr6VN5DZnBhsrBMtKjoFAoa +MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgcIG8PWL/TJNsXDQh +JdkNl3ZRu4EBAc87HoYdOXuVJtGhRANCAARhSwH6nAhxmkyr6inAHdtUwS4X8EPN +03Ge9G72kK5CrrrgHO9I8wvzqoQowrHUxWk3ibzgMuoqSRxDzmgA54eV -----END PRIVATE KEY----- diff --git a/demo.ipynb b/demo.ipynb index 7e3647f..c7af75e 100644 --- a/demo.ipynb +++ b/demo.ipynb @@ -1,5 +1,14 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Step 1 - Configure the Venafi control plane to for a new Firefly instance. \n", + "\n", + "This task would usually be done using the UI, however it can be fully automated using the API. As a convenience, and to get you started using Firefly in the shortest possible time, we will use a utility called \"elevate\" to do this. This will run in a Docker container and we'll use Docker Compose to orchestrate it. However before we can do this you need will need your API key as described in the project documentation. " + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -19,21 +28,19 @@ "* Policies: basic-demo\n", "* Configurations: basic-demo\n", "\n", - "For the purposes of this demonstrations some simple policies have been created. \n", - "\n", - "f\n" + "For the purposes of this demonstrations some simple policies have been created. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "Lets start by adding our Venafi cloud API key to the environment. The following command creates a new `.env` file that contains an API key that will be used by the Docker compose file to generate a working Firefly configuration. " + "Lets start by adding our Venafi cloud API key to the environment. The following command creates a new `.env` file that contains an API key that will be used by the Docker compose file to generate a working Firefly configuration. Replace the placeholder text with your own API key. " ] }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 3, "metadata": { "vscode": { "languageId": "shellscript" @@ -41,7 +48,7 @@ }, "outputs": [], "source": [ - "echo \"TLSPC_API_KEY=xxxx-xxxxx-xxxx-xxxxx\" > .env" + "echo \"TLSPC_API_KEY=97f26f6e-9935-4aff-a505-d286f3747981\" > .env" ] }, { diff --git a/docker-compose.yml b/docker-compose.yml index 7313e11..ccba78f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -26,7 +26,7 @@ services: volumes: - ./config/config.yaml:/etc/firefly/config.yaml - ./config:/etc/firefly:ro - + - ./socket:/opt/firefly:rw cap_add: - IPC_LOCK environment: diff --git a/docs/images/copy-api-key.png b/docs/images/copy-api-key.png new file mode 100644 index 0000000..699687f Binary files /dev/null and b/docs/images/copy-api-key.png differ diff --git a/docs/images/generate-api-key.png b/docs/images/generate-api-key.png new file mode 100644 index 0000000..5d7affe Binary files /dev/null and b/docs/images/generate-api-key.png differ diff --git a/docs/images/preferences.png b/docs/images/preferences.png new file mode 100644 index 0000000..e29391f Binary files /dev/null and b/docs/images/preferences.png differ diff --git a/docs/index.md b/docs/index.md index 3612c25..3031070 100644 --- a/docs/index.md +++ b/docs/index.md @@ -35,10 +35,8 @@ This playground can be run in one of two ways as follows: * A working GitHub account * Venafi Cloud account for {{ component_name }} - you can signup for a free 30 day trial [here](https://venafi.com/try-venafi/firefly/) - * An API key for your Venafi Cloud account. This can be obtained as follows: - 1. Log in to TLS Protect Cloud. - 2. In the menu bar, click your **avatar** in the top-right corner, and then click **Preferences**. - 3. On the **API Keys** tab, click the link to generate and copy your API key. + * An API key for your Venafi Cloud account. Use the instructions below to get your API key. + @@ -50,10 +48,7 @@ This playground can be run in one of two ways as follows: * Access to a fairly recent Docker runtime environment * Venafi Cloud account for Firefly - you can signup for a free 30 day trial [here](https://venafi.com/try-venafi/firefly/) - * An API key for your Venafi Cloud account. This can be obtained as follows: - 1. Log in to TLS Protect Cloud. - 2. In the menu bar, click your **avatar** in the top-right corner, and then click **Preferences**. - 3. On the **API Keys** tab, click the link to generate and copy your API key. + * An API key for your Venafi Cloud account. Use the instructions below to get your API key. * The following utilities are not required to run the Firefly playground but are used as a convenience to quickly demonstrate the Firefly API. * Locally installed (cURL)[https://curl.se] command line utility * Locally installed (JQ)[https://jqlang.github.io/jq/] command line utility @@ -61,6 +56,23 @@ This playground can be run in one of two ways as follows: * Locally installed (JWT)[https://github.com/mike-engel/jwt-cli] command line utility +??? tip "Getting an API Key" + + If you don't have an API key you can follow this steps: + + 1. Login to https://ui.venafi.cloud. If you don't already have an account you can sign-up for a 30 day trail. + 2. In the menu bar, click your **avatar** in the top-right corner, and then click **Preferences**.
+ ![Image title](images/preferences.png){ width="300" } +
+ 3. Click the "Generate New Key" link, then specify the "API Key Validity Period". Recommend 30 days.
+ ![Image title](images/generate-api-key.png){ width="300" } +
+ 4. Click the "Generate" button at the bottom of the page. You will then see options to view or copy the new key. Keep a note of the API key somewhere secure for later
+ ![Image title](images/copy-api-key.png){ width="300" } +
+ + + ## Audience @@ -71,7 +83,7 @@ The intended audience for this playground is: * Developers, SRE's and platform engineering teams wanting to learn more about the services that Info Sec teams should be providing * Internal Venafi staff wanting to demonstrate Firefly to partners and customers. -## Get Started +## Getting Started The quick-start demo runs entirely in Docker and consists of three container images that a pulled from the public Docker repositories. @@ -106,24 +118,35 @@ To simplify the this demonstration, the project includes an interactive Jupyter Before you can run Firefly, you must edit the `.env` file to include a valid Venafi cloud API key (referenced in the prerequisites) at the placeholder. This is the only thing you need to change. - ```text title=".env file" - TLSPC_API_KEY=xxxxx-xxxxxx-xxxxxx-xxxxxx + The first task in the demo creates a `.env` file that is used to store a variable for the API key. + + e.g. + + ```text title="create a .env file" + echo "TLSPC_API_KEY=xxxxx-xxxxxx-xxxxxx-xxxxxx" > .env ``` +At this point you can either follow the instructions here and cut/past the commands into the terminal in the codesdpace, or just step through and run each of the cells in the `demo.ipynb` interactive notebook file. + +### Step 1 - Configure the control plane +Every Firefly instance requires a valid service account, configuration and policy in the Venafi Control Plane (TLS Protect Cloud). For production, this task would often be completed by your InfoSec team. However, it might be undertaken by the platform engineering teams. Either way, you need to login to https://ui.venafi.cloud to create various config items. -You can now run a docker command to configure the Venafi Cloud control plane as follows: +To simplify this process and reduce the time it takes to get started, we will use the prebuilt `3goats/elevate` container that fully automates the creation of the service account, configuration and policy. It will also create a private key file `private-key.pem` and local firefly `config.yaml` in the `config` directory. -``` bash +To do this use the following `docker compose` command. This will run only the `3goats/elevate` container. + +???+ warning "Important" + + Do not run the `docker` commands in the interactive `demo.ipynb` environment. Instead type or cut and past the commands into the terminal. + +``` bash title="Configure the Control Plane" docker compose --profile control-plane up ``` You should see the following output. You should also the following new files in the `./config` directory. -* **config.yaml** - This is a generated Firefly configuration that will be used to pass the Firefly instance some basic values that are required as part of the bootstrap process, -* **private-key.pem** This is the private part of a generated key pair that will be used by firefly to authenticate to the Venafi Cloud control plane. - -```bash +```bash title="Example output" [+] Running 2/0 ✔ Network firefly-quickstart_default Created 0.0s ✔ Container firefly-quickstart-elevate-1 Created 0.0s @@ -148,3 +171,32 @@ elevate-1 | elevate-1 exited with code 0 ``` +The following files will also be updated to include valid content. + +* **config.yaml** - This is a generated Firefly configuration that will be used to pass the Firefly instance some basic values that are required as part of the bootstrap process, +* **private-key.pem** This is the private part of a generated key pair that will be used by firefly to authenticate to the Venafi Cloud control plane. + +### Step 2 - Start Firefly and the local JWT service + +Now that we've configured the Control Plane, we can now start the Firefly container `public.ecr.aws/venafi-images/firefly` and the `tr1ck3r/jwt-this`. + +To do this use the following `docker compose` command. The `--profile demo` flag tells Docker to run only the `public.ecr.aws/venafi-images/firefly` and the `tr1ck3r/jwt-this` containers. + +``` bash title="Start Firefly & the JWT service" +docker compose --profile demo up +``` + +You should see the following output. + +```bash title="Example output" +todo +......... +......... +......... +``` + +!!! note + + The above command runs docker in interactive mode which means that the process does not exit. + + diff --git a/config/.DS_Store b/socket/.DS_Store similarity index 91% rename from config/.DS_Store rename to socket/.DS_Store index 5008ddf..8598f55 100644 Binary files a/config/.DS_Store and b/socket/.DS_Store differ