Updating documentation

Venafi · Feb 7, 2024 · e23367e · e23367e
1 parent 614d1d9
commit e23367e
Show file tree

Hide file tree

Showing 10 changed files with 175 additions and 119 deletions.
diff --git 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
@@ -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
diff --git 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
@@ -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,29 +28,27 @@
     "* 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"
     }
    },
    "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
@@ -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
diff --git a/docs/images/generate-api-key.png b/docs/images/generate-api-key.png
diff --git a/docs/images/preferences.png b/docs/images/preferences.png
diff --git 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,17 +48,31 @@ 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
             * Locally installed (OpenSSL)[https://www.openssl.org] command line utility
             * 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**. <figure markdown>
+      ![Image title](images/preferences.png){ width="300" }
+      </figure>
+    3. Click the "Generate New Key" link, then specify the "API Key Validity Period". Recommend 30 days. <figure markdown>
+      ![Image title](images/generate-api-key.png){ width="300" }
+      </figure>
+    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<figure markdown>
+      ![Image title](images/copy-api-key.png){ width="300" }
+      </figure>
+
+
+
         
 ## 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 → socket/.DS_Store b/config/.DS_Store → socket/.DS_Store