add 2 more examples

README.rst

@@ -6,7 +6,7 @@
 
 .. image:: https://goreportcard.com/badge/github.com/bbva/kapow
     :target: https://goreportcard.com/report/github.com/bbva/kapow
-    
+
 **Kapow!** If you can script it, you can HTTP it.
 
 
@@ -121,7 +121,7 @@ Kapow! can't help when:
 
 
 When it is your best friend:
---------------------------
+----------------------------
 
 * Easy command + Hard API = Kapow! to the rescue
 * SSH for one command?  Kapow! allows you to share only that command

docs/source/examples/index.rst

@@ -9,12 +9,14 @@ A .pow file is a plain text with shell instructions, usually, you can use Kapow!
 **Starting Kapow! using .pow file**
 
 .. code-block:: console
+   :linenos:
 
     $ kapow server example.pow
 
 With the example.pow:
 
 .. code-block:: console
+   :linenos:
 
     #
     # This is a simple example of a .pow file
@@ -35,6 +37,7 @@ Load more than 1 .pow file
 You can load more than one .pow file at time. This can help you have your .pow files ordered.
 
 .. code-block:: console
+   :linenos:
 
     $ ls pow-files/
     example-1.pow   example-2.pow
@@ -47,12 +50,10 @@ Add a new route
 
     Be aware when you defined more than routes in same path, only first routed added will be resolved.
 
-    Example:
+    For example, if you add these routes:
 
-    If you add these routes:
+    1. http://localhost:8080/echo
-
+    2. http://localhost:8080/echo/{message}
-    - http://localhost:8080/echo
-    - http://localhost:8080/echo/{message}
 
     Only first one route will be resolved.
 
@@ -61,12 +62,14 @@ Add a new route
 Defining route:
 
 .. code-block:: console
+   :linenos:
 
     $ kapow route add '/my/route' -c 'echo "hello world" | kapow set /response/body'
 
 Calling route:
 
 .. code-block:: console
+   :linenos:
 
     $ curl http://localhost:8080/my/route
     hello world
@@ -76,12 +79,14 @@ Calling route:
 Defining route:
 
 .. code-block:: console
+   :linenos:
 
     $ kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
 
 Calling route:
 
 .. code-block:: console
+   :linenos:
 
     $ curl -d "hello world" -X POST http://localhost:8080/echo
     hello world%
@@ -91,12 +96,14 @@ Calling route:
 Defining route:
 
 .. code-block:: console
+   :linenos:
 
     $ kapow route add '/echo/{message}' -c 'kapow get /request/matches/message | kapow set /response/body'
 
 Calling route:
 
 .. code-block:: console
+   :linenos:
 
     $ curl http://localhost:8080/echo/hello%20world
     hello world%
@@ -108,6 +115,7 @@ Listing routes
 You can list active route in kapow! server.
 
 .. code-block:: console
+   :linenos:
 
     $ kapow route list
     [{"id":"20c98328-0b82-11ea-90a8-784f434dfbe2","method":"GET","url_pattern":"/echo/{message}","entrypoint":"/bin/sh -c","command":"kapow get /request/matches/message | kapow set /response/body","index":0}]
@@ -115,6 +123,7 @@ You can list active route in kapow! server.
 Or, for pretty output, you can use samp:`jq`:
 
 .. code-block:: console
