Project

firewool

0.02
Repository is archived
No commit activity in last 3 years
No release in over 3 years
Firewool blocks and allows IPs to your controller actions.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

>= 0.7.0
 Project Readme

Firewool¶ ↑

abandoned See (rack-attack) for a nice alternative with more features.

Firewool is an IP firewall for Rails. You set what IPs to block and what IPs to allow. Specifics below.

Why would I need this?¶ ↑

Using authentication to protect your app is great but sometimes you just want to do some simple IP filtering. Firewool can help you in the following use cases:

  • You have a report job that needs to hit /users/report and you want to restrict access without authentication, ie: you don’t want to create a “report” user which might get reported on or otherwise makes you a sad panda.

  • A simple firewall with IP/ports (layer 3) can’t protect rails URLs.

  • A layer 7 firewall which can protect URLs is too expensive / hard to set up.

  • Belt and suspenders style double security check.

  • You killed your network guy and no one knows.

Install¶ ↑

gem install firewool

  • Tested on Rails 3.0.4.

  • Tested on Ruby 1.9.2 / 1.8.7.

  • Untested on Rails 2.x. Probably won’t work because no engines.

Configuration¶ ↑

Add firewool dependency to Gemfile:

gem 'firewool'

Create a configuration file in config/firewool.yml

# config/firewool.yml
# changing any values requires app server restart (Apache/Webrick/etc..)

development:
  ip_restriction: true
  allow: [ 127.0.0.1 ]

test:
  ip_restriction: false

production:
  ip_restriction: true
  allow: [ 1.1.0.0/16, 1.2.0.0/16, 1.3.0.0/16 ]
  deny:  [ 10.50.0.0/16 ]

Add these lines to the controller you want to protect:

class DummyController < ApplicationController
  include Firewool
  acts_as_firewalled
  before_filter :ip_filter

Optionally, you can just filter certain actions like any filter:

before_filter :ip_filter, :only => [:admin, :secret]

About¶ ↑

Firewool has an implicit deny by default. This means that Firewool does the following evaluation:

Deny first
Allow all in allow list
Deny all in deny list

This allows you to have security by default, a whitelist and then exceptions to that whitelist. However, sometimes you want a default allow and only exceptions to that rule. In that case, use an allow with 0.0.0.0 like this:

allow: [ 0.0.0.0 ]
deny:  [ whatever ]

So then firewool will do allow -> deny.

IPs can be spoofed so in the case of strong security, you’ll want to use this with one or more factor authentication.

Quick Network Primer¶ ↑

So how do I write the rules when I’m not a network guy? No problem, let’s go through some examples.

First, the IP address is four numbers separated by periods. Each number is called an octet. The slash number (like /16 up above) is how many bits match. So to match every usable IP from 10.0.0.1 to 10.0.0.254, we can just say: 10.0.0.0/24 instead of naming all 253 IPs one at a time.

10.0.0.0/24 matches 10.0.0.* so the following happens:

10.0.0.1      (match)
10.0.0.204    (match)
10.0.1.1      (no match)
 7.8.9.10     (no match)

If we just want to match one IP address we can use the /32 or just specify the IP address by itself.

192.168.0.1/32  (matches only 192.168.0.1)

Some more examples:

192.168.0.1     (matches only 192.168.0.1, same meaning as /32)
5.0.0.0/8       (matches 5.*.*.*)
5.6.0.0/16      (matches 5.6.*.*)
5.6.0.0/24      (matches 5.6.0.*)
5.6.7.0/24      (matches 5.6.7.*)

These are the simplest examples of this notation (called CIDR if you want to read more) but it’s enough to build a few use cases. Let’s say we want to allow our customers in but block anyone coming from Evil Hackers’ Inc. Our customer’s external network is 5.6.7.* (ie: what they see when they go to whatismyip.com) and let’s say that Evil Hackers’ proxy is 58.14.0.0. This would be our config/firewool.yml:

production:
  ip_restriction: true
  allow: [ 5.6.7.0/24 ]
  deny:  [ 58.14.0.0/16 ]

Now we’d want to be careful that 5.6.7.* was really where our users are coming from. If another group of people that we want to keep out are coming from 5.6.7.200 then we’d want to tighten up our rule a little bit and not allow all of the 5.6.7.* network in because .200 is in 5.6.7.*. So we would research what our customer’s IP block really is, or add only the IPs we know about as individual IPs.

As a special case, 0.0.0.0 means ..., or all IPs. Also a special case, 127.0.0.1 means localhost which is good to leave in your development allow section so you can develop your app with firewool on.

Pretty Up¶ ↑

If 403.html doesn’t exist in your public directory, then a blocked user will simply see “Public Access Denied.” which isn’t that great. Create a 403.html file in public, you can use this 403.html template as an example.

Thanks to¶ ↑

Bluemonk for his awesome ipaddress gem. And sinisterchipmunk for his help in understanding how to test Rails 3 gems quickly.