bettercap 1.1.10 → 1.2.0

data/lib/bettercap/discovery/{discovery.rb → thread.rb}

@@ -10,18 +10,23 @@ This project is released under the GPL 3 license.
 
 =end
 module BetterCap
-class Discovery
+module Discovery
+# Class responsible to actively discover targets on the network.
+class Thread
+  # Initialize the class using the +ctx+ BetterCap::Context instance.
   def initialize( ctx )
     @ctx     = ctx
     @running = false
     @thread  = nil
   end
 
+  # Start the active network discovery thread.
   def start
     @running = true
-    @thread  = Thread.new { worker }
+    @thread  = ::Thread.new { worker }
   end
 
+  # Stop the active network discovery thread.
   def stop
     @running = false
     if @thread != nil
@@ -39,15 +44,10 @@ class Discovery
     Logger.debug( 'Network discovery thread started.' ) unless @ctx.options.arpcache
 
     while @running
-      empty_list = @ctx.targets.empty?
-
-      if @ctx.options.should_discover_hosts?
-        Logger.info 'Searching for targets ...' if empty_list
-      end
-
+      was_empty = @ctx.targets.empty?
       @ctx.targets = Network.get_alive_targets(@ctx).sort_by { |t| t.sortable_ip }
 
-      if empty_list and not @ctx.targets.empty?
+      if was_empty and not @ctx.targets.empty?
         Logger.info "Collected #{@ctx.targets.size} total targets."
 
         msg = "\n"
@@ -62,3 +62,4 @@ class Discovery
   end
 end
 end
+end

data/lib/bettercap/error.rb

@@ -9,8 +9,7 @@ Blog   : http://www.evilsocket.net/
 This project is released under the GPL 3 license.
 
 =end
-
-# class used to distinghuish between handled and unhandled exceptions
 module BetterCap
+  # Class used to distinghuish between handled and unhandled exceptions.
   class Error < StandardError; end
 end

data/lib/bettercap/factories/{firewall_factory.rb → firewall.rb}

@@ -14,25 +14,29 @@ require 'bettercap/firewalls/osx'
 require 'bettercap/firewalls/linux'
 
 module BetterCap
-class FirewallFactory
+module Factories
+# Factory class responsible of creating the correct object for the current
+# operating system of the user.
+class Firewall
   @@instance = nil
-
-  def self.get_firewall
+  # Save and return an instance of the appropriate BetterCap::Firewalls object.
+  def self.get
     return @@instance unless @@instance.nil?
 
     if RUBY_PLATFORM =~ /darwin/
-      @@instance = OSXFirewall.new
+      @@instance = Firewalls::OSX.new
     elsif RUBY_PLATFORM =~ /linux/
-      @@instance = LinuxFirewall.new
+      @@instance = Firewalls::Linux.new
     else
       raise BetterCap::Error, 'Unsupported operating system'
     end
 
     @@instance
   end
-
-  def FirewallFactory.clear_firewall
+  # Clear the instance of the BetterCap::Firewalls object.
+  def self.clear
     @@instance = nil
   end
 end
 end
+end

data/lib/bettercap/factories/{parser_factory.rb → parser.rb}

@@ -14,10 +14,14 @@ require 'bettercap/error'
 require 'bettercap/logger'
 
 module BetterCap
-class ParserFactory
+module Factories
+# Factory class responsible for listing, parsing and creating BetterCap::Parsers
+# object instances.
+class Parser
   @@path = File.dirname(__FILE__) + '/../sniffer/parsers/'
 
   class << self
+    # Return a list of available parsers.
     def available
       avail = []
       Dir.foreach( @@path ) do |file|
@@ -28,6 +32,8 @@ class ParserFactory
       avail
     end
 
+    # Parse the +v+ command line argument and return a list of parser names.
+    # Will raise BetterCap::Error if one or more parser names are not valid.
     def from_cmdline(v)
       raise BetterCap::Error, "No parser names provided" if v.nil?
 
@@ -39,6 +45,7 @@ class ParserFactory
       list
     end
 
+    # Return a list of BetterCap::Parsers instances by their +parsers+ names.
     def load_by_names(parsers)
       loaded = []
       Dir.foreach( @@path ) do |file|
