OWASP Web Knocking Project

=Main= The OWASP Web Knocking Project has been renamed the OWASP WebSpa Project. The new project page can be found [here].

{| style="padding: 0;margin:0;margin-top:10px;text-align:left;" |-
 * valign="top" style="border-right: 1px dotted gray;padding-right:25px;" |

OWASP Web Knocking Project
The OWASP Web Knocking Project is a Java web knocking tool for sending a single HTTP/S request to your web server in order to authorise the execution of a premeditated Operating System (O/S) command. It provides a cryptographically protected "open sesame" mechanism on the web application layer, comparable to well-known port-knocking techniques.

Description
This project implements the concept of web knocking by offering a jar file that 'tails' the access log of an existing web server. A user submits a specially crafted URL, therefore executing a predefined O/S command. No new ports or services are created.

Similarly to traditional network port-knocking schemes, the OWASP Web Knocking Project aims to create a covert channel of communication for O/S commands over the web application layer. This channel is by no means bi-directional: It is only the client that can issue commands to the server. The inverse, i.e. the server issuing commands to the client, is not an option within the current version.

Licensing
The OWASP Web Knocking Project is free to use. It is licensed under the http://creativecommons.org/licenses/by-sa/3.0/ Creative Commons Attribution-ShareAlike 3.0 license], so you can copy, distribute and transmit the work, and you can adapt it, and use it commercially, but all provided that you attribute the work and if you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.

The source code that comes with the OWASP Web Knocking Project in the form of the tool named Web-Spa is released as open source software under the terms of the GNU Public License (GPL) version 3. For reference, the full text of the GPL_v3 can be downloaded from the Free Software Foundation. There are no plans to change the license; web-spa will always remain an open source project free for use by anyone subject to the terms of the license.


 * valign="top" style="padding-left:25px;width:200px;border-right: 1px dotted gray;padding-right:25px;" |

What is Web Knocking?
OWASP Web Knocking provides:


 * A secure channel for executing premeditated O/S commands on your web server
 * A resource-efficient single jar-file that can either be run as server, or client application, depending on the command line parameters

Presentation
https://code.google.com/p/web-spa/


 * valign="top" style="padding-left:25px;width:200px;" |

Quick Download

 * http://goo.gl/4T82Ug

Classifications

 * }

= Videos =

= Tutorial =

Supporting Documentation
The discrepant event discussed herein is web knocking. Within the latest download you can find three documents with the purpose of describing how WebSpa can be used. The three documents are:


 * 'WebSpa Administration Guide This document describes how to setup and use the server component. It details how to create new users and add new action numbers with respective O/S commands assigned to them


 * WebSpa Specification Guide This document describes the actual design detailing the use case, specification, requirements and actual attacks, which this tool has been engineered to withstand


 * WebSpa User Guide This document describes how to use the client for issuing commands through a URL request to a web server

The administration guide aims to enable anyone who would be interested in using WebSpa to be able to setup the server side component of it. After configuring the server component of WebSpa, you'll be ready to use the corresponding client for issuing direct actions as O/S commands to it.

If this is your first time using WebSpa, please note that the server operations described in this document, will not work if a WebSpa client does not submit a web-knock to your web server in a timely manner.

Thus, knowing a client implementation goes hand-in-hand with a server instance for it, please also have a look at the WebSpa user guide document to see how the two can be used in tandem.

The user guide aims to enable anyone who would be interested in using web-spa to do so. As soon as you install the server side component and decide what actions to allow, you'll be ready to use the corresponding client for issuing direct actions that work for you.

Finally, the specification guide aims to enable anyone who would be interested in implementing their own version of WebSpa to do so.

HelloWorld! Enabling SSH via Web Knocking with WebSpa
In this section we describe the setup you should follow in order to get to the stage of being able to execute the video entitled: Enabling SSH via Web Knocking with Web-Spa (_v0.5) on your server.

We assume you can SSH into your web server using the user 'web-spa'. We also assume that the user 'web-spa' has permissions to run the necessary service start and stop commands for this service. So, let's login to the box and get the latest WebSpa download:

ssh web-spa@web.spa.seleucus.net web-spa@web:~$ cd /tmp web-spa@web:/tmp$ wget https://downloads.sourceforge.net/project/webspa/webspa-06.zip

It would be wise at this stage to check the SHA1 digest of what we just downloaded. Sourceforge publishes the SHA1 of all files available for download; copying the value into our command prompt yields:

