Fix some typos in 'The Project' section
This commit is contained in:
Héctor Hurtado
+20
-9
@@ -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 <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
|
||||
=======
|
||||
|
||||
**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 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::
|
||||
|
||||
@@ -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 <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!
|
||||
++++++++++++++
|
||||
|
||||
Follow :doc:`Install Kapow! <install_and_configure>`.
|
||||
Follow :doc:`Install Kapow! <install_and_configure>` 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.
|
||||
As you can see, Kapow! performs the *magic* between system commands and HTTP
|
||||
API.
|
||||
|
||||
Reference in New Issue
Block a user