@@ -48,16 +55,19 @@ class ParserFactory
 
           require_relative "#{@@path}#{file}"
 
-          loaded << Kernel.const_get("BetterCap::#{cname.capitalize}Parser").new
+          loaded << Kernel.const_get("BetterCap::Parsers::#{cname.capitalize}").new
         end
       end
       loaded
     end
 
+    # Load and return an instance of the BetterCap::Parsers::Custom parser
+    # given the +expression+ Regex object.
     def load_custom(expression)
       require_relative "#{@@path}custom.rb"
-      [ BetterCap::CustomParser.new(expression) ]
+      [ BetterCap::Parsers::Custom.new(expression) ]
     end
   end
 end
 end
+end

data/lib/bettercap/factories/{spoofer_factory.rb → spoofer.rb}

@@ -12,18 +12,24 @@ This project is released under the GPL 3 license.
 require 'bettercap/error'
 
 module BetterCap
-class SpooferFactory
+module Factories
+# Factory class responsible for listing, parsing and creating BetterCap::Spoofers
+# object instances.
+class Spoofer
   class << self
+    # Return a list of available spoofers.
     def available
       avail = []
       Dir.foreach( File.dirname(__FILE__) + '/../spoofers/') do |file|
-        if file =~ /.rb/
+        if file =~ /.rb/ and file != 'base.rb'
           avail << file.gsub('.rb','').upcase
         end
       end
       avail
     end
 
+    # Create an instance of a BetterCap::Spoofers object given its +name+.
+    # Will raise a BetterCap::Error if +name+ is not valid.
     def get_by_name(name)
       raise BetterCap::Error, "Invalid spoofer name '#{name}'!" unless available? name
 
@@ -31,7 +37,7 @@ class SpooferFactory
 
       require_relative "../spoofers/#{name}"
 
-      Kernel.const_get("BetterCap::#{name.capitalize}Spoofer").new
+      Kernel.const_get("BetterCap::Spoofers::#{name.capitalize}").new
     end
 
     private
@@ -42,3 +48,4 @@ class SpooferFactory
   end
 end
 end
+end

data/lib/bettercap/firewalls/base.rb

@@ -0,0 +1,76 @@
+=begin
+
+BETTERCAP
+
+Author : Simone 'evilsocket' Margaritelli
+Email  : evilsocket@gmail.com
+Blog   : http://www.evilsocket.net/
+
+This project is released under the GPL 3 license.
+
+=end
+module BetterCap
+module Firewalls
+# Base class for BetterCap::Firewalls objects.
+class Base
+  # Initialize the firewall object.
+  # Raise NotImplementedError
+  def initialize
+    @frwd_initial_state = forwarding_enabled?
+  end
+
+  # If +enabled+ is true will enable packet forwarding, otherwise it will
+  # disable it.
+  # Raise NotImplementedError
+  def enable_forwarding(enabled)
+    not_implemented_method!
+  end
+
+  # If +enabled+ is true will enable icmp_echo_ignore_broadcasts, otherwise it will
+  # disable it.
+  # Raise NotImplementedError
+  def enable_icmp_bcast(enabled)
+    not_implemented_method!
+  end
+
+  # If +enabled+ is true will enable send_redirects, otherwise it will
+  # disable it.
+  # Raise NotImplementedError
+  def enable_send_redirects(enabled)
+    not_implemented_method!
+  end
+
+  # Return true if packet forwarding is currently enabled, otherwise false.
+  # Raise NotImplementedError
+  def forwarding_enabled?
+    not_implemented_method!
+  end
+
+  # Apply the +r+ BetterCap::Firewalls::Redirection port redirection object.
+  # Raise NotImplementedError
+  def add_port_redirection( r )
+    not_implemented_method!
+  end
+
+  # Remove the +r+ BetterCap::Firewalls::Redirection port redirection object.
+  # Raise NotImplementedError
+  def del_port_redirection( r )
+    not_implemented_method!
+  end
+
+  # Restore the system's original packet forwarding state.
+  # Raise NotImplementedError
+  def restore
+    if forwarding_enabled? != @frwd_initial_state
+      enable_forwarding @frwd_initial_state
+    end
+  end
+
+private
+
+  def not_implemented_method!
+    raise NotImplementedError, 'Firewalls::Base: Unimplemented method!'
+  end
+end
+end
+end

