Merge branch 'dev' of https://github.com/f5devcentral/f5xc-emea-workshop

 into dev

docs/class4/module1/lab1/lab1.rst

@@ -95,11 +95,8 @@ a) Web App & API Protection -> Load Balancers -> HTTP Load Balancer -> Add HTTP
       **Origin Pools**                        Click **Add Item**, for the **Origin Pool** select $$namespace$$/sentence-public-endpoint -> Apply
       ====================================    =================================================================================================
 
-   .. raw:: html   
-
-      <script>c1m1l2b();</script>  
 
-3. So far, Sentence application is not protected but exposed all over the world on all F5XC RE. 
+1. So far, Sentence application is not protected but exposed all over the world on all F5XC RE. 
 Check your Sentence application is exposed and reachable from the F5XC Global Network by browsing to :ext_link:`http://sentence-re-$$makeId$$.workshop.emea.f5se.com`
 
 .. warning:: Some Service Providers have a very long recursive cache. It can take several minutes to get a DNS response. You can change your DNS server to 1.1.1.1 or 8.8.8.8 to fix that.

docs/class4/module1/lab3/lab3.rst

@@ -1,18 +1,23 @@
 Test your modern API application protection
 ===========================================
 
-#. Open Postman
+#. If you have curl on your machine, go to the next step. Else, connect with SSH or WEBSSH to the Jumphost machine
 #. Run the below calls
 
-   #. GET /api/adjectives
-   #. GET /api/animals
-   #. GET /api/locations
+   .. code-block:: bash
+
+      curl -H "Content-Type: application/json;charset=UTF-8" http://sentence-re-$$makeId$$.workshop.emea.f5se.com/api/adjectives
+      curl -H "Content-Type: application/json;charset=UTF-8" http://sentence-re-$$makeId$$.workshop.emea.f5se.com/api/animals
+      curl -H "Content-Type: application/json;charset=UTF-8" http://sentence-re-$$makeId$$.workshop.emea.f5se.com/api/locations
+
    
    .. note:: The 3 calls are successful because there are defined in the OAS file (method + endpoint)
 
 #. Now, run the below call
 
-   #. GET /api/colors
+   .. code-block:: bash
+
+      curl -H "Content-Type: application/json;charset=UTF-8" http://sentence-re-$$makeId$$.workshop.emea.f5se.com/api/colors
 
    .. note:: This call is denied because not part of the OAS file
 
@@ -26,4 +31,5 @@ Check the logs
 .. note:: Scroll and search for API events
 
 .. image:: ../pictures/api-protect-event.png
-   :align: center
+   :align: center
+

docs/class4/module2/lab1/lab1.rst

@@ -1,10 +1,90 @@
-Enable API discovery
-====================
+Enable API Validation
+=====================
 
-Enable Endpoint Discovery
--------------------------
+In the previous section, we enabled AOU Protection. API Protection is based on rules (allow, deny), but API Validation goes deeper into the validation.
 
+API Validation validates the requests and the responses, but also the content (JSON payload) based on the OpenAPI Specifications.
 
