catflap 0.0.2 → 1.0.1

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'catflap'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require 'pry'
+Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/catflap.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'catflap/version'
+
+Gem::Specification.new do |s|
+  s.name = 'catflap'
+  s.version = Catflap::VERSION
+  s.summary = 'Manage NetFilter-based rules to grant port access on-demand ' \
+    'commandline or REST API requests.'
+  s.description = 'A simple solution to provide on-demand service access (e.g.
+  port 80 on webserver), where a more robust and secure VPN solution is not
+  available. Essentially, it is a more user-friendly form of "port knocking".
+  The original proof-of-concept implementation was run for almost three years
+  by Demotix, to protect development and staging servers from search engine
+  crawlers and other unwanted traffic.'
+  s.authors = ['Nyk Cowham']
+  s.email = 'nykcowham@gmail.com'
+  s.homepage = 'https://github.com/nyk/catflap'
+  s.files	= `git ls-files -z`
+    .split("\x0")
+    .reject { |f| f.match(%r{^(test|spec|tasks|features)/}) }
+  s.executables = ['catflap']
+  s.licenses	= ['MIT']
+  s.requirements = 'NetFilters (iptables) installed and working.'
+  s.require_paths = ['lib']
+  s.add_dependency 'json', '>= 1.8.3'
+  s.add_development_dependency 'bundler', '~> 1.11'
+  s.add_development_dependency 'rake', '~> 10.0'
+  s.add_development_dependency 'rspec', '~> 3.0'
+  s.bindir = 'bin'
+end

data/etc/config.yaml

@@ -0,0 +1,30 @@
+# This is an example of the main configuration file for catflap.
+# By default catflap looks for this file in /usr/local/etc/catflap/config.yaml
+# but you can change the location by using the --config-file <filepath> option
+# of the bin/catflap command line interface.
+
+server:
+  listen_addr: '0.0.0.0' # what ip address the catflap server should listen on.
+  port: 8778 # the TCP port that the catflap server listens to.
+  docroot: './ui' # you can override the ui location.
+  endpoint: '/catflap' # the endpoint for the REST API.
+  passfile: './etc/passfile.yaml' # pass phrases are stored here.
+  token_ttl: 15 # expire tokens after 15 seconds.
+  pid_path: '/var/run' # The path where the pid file should be written.
+
+  https:
+    port: 4773 # TCP oport that catflap https server listens to.
+    force: true # Force HTTP requests to redirect to HTTPS.
+    certificate: '' # Path to your SSL certificate file.
+    private_key: '' # Private key for your SSL certificate.
+
+firewall:
+  plugin: 'netfilter' # options are netfilter or iptables
+  dports: '80,443' # lock multiple ports separating them by commas.
+  options: # options are specific to each firewall plugin driver.
+    chain: 'CATFLAP' # Namespace for the chains (e.g. CATFLAP-ALLOW, CATFLAP-DENY).
+    forward:
+      80: 8778
+      443: 4773
+    log_rejected: true
+    accept_local: true # this is set to false only when devs are testing catflap.

data/etc/init.d/catflap

@@ -0,0 +1,89 @@
+### BEGIN INIT INFO
+# Provides:          catflap
+# Default-Start:     2 3 4 5
+# Default-Stop:      0 1 6
+# Short-Description: Catflap daemon to provide API web service.
+# Description:       Provides a means to request and gain access
+#                    to certain restricted ports like 80 and 443
+### END INIT INFO
+
+# Using the lsb functions to perform the operations.
+. /lib/lsb/init-functions
+# Process name ( For display )
+NAME=catflap
+# Daemon name, where is the actual executable
+DAEMON=/usr/local/bin/catflap
+
+# pid file for the daemon
+PIDFILE=/var/run/catflap.pid
+
+# Include catflap defaults if available
+if [ -f /etc/default/catflap ] ; then
+        . /etc/default/catflap
+fi
+
+# If the daemon is not there, then exit.
+test -x $DAEMON || exit 5
+
+case $1 in
+ start)
+  # Checked the PID file exists and check the actual status of process
+  if [ -e $PIDFILE ]; then
+   status_of_proc -p $PIDFILE $DAEMON "$NAME process" && status="0" || status="$?"
+   # If the status is SUCCESS then don't need to start again.
+   if [ $status = "0" ]; then
+    exit # Exit
+   fi
+  fi
+  # Start the daemon.
+  log_daemon_msg "Starting the process" "$NAME"
+  # Start the daemon with the help of start-stop-daemon
+  # Log the message appropriately
+  if start-stop-daemon --start --quiet --oknodo --background --make-pidfile --pidfile $PIDFILE --exec $DAEMON -- $DAEMON_OPTS " start" 2>&1; then
+   log_end_msg 0
+  else
+   log_end_msg 1
+  fi
+  ;;
+ stop)
+  # Stop the daemon.
+  if [ -e $PIDFILE ]; then
+   status_of_proc -p $PIDFILE $DAEMON "Stoppping the $NAME process" && status="0" || status="$?"
+   if [ "$status" = 0 ]; then
+    start-stop-daemon --stop --quiet --oknodo --pidfile $PIDFILE
+    /bin/rm -rf $PIDFILE
+   fi
+  else
+   log_daemon_msg "$NAME process is not running"
+   log_end_msg 0
+  fi
+  ;;
+ restart)
+  # Restart the daemon.
+  $0 stop && sleep 2 && $0 start
+  ;;
+ status)
+  # Check the status of the process.
+  if [ -e $PIDFILE ]; then
+   status_of_proc -p $PIDFILE $DAEMON "$NAME process" && exit 0 || exit $?
+  else
+   log_daemon_msg "$NAME Process is not running"
+   log_end_msg 0
+  fi
+  ;;
+ reload)
+  # Reload the process. Basically sending some signal to a daemon to reload
+  # it configurations.
+  if [ -e $PIDFILE ]; then
+   start-stop-daemon --stop --signal USR1 --quiet --pidfile $PIDFILE --name $NAME
+   log_success_msg "$NAME process reloaded successfully"
+  else
+   log_failure_msg "$PIDFILE does not exists"
+  fi
+  ;;
+ *)
+  # For invalid arguments, print the usage message.
+  echo "Usage: $0 {start|stop|restart|reload|status}"
+  exit 2
+  ;;
+esac

