bettercap 1.1.10 → 1.2.0

data/lib/bettercap/logger.rb

@@ -10,14 +10,21 @@ This project is released under the GPL 3 license.
 
 =end
 module BetterCap
+# Class responsible for console and file logging.
 module Logger
   class << self
+    @@ctx     = nil
     @@queue   = Queue.new
     @@debug   = false
     @@silent  = false
     @@logfile = nil
     @@thread  = nil
 
+    # Initialize the logging system.
+    # If +debug+ is true, debug logging will be enabled.
+    # If +logfile+ is not nil, every message will be saved to that file.
+    # If +silent+ is true, all messages will be suppressed if they're not errors
+    # or warnings.
     def init( debug, logfile, silent )
       @@debug   = debug
       @@logfile = logfile
@@ -26,31 +33,41 @@ module Logger
       @@ctx     = Context.get
     end
 
+    # Log an error +message+.
     def error(message)
       @@queue.push formatted_message(message, 'E').red
     end
 
+    # Log an information +message+.
     def info(message)
       @@queue.push( formatted_message(message, 'I') ) unless @@silent
     end
 
+    # Log a warning +message+.
     def warn(message)
       @@queue.push formatted_message(message, 'W').yellow
     end
 
+    # Log a debug +message+.
     def debug(message)
       if @@debug and not @@silent
         @@queue.push formatted_message(message, 'D').light_black
       end
     end
 
+    # Log a +message+ as it is.
     def raw(message)
       @@queue.push( message )
     end
 
+    # Wait for the messages queue to be empty.
     def wait!
       while not @@queue.empty?
-        sleep 0.3
+        if @@thread.nil?
+          emit @@queue.pop
+        else
+          sleep 0.3
+        end
       end
     end
 
@@ -59,17 +76,21 @@ module Logger
     def worker
       loop do
         message = @@queue.pop
