OWASP WebSpa Project
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.
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.
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:
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 firstname.lastname@example.org 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.
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@example.com)
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
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: firstname.lastname@example.org -[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>
- [19 Feb 2015] The source WebSpa code repository has been migrated to GitHub. The compiled releases (.jar) are still made available on SourceForge.
- [17 Feb 2015] WebSpa has a new contributor – Daniel Imber. Dan, welcome to the team!
- [12 Jan 2015] Patryk Arciszewski decided to retire from the project. Patryk, thank you for your good work and may the Power of SPA be with you.
- [23 Nov 2014] Version 0.8 has been released and can now be found in the download section. We are proud to offer a working, stable proof-of-concept of WebSpa.
- [19 Aug 2014] Our project was featured in the OWASP Connector newsletter. (link)
- [07 May 2014] Added four video links in the respective "Video" tab, referencing YouTube
- [24 Apr 2014] Version 0.7 has been release and can now be found in the download section. Also, we welcome Joël to the team.
- [20 Mar 2014] WebSpa has been presented during OWASP London Chapter Meeting
- [16 Mar 2014] WebSpa has a new contributor – Paweł Goleń. Paweł, welcome to the team!
- [14 Mar 2014] Scheduled the deletion of the Google code project, given that downloads require a new account
- [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 now be found in the download section
- [08 Nov 2013] The OWASP Web Knocking Project is created
- Does WebSpa supports older versions of Java?
- No. WebSpa is tested with an up-to-date JRE package, thus to run WebSpa a JRE 1.7 or greater is needed.
Using older versions of Java may lead to unexpected system behaviors.
- What does the ASCII-Art for WebSpa look like?
__ /\ \ __ __ __ __\ \ \____ ____ _____ __ /\ \/\ \/\ \ /'__`\ \ '__`\ _______ /',__\/\ '__`\ /'__`\ \ \ \_/ \_/ \/\ __/\ \ \L\ \/\______\/\__, `\ \ \L\ \/\ \L\.\_ \ \___x___/'\ \____\\ \_,__/\/______/\/\____/\ \ ,__/\ \__/.\_\ \/__//__/ \/____/ \/___/ \/___/ \ \ \/ \/__/\/_/ \ \_\ \/_/
The font is Larry 3D generated here.
- 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.
- Yiannis Pavlosoglou - Inception & Development
- Paweł Goleń - Breaking & Infrastructure
- Joël Rouiller - Development & Optimisation
- Daniel Imber - Development & Refactoring
- Oliver Merki - Leader & Operations
- Markus Maria Miedaner
- Patryk Arciszewski
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, but also offer improved usability features, which will simplify installing, configuring and running WebSpa.. 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 15 Add easy way to run the server as a background daemon
WebSpa_v0.8 is 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 40 Log to /var/log instead of a log.txt file 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) - FIXED: Modified the checking of 2 arrays being equal to be constant in time (Ticket #27) 2 Create maven build task for release
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 they want to connect web servers with untrusted 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)
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
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.
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
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
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?