+   :linenos:
 
     $ kapow route list | jq
     [
@@ -140,6 +149,7 @@ Deleting routes
 If we want to delete a route you need their ID. Using de above example, you can delete the route by typing:
 
 .. code-block:: console
+   :linenos:
 
     $ kapow route remove 20c98328-0b82-11ea-90a8-784f434dfbe2
 
@@ -149,6 +159,7 @@ Writing multiline .pow files
 Some time you need to write more complex actions. So you can write multiline commands:
 
 .. code-block:: console
+   :linenos:
 
     kapow route add /log_and_stuff - <<-'EOF'
         echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body
@@ -165,13 +176,14 @@ Some time you need to write more complex actions. So you can write multiline com
 
 
 Add or modify a HTTP Header
-++++++++++++++++++++++++++
++++++++++++++++++++++++++++
 
 Some times you want add some extra HTTP header to response.
 
 In this example we'll adding the security header "nosniff" in a sniff.pow:
 
 .. code-block:: console
+   :linenos:
 
     $ cat sniff.pow
     kapow route add /sec-hello-world - <<-'EOF'
@@ -186,6 +198,7 @@ Test with curl:
 
 .. code-block:: console
    :emphasize-lines: 11
+   :linenos:
 
     $ curl -v http://localhost:8080/sec-hello-world
     *   Trying ::1...
@@ -214,6 +227,7 @@ Modify JSON by using shell
 In this example our Kapow! service will receive a JSON value with an incorrect date, then our .pow file will fix then and return the correct value to the user.
 
 .. code-block:: console
+   :linenos:
 
     $ cat fix_date.pow
     kapow route add -X POST '/fix-date' - <<-'EOF'
@@ -224,6 +238,7 @@ In this example our Kapow! service will receive a JSON value with an incorrect d
 Call service with curl:
 
 .. code-block:: console
+   :linenos:
 
     $ curl -X POST http://localhost:8080/fix-date -H "Content-Type: application/json" -d '{"incorrectDate": "no way"}'
 
@@ -233,6 +248,7 @@ Upload files
 Upload a file using Kapow! is very simple:
 
 .. code-block:: console
+   :linenos:
 
     $ cat upload.pow
     kapow route add -X POST '/upload-file' - <<-'EOF'
@@ -240,6 +256,7 @@ Upload a file using Kapow! is very simple:
     EOF
 
 .. code-block:: console
+   :linenos:
 
     $ cat results.json
     {"hello": "world"}
@@ -249,12 +266,78 @@ Upload a file using Kapow! is very simple:
 Protecting again Command Injection Attacks
 ++++++++++++++++++++++++++++++++++++++++++
 
+When you resolve variable values be careful to *escape* by using double quotes. Otherwise you could be vulnerable to **command injection attack**.
 
+**This examples is VULNERABLE to command injection**
+
+In this example, an attacker can execute arbitrary command.
+
+.. code-block:: console
+   :linenos:
+
+    $ cat command-injection.pow
+    kapow route add '/vulnerable/{value}' - <<-'EOF'
+         ls $(kapow get /request/matches/value) | kapow set /response/body
+    EOF
+
+Exploding using curl:
+
+.. code-block:: console
+   :linenos:
+
+   $ curl "http://localhost:8080/vulnerable/;echo%20hello"
+
+**This examples is NOT VULNERABLE to command injection**
+
+Be aware of we add double quotes when we recover *value* data from url:
+
+.. code-block:: console
+   :linenos:
+
+    $ cat command-injection.pow
+    kapow route add '/vulnerable/{value}' - <<-'EOF'
+         ls "$(kapow get /request/matches/value)" | kapow set /response/body
+    EOF
+
+.. note::
+
+   If want to read more about command injection, you can check `OWASP site <https://www.owasp.org/index.php/Command_Injection>`_
 
 Sending HTTP error codes
 ++++++++++++++++++++++++
 
+You can specify custom status code for HTTP response:
 
+.. code-block:: console
+   :linenos:
+
+    $ cat error.pow
+    kapow route add '/error' - <<-'EOF'
+        kapow set /response/status 401
+        echo "401 error" | kapow set /response/body
+    EOF
+
+Testing with curl:
+
+.. code-block:: console
+   :emphasize-lines: 8
+   :linenos:
+
+   $ curl -v http://localhost:8080/error
+   *   Trying ::1...
+   * TCP_NODELAY set
+   * Connected to localhost (::1) port 8080 (#0)
+   > GET /error HTTP/1.1
+   > Host: localhost:8080
+   > User-Agent: curl/7.54.0
+   > Accept: */*
+   >
+   < HTTP/1.1 401 Unauthorized
+   < Date: Wed, 20 Nov 2019 14:06:44 GMT
+   < Content-Length: 10
+   < Content-Type: text/plain; charset=utf-8
+   <
+   401 error
 
 How to redirect using HTTP
 ++++++++++++++++++++++++++
@@ -262,6 +345,7 @@ How to redirect using HTTP
 In this example we'll redirect our users to Google:
 
 .. code-block:: console
+   :linenos:
 
     $ cat redirect.pow
     kapow route add '/redirect' - <<-'EOF'
@@ -271,6 +355,7 @@ In this example we'll redirect our users to Google:
 
 .. code-block:: console
    :emphasize-lines: 10-11
+   :linenos:
 
     $ curl -v http://localhost:8080/redirect
     *   Trying ::1...
@@ -295,6 +380,7 @@ How to execute two processes parallel
 We want to samp:`ping` two machines parallel. Kapow! get IPs from query params:
 
 .. code-block:: console
+   :linenos:
 
     $ cat parallel.pow
     kapow route add /parallel/{ip1}/{ip2} - <<-'EOF'
@@ -306,6 +392,7 @@ We want to samp:`ping` two machines parallel. Kapow! get IPs from query params:
 Calling with curl:
 
 .. code-block:: console
+   :linenos:
 
     $ curl -v http://localhost:8080/parallel/10.0.0.1/10.10.10.1
 

docs/source/index.rst

@@ -7,6 +7,12 @@
    install
    quickstart
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Example
+
+   examples/index
+
 .. toctree::
    :maxdepth: 2
    :caption: Tutorial