dvash 0.0.3 → 0.0.4

data/dvash.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = "dvash"
-  s.version = "0.0.3"
+  s.version = "0.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ari Mizrahi"]
@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.description = "Part honeypot, part defense system.  Opens up ports and simulates services in order to look like an attractive target.  Hosts that try to connect to the fake services are considered attackers and blocked from all access."
   s.email = "codemunchies@gmail.com"
   s.executables = ["dvash"]
-  s.files = ["etc/dvash-baseline.conf", "lib/dvash/honeyports/ipv4/http.rb", "lib/dvash/honeyports/ipv6/http.rb", "lib/dvash/os/linux.rb", "lib/dvash/os/mac.rb", "lib/dvash/os/windows.rb", "lib/dvash/application.rb", "lib/dvash/validation.rb", "lib/dvash.rb", "dvash.gemspec", "Gemfile"]
+  s.files = ["etc/dvash-baseline.conf", "lib/dvash/honeyports/ipv4/http.rb", "lib/dvash/honeyports/ipv6/http.rb", "lib/dvash/os/linux.rb", "lib/dvash/os/mac.rb", "lib/dvash/os/windows.rb", "lib/dvash/application.rb", "lib/dvash/core.rb", "lib/dvash.rb", "dvash.gemspec", "Gemfile"]
   s.homepage = "http://github.com/codemunchies/dvash"
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.25"

data/lib/dvash.rb

@@ -2,6 +2,7 @@ require 'dvash/application'
 
 require 'optparse'
 
+#
 # Dvash Defense
 # 
 # Written By: Ari Mizrahi
@@ -12,37 +13,51 @@ require 'optparse'
 # 
 # Heavily inspired by The Artillery Project by Dave Kennedy (ReL1K) with a
 # passion for ruby and a thirst for knowledge.
+#
 
 module Dvash
   
-  # Start a new Dvash instance
   def self.start(paths={})
 
-    # Set default options
+    #
+    # Set default path to config and log files
+    # TODO: These settings assume Linux default paths, should determine the operating system then configure accordingly
+    #
     paths[:config_path] = '/etc/dvash.conf'
     paths[:log_path] = '/var/log/dvash.conf'
     
-    # Command-line interface
+    #
+    # A command-line interface using OptionParser
+    #
     OptionParser.new do |opts|
       opts.banner = "Usage: #{__FILE__} [options]"
 
+      #
+      # Option to set an alternate configuration file
+      #
       opts.on("--config-file [PATH]", "Set path to config file") do |arg|
         paths[:config_path] = arg
       end
 
+      #
+      # Option to set an alternate log file destination and filename
+      #
       opts.on("--log-file [PATH]", "Set path to log file") do |arg|
         paths[:log_path] = arg
       end
     end.parse!
 
+    #
     # Create and start an Application instance
-    #begin
+    #
+    begin
       application = Dvash::Application.new(paths)
       application.start
-    #rescue
-    #  puts "couldn't start application" # replace me
-    #  exit
-    #end
+    rescue
+      # TODO: Use 'logger' gem to output debug information
+      puts "couldn't start application"
+      exit
+    end
 
 
   end

data/lib/dvash/application.rb

@@ -1,26 +1,55 @@
-require 'dvash/validation'
+require 'dvash/core'
 
 require 'parseconfig'
 
 module Dvash
 
-	class Application < Validation
+	class Application < Core
 
+		#
+		# Methods that should run when the Dvash Application object is created
+		# Requires one argument of type Array including paths to configuration
+		# file and destination for log file
+		#
 		def initialize(paths)
+			#
+			# Create @honey_threads Array to hold all 'honeyport' threads
+			#
 			@honey_threads = Array.new
+			#
+			# Load passed Array paths into @paths for use in the class
+			#
 			@paths = paths
-
+			#
+			# Call method to load the configuration file
+			#
 			load_conf
+			#
+			# Call method to validate the operating system and load necessary Dvash methods
+			#
 			validate_os
 		end
 
+		#
+		# Fire in the hole!
+		#
 		def start
+			#
+			# Make sure we are running with elevated privileges
+			#
 			unless valid_user?
-				puts "invalid user" # replace me
+				# TODO: Use 'logger' gem to output debug information
+				puts "invalid user"
 				exit
 			end
 
+			#
+			# Call method to load all 'honeyports' set as 'true' in the configuration file
+			#
 			load_honeyport
+			#
+			# Start all loaded threads
+			#
 			@honey_threads.each { |thr| thr.join }
 		end
 