-        if @@ctx.running
-          puts message
-          unless @@logfile.nil?
-            f = File.open( @@logfile, 'a+t' )
-            f.puts( message.gsub( /\e\[(\d+)(;\d+)*m/, '') + "\n")
-            f.close
-          end
+        if @@ctx.nil? or @@ctx.running
+          emit message
         end
       end
     end
 
+    def emit(message)
+      puts message
+      unless @@logfile.nil?
+        f = File.open( @@logfile, 'a+t' )
+        f.puts( message.gsub( /\e\[(\d+)(;\d+)*m/, '') + "\n")
+        f.close
+      end
+    end
+
     def formatted_message(message, message_type)
       "[#{message_type}] #{message}"
     end

data/lib/bettercap/network.rb

@@ -12,142 +12,142 @@ This project is released under the GPL 3 license.
 require 'thread'
 
 module BetterCap
+# Handles various network related tasks.
 class Network
-    class << self
-    def is_ip?(ip)
-      if /\A(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\Z/ =~ ip.to_s
-        return $~.captures.all? {|i| i.to_i < 256}
-      end
-      false
+class << self
+  # Return true if +ip+ is a valid IP address, otherwise false.
+  def is_ip?(ip)
+    if /\A(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\Z/ =~ ip.to_s
+      return $~.captures.all? {|i| i.to_i < 256}
     end
+    false
+  end
 
-    def is_mac?(mac)
-      ( /^[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}$/i =~ mac.to_s )
-    end
+  # Return true if +mac+ is a valid MAC address, otherwise false.
+  def is_mac?(mac)
+    ( /^[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}\:[a-f0-9]{1,2}$/i =~ mac.to_s )
+  end
 
-    def get_gateway
-      nstat = Shell.execute('netstat -nr')
+  # Return the current network gateway or nil.
+  def get_gateway
+    nstat = Shell.execute('netstat -nr')
 
-      Logger.debug "NETSTAT:\n#{nstat}"
+    Logger.debug "NETSTAT:\n#{nstat}"
 
-      out = nstat.split(/\n/).select {|n| n =~ /UG/ }
-      gw  = nil
-      out.each do |line|
-        if line.include?( Context.get.options.iface )
-          tmp = line.split[1]
-          if is_ip?(tmp)
-            gw = tmp
-            break
-          end
+    out = nstat.split(/\n/).select {|n| n =~ /UG/ }
+    gw  = nil
+    out.each do |line|
+      if line.include?( Context.get.options.iface )
+        tmp = line.split[1]
+        if is_ip?(tmp)
+          gw = tmp
+          break
         end
       end
-      gw
     end
+    gw
+  end
 
-    def get_local_ips
-      ips = []
+  # Return a list of IP addresses associated to this device network interfaces.
+  def get_local_ips
+    ips = []
 
-      Shell.ifconfig.split("\n").each do |line|
-        if line =~ /inet [adr:]*([\d\.]+)/
-          ips << $1
-        end
+    Shell.ifconfig.split("\n").each do |line|
+      if line =~ /inet [adr:]*([\d\.]+)/
+        ips << $1
       end
-
-      ips
     end
 
-    def get_alive_targets( ctx, timeout = 5 )
-      if ctx.options.should_discover_hosts?
-        start_agents( ctx, timeout )
-      else
-        Logger.debug 'Using current ARP cache.'
-      end
-
-      ArpAgent.parse ctx
-    end
+    ips
+  end
 
-    def get_ip_address( ctx, mac, timeout = 5 )
-      ip = ArpAgent.find_mac( mac )
-      if ip.nil?
-        start_agents( ctx, timeout )
-        ip = ArpAgent.find_mac( mac )
-      end
-      ip
+  # Return a list of BetterCap::Target objects found on the network, given a
+  # BetterCap::Context ( +ctx+ ) and a +timeout+ in seconds for the operation.
+  def get_alive_targets( ctx )
+    if ctx.options.should_discover_hosts?
+      start_agents( ctx )
+    else
+      Logger.debug 'Using current ARP cache.'
     end
 
-=begin
-  Apparently on Mac OSX the gem pcaprub ( or libpcap itself ) has
-  a bug, so we can't use 'PacketFu::Utils::arp' since the funtion
-  it's using:
+    Discovery::Agents::Arp.parse ctx
+  end
 
-  if cap.save > 0
-    ...
+  # Return the IP address associated with the +mac+ hardware address using the
+  # given BetterCap::Context ( +ctx+ ).
+  def get_ip_address( ctx, mac )
+    ip = Discovery::Agents::Arp.find_mac( mac )
+    if ip.nil?
+      start_agents( ctx )
+      ip = Discovery::Agents::Arp.find_mac( mac )
+    end
+    ip
   end
 
-  won't catch anything, instead we're using cap.stream.each.
-=end
-    def get_hw_address( iface, ip_address, attempts = 2 )
-      hw_address = ArpAgent.find_address( ip_address )
-
-      if hw_address.nil?
-        attempts.times do
-          arp_pkt = PacketFu::ARPPacket.new
-
-          arp_pkt.eth_saddr     = arp_pkt.arp_saddr_mac = iface[:eth_saddr]
-          arp_pkt.eth_daddr     = 'ff:ff:ff:ff:ff:ff'
-          arp_pkt.arp_daddr_mac = '00:00:00:00:00:00'
-          arp_pkt.arp_saddr_ip  = iface[:ip_saddr]
-          arp_pkt.arp_daddr_ip  = ip_address
-
-          cap_thread = Thread.new do
-            target_mac = nil
-            timeout = 0
-
-            cap = PacketFu::Capture.new(
-              iface: iface[:iface],
-              start: true,
-              filter: "arp src #{ip_address} and ether dst #{arp_pkt.eth_saddr}"
-            )
-            arp_pkt.to_w(iface[:iface])
-
-            begin
-              Logger.debug 'Attempting to get MAC from packet capture ...'
-              target_mac = Timeout::timeout(0.5) { get_mac_from_capture(cap, ip_address) }
-            rescue Timeout::Error
-              timeout += 0.1
-              retry if target_mac.nil? && timeout <= 5
-            end
-
-            target_mac
+  # Return the hardware address associated with the specified +ip_address+ using
+  # the +iface+ network interface.
+  # The resolution will be performed for the specified number of +attempts+.
+  def get_hw_address( iface, ip_address, attempts = 2 )
+    hw_address = Discovery::Agents::Arp.find_address( ip_address )
+
+    if hw_address.nil?
+      attempts.times do
+        arp_pkt = PacketFu::ARPPacket.new
+
+        arp_pkt.eth_saddr     = arp_pkt.arp_saddr_mac = iface[:eth_saddr]
+        arp_pkt.eth_daddr     = 'ff:ff:ff:ff:ff:ff'
+        arp_pkt.arp_daddr_mac = '00:00:00:00:00:00'
+        arp_pkt.arp_saddr_ip  = iface[:ip_saddr]
+        arp_pkt.arp_daddr_ip  = ip_address
+
+        cap_thread = Thread.new do
+          Context.get.packets.push(arp_pkt)
+
+          target_mac = nil
+          timeout = 0
+
+          cap = PacketFu::Capture.new(
+            iface: iface[:iface],
+            start: true,
+            filter: "arp src #{ip_address} and ether dst #{arp_pkt.eth_saddr}"
+          )
+
+          begin
+            Logger.debug 'Attempting to get MAC from packet capture ...'
+            target_mac = Timeout::timeout(0.5) { get_mac_from_capture(cap, ip_address) }
+          rescue Timeout::Error
+            timeout += 0.1
+            retry if target_mac.nil? && timeout <= 5
           end
-          hw_address = cap_thread.value
 
-          break unless hw_address.nil?
+          target_mac
         end
-      end
+        hw_address = cap_thread.value
 
-      hw_address
+        break unless hw_address.nil?
+      end
     end
 
-    private
+    hw_address
+  end
 
-    def start_agents( ctx, timeout )
-      icmp = IcmpAgent.new timeout
-      udp  = UdpAgent.new ctx.ifconfig, ctx.gateway, ctx.ifconfig[:ip_saddr]
-      arp  = ArpAgent.new ctx.ifconfig, ctx.gateway, ctx.ifconfig[:ip_saddr]
+  private
 
-      icmp.wait
-      arp.wait
-      udp.wait
+  def start_agents( ctx )
+    [ 'Icmp', 'Udp', 'Arp' ].each do |name|
+      Kernel.const_get("BetterCap::Discovery::Agents::#{name}").new( ctx )
     end
+    ctx.packets.wait_empty( ctx.timeout )
+  end
 
-    def get_mac_from_capture( cap, ip_address )
-      cap.stream.each do |p|
-        arp_response = PacketFu::Packet.parse(p)
-        target_mac = arp_response.arp_saddr_mac if arp_response.arp_saddr_ip == ip_address
-        break target_mac unless target_mac.nil?
-      end
+  def get_mac_from_capture( cap, ip_address )
+    cap.stream.each do |p|
+      arp_response = PacketFu::Packet.parse(p)
+      target_mac = arp_response.arp_saddr_mac if arp_response.arp_saddr_ip == ip_address
+      break target_mac unless target_mac.nil?
     end
   end
+
+end
 end
 end

data/lib/bettercap/options.rb

@@ -9,41 +9,79 @@ Blog   : http://www.evilsocket.net/
 This project is released under the GPL 3 license.
 
 =end
+
 module BetterCap
+# Parse command line arguments, set options and initialize +Context+
+# accordingly.
 class Options
-  attr_accessor :gateway,
-                :iface,
-                :spoofer,
-                :half_duplex,
-                :target,
-                :logfile,
-                :silent,
-                :debug,
-                :arpcache,
-                :ignore,
-                :sniffer,
-                :sniffer_pcap,
-                :sniffer_filter,
-                :sniffer_src,
-                :parsers,
-                :custom_parser,
-                :local,
-                :proxy,
-                :proxy_https,
-                :proxy_port,
-                :proxy_https_port,
-                :proxy_pem_file,
-                :proxy_module,
-                :custom_proxy,
-                :custom_proxy_port,
-                :custom_https_proxy,
-                :custom_https_proxy_port,
-                :httpd,
-                :httpd_port,
-                :httpd_path,
-                :check_updates,
-                :no_target_nbns
-
+  # Gateway IP address.
+  attr_accessor :gateway
+  # Network interface.
+  attr_accessor :iface
+  # Name of the spoofer to use.
+  attr_accessor :spoofer
+  # If true half duplex mode is enabled.
+  attr_accessor :half_duplex
+  # Comma separated list of targets.
+  attr_accessor :target
+  # Log file name.
+  attr_accessor :logfile
+  # If true will suppress every log message which is not an error or a warning.
+  attr_accessor :silent
+  # If true will enable debug messages.
+  attr_accessor :debug
+  # If true will disable active network discovery, the program will just use
+  # the current ARP cache.
+  attr_accessor :arpcache
+  # Comma separated list of ip addresses to ignore.
+  attr_accessor :ignore
+  # If true the BetterCap::Sniffer will be enabled.
+  attr_accessor :sniffer
+  # PCAP file name to save captured packets to.
+  attr_accessor :sniffer_pcap
+  # BPF filter to apply to sniffed packets.
+  attr_accessor :sniffer_filter
+  # Input PCAP file, if specified the BetterCap::Sniffer will read packets
+  # from it instead of the network.
+  attr_accessor :sniffer_src
+  # Comma separated list of BetterCap::Parsers to enable.
+  attr_accessor :parsers
+  # Regular expression to use with the BetterCap::Parsers::Custom parser.
+  attr_accessor :custom_parser
+  # If true, bettercap will sniff packets from the local interface as well.
+  attr_accessor :local
+  # If true, HTTP transparent proxy will be enabled.
+  attr_accessor :proxy
+  # If true, HTTPS transparent proxy will be enabled.
+  attr_accessor :proxy_https
+  # HTTP proxy port.
+  attr_accessor :proxy_port
+  # HTTPS proxy port.
+  attr_accessor :proxy_https_port
+  # File name of the PEM certificate to use for the HTTPS proxy.
+  attr_accessor :proxy_pem_file
+  # File name of the transparent proxy module to load.
+  attr_accessor :proxy_module
+  # Custom HTTP transparent proxy address.
+  attr_accessor :custom_proxy
+  # Custom HTTP transparent proxy port.
+  attr_accessor :custom_proxy_port
+  # Custom HTTPS transparent proxy address.
+  attr_accessor :custom_https_proxy
+  # Custom HTTPS transparent proxy port.
+  attr_accessor :custom_https_proxy_port
+  # If true, BetterCap::HTTPD::Server will be enabled.
+  attr_accessor :httpd
+  # The port to bind BetterCap::HTTPD::Server to.
+  attr_accessor :httpd_port
+  # Web root of the BetterCap::HTTPD::Server.
+  attr_accessor :httpd_path
+  # If true, bettercap will check for updates then exit.
+  attr_accessor :check_updates
+  # If true, targets NBNS hostname resolution won't be performed.
+  attr_accessor :no_target_nbns
+
+  # Create a BetterCap::Options class instance using the specified network interface.
   def initialize( iface )
     @gateway = nil
     @iface = iface
@@ -86,6 +124,9 @@ class Options
     @check_updates = false
   end
 
+  # Initialize the BetterCap::Context, parse command line arguments and update program
+  # state accordingly.
+  # Will rise a BetterCap::Error if errors occurred.
   def self.parse!
     ctx = Context.get
 
@@ -101,7 +142,7 @@ class Options
         ctx.options.iface = v
       end
 
-      opts.on( '-S', '--spoofer NAME', 'Spoofer module to use, available: ' + SpooferFactory.available.join(', ') + ' - default: ' + ctx.options.spoofer ) do |v|
+      opts.on( '-S', '--spoofer NAME', 'Spoofer module to use, available: ' + Factories::Spoofer.available.join(', ') + ' - default: ' + ctx.options.spoofer ) do |v|
         ctx.options.spoofer = v
       end
 
@@ -145,9 +186,9 @@ class Options
         ctx.options.sniffer_filter = v
       end
 
-      opts.on( '-P', '--parsers PARSERS', 'Comma separated list of packet parsers to enable, "*" for all ( NOTE: Will set -X to true ), available: ' + ParserFactory.available.join(', ') + ' - default: *' ) do |v|
+      opts.on( '-P', '--parsers PARSERS', 'Comma separated list of packet parsers to enable, "*" for all ( NOTE: Will set -X to true ), available: ' + Factories::Parser.available.join(', ') + ' - default: *' ) do |v|
         ctx.options.sniffer = true
-        ctx.options.parsers = ParserFactory.from_cmdline(v)
+        ctx.options.parsers = Factories::Parser.from_cmdline(v)
       end
 
       opts.on( '--custom-parser EXPRESSION', 'Use a custom regular expression in order to capture and show sniffed data ( NOTE: Will set -X to true ).' ) do |v|
@@ -281,26 +322,33 @@ class Options
     ctx
   end
 
+  # Return true if active host discovery is enabled, otherwise false.
   def should_discover_hosts?
     !@arpcache
   end
 
+  # Return true if a proxy module was specified, otherwise false.
   def has_proxy_module?
     !@proxy_module.nil?
   end
 
+  # Return true if a spoofer module was specified, otherwise false.
   def has_spoofer?
     @spoofer != 'NONE' and @spoofer != 'none'
   end
 
+  # Return true if the BetterCap::Parsers::URL is enabled, otherwise false.
   def has_http_sniffer_enabled?
     @sniffer and ( @parsers.include?'*' or @parsers.include?'URL' )
   end
 
+  # Return true if the +ip+ address needs to be ignored, otherwise false.
   def ignore_ip?(ip)
     !@ignore.nil? and @ignore.include?(ip)
   end
 
+  # Setter for the #ignore attribute, will raise a BetterCap::Error if one
+  # or more invalid IP addresses are specified.
   def ignore=(value)
     @ignore = value.split(",")
     valid = @ignore.select { |target| Network.is_ip?(target) }
@@ -317,16 +365,22 @@ class Options
     Logger.warn "Ignoring #{valid.join(", ")} ."
   end
 
+  # Setter for the #custom_proxy attribute, will raise a BetterCap::Error if
+  # +value+ is not a valid IP address.
   def custom_proxy=(value)
     @custom_proxy = value
     raise BetterCap::Error, 'Invalid custom HTTP upstream proxy address specified.' unless Network.is_ip? @custom_proxy
   end
 
+  # Setter for the #custom_https_proxy attribute, will raise a BetterCap::Error if
+  # +value+ is not a valid IP address.
   def custom_https_proxy=(value)
     @custom_https_proxy = value
     raise BetterCap::Error, 'Invalid custom HTTPS upstream proxy address specified.' unless Network.is_ip? @custom_https_proxy
   end
 
+  # Split specified targets and parse them ( either as IP or MAC ), will raise a
+  # BetterCap::Error if one or more invalid addresses are specified.
   def to_targets
     targets = @target.split(",")
     valid_targets = targets.select { |target| Network.is_ip?(target) or Network.is_mac?(target) }
@@ -341,20 +395,24 @@ class Options
     valid_targets.map { |target| Target.new(target) }
   end
 
+  # Parse spoofers and return a list of BetterCap::Spoofers objects. Raise a
+  # BetterCap::Error if an invalid spoofer name was specified.
   def to_spoofers
     spoofers = []
     spoofer_modules_names = @spoofer.split(",")
     spoofer_modules_names.each do |module_name|
-      spoofers << SpooferFactory.get_by_name( module_name )
+      spoofers << Factories::Spoofer.get_by_name( module_name )
     end
     spoofers
   end
 
+  # Create a list of BetterCap::Firewalls::Redirection objects which are needed
+  # given the specified command line arguments.
   def to_redirections ifconfig
     redirections = []
 
     if @proxy
-      redirections << Redirection.new( @iface,
+      redirections << Firewalls::Redirection.new( @iface,
                                        'TCP',
                                        80,
                                        ifconfig[:ip_saddr],
@@ -362,7 +420,7 @@ class Options
     end
 
     if @proxy_https
-      redirections << Redirection.new( @iface,
+      redirections << Firewalls::Redirection.new( @iface,
                                        'TCP',
                                        443,
                                        ifconfig[:ip_saddr],
@@ -370,7 +428,7 @@ class Options
     end
 
     if @custom_proxy
-      redirections << Redirection.new( @iface,
+      redirections << Firewalls::Redirection.new( @iface,
                                        'TCP',
                                        80,
                                        @custom_proxy,
@@ -378,7 +436,7 @@ class Options
     end
 
     if @custom_https_proxy
-      redirections << Redirection.new( @iface,
+      redirections << Firewalls::Redirection.new( @iface,
                                        'TCP',
                                        443,
                                        @custom_https_proxy,