catflap 0.0.2 → 1.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,21 @@
+inherit_from: .rubocop_todo.yml
+
+Style/SignalException:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesignalexception
+
+Style/RegexpLiteral:
+  MaxSlashes: 0
+
+Metrics/AbcSize:
+  Max: 50
+
+Metrics/CyclomaticComplexity:
+  Max: 22
+
+Metrics/MethodLength:
+  Max: 42
+
+Metrics/PerceivedComplexity:
+  Max: 12
+

data/.rubocop_todo.yml

@@ -0,0 +1,7 @@
+# This configuration was generated by `rubocop --auto-gen-config`
+# on 2016-02-24 16:27:57 +0700 using RuboCop version 0.27.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at Nicholas.Cowham@corbis.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in catflap.gemspec
+gemspec
+gem 'pry', '~> 0.10.3'
+gem 'yard', '~> 0.8.7.6'
+gem 'redcarpet', '~> 3.3', '>= 3.3.4'

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    catflap (1.0.0)
+      json (>= 1.8.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    json (1.8.3)
+    method_source (0.8.2)
+    pry (0.10.3)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.5.0)
+    redcarpet (3.3.4)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.2)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    slop (3.6.0)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.11)
+  catflap!
+  pry (~> 0.10.3)
+  rake (~> 10.0)
+  redcarpet (~> 3.3, >= 3.3.4)
+  rspec (~> 3.0)
+  yard (~> 0.8.7.6)
+
+BUNDLED WITH
+   1.11.2

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Nyk Cowham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+Catflap
+=======
+![alt catflap](https://raw.githubusercontent.com/nyk/catflap/master/ui/images/catflap.png)
+
+Catflap provides firewall level protection of multiple ports with a password
+protected web gateway to allow developers and/or site demo/stage reviewers to
+request entry after providing valid authentication credentials. Currently Catflap
+supports Linux running the NetFilter (iptables) kernel-level firewall. However,
+firewall specific implementations are provided as firewall plugin drivers and it
+should be possible to write a separate plugin for the ipfw firewall on Mac OSX
+and other FreeBSD derivatives.
+
+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.
+
+# Use Cases
+- Prevent web-bots and spiders from crawling and indexing your development,
+  demo and staging servers. Since they are protected by a firewall there are no
+  back doors.
+- Provide a seamless login to sensitive web backends that may not have their own
+  complete user authentication enabled. One example is Kibana, used as a part of
+  the ELK logging service.
+- Allow non-technical people to request access through a firewall when they do
+  not have a static IP (e.g. from home office) and no access to a VPN.
+- Provides simple to use "port knocking" that does not require any technical
+  knowledge of command line networking from end users.
+
+# Installation
+Catflap is available as a ruby gem and can be installed with:
+
+```
+gem install catflap
+```
+
+You may also want to download the generic Linux init script
+(https://github.com/nyk/catflap/blob/master/etc/init.d/catflap) and place that
+in /etc/init.d/.
+
+# Configuration
+It is advisable to create a configuration file: /usr/local/etc/catflap.yaml
+(this is the default location referenced by the init script, but you can specify
+the location of your configuration file with the --config-file parameter to
+the catflap command line tool.
+
+This configuration file is a YAML file and the default configuration is listed
+below:
+
+```YAML
+server:
+  listen_addr: '0.0.0.0'          # What ip address the catflap server should listen on.
+  port: 4777                      # The TCP port that the catflap server listens on.
+  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 in this file.
+  token_ttl: 15                   # Expire tokens after 15 seconds.
+
+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'              # Two chains will be created <chain>-ALLOW & <chain>-DENY.
+    log_rejected: true            # Enable logging of rejected requests.
+    accept_local: true            # This is only set to false only when developers are testing catflap.
+```
+
+Once your configuration is in place you will then want to install the rules and
+initialize catflap. This can be done with the command line tool:
+
+```
+sudo catflap -f /etc/catflap.yaml install
+```
+
+Catflap has a command line tool that you can use to add or remove addresses from
+the access chain and other household maintenance. Just run 'catflap help' to see
+the available options.
+
+Now you will want to start the service. If you are using the init.d script this
+is easy:
+
+```
+sudo service catflap start
+```
+
+If not you will need to start it with the command line directly (useful for
+testing and debugging issues):
+```
+sudo catflap -f /etc/catflap.yaml start
+```
+
+# Gaining Access
+Addresses and address ranges can be added using the command line with the 'add'
+command, but remote users can request that their current IP address be granted
+access by visiting the URL of the website that is being catflapped with their
+web-browser. Catflap will redirect the target port (e.g. port 80) to the
+Catflap port (e.g. 4777), so they will see the Catflap login screen. Once they
+provide a valid pass phrase, their browser will refresh and they will see the
+target website.
+
+This is the default configuration, provided by the 'netfilter'
+driver, which uses NAT on the firewall to forward the ports. You can use the
+'ipfilter' driver instead, if you want to reject or drop packets rather than
+automatically redirect to the Catflap login. The user would instead have to go
+to the Catflap URL directly. However, the default 'netfilter' driver is
+recommended if you want the best and most seamless end-user experience.
+
+# Security considerations
+Although we have been careful to avoid application level security vulnerabilities,
+such as shell injection attacks, and no web user submitted data is passed to the
+operating system without being sanitized (i.e. IP addresses are validated as being
+valid IP addresses before being sent to the firewall interface), there are still
+some areas of security concern to be aware of:
+- The web service must run with root privileges, at the very least be run sudo
+  as a user with root privileges to add rules to the firewall. Such privileges are
+  unavoidable because the firewall runs in the kernel of the operating system.
+  A future release will separate the firewall execution process from the web
+  server, so the web server will run as an unprivileged user and only the
+  'Executor' process will run with higher privileges on an internal TCP network.
+- The pass phrases in the passfile.yaml file are not encrypted. This file should
+  be placed in a private directory owned by root, chmod 600. If an unauthorized user
+  can read that file, then you have larger security problems than Catflap :)
+- Unless you use SSL encryption it is not easy, but possible, for a network sniffer to capture
+  a valid token and possibly reuse the token to open the port for their own IP
+  address. This risk is very much lessened by the use of timestamps to expire
+  authentication tokens, but there is still some potential risk exposure. That
+  risk is eliminated entirely by encrypting traffic with TLS/SSL.
+- It is recommended to flush the Catflap access rules every day or so (e.g. using
+  a cron job that calls 'sudo catflap purge' command). This is analogous to expiring
+  user login sessions.
+- If you want to revoke access on a particular pass phrase, you must remove the
+  pass phrase from the passfile and ALSO flush the CATFLAP-ALLOW firewall chain, by
+  using the 'catflap purge' command, or remove each IP address with the
+  'catflap revoke <ip>' command.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+Dir.glob('tasks/**/*.rake').each(&method(:import))
+
+task default: :spec

data/bin/catflap

@@ -1,82 +1,89 @@
 #!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 
 require 'optparse'
-require 'catflap'
+require 'catflap/command'
 
+# Parse options
 options = {}
-optparse = OptionParser.new do |opts|
-  opts.separator ""
-  opts.separator "Install/Configure/Service options:"
-  opts.on('-i', '--install', 'Install and initialize the catflap chain') do
-    options['install'] = true
+OptionParser.new do |opts|
+  opts.banner = ''
+  opts.on('-d', '--daemonize', 'Run services as background processes') do
+    options[:daemonize] = true
   end
-  opts.on('-u', '--uninstall', 'Uninstall catflap from iptables') do
-    options['uninstall'] = true
+  opts.on('-f', '--config-file <filepath>', String, 'Use config file' \
+    ' to override default values') do |filepath|
+    options[:config_file] = filepath
   end
-  opts.on('-f', '--config-file <filepath>', String, 'Use config file to override default values') do |filepath|
-    options['config_file'] = filepath
+  opts.on('-V', '--version', 'Display the version of catflap') do
+    options[:version] = true
   end
-  opts.on('-s', '--start-server', 'Start the web api server daemon') do
-    options['start_server'] = true
+  opts.on('-n', '--noop', 'Do not run destructive operations on firewall') do
+    options[:noop] = true
   end
-  opts.separator ""
-  opts.separator "Access rule control options:"
-  opts.on('-c', '--check <ipaddr>', String, 'Check if an IP address has access alreqdy') do |ip|
-    options['check'] = ip
+  opts.on('-s', '--https', 'Use HTTPS/SSL to start or manage service') do
+    options[:https] = true
   end
-  opts.on('-a', '--add <ipaddr>', String, 'IP address to which access should be granted') do |ip|
-    options['add'] = ip
+  opts.on('-v', '--verbose', 'Display additional information to screen') do
+    options[:verbose] = true
   end
-  opts.on('-d', '--delete <ipaddr>', String, 'IP address or range to remove access previously granted') do |ip|
-    options['del'] = ip
-  end
-  opts.on('-F', '--file <filepath>', String, 'Input file of whitelisted IP addresses') do |filepath|
-    options['filepath'] = filepath
-  end
-  opts.on('-x', '--purge', 'Purge all catflap rules from iptables') do
-    options['purge'] = true
-  end
-  opts.on('-l', '--list', 'List catflap access rules') do
-    options['list'] = true
-  end
-  opts.separator ""
-  opts.separator "Output and process options:"
-  opts.on('-n', '--noop', 'Do not run the operation on iptables - no operation') do
-    cf.noop = true
-  end
-  opts.on('-p', '--print', 'Print the iptables generated to screen') do
-    cf.print = true
-  end
-  opts.on('-h', '--help', 'Print this help page.') do 
+  opts.on('-h', '--help', 'Print this help page.') do
+    puts "Usage: catflap <command> [<arg>]\n\n"
+    puts 'Commands:'
+    puts "\tstart \t\t\t Start a catflap server"
+    puts "\tstop \t\t\t Stop a catflap server"
+    puts "\trestart \t\t\t Restart a catflap server"
+    puts "\treload \t\t\t Reload the pass phrases without restarting the server"
+    puts "\tstatus \t\t\t Display the status of a catflap server"
+    puts "\tinstall \t\t Install and initialize the catflap rule chain"
+    puts "\tuninstall \t\t Uninstall catflap rules from firewall"
+    puts "\tcheck <ip> \t\t Check if <ip> already has access"
+    puts "\tgrant <ip> \t\t Add <ip> to allow access"
+    puts "\trevoke <ip> \t\t Remove access for <ip>"
+    puts "\tpurge \t\t\t Remove all catflap managed access grants"
+    puts "\tbulkload <filename> \t Bulk load a list of IPs from file"
+    puts "\tlist \t\t\t Display a list of all catflap managed access grants"
     puts opts
     exit 0
   end
-end.parse! ARGV
+end.parse! ARGV # the options are stripped from ARGV after parsing.
+command, arg = ARGV # destructure what is left into a command and its arguments.
+
+cli = CfCommand.new options
 
 begin
-  cf = Catflap.new options['config_file']
-rescue Psych::SyntaxError
-  puts "There is a YAML syntax error in your catflap configuration file.\n"
-  exit 1
-rescue NoMethodError
-  puts "Cannot read the configuration file (#{options['config_file']}) or default file location: /usr/local/etc/catflap.yaml\n"
-  exit 1
-end
-unless options['start_server']
-  begin
-    cf.purge_rules! if options['purge']
-    cf.install_rules! if options['install']
-    cf.uninstall_rules! if options['uninstall']
-    cf.add_address! options['add'] if options['add']
-    cf.delete_address! options['del'] if options['del']
-    cf.add_addresses_from_file! options['filepath'] if options['filepath']
-    cf.check_address options['check'] if options['check']
-    cf.list_rules if options['list']
-  rescue ArgumentError
-    puts "Invalid Argument: make sure IP address or range is correct (i.e. CIDR format)\n"
+  # pass command and arg to command dispatcher.
+  status = cli.dispatch_commands command, arg
+
+  puts status if command == 'version'
+
+  if command == 'check'
+    if status
+      puts "The ip '#{arg}' has access GRANTED"
+    else
+      puts "The ip '#{arg}' does NOT have access"
+    end
   end
-else
-  require 'catflap-http'
-  CatflapWebserver::start_server cf
-end
 
+  if command == 'status'
+    if status[:pid] > 0
+      puts "Server listening on #{status[:address]}:#{status[:port]}" \
+        " <pid:#{status[:pid].to_s.chomp}>"
+    else
+      puts "Server is not running on #{status[:address]}:#{status[:port]}"
+    end
+  end
+
+rescue Resolv::ResolvError => err
+  warn 'Malformed IP address error: ' << err.message
+rescue Psych::SyntaxError => err
+  warn 'There is a YAML syntax error in your config file: ' << err.message
+rescue ArgumentError => err
+  warn 'Missing argument error: ' << err.message
+rescue IOError => err
+  warn 'File error: ' << err.message
+rescue NameError => err
+  warn 'Command unknown error: ' << err.message
+rescue StandardError => err
+  warn 'There was an error: ' << err.message
+end