data/etc/passfile.yaml

@@ -0,0 +1,7 @@
+# This is a sample passfile. It is recommened that you use your own
+# pass phrases. A pass phrase must consist of at least two words separated by
+# a space. The first word of the phrase is used as a unique key for efficient
+# lookup of multiple pass phrases.
+passphrases:
+  frisky: 'frisky kitten'
+  peeky: 'peeky blinders'

data/lib/catflap.rb

@@ -1,87 +1,131 @@
+require 'catflap/version'
 require 'yaml'
-require 'ipaddr'
+require 'digest'
 
+##
+# Catflap controller class
+#
+# This class controls the initialization of the configuration file, setting
+# options, initializing the firewall plugin driver and loading pass phrases.
+#
+# @author Nyk Cowham <nykcowham@gmail.com>
 class Catflap
+  # @!attribute noop
+  #   @return [Boolean] true if no operation is to be performed.
+  # @!attribute verbose
+  #   @return [Boolean] true if command output should be written to stdout.
+  # @!attribute [r] fwplugin
+  #   @return [String] the name of the firewall driver plugin file and class.
+  # @!attribute [r] bind_addr
+  #   @return [String] the IP address the Catflap server should listen to.
+  # @!attribute [r] port
+  #   @return [Integer] the port number the Catflap server should listen to.
+  # @!attribute [r] docroot
+  #   @return [String] file path location that HTML/CSS/JS files are located.
+  # @!attribute [r] endpoint
+  #   @return [String] the name of the REST service endpoint (e.g. /catflap).
+  # @!attribute [r] https
+  #   @return [Hash<Symbol, String>] the HTTPS server configuration options.
+  # @!attribute [r] daemonize
+  #   @return [Boolean] true if the web server should run in the background.
+  # @!attribute [r] dports
+  #   @return [String] comma-separated list of ports to guard. (e.g. '80,443').
+  # @!attribute [r] passphrases
+  #   @return [Hash<String, String>] associative array of pass phrases. The
+  #     key is the first word of the pass phrase where words are separated by
+  #     a space or non-alphanumeric character (except for the underscore).
+  # @!attribute [r] passfile
+  #   @return [String] file path of the YAML file containg pass phrases.
+  # @!attribute [r] token_ttl
+  #   @return [Integer] the time-to-live in seconds before tokens expire.
+  # @!attribute [r] pid_path
+  #   @return [String] path/directory where pid file should be written.
+  # @!attribute [r] redirect_url
+  #   @return [String] URL browser should be redirect to after authentication.
+  # @!attribute [r] firewall
+  #   @return [FirewallPlugin]
+  #     a firewall object that is implemented by the firewall driver plugin.
 
-  attr_accessor :config, :chain, :port, :dports, :print, :noop, :log_rejected
+  attr_accessor :verbose, :noop, :daemonize
 
-  def initialize config_file
-    config_file = config_file || '/usr/local/etc/catflap.yaml'
-    @config = {}
-    @config = YAML.load_file config_file if File.readable? config_file
-    @port = @config['server']['port'] || 4777
-    @chain = @config['rules']['chain'] || 'catflap-accept'
-    @dports = @config['rules']['dports'] || '80,443'
-    @print = false
-    @noop = false
-    @log_rejected = true
-  end
+  attr_reader :fwplugin, :listen_addr, :port, :docroot, :endpoint, :dports,
+              :passfile, :passphrases, :token_ttl, :pid_path, :redirect_url,
+              :firewall, :https
 