data/lib/dvash/{validation.rb → core.rb}

@@ -3,12 +3,18 @@ require 'securerandom'
 
 module Dvash
 
-	class Validation
+	class Core
 
+		#
+		# Validates user, must be root
+		#
 		def valid_user?
 			Process.uid == 0
 		end
 
+		#
+		# Validates an IP address, must be valid IPv4 or IPv6 address
+		#
 		def valid_ip?(address)
 			begin
 				IPAddr.new("#{address}")
@@ -18,6 +24,11 @@ module Dvash
 			end
 		end
 
+		#
+		# Validates the operating system, must be windows, os x, or linux
+		# Creates a new instance the operating system specific Dvash libraries required to block IP addresses properly
+		# @@os is used as a class variable to call its methods from within a Honeyport
+		#
 		def validate_os
 			system = RUBY_PLATFORM
 			case system
@@ -34,34 +45,57 @@ module Dvash
 				# TODO: BSD support
 				exit
 			else
-				puts "invalid operating system" # replace me
+				# TODO: Use 'logger' gem to output debug information
+				puts "invalid operating system"
 	      exit
 			end
 		end
 
+		#
+		# Loads the configuration file using ParseConfig
+		#
 		def load_conf
 			begin
 				@@cfgfile = ParseConfig.new(@paths[:config_path])
 			rescue
-				puts "invalid configuration file" # replace me
+				# TODO: Use 'logger' gem to output debug information
+				puts "invalid configuration file"
 				exit
 			end
 		end
 
+		#
+		# Load all Honeyports set 'true' in the configuration file
+		# 
 		def load_honeyport
+			# 
+			# Read 'honeyports' group in configuration file, parse keys and values
+			#
 			@@cfgfile['honeyports'].each do |key, value|
 				if value == 'true' then
 					ipver, proto = key.split("_")
+					#
+					# Load methods for all 'honeyports' set to 'true'
+					#
 					require "dvash/honeyports/#{ipver}/#{proto}"
+					#
+					# Push the loaded 'honeyport' into a thread
+					#
 					@honey_threads << Thread.new { Dvash::Honeyport.new.send(key) }
 				end
 			end
 		end
 
+		#
+		# Return a string of random characters 64 bytes long
+		#
 		def random_data
 			SecureRandom.random_bytes(64)
 		end
 
+		#
+		# Return the client source IP address from a TCPServer object
+		#
 		def client_ip(client)
 			client.peeraddr[3]
 		end

data/lib/dvash/honeyports/ipv4/http.rb

@@ -10,17 +10,38 @@
 ###############################################################################
 module Dvash
 
-	class Honeyport < Validation
+	class Honeyport < Core
 
 		def ipv4_http
+			#
+			# Create a new IPv4 TCPServer object
+			#
 			server = TCPServer.new(80)
+			#
+			# Infinite loop listens on port 80 pretending to be an HTTP server
+			#
 			loop do
+					#
+					# Fork a new instance of the TCPServer object when a client connects
+					# TODO: Maybe we should not send junk data until after the client IP has been validated
+					#	
 			    Thread.fork(server.accept) do |client| 
-			        # send the client junk data
+			    		#
+			        # Send the connected client junk data
+			        #
 			        client.puts(random_data)
+			        #
+			        # Make sure the client has a valid IP address
+			        #
 			        if valid_ip?(client_ip(client)) then 
+			        	#
+			        	# Block the IP address
+			        	#
 			        	@@os.block_ip(client_ip(client))
 			        end
+			        #
+			        # Close the connection to the client and kill the forked process
+			        #
 			        client.close
 			    end
 			end

data/lib/dvash/honeyports/ipv6/http.rb

@@ -10,17 +10,38 @@
 ###############################################################################
 module Dvash
 
-	class Honeyport < Validation
+	class Honeyport < Core
 
-		def ipv4_http
+		def ipv6_http
+			#
+			# Create a new IPv6 TCPServer object
+			#
 			server = TCPServer.new('::', 80)
+			#
+			# Infinite loop listens on port 80 pretending to be an HTTP server
+			#
 			loop do
+					#
+					# Fork a new instance of the TCPServer object when a client connects
+					# TODO: Maybe we should not send junk data until after the client IP has been validated
+					#	
 			    Thread.fork(server.accept) do |client| 
-			        # send the client junk data
+			    		#
+			        # Send the connected client junk data
+			        #
 			        client.puts(random_data)