web-spa@web:/tmp$ echo "a630f23f88c49d02b5895a3d7e16aad245c387f3 *webspa-06.zip" | sha1sum -c - webspa-06.zip: OK web-spa@web:/tmp$

Ok, so we have downloaded something that we can vouch for-ish. Let's extract and setup.

unzip webspa-06.zip

A lot of noise comes back from this command. Apologies, different groups have clearly stated they have wanted the source code as well the documentation to be included within the download. Let's have a look at the install file:

================================================= - Prerequisites for web-spa =================================================

The following programs must be installed in order for web-spa to run:

- Java 1.6 or later

If you don't have java installed, consider using the following command:

sudo aptitude install openjdk-7-jre

This will meet the one prerequisite for using WebSpa. As this is a production server, docs and src folders will not be missed. Also, we like to store things in /opt, ergo:

web-spa@web:/tmp$ rm -frv /tmp/web-spa-0.6/src/ web-spa@web:/tmp$ rm -frv /tmp/web-spa-0.6/docs/ web-spa@web:/tmp$ sudo mv -v /tmp/web-spa-0.6/ /opt

We now have WebSpa in /opt, let's run the server and create some users.

web-spa@web:/tmp$ cd /opt/web-spa-0.6/ web-spa@web:/opt/web-spa-0.6$ java -jar web-spa-0.6.jar -server

Web-Spa - Single HTTP/S Request Authorisation version 0.6 (web-spa@seleucus.net)

This is a holding prompt, type "exit" or "x" to quit

- type "service start" to start the web-spa server - type "help" or "?" for more options

web-spa-server>

The last line above is the server's holding prompt; all commands are issued via this prompt. In order to exit this prompt, type 'exit' or 'quit'. In the next step we will add 3 users and assign a unique pass-phrase to each one of them.

web-spa-server>user add =[Required] Enter the New User's Full Name: Yiannis Pavlosoglou =[Required] Enter the New User's Pass-Phrase: =[Required] Re-enter the above value: -[Optional] Please enter the New User's Email Address: yiannis@xxxxxx.com -[Optional] Please enter the New User's Phone Number: web-spa-server>

Please note that only a user's full name and pass-phrase are required to be entered. Let's create another user:

web-spa-server>user add =[Required] Enter the New User's Full Name: Oliver Merki =[Required] Enter the New User's Pass-Phrase: =[Required] Re-enter the above value: -[Optional] Please enter the New User's Email Address: -[Optional] Please enter the New User's Phone Number: web-spa-server>

Note that we did not specify a user's e-mail address nor a phone number, as both these fields were optional. Finally, adding a third user:

web-spa-server>user add =[Required] Enter the New User's Full Name: Patryk =[Required] Enter the New User's Pass-Phrase: =[Required] Re-enter the above value: -[Optional] Please enter the New User's Email Address: -[Optional] Please enter the New User's Phone Number: web-spa-server>

For Patryk we only specified his first name and a unique pass-phrase. You get the picture. Now that we have created our users, let's add some actions to each user. We would like to give Patryk the ability to bounce the SSH service; ergo, let's add two actions:

web-spa-server>action add Users: ___________________________________________________________ ID Active  Full Name               Last Modified --- 11 false   Yiannis Pavlosoglou     2014-02-23 12:09:26.240 12 false   Oliver Merki            2014-02-23 12:12:13.313 13 false   Patryk                  2014-02-23 12:14:57.895 ___________________________________________________________ -[Optional] Select a User ID: 13 The existing actions for this user are: Actions for user with ID: 13 ___________________________________________________________ --- ___________________________________________________________ =[Required] Enter the new O/S Command: sudo service ssh start =[Required] Select an action number for this O/S Command [0,9]: 1 web-spa-server>
 * 1)  O/S Command                     Last Executed

The above adds the O/S command 'sudo service ssh start' to action number 1 for user Patryk. Let's also add the stop command:

web-spa-server>action add Users: ___________________________________________________________ ID Active  Full Name               Last Modified --- 11 false   Yiannis Pavlosoglou     2014-02-23 12:09:26.240 12 false   Oliver Merki            2014-02-23 12:12:13.313 13 false   Patryk                  2014-02-23 12:14:57.895 ___________________________________________________________ -[Optional] Select a User ID: 13 The existing actions for this user are: Actions for user with ID: 13 ___________________________________________________________ --- 1 sudo service ssh start          has never been executed ___________________________________________________________ =[Required] Enter the new O/S Command: sudo service ssh stop =[Required] Select an action number for this O/S Command [0,9]: 0 web-spa-server>
 * 1)  O/S Command                     Last Executed

