patronus_fati 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0cb6f174187ef3f5adfa38bc95f3a6492aec44e3
-  data.tar.gz: 8bc31ce133c6bd96416e1e32c1211c19d0e0e5f7
+  metadata.gz: 29f01b90c143b565522531ec08eb46baaa467b3e
+  data.tar.gz: 797ee832481e9ad310001f22d8db6ef438eb0131
 SHA512:
-  metadata.gz: 881e15810f934ba0595c198a02f3d5de671a444bcc58c8719975b9de9fb070e79ac886f548e0b4b17b0701584fd05800d7063bc8971efaa7b2538582a692fb12
-  data.tar.gz: 38487f6aee94ea8e48badf6a811b4d10fa8fbbd48db1c4ebb4393d753e19f60d7c55269405cb89ad7c4bb688bdb62400315643ade808ec27d3cf4af2c8d01b48
+  metadata.gz: d1cfc2d362d834b03c9753eea64bbbc477d81330e3e2f4d6fe8c2cc025965e0f4151ce5d49a460c8a998feb91c3861e6b7af72bfaecdbb070542839c24673301
+  data.tar.gz: 7847043863e93749ef3a072bbcec8fa87352fa017a4bfe4c775af8dbece4b709d63da351ca9290044bd98b45acd472f1dd31ab229d5447e1aaa12e22ec53bb76

data/lib/patronus_fati/bit_helper.rb

@@ -0,0 +1,56 @@
+module PatronusFati
+  module BitHelper
+    # Count the consecutive number of bits in the provided number
+    #
+    # @param [Fixnum] num
+    # @return [Fixnum]
+    def self.count_consecutive_bits(num)
+      count = 0
+      while num != 0
+        num = (num & (num << 1))
+        count += 1
+      end
+      count
+    end
+
+    # This is a bit of an odd algorithm. It needs to find the length of the
+    # longest common bits between n number of bit fields (in the context of
+    # this program that is 64 bit numbers).
+    #
+    # The algorithm works by iterating over each bit field , and for each of
+    # them calculating a reference bit field that is the combination of all
+    # uncompared bit strings (those further down the list, prior ones will have
+    # already been checked).
+    #
+    # By comparing the current bit list against the reference we can see where
+    # that bit was present with at least one other bit from the other bit
+    # field. Translating that into this domain specific context, was our SSID
+    # announced at the same time as any other SSID for that minute (bit)?
+    #
+    # Once we have the comparison we can count the longest consecutive bits
+    # between the current field and the reference field to find out how long
+    # any given SSID was simultaneously transmitting as any other on the same
+    # access point.
+    #
+    # This algorithm effectively has a computational cost of almost n^2 which
+    # could potentially get nasty in the event of a huge number of active SSIDs
+    # on a single AP. An upper limit should likely be decided on and in the
+    # event it is reached an alternative method should likely be used (in our
+    # case assuming it's broadcasting multiple is likely fine for these kinds
+    # of floods).
+    #
+    # @param [Array<Fixnum>] bit_list
+    # @return [Boolean]
+    def self.largest_bit_overlap(bit_list)
+      bit_list.map.with_index do |bits, i|
+        # We're at the end of the list there are no bits to compare
+        next 0 if bit_list.length == (i + 1)
+        # Build a reference bit string of all the bit fields we haven't
+        # compared this SSID to yet
+        reference = bit_list[(i + 1)..-1].inject { |ref, bits| ref | bits }
+        # Find the common bits between the reference and this bit string
+        count_consecutive_bits(reference & bits)
+      end.max
+    end
+  end
+end

data/lib/patronus_fati/consts.rb

@@ -79,6 +79,14 @@ module PatronusFati
     dirtyChildren: (1 << 3),
   }.freeze
 
+  # This is how many tracked intervals that need to be seen overlapping before
+  # we consider an access point as transmitting multiple SSIDs. The length of
+  # this is dependent on the length of presence intervals. The value of
+  # INTERVAL_DURATION determines the length of one interval.
+  #
+  # @see PatronusFati::INTERVAL_DURATION
+  SIMULTANEOUS_SSID_THRESHOLD = 2
+
   # Number of seconds before we consider an access point as offline
   AP_EXPIRATION = 300
 