-Enable PII Discovery
---------------------
+As a reminder, this is the difference between Protection and API Validation. 
+
+.. image:: ../pictures/slide-api-protection.png
+   :align: center
+   :scale: 40%
+
+.. note:: As an example, API Validation validates if the value of a JSON key matches the specifications (integer, string, array ...)
+
+Example below
+
+.. code-block:: YAML
+   :emphasize-lines: 24, 36, 38
+
+    /adjectives:
+    get:
+      description: List all adjectives
+      tags:
+        - adjectives
+      responses:
+        '200':
+          description: a list of adjectives with their index
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Adjectives"
+    post:
+      description: create an adjective
+      tags:
+        - adjectives
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+            example:
+              name: worried
+      responses:
+        '201':
+          description: adjective created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: 
+                  id:
+                    type: integer
+                  name:
+                    type: string
+              example:
+                id: 4
+                name: worried
+
+Having said, let's enable API Validation, and disable API Protection. It does not make sense to use both at the same time except if you need a specific rule for a specific endpoint.
+
+Update your API Load Balancer
+-----------------------------
+
+* Edit your Load Balancer and remove all API Protection rules (click on Reset Configuration and confirm)
+* Enable API Validation for ``All Endpoints``
+
+   .. image:: ../pictures/enable-api-validation.png
+      :align: left
+      :scale: 50%
+
+* Click on ``View Configuration`` to customize the settings``
+* Enable the ``Validation`` for ``Request`` and ``Response`` and select all the properties
+* Keep the setting ``Fall Through Mode`` to ``Allow``
+
+   .. image:: ../pictures/api-validation-settings.png
+      :align: left
+      :scale: 50%
+
+.. note:: The ``Fall Through Mode`` to ``Allow`` tells the system to let unknwon endpoints pass. In a nutshell, any unknown API endpoint will not be blocked and it is the API Discovery process which will take care of it.
+
+.. warning:: Why not to block unknown endpoint ? Because this endpoint can be legitimate from Dev Teams, but SecOps are not aware. And it is better to have a visilibity on what is unknown instead of breaking the business
+
+* SAVE your Load Balancer
+
+.. note:: We do not test now our configuration. We must enable API Discovery first, in order to have a full protection and visibility.
 

docs/class4/module2/lab2/lab2.rst

@@ -1,18 +1,53 @@
-API Discovery outcomes
-======================
+Enable API discovery
+====================
 
-Endpoint Discovery
-------------------
+In the previous section, we enabled ``API Validation`` in order to enforce protection on ``what we know`` from the OpenAPI Spec file.
+But we kept the ``Fall Through Mode`` to ``Allow`` so that we do not break the business down when DevOps pushes a new version of the API, but SecOps are not ready or up to date.
 
+The ``API Discovery`` will provide with visility to SecOps in order to see this ``Drift``. A drift is the difference between ``what we know`` and ``what we see / what is consumed``
 
-PII Discovery
--------------
+.. image:: ../pictures/slide-api-discovery.png
+   :align: center
+   :scale: 40%
 
+Enable Endpoint Discovery
+-------------------------
 
+* Edit you Load Balancer and enable API Discovery (keep the default settings)
 
-Authentication Discovery
-------------------------
+.. image:: ../pictures/enable-api-discovery.png
+   :align: left
+   :scale: 40%
 
+Enable PII Discovery
+--------------------
+
+OWASP Top10 API requires to detect and discover sensitive datas in Request and Response. To do so, F5 Distributed Cloud has a list of known PII (Personal Identifiable Information), such as:
+
+* email
+* credit card number
+* US Social Security Number
+* IP address
+
+But you want to detect your own PII, such as:
+
+* French Social Security Number
+* French Mobile Phone Number
+* Etc ...
+
+Create custom PII
+^^^^^^^^^^^^^^^^^
+
+* In Sensitive Data Protection, click on ``configure``
+* Add 2 new ``Defined Custom Sensitive Data Types``, enable detection for ``All Endpoint, Request and Response, Value Pattern``
+
+  * French SSN, use this regex [12][0-9]{2}(0[1-9]|1[0-2])(2[AB]|[0-9]{2})[0-9]{3}[0-9]{3}([0-9]{2})
+
+  * French Mobile Phone, use this regex ^(?:(?:\+|00)33|0)\s*[1-9](?:[\s.-]*\d{2}){4}$
+
+.. image:: ../pictures/pii.png
+   :align: left
+   :scale: 40%
+
+* SAVE your Load Balancer
 
-AI/ML Security Posture
-----------------------

docs/class4/module2/lab3/lab3.rst

