Class: LogStash::Filters::Phpipam

Inherits:
Base
  • Object
show all
Defined in:
lib/logstash/filters/phpipam.rb

Overview

A Logstash filter that looks up an IP-address, and returns results from phpIPAM

Instance Method Summary collapse

Instance Method Details

#close ⇒ Object 



64
65
66
67
68
69
70
71
 
# File 'lib/logstash/filters/phpipam.rb', line 64

def close
  # Persist the database to disk, when the pipeline ends
  @cs_ip.bgsave
  @cs_subnet.bgsave
  @cs_vlan.bgsave
  @cs_device.bgsave
  @cs_location.bgsave
end

#filter(event) ⇒ Object 



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/logstash/filters/phpipam.rb', line 73

def filter(event)
  ip = event.get(@source)

  return if ip.nil?

  return unless valid_ip?(ip, event)

  # Get the data
  event_data = phpipam_data(ip)

  # Tag and return if no IP was found
  if event_data.nil?
    event.tag('_phpipam_ip_not_found')
    return
  end

  # Set the data to the target path
  event.set(@target, event_data)

  # filter_matched should go in the last line of our successful code
  filter_matched(event)
end

#nil_or_empty?(value) ⇒ bool

Checks whether the value is nil or empty

Parameters:

  • value: —

    a value to check

Returns:

  • (bool) 


176
177
178
 
# File 'lib/logstash/filters/phpipam.rb', line 176

def nil_or_empty?(value)
  value.nil? || value.empty?
end

#normalize_target(target) ⇒ string

make sure @target is in the format [field name] if defined, i.e. not empty and surrounded by brakets

Parameters:

  • target: —

    the target to normalize

Returns:

  • (string) 


100
101
102
103
 
# File 'lib/logstash/filters/phpipam.rb', line 100

def normalize_target(target)
  target = "[#{target}]" if target !~ %r{^\[[^\[\]]+\]$}
  target
end

#phpipam_data(ip) ⇒ hash/nil

Get phpIPAM data either from cache or phpIPAM. If data was found from phpIPAM, it will cache it for future needs. If the data wasn’t found in either cache or phpIPAM, nil is returned.

Parameters:

  • ip —

    • IP-address to lookup

Returns:

  • (hash/nil) 


185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/logstash/filters/phpipam.rb', line 185