@@ -102,6 +110,16 @@ module PatronusFati
     (1 << 2) => 'WPS_LOCKED',
   }
 
+  # How many seconds do each of our windows last
+  WINDOW_LENGTH = 3600
+
+  # How many intervals do we break each of our windows into? This must be
+  # less than 64.
+  WINDOW_INTERVALS = 60
+
+  # How long each interval will last in seconds
+  INTERVAL_DURATION = WINDOW_LENGTH / WINDOW_INTERVALS
+
   Error = Class.new(StandardError)
   DisconnectError = Class.new(PatronusFati::Error)
   ParseError = Class.new(PatronusFati::Error)

data/lib/patronus_fati/data_models/access_point.rb

@@ -12,7 +12,16 @@ module PatronusFati
       end
 
       def active_ssids
-        ssids.select { |_, v| v.active? } if ssids
+        return unless ssids
+        # If there is any active SSIDs return them
+        active = ssids.select { |_, v| v.active? }
+        return active unless active.empty?
+
+        # If there are no active SSIDs try and find the most recently seen SSID
+        # and report that as still active. Still return an empty set if there
+        # are no SSIDs.
+        most_recent = ssids.sort_by { |_, v| v.presence.last_visible || 0 }.last
+        most_recent ? Hash[[most_recent]] : {}
       end
 
       def add_client(mac)
@@ -53,6 +62,25 @@ module PatronusFati
         mark_synced
       end
 
+      def broadcasting_multiple?
+        return false unless ssids
+        return false if active_ssids.count == 1
+
+        presences = active_ssids.map(&:presence)
+        # This check becomes very expensive at larger numbers, if we get too
+        # high just short circuit and assume that yes there are simultaneous
+        # SSIDs being transmitted. This is likely a sign of a malicious device.
+        return true if presences.length >= 100
+
+        current_presence_bits = presences.map { |p| p.current_presence.bits }
+        return true if PatronusFati::BitHelper.largest_bit_overlap(current_presence_bits) >= SIMULTANEOUS_SSID_THRESHOLD
+
+        last_presence_bits = presences.map { |p| p.last_presence.bits }
+        return true if PatronusFati::BitHelper.largest_bit_overlap(last_presence_bits) >= SIMULTANEOUS_SSID_THRESHOLD
+
+        false
+      end
+
       def cleanup_ssids
         return if ssids.nil? || ssids.select { |_, v| v.presence.dead? }.empty?
 
@@ -72,10 +100,11 @@ module PatronusFati
       def full_state
         state = local_attributes.merge({
           active: active?,
+          broadcasting_multiple: broadcasting_multiple?,
           connected_clients: client_macs,
           vendor: vendor
         })
-        state[:ssids] = active_ssids.values.map(&:local_attributes) if ssids
+        state[:ssids] = active_ssids.values.map(&:full_state) if ssids
         state
       end
 

data/lib/patronus_fati/data_models/ssid.rb

@@ -21,6 +21,10 @@ module PatronusFati
         }
       end
 
+      def full_state
+        { last_visible: presence.last_visible }.merge(local_attributes)
+      end
+
       def update(attrs)
         attrs.each do |k, v|
           next unless LOCAL_ATTRIBUTE_KEYS.include?(k)

data/lib/patronus_fati/presence.rb

@@ -5,16 +5,6 @@ module PatronusFati
   class Presence
     attr_accessor :current_presence, :first_seen, :last_presence, :window_start
 
-    # How many seconds do each of our windows last
-    WINDOW_LENGTH = 3600
-
-    # How many intervals do we break each of our windows into? This must be
-    # less than 64.
-    WINDOW_INTERVALS = 60
-
-    # How long each interval will last in seconds
-    INTERVAL_DURATION = WINDOW_LENGTH / WINDOW_INTERVALS
-
     # Translate a timestamp relative to the provided reference window into an
     # appropriate bit within our bit field.
     def bit_for_time(reference_window, timestamp)
@@ -112,7 +102,7 @@ module PatronusFati
       rotate_presence
 
       return false unless (lv = last_visible)
