From e773f8ec29b0b360446655ab3427b3f71b6b9f92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9sar=20Gallego=20Rodr=C3=ADguez?= Date: Thu, 20 Jun 2019 11:04:24 +0200 Subject: [PATCH] more simple Readme and brand new doc --- README.md | 206 ++++++------------------------------------------- doc/readme.rst | 189 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 214 insertions(+), 181 deletions(-) create mode 100644 doc/readme.rst diff --git a/README.md b/README.md index 9afe6a1..61d858f 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ ![Kapow!](https://trello-attachments.s3.amazonaws.com/5c6edee98297dc18aa4e2b63/960x720/ff8d28fc24af11e3295afa5a9665bdc0/kapow-1601675_960_720.png) -**Kapow!** allows you to leverage the Ultimate Power™ of the UNIX® shell via HTTP. +**Kapow!** If you can script it, you can HTTP it. # CAVEAT EMPTOR -**Warning!!! Kapow!** is in the process of being defined by a -[specification](/spec/); the provided code is an *unsupported* Proof of Concept. +**Warning!!! Kapow!** is under heavy develepment and +[specification](/spec/); the provided code is a Proof of Concept and the final +version will not even share programming language. Ye be warned. @@ -16,200 +17,43 @@ Some awesome history is coming. # Kapow! for the impatient +When you need to share a command but not a whole system, Kapow! will help you by +the power of HTTP: + +![Kapow! lives](https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png) + Kapow! allows you to write a litte script that will serve an executable. This script will let you define how connect HTTP to Shell using Kapow!'s shell abstractions to the HTTP world. See it to believe: ![Kapow! in action](https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/b5e2554ff02fd9dba5ed2cec5c5d41e1/hello_kapow.gif) -On a simple schematics you can understand where Kapow! lives: -![Kapow! lives](https://trello-attachments.s3.amazonaws.com/5c824318411d973812cbef67/5ca1af818bc9b53e31696de3/784a183fba3f24872dd97ee28e765922/Kapow!.png) - - -## Kapow! Features +## Kapow! Superpowers Kapow! gives you: - * A very simple way of APIfy any shell executable + * A very simple way to turn any shell executable into an API * A remote administration API * Opinion free shell integration -When Kapow! is your best ally: + +## Kapow! Curses + +Kapow! can't help when: + + * You need high throughput: Kapow! spawn a new executable every HTTP call + * You must perform complex logic to attend the request: never use Kapow! if + your executables doesn't perform al least 90% of the hard work + * You are building a huge application + + +## When Kapow! is your best ally: * Easy command + Hard API = Kapow! to the rescue * SSH for one command? Kapow! allow you to share only that command * Remote instrumentation of several machines? make it easy with Kapow! +# Kapow! The more you know -# What is Kapow! - -Kapow! is an adapter between the world of Pure UNIX® Shell and an HTTP service. - -Some tasks are more convenient in the shell, like cloud interactions, or some -administrative tools. On the other hand, some tasks are more convenient as a -service, like DevSecOps tooling. - -Kapow! lies between these two worlds, making your life easier. Maybe you wonder -about how this kind of magic can happen; if you want to know the nitty-gritty -details, just read our [spec](/spec/). Or, if you want to know how Kapow! can -help you first, let's start with a common situation. - -Think about that awesome command that you use every day, something very -familiar, like `cloudx storage ls /backups`. Then someone asks you for an -specific backup, so you `ssh` into the host, execute your command, possibly -`grepping` through its output, copy the result and send it back to him. -And that's fine... for the 100 first times. - -Then you decide, let's use an API for this and generate an awesome web server -with it. So, you create a project, manage its dependencies, code the server, -parse the request, learn how to use the API, call the API and deploy it -somewhere. And that's fine... until you find yourself again in the same -situation with another awesome command. - -The awesomeness of UNIX® commands is infinite, so you'll be in this situation -an infinite number of times! Instead, let's put Kapow! into action. - -With Kapow!, when someone asks you for an specific backup (remember your -familiar command?) you just need to create a `.pow` file named `backups.pow` -that contains: - -```bash -kapow route add /backups \ - -c 'cloudx storage ls /backups | grep $(request /params/query) | response /body' -``` - -and execute it in the host with the command: -```bash -kapow server backups.pow -``` - -and that's it. Done. Do you like it? yes? Then let's start learning a little -more. - - -## The mandatory Hello World (for WWW fans) - -First you must create a pow file named `hello.pow` with the following contents: - -```bash -kapow route add /greet -c "echo 'hello world' | response /body" -``` - -then, you must execute: - -```bash -kapow server hello.pow -``` - -and you can check that it works as intended with good ole' `curl`: - -```bash -curl localhost:8080/greet -``` - - -## The mandatory Echo (for UNIX fans) - -First you must create a pow file named `echo.pow` with the following contents: - -```bash -kapow route add -X POST /echo -c 'request /body | response /body' -``` - -then, you must execute: - -```bash -kapow server echo.pow -``` - -and you can check that it works as intended with good ole `curl`: - -```bash -curl -X POST -d '1,2,3... testing' localhost:8080/echo -``` - - -## The multiline fun - -Unless you're a hardcore Perl hacker, you'll probably need to write your stuff -over more than one line. - -Don't worry, we need to write several lines, too. Bash, in its magnificent -UNIX® style, provides us with the -[here-documents](https://www.gnu.org/software/bash/manual/bash.html#Here-Documents) -mechanism that we can leverage precisely for this purpose. - -Let's write a `multiline.pow` file with the following content: - -```bash -kapow route add /log_and_love - <<- 'EOF' - echo "[$(date)] and stuff" >> stuff.log - echo love | response /body -EOF -``` - -and then we serve it with `kapow`: - -```bash -kapow server multiline.pow -``` - -Yup. As simple as that. - - -# Sample Docker usage - -## Clone the project - -```bash -# clone this project -``` - - -## Build the kapow! docker image - -```bash -docker build -t bbva/kapow:0.1 /path/to/kapow/poc -``` - -## Build a docker image for running the nmap example -```bash -docker build -t kapow-nmap /path/to/kapow/poc/examples/nmap -``` - -## Run kapow -```bash -docker run \ - -it \ - -p 8080:8080 \ - kapow-nmap -``` -which will output something like this: -``` -======== Running on http://0.0.0.0:8080 ======== -(Press CTRL+C to quit) -Route created POST /list/{ip} -ROUTE_8ed01c48_bf23_455a_8186_a1df7ab09e48 -bash-4.4# -``` - - -## Test /list endpoint -In another terminal, try running: -```bash -curl http://localhost:8080/list/github.com -``` -which will respond something like: -``` -Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC -Nmap scan report for github.com (140.82.118.3) -rDNS record for 140.82.118.3: lb-140-82-118-3-ams.github.com -Nmap done: 1 IP address (0 hosts up) scanned in 0.04 seconds - -``` -et voilà ! - -# License - -This project is distributed under the [Apache License 2.0](/LICENSE). +If you want to know more, please follow our [documentation](/doc). diff --git a/doc/readme.rst b/doc/readme.rst new file mode 100644 index 0000000..6f47f80 --- /dev/null +++ b/doc/readme.rst @@ -0,0 +1,189 @@ +What is Kapow! +============== + +Kapow! is an adapter between the world of Pure UNIX® Shell and an HTTP service. + +Some tasks are more convenient in the shell, like cloud interactions, or some +administrative tools. On the other hand, some tasks are more convenient as a +service, like DevSecOps tooling. + +Kapow! lies between these two worlds, making your life easier. Maybe you wonder +about how this kind of magic can happen; if you want to know the nitty-gritty +details, just read our [spec](/spec/). Or, if you want to know how Kapow! can +help you first, let's start with a common situation. + +Think about that awesome command that you use every day, something very +familiar, like ``cloudx storage ls /backups``. Then someone asks you for an +specific backup, so you ``ssh`` into the host, execute your command, possibly +``grepping`` through its output, copy the result and send it back to him. +And that's fine... for the 100 first times. + +Then you decide, let's use an API for this and generate an awesome web server +with it. So, you create a project, manage its dependencies, code the server, +parse the request, learn how to use the API, call the API and deploy it +somewhere. And that's fine... until you find yourself again in the same +situation with another awesome command. + +The awesomeness of UNIX® commands is infinite, so you'll be in this situation +an infinite number of times! Instead, let's put Kapow! into action. + +With Kapow!, when someone asks you for an specific backup (remember your +familiar command?) you just need to create a ``.pow`` file named ``backups.pow`` +that contains: + +.. code-block:: bash + + kapow route add /backups \ + -c 'cloudx storage ls /backups | grep $(request /params/query) | response /body' + +and execute it in the host with the command: + +.. code-block:: bash + + kapow server backups.pow + +and that's it. Done. Do you like it? yes? Then let's start learning a little +more. + + +The mandatory Hello World (for WWW fans) +---------------------------------------- + +First you must create a pow file named ``hello.pow`` with the following contents: + +.. code-block:: bash + + kapow route add /greet -c "echo 'hello world' | response /body" + +then, you must execute: + +.. code-block:: bash + + kapow server hello.pow + +and you can check that it works as intended with good ole' ``curl``: + +.. code-block:: bash + + curl localhost:8080/greet + + +The mandatory Echo (for UNIX fans) +---------------------------------- + +First you must create a pow file named ``echo.pow`` with the following contents: + +.. code-block:: bash + + kapow route add -X POST /echo -c 'request /body | response /body' + +then, you must execute: + +.. code-block:: bash + + kapow server echo.pow + +and you can check that it works as intended with good ole ``curl``: + +.. code-block:: bash + + curl -X POST -d '1,2,3... testing' localhost:8080/echo + + +The multiline fun +----------------- + +Unless you're a hardcore Perl hacker, you'll probably need to write your stuff +over more than one line. + +Don't worry, we need to write several lines, too. Bash, in its magnificent +UNIX® style, provides us with the +`here-documents`_ mechanism that we can leverage precisely for this purpose. + +.. _here-documents: https://www.gnu.org/software/bash/manual/bash.html#Here-Documents + +Let's write a ``multiline.pow`` file with the following content: + +.. code-block:: bash + + kapow route add /log_and_love - <<- 'EOF' + echo "[$(date)] and stuff" >> stuff.log + echo love | response /body + EOF + +and then we serve it with ``kapow``: + +.. code-block:: bash + + kapow server multiline.pow + +Yup. As simple as that. + + +Sample Docker usage +=================== + +Clone the project +----------------- + +.. code-block:: bash + + # clone this project + + +Build the kapow! docker image +----------------------------- + +.. code-block:: bash + + docker build -t bbva/kapow:0.1 /path/to/kapow/poc + +Build a docker image for running the nmap example + +.. code-block:: bash + + docker build -t kapow-nmap /path/to/kapow/poc/examples/nmap + +Run kapow +--------- +.. code-block:: bash + + docker run \ + -it \ + -p 8080:8080 \ + kapow-nmap + +which will output something like this: + +.. code-block:: bash + + ======== Running on http://0.0.0.0:8080 ======== + (Press CTRL+C to quit) + Route created POST /list/{ip} + ROUTE_8ed01c48_bf23_455a_8186_a1df7ab09e48 + bash-4.4# + + +Test /list endpoint +------------------- +In another terminal, try running: + +.. code-block:: bash + + curl http://localhost:8080/list/github.com + +which will respond something like: + +.. code-block:: bash + + Starting Nmap 7.70 ( https://nmap.org ) at 2019-05-10 14:01 UTC + Nmap scan report for github.com (140.82.118.3) + rDNS record for 140.82.118.3: lb-140-82-118-3-ams.github.com + Nmap done: 1 IP address (0 hosts up) scanned in 0.04 seconds + +et voilà ! + +License +======= + +This project is distributed under the [Apache License 2.0](/LICENSE).