@@ -0,0 +1,101 @@
+API Discovery outcomes
+======================
+
+At the first stage, API Discovery process requires several hours to collect datas and make them visible. Don't be surprised if you must wait 2 hours to see the first datas.
+
+But in this lab, the instructor have ``super powers`` and can force the discovery.
+
+Endpoint Discovery
+------------------
+
+* Switch to ``Dashboard`` > ``Security Dashboard``
+* Click on your Application Load Balancer
+* Go to the ``API Endpoints`` tab
+
+You can see the ``Graph`` page with the Octopus :) It represents what is known and what is seen.
+
+.. image:: ../pictures/octopus.png
+   :align: left
+   :scale: 50%
+
+Understand the API Discovery elements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On the top left corner, there are 3 important elements:
+
+* Inventory : Endpoints known by the OpenAPI Spec file
+
+  * In our lab, there are 3 endpoints know (adjectives, animals, locations)
+
+* Discovered : What the F5 XC platform is seeing at the moment (Known and Unknown endpoints)
+* Shadow : What is ``Discovered`` but **NOT PART** of the ``Inventory``
+
+You can filter on ``Shadow`` only for instance. You can see the ``/colors`` as a Shadow API.
+
+Go deeper into the discovery
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Click on the ``/colors`` shadow API endpoint. A pop-up will appear on the right side of the screen.
+* You can see on the op right corner, 2 actions
+
+  * API Protection rule : if you want to block this endpoint. Let's say SecOps have this power to block unknown endpoints.
+
+  * Rate Limiting : if you want to Rate Limit this endpoint because SecOps don't have the full power and don't want to break the app.
+
+* Click on the ``Discovered`` tab and navigate into the sub-menus. You will see all the details discovered by the platform. We will go in details in some of them in few minutes.
+
+.. image:: ../pictures/discovered.png
+   :align: left
+   :scale: 50%
+
+
+PII Discovery
+-------------
+
+* Switch to the ``Table`` view, instead of the ``Graph`` view
+* You can see more information in this screen, such as PII
+* Click on an endpoint with PII deteted, such as French SSN
+
+  .. image:: ../pictures/pii-1.png
+     :align: left
+     :scale: 50%
+
+* Click on ``Discovered`` tab and check the PII detected (request and response)
+
+  .. image:: ../pictures/pii-2.png
+     :align: left
+     :scale: 50%
+
+.. warning:: I anticipate a question : Can we hide those PII in the response. Currently, only Dataguard can do it, but not with Custom PII. This feature is in the roadmap. OWASP Top 10 does not require to ``hide`` sensitive datas.
+
+
+Authentication Discovery
+------------------------
+
+* Click on an endpoint with an ``Authenticated`` state.
+* Click on ``Discovered`` tab and check the Authentication details
+
+  .. image:: ../pictures/auth-discovery.png
+     :align: left
+     :scale: 50%
+
+* You can notice the information collected from the OpenAPI Spec, and also the information discovered. If both don't match, a Security Posture is raised.
+
+  .. image:: ../pictures/basic-auth.png
+     :align: left
+     :scale: 50%
+
+AI/ML Security Posture
+----------------------
+
+* Click on an endpoint with the highest ``Risk Score``
+* And click on the ``Security Posture`` tab
+* Review the recommandations done by AI/ML engines
+
+.. image:: ../pictures/security-posture.png
+   :align: left
+   :scale: 50%
+
+* You can click on the ``Evidence`` link to get more details about the logs who generated this security posture.
+
+.. note:: Congratulation, your application is now protected by a modern engine enforcing (validating) what is provided by the developpers, but also providing visibility for unkown traffic

docs/class4/module2/module2.rst

@@ -1,7 +1,7 @@
 Dynamic API Protection
 ######################
 
-In this section, we will protect the same modern application with F5 Distributed Cloud, but we will enable the **dynamic** protection where SecOps apply the API Discovery and validation.
+In this section, we will protect the same modern application with F5 Distributed Cloud, but we will enable the **dynamic** protection where SecOps apply the API Discovery and Validation.
 
 
 **Module 2 - All sections**