-  def install_rules!
-    output  = "iptables -N #{@chain}\n" # Create a new user-defined chain as a container for our catflap netfilter rules
-    output << "iptables -A #{@chain} -s 127.0.0.1 -p tcp -m multiport --dports #{@dports} -j ACCEPT\n" # Accept packets to localhost
-    output << "iptables -A INPUT -p tcp -m multiport --dports #{@dports} -j #{@chain}\n" # Jump from INPUT chain to the catflap chain
-    output << "iptables -A INPUT -p tcp -m multiport --dports #{@dports} -j LOG\n" if @log_rejected # Log any rejected packets to /var/log/messages
-    output << "iptables -A INPUT -p tcp -m multiport --dports #{@dports} -j DROP\n" # Drop any other packets to the ports on the INPUT chain
-    execute! output
+  # @param [String, nil] file_path file path of the YAML configuration file.
+  # @param [Boolean] noop set to true to suppress destructive operations.
+  # @param [Boolean] verbose set to true to print operations to stdout stream.
+  # @return [Catflap]
+  def initialize(file_path = nil, noop = false, verbose = false)
+    @noop = noop
+    @verbose = verbose
+    initialize_config(file_path)
+    initialize_firewall_plugin
+    load_passphrases
   end
 
-  def uninstall_rules!
-    output  = "iptables -D INPUT -p tcp -m multiport --dports #{@dports} -j #{@chain}\n" # Remove user-defined chain from INPUT chain
-    output << "iptables -F #{@chain}\n" # Flush the catflap user-defined chain
-    output << "iptables -X #{@chain}\n" # Remove the catflap chain
-    output << "iptables -D INPUT -p tcp -m multiport --dports #{@dports} -j LOG\n" # Remove the logging rule
-    output << "iptables -D INPUT -p tcp -m multiport --dports #{@dports} -j DROP\n" # Remove the packet dropping rule
-    execute! output
-  end
+  # Initialize the configuration options from the YAML configuration file.
+  # @param [String, nil] file_path file path of the YAML configuration file.
+  # @return void
+  def initialize_config(file_path = nil)
+    @config = read_config_file(file_path)
+    alias_server_attributes
 
-  def purge_rules!
-    output = "iptables -F #{@chain}"
-    execute! output
+    @https ||= {}
   end
 
-  def list_rules
-    system "iptables -S #{@chain}"
+  # Alias the server configuration attributes to instance variables.
+  def alias_server_attributes
+    @config['server'].each do |key, value|
+      instance_variable_set('@' + key, value)
+    end
   end
 
-  def check_address ip
-    check_user_input ip
-    return system "iptables -C #{@chain} -s #{ip} -p tcp -m multiport --dports #{@dports} -j ACCEPT\n"
-  end
+  # Find YAML configuration file, load and read it.
+  # @param [String, nil] file_path if one was passed on command line.
+  # @return [Hash] the parsed YAML file as a nested hash.
+  def read_config_file(file_path)
+    # Look for config file in order of precedence.
+    unless file_path
+      ['~/.catflap', '/usr/local/etc/catflap', '/etc/catflap'].each do |path|
+        file = File.expand_path(path + '/config.yaml')
+        if File.readable? file
+          file_path = file
+          break
+        end
+      end
+    end
 
-  def add_address! ip
-    check_user_input ip
-    output = "iptables -I #{@chain} 1 -s #{ip} -p tcp -m multiport --dports #{@dports} -j ACCEPT\n"
-    execute! output
+    YAML.load_file(file_path || './etc/config.yaml')
   end
 
-  def delete_address! ip
-    check_user_input ip
-    output = "iptables -D #{@chain} -s #{ip} -p tcp -m multiport --dports #{@dports} -j ACCEPT\n"
-    execute! output
-  end 
+  # Initialize the firewall plugin driver.
+  # @return [FirewallPlugin] an object of a class inheriting from FirewallPlugin
+  def initialize_firewall_plugin
+    plugin = @config['firewall']['plugin']
+    driver = plugin.capitalize + 'Driver'
+    require_relative "catflap/plugins/firewall/#{plugin}.rb"
+    @firewall =
+      Object.const_get(driver).new(@config, @noop, @verbose)
+  end
 
-  def add_addresses_from_file! filepath
-    if File.readable? filepath
-      output = ""
-      File.open(filepath, "r").each_line do |ip|
-        check_user_input ip
-        output << "iptables -I #{@chain} 1 -s #{ip.chomp} -p tcp -m multiport --dports #{@dports} -j ACCEPT\n"
-      end
-      execute! output
+  # Load the pass phrase YAML file.
+  # @raise [IOError] if the file is missing or not readable.
+  # @return void
+  def load_passphrases
+    if @passfile && File.readable?(@passfile)
+      phrases = YAML.load_file(@passfile)
+      @passphrases = phrases['passphrases']
     else
