OWASP WebSpa Project

From OWASP
(Redirected from OWASP Web Knocking Project)
Jump to: navigation, search
[edit]

OWASP WebSpa Project

The OWASP WebSpa Project is a Java web knocking tool for sending a single HTTP/S request to your web server in order to authorize 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 WebSpa 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 WebSpa 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 WebSpa 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.


What is WebSpa?

OWASP WebSpa 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

http://sourceforge.net/projects/webspa/



Quick Download

Classifications

Owasp-incubator-trans-85.png Owasp-builders-small.png
Owasp-defenders-small.png
Cc-button-y-sa-small.png
Project Type Files CODE.jpg

OWASP Web Knocking Project Demo
OWASP Web Knocking Project Demo
OWASP Web Knocking Project Demo
OWASP Web Knocking Project Demo

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
___________________________________________________________
#  O/S Command                     Last Executed            
-----------------------------------------------------------
___________________________________________________________
=[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>

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
___________________________________________________________
#  O/S Command                     Last Executed            
-----------------------------------------------------------
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>

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>

Can one deploy WebSpa over HTTP?
Yes, WebSpa can be deployed over HTTP, however for security reasons it is highly recommended to utilize HTTPS.
How to report a WebSpa bug?
To report a WebSpa bug please feel free to create a ticket on the sourceforge.net. A sourceforge account is necessary. If you don’t own a sourceforge account you may send an e-mail to one of the contributors.

The OWASP WebSpa 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 - Inception & Development
  • Patryk Arciszewski - Theoretician & Documentation
  • Paweł Goleń - Breaking & Infrastructure
  • Oliver Merki - Leader & Operations


Retired contributors:

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 WebSpa 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 INFO
What does this OWASP project offer you?
RELEASE(S) INFO
What releases are available for this project?
what is this project?
Name: OWASP WebSpa Project
Purpose: 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.
License: GNU GPL_v3
who is working on this project?
Project Leader(s):
  • Oliver Merki @
how can you learn more?
Project Pamphlet: Not Yet Created
Project Presentation:
Mailing list: Mailing List Archives
Project Roadmap: View
Key Contacts
  • Contact Oliver Merki @ to contribute to this project
  • Contact Oliver Merki @ to review or sponsor this project
  • Contact the GPC to report a problem or concern about this project or to update information.
current release
WebSpa v0.6
last reviewed release
Not Yet Reviewed


other releases