data/lib/bettercap/firewalls/linux.rb

@@ -9,43 +9,53 @@ Blog   : http://www.evilsocket.net/
 This project is released under the GPL 3 license.
 
 =end
-require 'bettercap/base/ifirewall'
+require 'bettercap/firewalls/base'
 require 'bettercap/shell'
 
 module BetterCap
-class LinuxFirewall < IFirewall
+module Firewalls
+# Linux firewall class.
+class Linux < Base
+  # If +enabled+ is true will enable packet forwarding, otherwise it will
+  # disable it.
   def enable_forwarding(enabled)
-    shell.execute("echo #{enabled ? 1 : 0} > /proc/sys/net/ipv4/ip_forward")
+    Shell.execute("echo #{enabled ? 1 : 0} > /proc/sys/net/ipv4/ip_forward")
   end
 
+  # Return true if packet forwarding is currently enabled, otherwise false.
   def forwarding_enabled?
-    shell.execute('cat /proc/sys/net/ipv4/ip_forward').strip == '1'
+    Shell.execute('cat /proc/sys/net/ipv4/ip_forward').strip == '1'
   end
 
+  # If +enabled+ is true will enable packet icmp_echo_ignore_broadcasts, otherwise it will
+  # disable it.
   def enable_icmp_bcast(enabled)
-    shell.execute("echo #{enabled ? 0 : 1} > /proc/sys/net/ipv4/icmp_echo_ignore_broadcasts")
+    Shell.execute("echo #{enabled ? 0 : 1} > /proc/sys/net/ipv4/icmp_echo_ignore_broadcasts")
   end
 
+  # If +enabled+ is true will enable send_redirects, otherwise it will
+  # disable it.
+  def enable_send_redirects(enabled)
+    Shell.execute("echo #{enabled ? 0 : 1} > /proc/sys/net/ipv4/conf/all/send_redirects")
+  end
+
+  # Apply the +r+ BetterCap::Firewalls::Redirection port redirection object.
   def add_port_redirection( r )
     # post route
-    shell.execute('iptables -t nat -I POSTROUTING -s 0/0 -j MASQUERADE')
+    Shell.execute('iptables -t nat -I POSTROUTING -s 0/0 -j MASQUERADE')
     # accept all
-    shell.execute('iptables -P FORWARD ACCEPT')
+    Shell.execute('iptables -P FORWARD ACCEPT')
     # add redirection
-    shell.execute("iptables -t nat -A PREROUTING -i #{r.interface} -p #{r.protocol} --dport #{r.src_port} -j DNAT --to #{r.dst_address}:#{r.dst_port}")
+    Shell.execute("iptables -t nat -A PREROUTING -i #{r.interface} -p #{r.protocol} --dport #{r.src_port} -j DNAT --to #{r.dst_address}:#{r.dst_port}")
   end
 
+  # Remove the +r+ BetterCap::Firewalls::Redirection port redirection object.
   def del_port_redirection( r )
     # remove post route
-    shell.execute('iptables -t nat -D POSTROUTING -s 0/0 -j MASQUERADE')
+    Shell.execute('iptables -t nat -D POSTROUTING -s 0/0 -j MASQUERADE')
     # remove redirection
-    shell.execute("iptables -t nat -D PREROUTING -i #{r.interface} -p #{r.protocol} --dport #{r.src_port} -j DNAT --to #{r.dst_address}:#{r.dst_port}")
-  end
-
-  private
-
-  def shell
-    Shell
+    Shell.execute("iptables -t nat -D PREROUTING -i #{r.interface} -p #{r.protocol} --dport #{r.src_port} -j DNAT --to #{r.dst_address}:#{r.dst_port}")
   end
 end
 end
+end

data/lib/bettercap/firewalls/osx.rb

@@ -9,29 +9,42 @@ Blog   : http://www.evilsocket.net/
 This project is released under the GPL 3 license.
 
 =end
-require 'bettercap/base/ifirewall'
+require 'bettercap/firewalls/base'
 require 'bettercap/shell'
 
 module BetterCap