-      unix_time <= last_visible
+      unix_time <= lv
     end
 
     # Returns the duration in seconds of how long the specific object was
@@ -122,7 +112,7 @@ module PatronusFati
     # of the last interval, which makes logical sense (1 bit set is 1 interval
     # duration, not zero seconds).
     def visible_time
-      (last_visible + INTERVAL_DURATION) - first_seen if first_seen
+      (last_visible + INTERVAL_DURATION) - first_seen if first_seen && last_visible
     end
   end
 end

data/lib/patronus_fati/version.rb

@@ -1,3 +1,3 @@
 module PatronusFati
-  VERSION = '1.2.2'
+  VERSION = '1.3.0'
 end

data/lib/patronus_fati.rb

@@ -13,6 +13,7 @@ require 'louis'
 require 'patronus_fati/consts'
 require 'patronus_fati/version'
 
+require 'patronus_fati/bit_helper'
 require 'patronus_fati/cap_struct'
 require 'patronus_fati/connection'
 require 'patronus_fati/event_handler'

data/spec/patronus_fati/bit_helper_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+
+RSpec.describe(PatronusFati::BitHelper) do
+  context '#count_consecutive_bits' do
+    let(:test_set) do
+      [
+        { bits: "00000000", answer: 0 },
+        { bits: "11111111", answer: 8 },
+        { bits: "11001111", answer: 4 },
+        { bits: "10101010", answer: 1 }
+      ]
+    end
+
+    it 'should correctly count varying number of consecutive bits in a number' do
+      test_set.each do |set|
+        num = set[:bits].to_i(2)
+        expect(described_class.count_consecutive_bits(num)).to eql(set[:answer])
+      end
+    end
+  end
+
+  context '#largest_bit_overlap' do
+    let(:test_set) do
+      [
+        {
+          bit_strings: [
+            "000000000000000000000000",
+            "000011100000111000001110",
+            "001111000011110000111100",
+            "111111111111111111111111"
+          ],
+          answer: 4
+        },
+        {
+          bit_strings: [
+            "0000"
+          ],
+          answer: 0
+        },
+        {
+          bit_strings: [
+            "1111111111111111",
+            "1111111111111111",
+            "0000000000000000"
+          ],
+          answer: 16
+        }
+      ]
+    end
+
+    it 'should correctly find the longest run of overlapping bits' do
+      test_set.each do |set|
+        nums = set[:bit_strings].map { |bs| bs.to_i(2) }
+        expect(described_class.largest_bit_overlap(nums)).to eql(set[:answer])
+      end
+    end
+  end
+end

data/spec/patronus_fati/data_models/access_point_spec.rb

@@ -11,12 +11,27 @@ RSpec.describe(PatronusFati::DataModels::AccessPoint) do
       expect(subject.active_ssids).to be_kind_of(Hash)
     end
 
-    it 'should not include inactive SSIDs' do
+    it 'should not include inactive SSIDs when an active SSID is present' do
+      inactive_ssid = double(PatronusFati::DataModels::Ssid)
+      expect(inactive_ssid).to receive(:active?).and_return(false)
+
+      active_ssid = double(PatronusFati::DataModels::Ssid)
+      expect(active_ssid).to receive(:active?).and_return(true)
+
+      subject.ssids = { tmp: inactive_ssid, tmp2: active_ssid }
+      expect(subject.active_ssids.values).to_not include(inactive_ssid)
+    end
+
+    it 'should include the last inactive SSID when no active SSIDs are present' do
+      presence = double(PatronusFati::Presence)
+      expect(presence).to receive(:last_visible).and_return(Time.now.to_i)
+
       ssid = double(PatronusFati::DataModels::Ssid)
       expect(ssid).to receive(:active?).and_return(false)
+      expect(ssid).to receive(:presence).and_return(presence)
 
       subject.ssids = { tmp: ssid }
-      expect(subject.active_ssids.values).to_not include(ssid)
+      expect(subject.active_ssids.values).to include(ssid)
     end
 
     it 'should include active SSIDs' do
@@ -118,8 +133,8 @@ RSpec.describe(PatronusFati::DataModels::AccessPoint) do
     it 'should include the attributes of active ssids' do
       subject.ssids = {}
       ssid_dbl = double(PatronusFati::DataModels::Ssid)
