Review examples against option substitution.

Co-authored-by: pancho horrillo <pedrofelipe.horrillo@bbva.com>

docs/source/examples/index.rst

@@ -284,7 +284,7 @@ order to generate a two-attribute JSON response.
 .. code-block:: console
 
    $ cat echo-attribute.pow
-   kapow route add -X POST '/echo-attribute' - <<-'EOF'
+   kapow route add -X POST /echo-attribute - <<-'EOF'
       JSON_WHO=$(kapow get /request/body | jq -r .name)
 
       kapow set /response/headers/Content-Type application/json
@@ -339,7 +339,7 @@ In this example we respond back with the line count of the file received in the
    :linenos:
 
    $ cat count-file-lines.pow
-   kapow route add -X POST '/count-file-lines' - <<-'EOF'
+   kapow route add -X POST /count-file-lines - <<-'EOF'
 
       # Get sent file
       FNAME=$(kapow get /request/files/myfile/filename)
@@ -349,7 +349,7 @@ In this example we respond back with the line count of the file received in the
 
       kapow set /response/status 200
 
-      echo $FNAME has $LCOUNT lines | kapow set /response/body
+      echo -- "$FNAME has $LCOUNT lines" | kapow set /response/body
    EOF
 
 .. code-block:: console
@@ -386,7 +386,7 @@ Exploiting using curl:
 .. code-block:: console
    :linenos:
 
-   $ curl "http://localhost:8080/vulnerable/-li%20hello"
+   $ curl "http://localhost:8080/vulnerable/-lai%20hello"
 
 **This example is NOT VULNERABLE to parameter injection**
 
@@ -398,15 +398,17 @@ request:
 
    $ cat command-injection.pow
    kapow route add '/not-vulnerable/{value}' - <<-'EOF'
-        ls "$(kapow get /request/matches/value)" | kapow set /response/body
+        ls -- "$(kapow get /request/matches/value)" | kapow set /response/body
    EOF
 
 
 .. warning::
 
    Quotes around parameters only protect against injection of additional
-   arguments, but not against turning a non-option into option or vice-versa.
+   arguments, but not against turning a non-option into option or
-   See the "Security Concern" section on the docs.
+   vice-versa.  Note that for many commands we can leverage double-dash
+   to signal the end of the options.  See the "Security Concern" section
+   on the docs.
 
 
 Sending HTTP error codes
@@ -418,9 +420,9 @@ You can specify custom status code for HTTP response:
    :linenos:
 
    $ cat error.pow
-   kapow route add '/error' - <<-'EOF'
+   kapow route add /error - <<-'EOF'
        kapow set /response/status 401
-       echo "401 error" | kapow set /response/body
+       echo -n '401 error' | kapow set /response/body
    EOF
 
 Testing with curl:
@@ -454,7 +456,7 @@ In this example we'll redirect our users to Google:
    :linenos:
 
    $ cat redirect.pow
-   kapow route add '/redirect' - <<-'EOF'
+   kapow route add /redirect - <<-'EOF'
        kapow set /response/headers/Location https://google.com
        kapow set /response/status 301
    EOF
@@ -490,9 +492,9 @@ params:
    :linenos:
 
    $ cat parallel.pow
-   kapow route add /parallel/{ip1}/{ip2} - <<-'EOF'
+   kapow route add '/parallel/{ip1}/{ip2}' - <<-'EOF'
-       ping -c 1 "$(kapow get /request/matches/ip1)" | kapow set /response/body &
+       ping -c 1 -- "$(kapow get /request/matches/ip1)" | kapow set /response/body &
-       ping -c 1 "$(kapow get /request/matches/ip2)" | kapow set /response/body &
+       ping -c 1 -- "$(kapow get /request/matches/ip2)" | kapow set /response/body &
        wait
    EOF
 
@@ -522,7 +524,7 @@ In the next example we'll set a cookie:
          kapow set /response/cookies/Kapow-Status 'Kapow Cookie Set'
       fi
 
-      echo OK | kapow set /response/body
+      echo -n OK | kapow set /response/body
    EOF
 
 Calling with ``curl``:

docs/source/tutorial/tutorial03.rst

@@ -47,9 +47,9 @@ We need to filter
 
   .. code-block:: sh
 