-class OSXFirewall < IFirewall
+module Firewalls
+# OSX Firewall class.
+class OSX < Base
+  # If +enabled+ is true will enable packet forwarding, otherwise it will
+  # disable it.
   def enable_forwarding(enabled)
-    shell.execute("sysctl -w net.inet.ip.forwarding=#{enabled ? 1 : 0}")
+    Shell.execute("sysctl -w net.inet.ip.forwarding=#{enabled ? 1 : 0}")
   end
 
+  # If +enabled+ is true will enable packet icmp_echo_ignore_broadcasts, otherwise it will
+  # disable it.
   def enable_icmp_bcast(enabled)
-    shell.execute("sysctl -w net.inet.icmp.bmcastecho=#{enabled ? 1 : 0}")
+    Shell.execute("sysctl -w net.inet.icmp.bmcastecho=#{enabled ? 1 : 0}")
   end
 
+  # Return true if packet forwarding is currently enabled, otherwise false.
   def forwarding_enabled?
-    shell.execute('sysctl net.inet.ip.forwarding').strip.split(' ')[1] == '1'
+    Shell.execute('sysctl net.inet.ip.forwarding').strip.split(' ')[1] == '1'
   end
 
+  # This method is ignored on OSX.
+  def enable_send_redirects(enabled); end
+
+  # If +enabled+ is true, the PF firewall will be enabled, otherwise it will
+  # be disabled.
   def enable(enabled)
     begin
-      shell.execute("pfctl -#{enabled ? 'e' : 'd'} >/dev/null 2>&1")
+      Shell.execute("pfctl -#{enabled ? 'e' : 'd'} >/dev/null 2>&1")
     rescue; end
   end
 
+  # Apply the +r+ BetterCap::Firewalls::Redirection port redirection object.
   def add_port_redirection( r )
     # create the pf config file
     config_file = "/tmp/bettercap_pf_#{Process.pid}.conf"
@@ -41,11 +54,12 @@ class OSXFirewall < IFirewall
     end
 
     # load the rule
-    shell.execute("pfctl -f #{config_file} >/dev/null 2>&1")
+    Shell.execute("pfctl -f #{config_file} >/dev/null 2>&1")
     # enable pf
     enable true
   end
 
+  # Remove the +r+ BetterCap::Firewalls::Redirection port redirection object.
   def del_port_redirection( r )
     # FIXME: This should search for multiple rules inside the
     # file and remove only this one.
@@ -60,11 +74,6 @@ class OSXFirewall < IFirewall
     end
 
   end
-
-  private
-
-  def shell
-    Shell
-  end
+end
 end
 end

data/lib/bettercap/firewalls/redirection.rb

@@ -10,9 +10,22 @@ This project is released under the GPL 3 license.
 
 =end
 module BetterCap
+module Firewalls
+# This class represents a firewall port redirection rule.
 class Redirection
-  attr_reader :interface, :protocol, :src_port, :dst_address, :dst_port
+  # Network interface name.
+  attr_reader :interface
+  # Protocol name.
+  attr_reader :protocol
+  # Source port.
+  attr_reader :src_port
+  # Destination address.
+  attr_reader :dst_address
+  # Destionation port.
+  attr_reader :dst_port
 
+  # Create the redirection rule for the specified +interface+ and +protocol+.
+  # Redirect *:+src_port+ to +dst_address+:+dst_port+
   def initialize( interface, protocol, src_port, dst_address, dst_port )
     @interface   = interface
     @protocol    = protocol
@@ -22,3 +35,4 @@ class Redirection
   end
 end
 end
+end

data/lib/bettercap/httpd/server.rb

@@ -15,7 +15,10 @@ require 'bettercap/logger'
 
 module BetterCap
 module HTTPD
+# Simple HTTP server class used to serve static assets when needed.
 class Server
+  # Initialize the HTTP server with the specified tcp +port+ using
+  # +path+ as the document root.
   def initialize( port = 8081, path = './' )
     @port = port
     @path = path
@@ -27,6 +30,7 @@ class Server
     )
   end
 
+  # Start the server.
   def start
     Logger.info "Starting HTTPD on port #{@port} and path #{@path} ..."
     @thread = Thread.new {
@@ -34,6 +38,7 @@ class Server
     }
   end
 
+  # Stop the server.
   def stop
     Logger.info 'Stopping HTTPD ...'