def phpipam_data(ip)
  # Base hash to format data in
  base = {
    'ip'       => {},
    'subnet'   => {},
    'vlan'     => {},
    'device'   => {},
    'location' => {},
  }

  # If 0 is returned, it has been cached as non-existent
  return nil if @cs_ip.get(ip) == '0'

  ## IP LOOKUP ##
  if @cs_ip.get(ip).nil?
    ip_data = send_rest_request('GET', "api/#{@app_id}/addresses/search/#{ip}/")

    # Return and cache 0 for this IP, if it wasn't found in phpIPAM
    if ip_data.nil?
      @cs_ip.set(ip, '0', ex: @cache_freshness)
      return nil
    end

    # IP information
    base['ip']['id']          = ip_data['id'].to_i
    base['ip']['address']     = ip_data['ip']
    base['ip']['description'] = ip_data['description'] unless nil_or_empty?(ip_data['description'])
    base['ip']['hostname']    = ip_data['hostname'] unless nil_or_empty?(ip_data['hostname'])
    base['ip']['mac']         = ip_data['mac'] unless nil_or_empty?(ip_data['mac'])
    base['ip']['note']        = ip_data['note'] unless nil_or_empty?(ip_data['note'])
    base['ip']['owner']       = ip_data['owner'] unless nil_or_empty?(ip_data['owner'])

    # Get all the ID's
    base['ip']['subnet_id']   = ip_data['subnetId'].to_i
    base['ip']['device_id']   = ip_data['deviceId'].to_i
    base['ip']['location_id'] = ip_data['location'].to_i

    @cs_ip.set(ip, base['ip'].to_json, ex: @cache_freshness)
  else
    base['ip'] = JSON.parse(@cs_ip.get(ip))
  end

  ## SUBNET LOOKUP ##
  subnet_id = base['ip']['subnet_id']

  # If 0 is returned, it doesn't exist. Only lookup if a nonzero value is returned
  if subnet_id.positive?
    if @cs_subnet.get(subnet_id).nil?
      subnet_data = send_rest_request('GET', "api/#{@app_id}/subnets/#{subnet_id}/")

      # Subnet data
      base['subnet']['id']         = subnet_id
      base['subnet']['section_id'] = subnet_data['sectionId'].to_i
      base['subnet']['bitmask']    = subnet_data['calculation']['Subnet bitmask'].to_i
      base['subnet']['wildcard']   = subnet_data['calculation']['Subnet wildcard']
      base['subnet']['netmask']    = subnet_data['calculation']['Subnet netmask']
      base['subnet']['network']    = subnet_data['calculation']['Network']

      # Get VLAN id and location _id
      base['subnet']['vlan_id']     = subnet_data['vlanId'].to_i
      base['subnet']['location_id'] = subnet_data['location'].to_i

      @cs_subnet.set(subnet_id, base['subnet'].to_json, ex: @cache_freshness)
    else
      base['subnet'] = JSON.parse(@cs_subnet.get(subnet_id))
    end
  end

  ## VLAN LOOKUP ##
  vlan_id = base['subnet']['vlan_id']

  # If 0 is returned, it doesn't exist. Only lookup if a nonzero value is returned
  if vlan_id.positive?
    if @cs_vlan.get(vlan_id).nil?
      vlan_data = send_rest_request('GET', "api/#{@app_id}/vlans/#{vlan_id}/")

      # VLAN data
      base['vlan']['id']          = vlan_id
      base['vlan']['domain_id']   = vlan_data['domainId'].to_i
      base['vlan']['number']      = vlan_data['number'].to_i unless nil_or_empty?(vlan_data['number'])
      base['vlan']['name']        = vlan_data['name'] unless nil_or_empty?(vlan_data['name'])
      base['vlan']['description'] = vlan_data['description'] unless nil_or_empty?(vlan_data['description'])

      @cs_vlan.set(vlan_id, base['vlan'].to_json, ex: @cache_freshness)
    else
      base['vlan'] = JSON.parse(@cs_vlan.get(vlan_id))
    end
  end

  ## DEVICE LOOKUP ##
  device_id = base['ip']['device_id']

  # If 0 is returned, it doesn't exist. Only lookup if a nonzero value is returned
  if device_id.positive?
    if @cs_device.get(device_id).nil?
      device_data = send_rest_request('GET', "api/#{@app_id}/tools/devices/#{device_id}/")

      # Device data
      type = send_rest_request('GET', "api/#{@app_id}/tools/device_types/#{device_data['type']}/")

      base['device']['id']          = device_id
      base['device']['name']        = device_data['hostname'] unless nil_or_empty?(device_data['hostname'])
      base['device']['description'] = device_data['description'] unless nil_or_empty?(device_data['description'])
      base['device']['type']        = type['tname'] unless nil_or_empty?(type['tname'])

      # Get device location
      base['device']['location_id'] = device_data['location'].to_i

      @cs_device.set(device_id, base['device'].to_json, ex: @cache_freshness)
    else
      base['device'] = JSON.parse(@cs_device.get(device_id))
    end
  end

  ## LOCATION LOOKUP ##
  # Get the first positive location_id from the list
  location_id = [base['ip']['location_id'], base['device']['location_id'], base['subnet']['location_id']].select { |num|
    !num.nil? && num.positive?
  }[0] || 0

  # If 0 is returned, it doesn't exist. Only lookup if a nonzero value is returned
  if location_id.positive?
    if @cs_location.get(location_id).nil?
      location_data = send_rest_request('GET', "api/#{@app_id}/tools/locations/#{location_id}/")

      # Location  data
      base['location']['id']          = location_id
      base['location']['address']     = location_data['address'] unless nil_or_empty?(location_data['address'])
      base['location']['name']        = location_data['name'] unless nil_or_empty?(location_data['name'])
      base['location']['description'] = location_data['description'] unless nil_or_empty?(location_data['description'])
      base['location']['location']    = { 'lat' => location_data['lat'].to_f, 'lon' => location_data['long'].to_f } unless nil_or_empty?(location_data['lat'])

      @cs_location.set(location_id, base['location'].to_json, ex: @cache_freshness)
    else
      base['location'] = JSON.parse(@cs_location.get(location_id))
    end
  end

  # Clean-up keys that aren't needed in the final Logstash output
  base['ip'].delete('subnet_id')
  base['ip'].delete('device_id')
  base['ip'].delete('location_id')
  base['subnet'].delete('vlan_id')
  base['subnet'].delete('location_id')
  base['device'].delete('location_id')
  base.delete_if { |_, val| val.empty? }

  # all your base are belong to us
  base
