This site is the archived OWASP Foundation Wiki and is no longer accepting Account Requests.
To view the new OWASP Foundation website, please visit https://owasp.org

OWASP WebSpa Project

From OWASP
Revision as of 09:36, 28 September 2014 by Yiannis (talk | contribs) (FAQs: Added 2 questions in the FAQ section of WebSpa)

Jump to: navigation, search

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.

If port knocking is defined as "a form of host-to-host communication in which information flows across closed ports" then we define web knocking as "a form of host-to-host communication in which information flows across erroneous URLs". Finally, in an attempt to mirror the operation of Single Packet Authorisation (SPA), the entirety of a user's action is submitted through a single GET request.

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

WebSpa v0.7

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
Linux Poweroff on Apache via Web Knocking with Web-Spa (_v0.7)
Enabling SSH via Web Knocking with Web-Spa (_v0.5)
Enabling SSH via Web Knocking with Web-Spa (_v0.4 )
Enabling SSH via Web Knocking with Web-Spa (_v0.4)

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 WebSpa 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 WebSpa (_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 [email protected]
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 WebSpa
=================================================
The following programs must be installed in order
for WebSpa 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 ([email protected])
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: [email protected]
-[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>
Who are the actors required in order to use the WebSpa tool?

There are two actors, the WebSpa administrator and the WebSpa user. Ultimately, they could be the same person. The administrator agrees with each user what each of their allowed O/S commands are, while the user, well, executes these commands on the server by using the client.

How does the crypto of WebSpa work?
From the perspective of cryptographic engineering, WebSpa uses a hash commitment scheme, where the commit phase during which a value is chosen is done using an out of band channel. WebSpa focuses on receiving a value specified through a single request from the client and processing it on the 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
  • Joël Rouiller - Development & Optimisation
  • Oliver Merki - Leader & Operations


Retired contributors:

Release 0.9 (Q3/2015)

WebSpa_v0.9 will be major release and include a comprehensive redesign of the WebKnock format in order to improve overall security and robustness of the request. The tickets for this release are:

44	New WebKnock request format should be defined
42	Do not limit the web knock to 100 characters, instead use SHA-512 lengths	 
35	A threat model for WebSpa should be created and reviewed	 
33	Apache should be replaced by nginx	 

Release 0.85 (Q1/2015)

WebSpa_v0.85 will offer improved usability features, which will simplify installing, configuring and running WebSpa. The tickets for this release are:

40	Log to /​var/​log instead of a log.txt file	
15	Add easy way to run the server as a background daemon	  

Release 0.8 (Q4/2014)

WebSpa_v0.8 will be sort of a proof-of-concept of WebSpa. A stable version to demonstrate the concept of WebKnocking, however, with some limitations with regards to usability/configuration and modularity (e.g. changing the hashing algorithm). The tickets for this release are:

43	Change SSL configuration to allow wget
41	WebSpa administrator to WebSpa user output	 
38	umask 077 should be added to webspa.sh	 
32	A known_hosts file should be used to maintain the list of successfully verified keys	 
31	Verification of server's public key fingerprint should be possible	 
30	Help Files Update (0.8)	 
27	Arrays.equals is not a constant time function	 
2	Create maven build task for release	 

Release 0.7 (24/Apr/2014)

This is the current release of WebSpa.

WebSpa _v0.7 offers enhanced user administration functionality. The WebSpa client now offers the possibility for a user to connect to a web server with an untrusted/self-signed certificate.

- NEW: The WebSpa client asks the user if he wants to connect web servers with unknown/untrusted/self-signed certificates. (Ticket #28) 
- NEW: Introduced ‘passwd’ command, which allows the WebSpa administrator to modify a user’s password.
- NEW: Introduced ‘pass-phrase show’ command, which allows the WebSpa administrator to print a user’s pass-phrase to the screen.
- FIXED: Array is no longer sorted, which reduced the entropy of the web-knock. (Ticket #24)
- FIXED: Reworked and added test cases.
- FIXED: Removed dependency on Spring security. (Ticket #18)

Release 0.6 (21/Dec/2013)

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
current release
WebSpa v0.7
last reviewed release
Not Yet Reviewed


other releases