diff --git a/README.rst b/README.rst index b0723f7..bcf6707 100644 --- a/README.rst +++ b/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 diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index 6eaa078..9e61232 100644 --- a/docs/source/examples/index.rst +++ b/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: - - - http://localhost:8080/echo - - http://localhost:8080/echo/{message} + 1. http://localhost:8080/echo + 2. 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 `_ 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index b39d9b3..23f2cbb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,6 +7,12 @@ install quickstart +.. toctree:: + :maxdepth: 2 + :caption: Example + + examples/index + .. toctree:: :maxdepth: 2 :caption: Tutorial