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

Fix some typos in 'The Project' section

Browse Source
This commit is contained in:
Héctor Hurtado
2019-11-27 08:53:41 +01:00
parent 530fad17c9
commit 4f2c8f3468
2 changed files with 123 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/index.rst
+20 -9
View File
@@ -12,34 +12,45 @@ Welcome to Kapow!
**If you can script it, you can HTTP it** **If you can script it, you can HTTP it**
What's Kapow! 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 .. image:: _static/kapow-quick-overview.png
:width: 80% :width: 80%
:align: center :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 Authors
======= =======
**Kapow!** is being developed by `BBVA-Labs Security team members <https://github.com/BBVA/kapow/blob/master/AUTHORS.rst>`_. **Kapow!** is being developed by
`BBVA-Labs Security team members <https://github.com/BBVA/kapow/blob/master/AUTHORS.rst>`_.
License License
======= =======
**Kapow!** is Open Source Software and available under the `Apache 2 license <https://raw.githubusercontent.com/BBVA/kapow/master/LICENSE>`_. **Kapow!** is Open Source Software and available under the
`Apache 2 license <https://raw.githubusercontent.com/BBVA/kapow/master/LICENSE>`_.
Contributions Contributions
============= =============
Contributions are of course welcome. See `CONTRIBUTING <https://raw.githubusercontent.com/BBVA/kapow/blob/master/CONTRIBUTING.rst>`_ or skim existing tickets to see where you could help out. Contributions are of course welcome. See
`CONTRIBUTING <https://github.com/BBVA/kapow/blob/master/CONTRIBUTING.rst>`_
or skim existing tickets to see where you could help out.
Table of content
Table of Contents
================ ================
.. toctree:: .. toctree::
docs/source/the_project/quickstart.rst
+103 -67
View File
@@ -1,135 +1,171 @@
Quick start 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 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: .. _quickstart_image:
.. image:: /_static/network.png .. image:: /_static/network.png
:align: center :align: center
:width: 80% :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. 1. We **don't want** to **grant access** to the :samp:`External Host` to
2. We **don't want** to manage VPNs or any similar solutions to access to *Internal Host* from the Internet. anybody.
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. 2. We **don't want** to manage VPNs or any similar solutions to access to
4. We **want** the most standard way mechanism. Easy to use and that facilitates the automation. *Internal Host* from the Internet.
5. We **don't have budget** to invest in a custom solution. 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) Conclusion: **Not a very good idea**
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)
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!) 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**. 1. Kapow! is Open Source, so **it's free**.
2. By using kapow! we don't need to program our own solution. Them: **don't waste time**. 2. By using kapow! we don't need to program our own solution, so
3. By using Kapow! we can run any command in the :samp:`External Host` limiting the command parameters. Them: **it's safe**. **don't waste time**.
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`** 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! Using Kapow!
------------ ------------
Following the example of the :ref:`Scenario <quickstart_image>` we'll follow these steps: In order to get the :ref:`Scenario <quickstart_image>` example working we need
to follow these steps:
Install Kapow! Install Kapow!
++++++++++++++ ++++++++++++++
Follow :doc:`Install Kapow! <install_and_configure>`. Follow :doc:`Install Kapow! <install_and_configure>` instructions.
Write ping.pow file 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 $ cat ping.pow
kapow route add /ping -c 'ping -c 1 10.10.10.100 | kapow set /response/body' 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 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 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 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 .. image:: /_static/sequence.png
:align: center :align: center
:width: 80% :width: 80%
As you can see, Kapow! perform the *magic* between system commands and HTTP API. As you can see, Kapow! performs the *magic* between system commands and HTTP
API.