-      expect(subject).to receive(:active_ssids).and_return({ pnt: ssid_dbl })
-      expect(ssid_dbl).to receive(:local_attributes).and_return('data')
+      expect(subject).to receive(:active_ssids).and_return({ pnt: ssid_dbl }).twice
+      expect(ssid_dbl).to receive(:full_state).and_return('data')
       expect(subject.full_state[:ssids]).to eql(['data'])
     end
   end

data/spec/patronus_fati/data_models/ssid_spec.rb

@@ -5,6 +5,21 @@ RSpec.describe(PatronusFati::DataModels::Ssid) do
 
   it_behaves_like 'a common stateful model'
 
+  context '#full_state' do
+    it 'should include all the local attributes' do
+      expect(subject).to receive(:local_attributes).and_return(test: :data)
+      expect(subject.full_state[:test]).to eql(:data)
+    end
+
+    it 'should include the last time it was seen' do
+      presence_dbl = double(PatronusFati::Presence)
+      expect(presence_dbl).to receive(:last_visible).and_return(1234)
+
+      expect(subject).to receive(:presence).and_return(presence_dbl)
+      expect(subject.full_state[:last_visible]).to eql(1234)
+    end
+  end
+
   context '#initialize' do
     it 'should initialize the local attributes with the essid' do
       expect(subject.local_attributes.keys).to include(:essid)

data/spec/patronus_fati/presence_spec.rb

@@ -28,7 +28,7 @@ RSpec.describe(PatronusFati::Presence) do
 
   context '#rotate_presence' do
     let(:old_window_start) do
-      subject.current_window_start - (2 * PatronusFati::Presence::WINDOW_LENGTH)
+      subject.current_window_start - (2 * PatronusFati::WINDOW_LENGTH)
     end
 
     it 'should not modify the last_presence if we\'re still in the window' do
@@ -71,14 +71,14 @@ RSpec.describe(PatronusFati::Presence) do
 
     it 'should return the time when the last_visible is in the current window' do
       # Note: bit 1 == minute 0, this which is why these two numbers differ
-      time = subject.current_window_start + (22 * PatronusFati::Presence::INTERVAL_DURATION)
+      time = subject.current_window_start + (22 * PatronusFati::INTERVAL_DURATION)
       subject.current_presence.set_bit(23)
       expect(subject.last_visible).to eql(time)
     end
 
     it 'should return the time when the last_visisble is in the last window' do
       # Note: bit 1 == minute 0, this which is why these two numbers differ
-      time = subject.last_window_start + (1 * PatronusFati::Presence::INTERVAL_DURATION)
+      time = subject.last_window_start + (1 * PatronusFati::INTERVAL_DURATION)
       subject.last_presence.set_bit(2)
       expect(subject.last_visible).to eql(time)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: patronus_fati
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Sam Stelfox
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-05 00:00:00.000000000 Z
+date: 2017-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: louis
@@ -142,6 +142,7 @@ files:
 - kismet_configs/patronus_fati_kismet.conf
 - lib/patronus_fati.rb
 - lib/patronus_fati/bit_field.rb
+- lib/patronus_fati/bit_helper.rb
 - lib/patronus_fati/cap_struct.rb
 - lib/patronus_fati/connection.rb
 - lib/patronus_fati/consts.rb
@@ -204,6 +205,7 @@ files:
 - lib/patronus_fati/version.rb
 - patronus_fati.gemspec
 - spec/patronus_fati/bit_field_spec.rb
+- spec/patronus_fati/bit_helper_spec.rb
 - spec/patronus_fati/data_models/access_point_spec.rb
 - spec/patronus_fati/data_models/client_spec.rb
 - spec/patronus_fati/data_models/connection_spec.rb
@@ -232,12 +234,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.10
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: A ruby implementation of the Kismet client protocol.
 test_files:
 - spec/patronus_fati/bit_field_spec.rb
+- spec/patronus_fati/bit_helper_spec.rb
 - spec/patronus_fati/data_models/access_point_spec.rb
 - spec/patronus_fati/data_models/client_spec.rb
 - spec/patronus_fati/data_models/connection_spec.rb