Introduction

This repository contains configuration, build scripts, and web UI for the OpenWireless router firmware, which is based off of Cerowrt and OpenWRT.

More details about the OpenWireless project can be found at https://openwireless.org/.

HOPE

Special for the weekend of the HOPE Conference, July 18-20, we have set up several instances of the web UI to be publicly accessible. Please try out one of these instances and report to us any vulnerabilities you find. Feel free to set and admin password: These instances will reset at the top of each hour.

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

Also, if you are at the Hotel Pennsylvania, we will occasionally have the routers running. If you see the networks "openwireless.org" or "Hack Open Wireless", you have our permission to connect to them and try to break in. Let us know what you find! The WPA2 passphrase for "Hack Open Wireless" is "Happy ownage, pentest enthusiasts".

Getting Started

Get the packages you need and install a git hook to run tests before push:

./install-dev-dependencies.sh

Try out the web UI locally:

./local-lighttpd/run-local-lighttpd.sh
firefox http://localhost:8888/

Sync the web UI to your router:

./sendAppToRouter --continuous
firefox http://gw.home.lan/

Running tests

./run-tests.sh

Continuous build at https://snap-ci.com/EFForg/OpenWireless/branch/master

UX Starter Kit

To contribute to UX components, please read the introduction to OpenWireless's UX philosophy at EFForg#81.

Security

There's a detailed writeup of our threats and mitigations in security.txt.

System Overview

The Open Wireless router firmware is built on top of CeroWRT, with some modifications to the firewall and services configs for better security and usability with guest networks. The web administration UI is unique to Open Wireless, and consists of an HTML + JS frontend calling a Python backend with a loosely JSONRPC-esque protocol. The frontend is under app/, and the backend is under routerapi/. We use Handlebars (similar to Mustache) for templating on the client side.

The CeroWRT code can be found in a submodule. To check out the CeroWRT code, run git submodule init / git submodule update. The build config used for OpenWireless is in OWrt/config-OWrt, and should be copied to cerowrt/.config to build.

Contributing and getting help

We welcome contributors! Our mailing list is [email protected]. Sign up at https://openwireless.org/mailman/listinfo/tech. Or drop into #openwireless on irc.oftc.net to ask questions or discuss the project.

We accept pull requests and issues on https://github.com/EFForg/OpenWireless or patches by mail to [email protected]

Coding Style

Two spaces for JavaScript, four for Python, no tabs. Spaces between function arguments, before braces, and around operators. In Python, imports are one per line, and only modules, not methods or classes. Generally we follow the Google Python Style Guide and Google JavaScript style guide. Try to write tests and document code well.

Some security guidelines: Strongly avoid jQuery's .html(data) and Handlebars' triple-stache {{{data}}}}. They make it easy to create an XSS vulnerability by accident. Similarly, in Python, never set shell=True when calling binaries.

Failsafe and recovery

If something is broken on the router, often you can fix it with failsafe mode. Mostly the standard OpenWRT directions apply. However, the Open Wireless firmware uses 172.30.42.1 by default, so make sure to modify the instructions to contact that address instead of 192.168.1.1.

To enter failsafe mode, reboot the router and press one of the front buttons repeatedly. The power LED will be solid, then slow blinking, then fast blinking. Once it's fast blinking, the router is in failsafe mode. Plug in an ethernet cable and run, on your host machine:

sudo service networking stop
ifconfig eth0 172.30.42.2
route add default gw 172.30.42.1
telnet 172.30.42.1

This should get you a root shell on the machine. From there, if you need to modify files, you can run:

# mount_root

To copy files over, you'll need to start the ssh service, which you can do by starting dropbear.

You will need to set a password for the root account for which you can run:

#passwd

Then start the ssh service with:

#dropbear

and e.g. copy a new image over to the /tmp directory with:

scp image_sysupgrade.bin [email protected]:/tmp

and then e.g. login to the router to reflash the router with:

sysupgrade -v /tmp/image_sysupgrade.bin

If the router does start up in failsafe mode, you can open it up and attach a serial cable to the motherboard during boot to further debug.