Module: IPAccess

Defined in:: lib/ipaccess/core.rb,
lib/ipaccess/ip_access_set.rb,
lib/ipaccess/ip_access_list.rb,
lib/ipaccess/ip_access_check.rb,
lib/ipaccess/patches/generic.rb

Overview

This module contains classes that are used to control IP access. There are three major components you may want to use:

IPAccess::List class

This class lets you create IP access list with blacklisted and whitelisted elements. It also has methods for checking whether given IP matches the list.

IPAccess::Set class

This class contains two objects that are instances of IPAccess::List class. It allows you to create so called access set. The access set contains members named input and output. All methods that validate IP access do it against one of the lists. Input access list is for incomming and output for outgoing IP traffic. In case of connection-oriented sockets and other network objects the convention is to use output access list to validate connections that we initiate. The incomming traffic in that model means the connections initiated by a remote peer.

Patching engine

IPAccess was initialy considered as a set of classes that you may use in your own programs to control IP access. That means your own classes used for communication should use access lists or sets before making any real connections or sending any datagrams.

Fortunately there are many network classes, including sockets, that Ruby ships with. It would be waste of resources to not modify them to support IP access control and automagically throw exceptions when access should be denied.

And here the special module method called IPAccess.arm comes in. It lets you patch most of Ruby’s networking classes and objects. Besides equipping them in IPAccess::Set instance it also adds some methods for doing quick checks and changes in access lists.

The patching engine can arm network classes and single network objects. It is not loaded by default since you may not want extra code attached to a program that uses access lists or sets with own access checking code.

Variants of popular classes

Sometimes you want to write a code that uses standard Ruby’s network objects but you find it dirty to alter classes or objects. In that case you may want to use static variants of Ruby’s network classes that are not patches but derived classes.

Exceptions

When you are dealing with patched (armed) versions of classes and objects or when you are using special variants of popular network classes, you have to rely on exceptions as the only way for access checking methods to tell your program that an event (like access denied) happened.

Note that when exception is thrown the communication session is closed in case of connection-oriented network objects. You may change it by setting opened_on_deny attribute to true.

See IPAccess::Set#check_in to know more about tracking original network object that caused exception to happend. Note that in case of armed versions of network classes (or access-contolled variants) an information about original network object stored within an exception will be set to nil if access had been denied before object was initialized. This shouldn’t happend often, since access checks are lazy (they are performed only when connection is going to be made).

See IPAccessDenied for more information about what you can do with exceptions.

Sockets in armed network objects

Specialized Ruby’s network classes, such as Net::HTTP or Net::Telnet and their variants created by this library, make use of socket objects. For example Net::HTTP class uses TCPSocket instance to create TCP connection. When versions of these Net:: objects with enabled access control are used then the internal routines of IPAccess will also try to patch underlying sockets and assign to them the same access set that is used by main object. It is done to avoid access leaks. However, such armed internal sockets will have opened_on_deny flag switched on since closing session (and an eventual connection) should be settled by main object.

Ordination of elements

To properly understand what are the most important structures mentioned above it’s worth to look at the diagram:

Usage

Handling access sets and access lists

If you need just IP access lists that you will handle in your own way you may want to use two classes:

IPAccess::Set to maintain access sets (containing input and output access lists),
IPAccess::List to maintain single access list.

Using socket classes

If you want standard sockets to have access control enabled you may want to use:

IPAccess::Socket (or issue IPAccess.arm Socket)
IPAccess::TCPSocket (or issue IPAccess.arm TCPSocket)
IPAccess::UDPSocket (or issue IPAccess.arm UDPSocket)
IPAccess::SOCKSocket (or issue IPAccess.arm SOCKSocket)
IPAccess::TCPServer (or issue IPAccess.arm TCPServer)

Before using any of them you must issue:

require 'ipaccess/socket'

Using the IPAccess.arm causes standard socket class to be altered, while IPAccess:: classes are just new variants of socket handling classes.

Using other supported network classes

If you want some working objects to have access control enabled you may want to use:

IPAccess::Net::Telnet (or issue IPAccess.arm Net::Telnet)
IPAccess::Net::HTTP (or issue IPAccess.arm Net::HTTP)
IPAccess::Net::FTP (or issue IPAccess.arm Net::FTP)
IPAccess::Net::POP3 (or issue IPAccess.arm Net::POP3)
IPAccess::Net::IMAP (or issue IPAccess.arm Net::IMAP)
IPAccess::Net::SMTP (or issue IPAccess.arm Net::SMTP)

Using single network objects

If you want to enable access control for single network object from the list shown above you may issue:

require 'ipaccess/net/http'
obj = Net::HTTP.new(host, port)
IPAccess.arm obj

require 'ipaccess/socket'
socket = IPAccess::TCPServer.new(31337)
IPAccess.arm socket

..and so on.

Structures

IP addresses used by the classes are internaly and interfacialy represented by NetAddr::CIDR objects (NetAddr::CIDRv4 and NetAddr::CIDRv6). Due to performance reasons any access list internally is represented as a tree (slightly modified NetAddr::Tree) with special tags assigning rules to virtual lists.

Relations

Here is a diagram which shows relations between the IPAccess::TCPSocket class and other classes from this module:

Defined Under Namespace

Modules: Net, Patches Classes: List, SOCKSSocket, Set, Socket, TCPServer, TCPSocket, UDPSocket

Class Method Summary collapse

.arm(*args) ⇒ Object

This special method patches Ruby’s standard library classes and enables IP access control for them.
.to_cidr(*addresses) ⇒ Object

This method calls IPAccess.to_cidrs and returns first obtained entry containing single IP address with mask (NetAddr::CIDR).
.to_cidrs(*addresses) ⇒ Object

This method converts names to NetAddr::CIDR objects.
.valid_acl?(obj) ⇒ Boolean

This method returns true if the given object can be used to initialize ACL.

Class Method Details

.arm(klass, acl = nil) ⇒ `Object` .arm(klass, : opened_on_deny) ⇒ `Object` .arm(klass, acl, : opened_on_deny) ⇒ `Object`

This special method patches Ruby’s standard library classes and enables IP access control for them. Instances of such altered classes will be equipped with member called acl, which is a kind of IPAccess::Set and allows you to manipulate access rules. It is also able to patch single instance of supported classes.

This method returns object that has been patched.

Supported classes

Currently supported classes are:

– Socket, UDPSocket, SOCKSSocket, TCPSocket, TCPServer,
– Net::HTTP,
– Net::Telnet,
– Net::FTP,
– Net::POP3,
– Net::IMAP,
– Net::SMTP.

Patching classes

Passed argument may be a class object, a string representation of a class object or a symbol representing a class object.

Patching single instances

Passed argument may be an instance of supported class. It’s possible to pass second, optional argument, which should be an initial access set. If this argument is omited then IPAccess::Set.Global is used. If :opened_on_deny is passed then any connection remains opened in case of IPAccessDenied exception during arming.

Patching Ruby’s sockets

To quickly patch all Ruby’s socket classes you may pass symbol :sockets as an argument.

Examples

Example 1 – sockets

require 'ipaccess/socket'                               # load sockets subsystem and IPAccess.arm method

IPAccess.arm TCPSocket                                  # arm TCPSocket class  
IPAccess::Set::Global.output.blacklist 'randomseed.pl'  # add host to black list of the global set
TCPSocket.new('randomseed.pl', 80)                      # try to connect

Example 2 – HTTP

require 'ipaccess/net/http'                             # load net/http subsystem and IPAccess.arm method

IPAccess.arm Net::HTTP                                  # arm TCPSocket class  
IPAccess::Set::Global.output.blacklist 'randomseed.pl'  # add host to black list of the global set
Net::HTTP.get_print('randomseed.pl', '/i.html')         # try to connect

Example 3 – single network object

require 'ipaccess/net/telnet'                           # load Net::Telnet version and IPAccess.arm method

opts = {}
opts["Host"]  = 'randomseed.pl'
opts["Port"]  = '80'

t = Net::Telnet.new(opts)                               # try to connect to remote host

acl = IPAccess::Set.new                                 # create custom access set
acl.output.blacklist 'randomseed.pl'                    # blacklist host
IPAccess.arm t, acl                                     # arm Telnet object and pass optional ACL