-      puts "The file #{filepath} is not readable!"
-      exit 1
+      raise IOError, "Cannot read the passfile: #{@passfile}!"
     end
   end
 
-  def execute! output
-    if @print then puts output end
-    system output unless @noop
-  end 
-
-  def check_user_input suspect
-    return IPAddr.new(suspect)
+  # Generates a SHA256 encrypted token based on a passphrase and a timestamp
+  # @param [String] pass the passphrase stored in passfile.
+  # @param [String] timestamp to salt the digest.
+  # @return [String] a token in the form of a SHA256 digest of a string.
+  def generate_token(pass, salt)
+    Digest::SHA256.hexdigest(pass + salt)
   end
-
 end

data/lib/catflap/command.rb

@@ -0,0 +1,102 @@
+require 'catflap'
+require 'catflap/http'
+
+##
+# Command controller class.
+#
+# This class separates the implementation details of the command line
+# interface from the actual interface. This allows for creating custom
+# command tools by directly implementing this class.
+# @author Nyk Cowham <nykcowham@gmail.com>
+class CfCommand
+  include CfWebserver
+
+  # Initialize a new CatflapCli object
+  # @param [Hash<String, String>] options an associative array of options
+  #   read from the configuration file built by Catflap::initialize_config().
+  # @return CatflapCli
+  # @see
+  #   Catflap - options are generated from file: Catflap::initialize_config()
+  def initialize(options)
+    @options = options
+    @cf = Catflap.new(
+      options[:config_file], options[:noop], options[:verbose]
+    )
+    @cf.daemonize = @options[:daemonize]
+  end
+
+  # A handler function to dispatch commands received from the front-end to the
+  # firewall driver class or the Catflap web service.
+  # @param [String] command the command that is to be executed.
+  # @param [String] arg and argument for the command, (e.g. an IP address).
+  # @return void
+  # @raise ArgumentError when a required command argument is missing.
+  # @raise NameError when the command is not recognized.
+  def dispatch_commands(command, arg)
+    # handle commands and options.
+    case command
+    when 'version'
+      "Catflap version #{Catflap::VERSION}"
+    when 'start'
+      server_start(@cf, @options[:https])
+    when 'stop'
+      server_stop(@cf, @options[:https])
+    when 'status'
+      server_status(@cf, @options[:https])
+    when 'restart'
+      begin
+        server_stop(@cf, @options[:https])
+        server_start(@cf, @options[:https])
+      end
+    when 'reload'
+      @cf.load_passphrases
+    when 'purge'
+      @cf.firewall.purge_rules
+    when 'install'
+      @cf.firewall.install_rules
+    when 'uninstall'
+      @cf.firewall.uninstall_rules
+    when 'list'
+      puts @cf.firewall.list_rules
+    when 'grant'
+      raise ArgumentError, 'You must provide a valid IP address' if arg.nil?
+      @cf.firewall.add_address(arg) unless @cf.firewall.check_address(arg)
+    when 'revoke'
+      raise ArgumentError, 'You must provide a valid IP address' if arg.nil?
+      @cf.firewall.delete_address(arg) if @cf.firewall.check_address(arg)
+    when 'check'
+      raise ArgumentError, 'You must provide a valid IP address' unless arg
+      return @cf.firewall.check_address(arg)
+    when 'bulkload'
+      raise ArgumentError, 'You must provide a file path' unless arg
+      add_addresses_from_file(arg)
+    when nil # catflap --version can be run with no command, so that's ok.
+    else
+      raise NameError, "there is no command '#{command}'"
+    end
+  end
+  # rubocop:enable Metrics/CyclomaticComplexity,Metrics/MethodLength
+  # rubocop:enable Metrics/PerceivedComplexity,Metrics/AbcSize
+
+  # Handler function to bulkload IP's to the firewall.
+  #
+  # Checking that the file path points to readable file ensures that we can
+  # safely accept the user-submitted parameter without any additional data
+  # sanitization.
+  # @param [String] filepath path to the bulkload file of IP addresses to add.
+  # @return void
+  # @raise IOError if the file cannot be found or is not readable.
+  #
+  # @note Every IP address in the file is validated to ensure that it resolves
+  #   to a valid IP address.
+  # @see Firewall Firewall::assert_valid_ipaddr(ip)
+  def add_addresses_from_file(filepath)
+    if File.readable? filepath
+      File.open(filepath, 'r').each_line do |ip|
+        @cf.firewall.add_address(ip.chomp)
+      end
+    else
+      raise IOError, "The file #{filepath} is not readable!"
+    end
+  end
+end