The above adds the O/S command 'sudo service ssh stop' to action number 0 for user Patryk. Two very important steps we must not forget is to enable the user Patryk and start the web-spa listening service.

web-spa-server>user activate Users: ___________________________________________________________ ID Active  Full Name               Last Modified --- 11 false   Yiannis Pavlosoglou     2014-02-23 12:09:26.240 12 false   Oliver Merki            2014-02-23 12:12:13.313 13 false   Patryk                  2014-02-23 12:14:57.895 ___________________________________________________________ -[Optional] Select a User ID: 13 User with ID: 13 is in-active -[Optional] Toggle user activation [Y/n]: User with ID: 13 is active web-spa-server>

And finally issue the service start command:

web-spa-server>service start [2014-02-23 12-36-07] Attempting to start web-spa... [2014-02-23 12-36-07] Found access log file: /...cus.net/logs/access.log [2014-02-23 12-36-07] Creating tail listener... [2014-02-23 12-36-07] Web-spa server started! [2014-02-23 12-36-07] Please make sure your web server is also up web-spa-server>

= News =


 * [04 Mar 2014] The WebSpa podcast has now been available!
 * [22 Feb 2014] Created the WebSpa project on sourceforge, started the import from google code
 * [22 Dec 2013] Version 0.6 has been released and can be found in the download section
 * [08 Nov 2013] The OWASP Web Knocking Project is created

=FAQs=


 * Q1
 * A1


 * Q2
 * A2

= People =

The OWASP Web Knocking Project is developed by a worldwide team of volunteers. Below is a list of all people that have contributed to the project so far.

Active contributors:
 * Yiannis Pavlosoglou
 * Patryk Arciszewski
 * Oliver Merki

Retired contributors:
 * Markus Maria Miedaner

= Roadmap =

Release 0.9 (Q2-Q3/2014)
WebSpa_v0.9 will examine attacks on the web knocking tool and propose controls in order to address the issues in question.

Release 0.8 (Q2/2014)
WebSpa_v0.8 will incorporate in the server side component (run with -server option) the ability for a web-spa administrator to generate a single output of all actions available for a Web Knocking user.

Release 0.7 (Q1/2014)
This is the next release of web-spa. The next release has not been scheduled yet.

For WebSpa_v0.7, a Java write-up of a number of test cases so that to increase test coverage within the tool. The ability to reset the pass-phrase for a web-spa user will also be added.

Release 0.6 (21/Dec/2013)
This is the current release of web-spa.

WebSpa _v0.6 offers enhanced logging functionality, fixing a bug that caused the server to become unresponsive upon starting and stopping. The client now offers to transmit a web knock request, thus not requiring for a user to copy-paste the URL into their browser.

Additional test cases have been added, the option "?" is now available to offer "help" and the log functionality tracks via means of a timestamp all events logged

Release 0.5 (21/Oct/2013)
WebSpa _v0.5 shortens the number of inputs required from a legitimate user of web-spa to only two: A valid pass-phrase, unique for each user and a single digit in the range of [0-9]. We refer to the latter as an action number and it represents a premeditated Operating System (O/S) command.

All the functionality (for both the client and the server) is now within a single jar file, accompanied by detailed documentation:

- 00-web-spa-administration-guide.pdf - 00-web-spa-specification-guide.pdf - 00-web-spa-user-guide.pdf

The server side functionality has been re-designed to operate with a single configuration file (created at first run) as well as a HyperSQL embedded file database (also created at first run).

Finally, no files are created or are required when web-spa runs in client mode, with the '-client' option.

Release 0.4 (27/Aug/2011)
A number of updates and bug fixes have been included within this version. Also, an update on the actual message format to further protect from replay attacks has been included.

WebSpa _v0.4 contains the necessary client and server components, as well as an elements API library. Thus, the files within the download are: * webspa-client-04.jar * webspa-elements-04.jar * webspa-server-04.jar

Release 0.3 (11/Jul/2011)
In its first usable release, WebSpa _v0.3 contains the necessary client and server components, as well as an elements API library. Thus, the files within the download are: * webspa-client-03.jar * webspa-elements-03.jar * webspa-server-03.jar

Contribution
Involvement in the development and promotion of the OWASP Web Knocking Project is actively encouraged! You do not have to be a security expert in order to contribute. Some of the ways you can help:
 * Quality assurance of resolved defects
 * Java development (good knowledge of Java desirable)

=Project About=