# File 'lib/ipaccess/patches/generic.rb', line 154

def self.arm(*args)
  cod = args.delete(:opened_on_deny).nil?
  klass, acl = *args
  singleton_obj = nil
  if klass.is_a?(Class)                                 # regular class
    klass_name = klass.name
  elsif klass.is_a?(Symbol) || klass.is_a?(String)
    klass_name = klass.to_s
    if klass.name.downcase == "sockets"                 # just a bunch of sockets
      require 'ipaccess/arm_sockets'
      return
    else                                                # regular class as a string or symbol
      klass = Kernel
      klass_name.to_s.split('::').each { |k| klass = klass.const_get(k) }
    end
  else                                                  # regular object (will patch singleton of this object)
    klass_name = klass.class.name
    singleton_obj = klass
    klass = (class <<klass; self; end)
  end
  begin
    patch_klass = IPAccess::Patches
    klass_name.split('::').each { |k| patch_klass = patch_klass.const_get(k, false) }
  rescue NameError
    raise ArgumentError, "Cannot enable IP access control for class #{klass_name}"
  end
  klass.__send__(:include, patch_klass)
  singleton_obj.__send__(:__ipa_singleton_hook, acl, cod) unless singleton_obj.nil?  # early initial check
  return klass
end

.to_cidr(*addresses) ⇒ `Object`

This method calls IPAccess.to_cidrs and returns first obtained entry containing single IP address with mask (NetAddr::CIDR).

# File 'lib/ipaccess/core.rb', line 518

def self.to_cidr(*addresses)
  r = self.to_cidrs(*addresses)
  return r.respond_to?(:first) ? first : r
end

.to_cidrs(*addresses) ⇒ `Object`

This method converts names to NetAddr::CIDR objects. It returns an array of CIDR objects.

Allowed input are strings (DNS names or IP addresses optionally with masks), numbers (IP addresses representation), IPSocket objects, URI objects, IPAddr objects, Net::HTTP objects, IPAddrList objects, NetAddr::CIDR objects, NetAddr::Tree objects, IPAccess::List objects, symbols, objects that contain file descriptors bound to sockets (including OpenSSL sockets) and arrays of these.

In case of resolving the IPv6 link-local addresses zone index is removed. In case of DNS names there may occur Resolv::ResolvError exception. If there is an object that cannot be converted the ArgumentError exception is raised.

When an argument called :include_origins is present then the method will attach original converted objects to results as the :Origin tag of CIDR objects (tag[:Origin]). This rule applies only to single objects or objects inside of arrays or sets. Objects that are kind of NetAddr::CIDR, IPAccess::Set, NetAddr::Tree and arrays will never be set as originators.

Examples

to_cidrs("127.0.0.1")                      # uses the IP address
to_cidrs(2130706433)                       # uses numeric representation of 127.0.0.1
to_cidrs(:private, "localhost")            # uses special symbol and DNS hostname
to_cidrs(:private, :localhost)             # uses special symbols
to_cidrs [:private, :auto]                 # other way to write the above
to_cidrs "10.0.0.0/8"                      # uses masked IP address
to_cidrs "10.0.0.0/255.0.0.0"              # uses masked IP address
to_cidrs IPSocket.new("www.pl", 80)        # uses the socket
to_cidrs IPAddr("10.0.0.1")                # uses IPAddr object
to_cidrs NetAddr::CIDR.create("10.0.0.1")  # uses NetAddr object
to_cidrs URI('http://www.pl/')             # uses URI
to_cidrs 'http://www.pl/'                  # uses the extracted host string
to_cidrs 'somehost.xx'                     # uses the host string (fetches ALL addresses from DNS)
to_cidrs 'somehost.xx/16'                  # uses the host string and a netmask

Special symbols

When symbol is passed to this method it tries to find out if it has special meaning. That allows you to create access rules in an easy way. For most of them you may also specify IP protocol version using ipv4_ or ipv6_ prefix.

Known symbols are:

:all (:any, :anyone, :world, :internet, :net, :everything, :everyone, :everybody, :anybody)