end

#register ⇒ Object

Raises:

  • (LogStash::ConfigurationError) 


45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/logstash/filters/phpipam.rb', line 45

def register
  # Validate auth
  raise LogStash::ConfigurationError, 'Authentication was enabled, but no user/pass found' if @auth && (@username.empty? || @password.empty?)

  # Get a session token
  @token = send_rest_request('POST', "api/#{@app_id}/user/")['token'] if @auth

  # Normalize target
  @target = normalize_target(@target)

  @cache_freshness = @cache_freshness.to_i

  @cs_ip       = Redis.new(db: @cache_ip, id: 'logstash-filter-phpipam')
  @cs_subnet   = Redis.new(db: @cache_subnet, id: 'logstash-filter-phpipam')
  @cs_vlan     = Redis.new(db: @cache_vlan, id: 'logstash-filter-phpipam')
  @cs_device   = Redis.new(db: @cache_device, id: 'logstash-filter-phpipam')
  @cs_location = Redis.new(db: @cache_location, id: 'logstash-filter-phpipam')
end

#send_rest_request(method, url_path) ⇒ hash/nil

Sends a GET method REST request. Returns nil if no data/an error was found

Parameters:

  • method: —

    which HTTP method to use (POST, GET)

  • url_path: —

    path to connect to

Returns:

  • (hash/nil)

Raises:

  • (LogStash::ConfigurationError) 


126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/logstash/filters/phpipam.rb', line 126

def send_rest_request(method, url_path)
  @logger.debug? && @logger.debug('Sending request', host: @host, path: url_path)

  url = URI("#{@host}/#{url_path}")

  http             = Net::HTTP.new(url.host, url.port)
  http.use_ssl     = url.scheme == 'https'
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = case method
            when 'POST' then Net::HTTP::Post.new(url)
            when 'GET' then Net::HTTP::Get.new(url)
            end

  request['accept']        = 'application/json'
  request['content-type']  = 'application/json'
  request['phpipam-token'] = @token unless @token.nil?
  request.basic_auth(@username, @password) if @token.nil? && @auth

  begin
    response = http.request(request)
  rescue StandardError
    raise LogStash::ConfigurationError, I18n.t(
      'logstash.runner.configuration.invalid_plugin_register',
      plugin: 'filter',
      type:   'phpipam',
      error:  'Could not connect to configured host',
    )
  end

  # Parse the body
  rsp = JSON.parse(response.body)

  # Raise an error if not a code 200 is returned
  raise LogStash::ConfigurationError, "#{rsp['code']}:#{rsp['message']}" if rsp['code'] != 200

  # Return nil if no data field is present, else return the data
  rsp = if rsp['data'].nil?
          nil
        else
          rsp['data'].is_a?(Array) ? rsp['data'][0] : rsp['data']
        end

  @logger.debug? && @logger.debug('Got response', body: response.body, data: rsp)
  rsp
end

#valid_ip?(ip, event) ⇒ bool

Validates a IP-address

Parameters:

  • ip: —

    an IP-address

  • event: —

    The Logstash event variable

Returns:

  • (bool) 


109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/logstash/filters/phpipam.rb', line 109

def valid_ip?(ip, event)
  IPAddr.new(ip)

  @logger.debug? && @logger.debug('Valid IP', ip: ip)

  # Return true. Rescue would take over if a non-valid IP was parsed
  true
rescue StandardError
  @logger.debug? && @logger.debug('NOT a valid IP', ip: ip)
  event.tag('_phpipam_invalid_ip')
  false
end