diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index e69de29..6eaa078 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -0,0 +1,314 @@ +Examples +======== + +Using a .pow file ++++++++++++++++++ + +A .pow file is a plain text with shell instructions, usually, you can use Kapow! + +**Starting Kapow! using .pow file** + +.. code-block:: console + + $ kapow server example.pow + +With the example.pow: + +.. code-block:: console + + # + # This is a simple example of a .pow file + # + echo "[*] Starting my script" + + # We add 2 Kapow! routes + kapow route add '/my/route' -c 'echo "hello world" | kapow set /response/body' + kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body' + +.. note:: + + Every manage task you with Kapow! could be done by .pow file + +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 + + $ ls pow-files/ + example-1.pow example-2.pow + $ kapow server <(cat *.pow) + +Add a new route ++++++++++++++++ + +.. note:: + + Be aware when you defined more than routes in same path, only first routed added will be resolved. + + Example: + + If you add these routes: + + - http://localhost:8080/echo + - http://localhost:8080/echo/{message} + + Only first one route will be resolved. + +**GET route** + +Defining route: + +.. code-block:: console + + $ kapow route add '/my/route' -c 'echo "hello world" | kapow set /response/body' + +Calling route: + +.. code-block:: console + + $ curl http://localhost:8080/my/route + hello world + +**POST route** + +Defining route: + +.. code-block:: console + + $ kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body' + +Calling route: + +.. code-block:: console + + $ curl -d "hello world" -X POST http://localhost:8080/echo + hello world% + +**Adding URL params** + +Defining route: + +.. code-block:: console + + $ kapow route add '/echo/{message}' -c 'kapow get /request/matches/message | kapow set /response/body' + +Calling route: + +.. code-block:: console + + $ curl http://localhost:8080/echo/hello%20world + hello world% + + +Listing routes +++++++++++++++ + +You can list active route in kapow! server. + +.. code-block:: console + + $ 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}] + +Or, for pretty output, you can use samp:`jq`: + +.. code-block:: console + + $ kapow route list | jq + [ + { + "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 + } + ] + + +.. note:: + + Kapow! server has a administration interface, by default, listen at **localhost:8081** + + +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 + + $ kapow route remove 20c98328-0b82-11ea-90a8-784f434dfbe2 + +Writing multiline .pow files +++++++++++++++++++++++++++++ + +Some time you need to write more complex actions. So you can write multiline commands: + +.. code-block:: console + + kapow route add /log_and_stuff - <<-'EOF' + echo this is a quite long sentence and other stuff | tee log.txt | kapow set /response/body + cat log.txt | kapow set /response/body + EOF + +.. note:: + + Be aware with the **"-"** at the end of Kapow! command. It allows to read commands from the samp:`stdin`. + +.. note:: + + Multiline depends of the shell you're using (Bash by default). If you want to learn more of multiline see: `Here Doc `_ + + +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 + + $ cat sniff.pow + kapow route add /sec-hello-world - <<-'EOF' + kapow set /response/headers/X-Content-Type-Options "nosniff" + + echo "more secure hello world" | kapow set /response/body + EOF + + $ kapow server nosniff.pow + +Test with curl: + +.. code-block:: console + :emphasize-lines: 11 + + $ curl -v http://localhost:8080/sec-hello-world + * Trying ::1... + * TCP_NODELAY set + * Connected to localhost (::1) port 8080 (#0) + > GET /sec-hello-word HTTP/1.1 + > Host: localhost:8080 + > User-Agent: curl/7.54.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < X-Content-Type-Options: nosniff + < Date: Wed, 20 Nov 2019 10:56:46 GMT + < Content-Length: 24 + < Content-Type: text/plain; charset=utf-8 + < + more secure hello world + +.. note:: + + You can read more about nosniff header `here `_. + +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 + + $ cat fix_date.pow + kapow route add -X POST '/fix-date' - <<-'EOF' + kapow set /response/headers/Content-Type "application/json" + kapow get /request/body | jq --arg newdate $(date +"%Y-%m-%d_%H-%M-%S") '.incorrectDate=$newdate' | kapow set /response/body + EOF + +Call service with curl: + +.. code-block:: console + + $ curl -X POST http://localhost:8080/fix-date -H "Content-Type: application/json" -d '{"incorrectDate": "no way"}' + +Upload files +++++++++++++ + +Upload a file using Kapow! is very simple: + +.. code-block:: console + + $ cat upload.pow + kapow route add -X POST '/upload-file' - <<-'EOF' + kapow get /request/files/data/content | kapow set /response/body + EOF + +.. code-block:: console + + $ cat results.json + {"hello": "world"} + $ curl -X POST -H "Content-Type: multipart/form-data" -F "data=@results.json" http://localhost:8080/upload-file + {"hello": "world"} + +Protecting again Command Injection Attacks +++++++++++++++++++++++++++++++++++++++++++ + + + +Sending HTTP error codes +++++++++++++++++++++++++ + + + +How to redirect using HTTP +++++++++++++++++++++++++++ + +In this example we'll redirect our users to Google: + +.. code-block:: console + + $ cat redirect.pow + kapow route add '/redirect' - <<-'EOF' + kapow set /response/headers/Location 'http://google.com' + kapow set /response/status 301 + EOF + +.. code-block:: console + :emphasize-lines: 10-11 + + $ curl -v http://localhost:8080/redirect + * Trying ::1... + * TCP_NODELAY set + * Connected to localhost (::1) port 8080 (#0) + > GET /redirect HTTP/1.1 + > Host: localhost:8080 + > User-Agent: curl/7.54.0 + > Accept: */* + > + < HTTP/1.1 301 Moved Permanently + < Location: http://google.com + < Date: Wed, 20 Nov 2019 11:39:24 GMT + < Content-Length: 0 + < + * Connection #0 to host localhost left intact + + +How to execute two processes parallel ++++++++++++++++++++++++++++++++++++++ + +We want to samp:`ping` two machines parallel. Kapow! get IPs from query params: + +.. code-block:: console + + $ cat parallel.pow + 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/ip2) | kapow set /response/body & + wait + EOF + +Calling with curl: + +.. code-block:: console + + $ curl -v http://localhost:8080/parallel/10.0.0.1/10.10.10.1 + +Manage cookies +++++++++++++++ +