Dark-Alex-17/kapow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new examples

Browse Source
This commit is contained in:
cr0hn
2019-11-20 12:56:41 +01:00
parent 206aac5747
commit 0de07c1132
1 changed files with 314 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/examples/index.rst
+314
View File
@@ -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 <https://en.wikipedia.org/wiki/Here_document>`_
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 <https://developer.mozilla.org/es/docs/Web/HTTP/Headers/X-Content-Type-Options>`_.
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
++++++++++++++