diff --git a/docs/source/index.rst b/docs/source/index.rst index 04a6e36..c192226 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,34 +12,45 @@ Welcome to Kapow! **If you can script it, you can HTTP it** + What's Kapow! ============= -Think in that **software** that you need but **only runs as command line**. Kapow! lets you to **wrap it into an HTTP API without write a single line of code**. + Think of that **software** that you need but **only runs as command line**. + Kapow! lets you to **wrap it into an HTTP API without write a single line of + code**. -.. image:: _static/kapow-quick-overview.png - :width: 80% - :align: center + .. image:: _static/kapow-quick-overview.png + :width: 80% + :align: center + + Want to know more? Check the :doc:`the_project/quickstart` section for a long + explanation of what Kapow! does. -Want to know more? Check the :doc:`the_project/quickstart` section for a long explanation of what Kapow! does. Authors ======= -**Kapow!** is being developed by `BBVA-Labs Security team members `_. + **Kapow!** is being developed by + `BBVA-Labs Security team members `_. + License ======= -**Kapow!** is Open Source Software and available under the `Apache 2 license `_. + **Kapow!** is Open Source Software and available under the + `Apache 2 license `_. Contributions ============= -Contributions are of course welcome. See `CONTRIBUTING `_ or skim existing tickets to see where you could help out. + Contributions are of course welcome. See + `CONTRIBUTING `_ + or skim existing tickets to see where you could help out. -Table of content + +Table of Contents ================ .. toctree:: diff --git a/docs/source/the_project/quickstart.rst b/docs/source/the_project/quickstart.rst index 50a7a27..f863f30 100644 --- a/docs/source/the_project/quickstart.rst +++ b/docs/source/the_project/quickstart.rst @@ -1,135 +1,171 @@ Quick start =========== -We'll explain a simple example to help you understand what Kapow! really does and why it awesome. + We'll explain a simple example to help you understand what Kapow! really does + and why it is awesome. + Scenario -------- -Our this example we'll consider that our scenario is a corporate network like this: + Consider that we're in a corporate network like the following one: -.. _quickstart_image: -.. image:: /_static/network.png - :align: center - :width: 80% + .. _quickstart_image: + .. image:: /_static/network.png + :align: center + :width: 80% -Our organization has an external host as a bridget between our intranet an the public Internet. + Our organization has an external host that act as a bridget between our + intranet an the public Internet. -**Our goal: our team need to check if the the host :samp:`Internal Machine` is alive.** + **Our goal: We need to check if the the ``Internal Host`` is alive.** -Limitations and constrains + +Limitations and constraints -------------------------- -1. We **don't want** to **grant access** to the :samp:`External Host` to anybody. -2. We **don't want** to manage VPNs or any similar solutions to access to *Internal Host* from the Internet. -3. We **want to limit the actions** that an user can perform in our intranet when while it is checking if :samp:`Internal Host` is alive. -4. We **want** the most standard way mechanism. Easy to use and that facilitates the automation. -5. We **don't have budget** to invest in a custom solution. + 1. We **don't want** to **grant access** to the :samp:`External Host` to + anybody. + 2. We **don't want** to manage VPNs or any similar solutions to access to + *Internal Host* from the Internet. + 3. We **want to limit the actions** that an user can perform in our intranet + while it is checking if :samp:`Internal Host` is alive. + 4. We **want** to use the most standard mechanism. Easy to use and that + facilitates the automation. + 5. We **don't have a budget** to invest in a custom solution. -Study options -------------- -Alter analyze the problem and our goal we conclude that is enough **with a simple :samp:`ping` to samp:`Internal Host`.** +What options we have? +--------------------- -So, then **we need analyze how to perform the ping.** + Alter analyzyng the problem and our goal we conclude that is enough + **to use a simple ``ping`` to ``Internal Host``.** -Accessing via SSH -+++++++++++++++++ + So, the next step is to **analyze how to perform the ping.** -In this case we need to create a system user in samp:`External Host` for each user that needs to check if :samp:`Internal host` is alive and we also need to grant access to each user through :samp:`SSH` to the system. -Conclusion: **Not good idea** +Accessing via SSH to :samp:`External Host` +++++++++++++++++++++++++++++++++++++++++++ -Reasons: + If we choose this option then we need to create a user and grant him access + via :samp:`SSH` to :samp:`External Host` for every person that needs to + check for :samp:`Internal host` status. - 1. We need to manage users (violates our constrains) - 2. We need to access users to system (violates our constrains) - 3. We can't control the :samp:`ping` options the user choice to ping :samp:`Internal Host` (violates our constrains) + Conclusion: **Not a very good idea** -Develop custom solution -+++++++++++++++++++++++ + Reasons: -Oks, this approach could maybe be the more customizable for our organization but: + 1. We need to manage users (violates a constraint) + 2. We need to grant access for users to system (violates a constraint) + 3. We can't control what :samp:`ping` options the user can use to ping + :samp:`Internal Host` (violates a constraint) -1. We'll need to start a new project. Develop it, test it, manage it and maintain it. -2. We need time for the development. -3. We need money. Even we have developers in our organization, their time it's not free. -Conclusion: **Not good idea** +Develop and deploy a custom solution +++++++++++++++++++++++++++++++++++++ -Reasons: + Ok, this approach could maybe be the better choice for our organization but: + + 1. We'll need to create a new project, develop, test, manage and maintain it. + 2. We need to wait for for the development to be production ready. + 3. We need a bucket, even we have developers in our organization. + + Conclusion: **Not a good idea** + + Reasons: + + 1. Need to spend money (violates a constraint) + 2. Need to spend time - 1. Need to spend money (violates our constrains) - 2. Need to spend time (violates our constrains) Using Kapow! (Spoiler: the winner!) +++++++++++++++++++++++++++++++++++ -Oks, lets analyze Kapow! and check our constrains: + Ok, lets analyze Kapow! and check it for our constraints: -1. Kapow! is Open Source. Them: **it's free**. -2. By using kapow! we don't need to program our own solution. Them: **don't waste time**. -3. By using Kapow! we can run any command in the :samp:`External Host` limiting the command parameters. Them: **it's safe**. -4. By using Kapow! we can launch any system command as HTTP API easily. Them: **we don't need to grant login access to anybody to :samp:`External Host`** + 1. Kapow! is Open Source, so **it's free**. + 2. By using kapow! we don't need to program our own solution, so + **don't waste time**. + 3. By using Kapow! we can run any command in the :samp:`External Host` + limiting the command parameters, so **it's safe**. + 4. By using Kapow! we can launch any system command as an HTTP API easily, + so **we don't need to grant login access to anybody to ``External Host``** -Conclusion: **Kapow! is the best choice**. + Conclusion: **Kapow! is the best choice**. + + Reasons: It satisfies all of our requirements. -Reasons: it cover all of our requirements. Using Kapow! ------------ -Following the example of the :ref:`Scenario ` we'll follow these steps: + In order to get the :ref:`Scenario ` example working we need + to follow these steps: + Install Kapow! ++++++++++++++ -Follow :doc:`Install Kapow! `. + Follow :doc:`Install Kapow! ` instructions. + Write ping.pow file +++++++++++++++++++ -Kapow! use plain text files to define the rules to expose the system command. For our example we need a file like that: + Kapow! use plain text files (called ``POW`` files) so you can define the + endpoints you want to expose the system command with. For our example we need + a file like this: -.. code-block:: console + .. code-block:: console - $ cat ping.pow - kapow route add /ping -c 'ping -c 1 10.10.10.100 | kapow set /response/body' + $ cat ping.pow + kapow route add /ping -c 'ping -c 1 10.10.10.100 | kapow set /response/body' -Explanation: + Explanation: + + 1. :samp:`kapow route add /ping` - adds a new HTTP API endpoint at + :samp:`/ping` path in the Kapow! server. You have to use GET method to + invoke the endpoint. + 2. :samp:`-c` - after this parameter we write the system command that Kapow! + will run each time the endpint is invoked. + 3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host + *10.10.10.100*, i.e. :samp:`Internal Host`. + 4. :samp:`| kapow set /response/body` - writes the ping output to the + response so you can see it. -1. :samp:`kapow route add /ping` - adds a new HTTP API end-point at :samp:`/ping`. -2. :samp:`-c` - after this parameter we write the system command that Kapow! will runs for each HTTP Request to :samp:`/ping`. -3. :samp:`ping -c 1 10.10.10.100` - sends 1 ping package to the host *10.10.10.100*, i.e. :samp:`Internal Host`. -4. :samp:`| kapow set /response/body` - sends the ping response to be the HTTP Response of HTTP End-point of :samp:`/ping`. Launch the service ++++++++++++++++++ -At this point we only need to launch kapow! with :samp:`simple.pow`: + At this point we only need to launch kapow! with our :samp:`simple.pow`: -.. code-block:: console + .. code-block:: console + + $ kapow server ping.pow - $ kapow server ping.pow Consume the service +++++++++++++++++++ -Then we can call HTTP Service as any usual tool for the web. In this example we'll use :samp:`curl`: + Now we can call our new created endpoint by using our favorite HTTP client. + In this example we're using :samp:`curl`: -.. code-block:: console + .. code-block:: console + + $ curl http://external.host/ping + PING 10.10.100 (10.10.100): 56 data bytes + 64 bytes from 10.10.100: icmp_seq=0 ttl=55 time=1.425 ms - $ curl http://external.host/ping - PING 10.10.100 (10.10.100): 56 data bytes - 64 bytes from 10.10.100: icmp_seq=0 ttl=55 time=1.425 ms Under the hoods ++++++++++++++++ -To understand what's happening in the hoods with Kapow! lets see the picture: + To understand what's happening under the hoods with Kapow! lets see the + picture: -.. image:: /_static/sequence.png - :align: center - :width: 80% + .. image:: /_static/sequence.png + :align: center + :width: 80% -As you can see, Kapow! perform the *magic* between system commands and HTTP API. \ No newline at end of file + As you can see, Kapow! performs the *magic* between system commands and HTTP + API.