-     kapow route add /db/backup_logs -e grep "$(kapow get /request/params/filter)" /var/log/backup_db.log \
+     kapow route add /db/backup_logs -c 'grep -- "$(kapow get /request/params/filter)" /var/log/backup_db.log \
        | tail -n "$(kapow get /request/params/lines)" \
-       | kapow set /response/body
+       | kapow set /response/body'
 
   It looks a bit weird but we'll have time to re-styling later.  Please make
   some tests on your laptop before to publish on the *Corporate Server*.

docs/source/tutorial/tutorial04.rst

@@ -131,14 +131,14 @@ I Need My Report
 
   .. code-block:: console
 
-     $ cat <<HERE
+     $ cat <<'EOF'
         you can put
         more than one line
         here
-       HERE
+       EOF
   
-  The shell will put the data between the first ``HERE`` and the second
+  The shell will put the data between the first ``EOF`` and the second
-  ``HERE`` as the ``stdin`` of the ``cat`` process.
+  ``EOF`` as the ``stdin`` of the ``cat`` process.
 
 **Junior**
 
@@ -150,7 +150,7 @@ I Need My Report
 
   .. code-block:: bash
 
-     kapow route add /capacityreport - <<-HERE
+     kapow route add /capacityreport - <<-'EOF'
          hostname | kapow set /response/body
          echo ================================================================================ | kapow set /response/body
          date | kapow set /response/body
@@ -161,7 +161,7 @@ I Need My Report
          echo ================================================================================ | kapow set /response/body
          df -h | kapow set /response/body
          echo ================================================================================ | kapow set /response/body
-     HERE
+     EOF
 
 **Senior**
 
@@ -195,7 +195,7 @@ I Need My Report
 
   .. code-block:: bash
 
-     kapow route add /capacityreport - <<-HERE
+     kapow route add /capacityreport - <<-'EOF'
          {
          hostname
          echo ================================================================================
@@ -208,7 +208,7 @@ I Need My Report
          df -h
          echo ================================================================================
          } | kapow set /response/body
-     HERE
+     EOF
 
 **Senior**
 

docs/source/tutorial/tutorial05.rst

@@ -40,9 +40,9 @@ Sharing the Stats
 
   .. code-block:: bash
 
-     kapow route add /capacitystats - <<-HERE 
+     kapow route add /capacitystats - <<-'EOF'
        echo "{\"memory\": \"`free -m`\"}"  | kapow set /response/body
-     HERE
+     EOF
 
 **Senior**
 
@@ -145,7 +145,7 @@ Sharing the Stats
 
   .. code-block:: bash
 
-     kapow route add /capacitystats - <<-HERE 
+     kapow route add /capacitystats - <<-'EOF'
        jq -n \
           --arg hostname "$(hostname)" \
           --arg date "$(date)" \
@@ -154,7 +154,7 @@ Sharing the Stats
           --arg disk "$(df -h)" \
           '{"hostname": $hostname, "date": $date, "memory": $memory, "load": $load, "disk": $disk}' \
        | kapow set /response/body
-     HERE
+     EOF
 
   What do you think?
    
@@ -179,7 +179,7 @@ Sharing the Stats
 
   .. code-block:: bash
 
-     kapow route add /capacitystats - <<-HERE 
+     kapow route add /capacitystats - <<-'EOF'
        jq -n \
           --arg hostname "$(hostname)" \
           --arg date "$(date)" \
@@ -189,7 +189,7 @@ Sharing the Stats
           '{"hostname": $hostname, "date": $date, "memory": $memory, "load": $load, "disk": $disk}' \
        | kapow set /response/body
        echo application/json | kapow set /response/headers/Content-Type
-     HERE
+     EOF
 
 **Senior**
 
@@ -211,7 +211,7 @@ Sharing the Stats
 
   .. code-block:: bash
 
-     kapow route add /capacitystats - <<-HERE 
+     kapow route add /capacitystats - <<-'EOF'
        kapow set /response/headers/Content-Type application/json
        jq -n \
           --arg hostname "$(hostname)" \
@@ -221,7 +221,7 @@ Sharing the Stats
           --arg disk "$(df -h)" \
           '{"hostname": $hostname, "date": $date, "memory": $memory, "load": $load, "disk": $disk}' \
        | kapow set /response/body
-     HERE
+     EOF
 
 **Senior**