+			        #
+			        # Make sure the client has a valid IP address
+			        #
 			        if valid_ip?(client_ip(client)) then 
+			        	#
+			        	# Block the IP address
+			        	#
 			        	@@os.block_ip(client_ip(client))
 			        end
+			        #
+			        # Close the connection to the client and kill the forked process
+			        #
 			        client.close
 			    end
 			end

data/lib/dvash/os/linux.rb

@@ -1,40 +1,66 @@
 module Dvash
 
-	class Linux < Validation
+	class Linux < Core
 
 		def initialize
+			#
+			# Check to make sure we have binaries for iptables using the paths
+			# set in the configuration file
+			#
 			unless File.exist?(@@cfgfile['iptables']['ipv4'])
+				# TODO: Use 'logger' gem to output debug information
 				puts "can't find iptables"
 				exit
 			end
 
-			# do not create if it has already been created
+			#
+			# Do not create a new iptables chain if one already exists
+			#
 			unless `"#{@@cfgfile['iptables']['ipv4']}" -L INPUT`.include?('DVASH')
-				# create a new chain
+				#
+				# Create a new DVASH chain
+				#
 				system("#{@@cfgfile['iptables']['ipv4']} -N DVASH")
-				# flush the new chain
+				#
+				# Flush the DVASH chain
+				#
 				system("#{@@cfgfile['iptables']['ipv4']} -F DVASH")
-				# associate new chain to INPUT chain
+				#
+				# Associate the DVASH chain to INPUT chain
+				#
 				system("#{@cfgfile['iptables']['ipv4']} -I INPUT -j DVASH")
 			end
 
-			# do not create if it has already been created
+			#
+			# Do not create a new ip6tables chain if one already exists
+			#
 			unless `"#{@@cfgfile['iptables']['ipv6']}" -L INPUT`.include?('DVASH')
-				# create a new chain
+				#
+				# Create a new DVASH chain
+				#
 				system("#{@@cfgfile['iptables']['ipv6']} -N DVASH")
-				# flush the new chain
+				#
+				# Flush the DVASH chain
+				#
 				system("#{@@cfgfile['iptables']['ipv6']} -F DVASH")
-				# associate new chain to INPUT chain
+				#
+				# Associate the DVASH chain to INPUT chain
+				#
 				system("#{@@cfgfile['iptables']['ipv6']} -I INPUT -j DVASH")
 			end
 		end
 
 		def block_ip(address)
-
+			#
+			# Block the client IP address using iptables binaries set in the configuration file
+			#
 			if IPAddr.new("#{address}").ipv4? then
 				system("#{@@cfgfile['iptables']['ipv4']} -I DVASH -s #{address} -j DROP")
 			end
 
+			#
+			# Block the client IP address using ip6tables binaries set in the configuration file
+			#
 			if IPAddr.new("#{address}").ipv6? then
 				system("#{@@cfgfile['iptables']['ipv6']} -I DVASH -s #{address} -j DROP")
 			end

data/lib/dvash/os/mac.rb

@@ -1,15 +1,23 @@
 module Dvash
 
-	class Mac < Validation
+	class Mac < Core
 
 		def initialize
+			#
+			# Check to make sure we have binaries for ipfw using the paths
+			# set in the configuration file
+			#
 			unless File.exist?(@@cfgfile['ipfw']['ipfw'])
+				# TODO: Use 'logger' gem to output debug information
 				puts "can't find ipfw"
 				exit
 			end
 		end
 
 		def block_ip(address)
+			#
+			# Block the client IP address using ipfw binaries set in the configuration file
+			#
 			system("#{@@cfgfile['ipfw']['ipfw']} -q add deny src-ip #{address}")
 		end
 

data/lib/dvash/os/windows.rb

@@ -1,10 +1,13 @@
 module Dvash
 	
-	class Windows
+	class Windows < Core
 
 		def block_ip(address)
-
-			# TODO
+			#
+			# Windows 7 and newer compatible
+			# Blackholes the client IP address by sending traffic to a non-existing gateway
+			#
+			system("route add #{address} mask 255.255.255.255 10.255.255.255 if 1 -p")
 		end
 
 	end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dvash
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -59,7 +59,7 @@ files:
 - lib/dvash/os/mac.rb
 - lib/dvash/os/windows.rb
 - lib/dvash/application.rb
-- lib/dvash/validation.rb
+- lib/dvash/core.rb
 - lib/dvash.rb
 - dvash.gemspec
 - Gemfile