Class: OpenVASOMP::OpenVASOMP

Inherits:
Object
  • Object
show all
Defined in:
lib/openvas-omp.rb

Overview

Core class for OMP communication protocol

Instance Method Summary collapse

Constructor Details

#initialize(p = {}) ⇒ OpenVASOMP

initialize object: try to connect to OpenVAS using URL, user and password

Usage:

ov=OpenVASOMP.new(user=>'user',password=>'pass') 
# default: host=>'localhost', port=>'9390'



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/openvas-omp.rb', line 93

def initialize(p={})
  if p.has_key?("host")
    @host=p["host"]
  else
    @host="localhost"
  end
  if p.has_key?("port")
    @port=p["port"]
  else
    @port=9390
  end
  if p.has_key?("user")
    @user=p["user"]
  else
    @user="openvas"
  end
  if p.has_key?("password")
    @password=p["password"]
  else
    @password="openvas"
  end
  if p.has_key?("bufsize")
    @bufsize=p["bufsize"]
  else
    @bufsize=16384
  end
  if p.has_key?("debug")
    @debug=p["debug"]
  else
    @debug=0
  end
    
  if @debug>3 
    puts "Host: "+@host
    puts "Port: "+@port.to_s()
    puts "User: "+@user
  end
  if @debug>99
    puts "Password: "+@password
  end
  @areq=''
  @read_timeout=3
  if defined? p["noautoconnect"] and not p["noautoconnect"]
    connect()
    if defined? p["noautologin"] and not p["noautologin"]
      ()
    end
  end
end

Instance Method Details

#config_copy(config_id, name) ⇒ Object

OMP - copy config with new name and returns new id

Usage:

new_config_id=config_copy(config_id,“new_name”);



638
639
640
641
642
643
644
645
646
647
648
 
# File 'lib/openvas-omp.rb', line 638

def config_copy (config_id,name)
  xmlreq=xml_attr("create_config",
  {"copy"=>config_id,"name"=>name}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
    id=xr.elements['create_config_response'].attributes['id']
    return id 
  rescue 
    raise OMPResponseError
  end
end

#config_create(name, rcfile) ⇒ Object

OMP - create config with specified RC file and returns new id name = name of new config rcfile = base64 encoded OpenVAS rcfile

Usage:

config_id=config_create(“name”,rcfile);



658
659
660
661
662
663
664
665
666
667
668
 
# File 'lib/openvas-omp.rb', line 658

def config_create (name,rcfile)
  xmlreq=xml_attr("create_config",
  {"name"=>name,"rcfile"=>rcfile}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
    id=xr.elements['create_config_response'].attributes['id']
    return id 
  rescue 
    raise OMPResponseError
  end
end

#config_get(p = {}) ⇒ Object

OMP - get configs and returns hash as response hash=config_name

Usage:

all_configs_hash=ov.config.get()

config_id=ov.config_get().index(“Full and fast”)



616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
 
# File 'lib/openvas-omp.rb', line 616

def config_get (p={})
  begin
    xr=config_get_raw(p)
    list=Hash.new
    xr.elements.each('//get_configs_response/config') do |config|
      id=config.attributes["id"]
      name=config.elements["name"].text
      list[id]=name
    end
    return list 
  rescue 
    raise OMPResponseError
  end
  return false
end

#config_get_all(p = {}) ⇒ Object

OMP - get configs and returns hash as response hash=config_name

Usage:

array_of_hashes=ov.config_get_all()



589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
 
# File 'lib/openvas-omp.rb', line 589

def config_get_all (p={})
  begin
    xr=config_get_raw(p)
    tc=Array.new
    xr.elements.each('//get_configs_response/config') do |config|
      c=Hash.new
      c["id"]=config.attributes["id"]
      c["name"]=config.elements["name"].text
      c["comment"]=config.elements["comment"].text
      tc.push c
    end
    return tc
  rescue 
    raise OMPResponseError
  end
  return false
end

#config_get_raw(p = {}) ⇒ Object

OMP - get configs and returns rexml object as response

Usage:

rexmldocument=ov.config_get_raw()



571
572
573
574
575
576
577
578
579
580
 
# File 'lib/openvas-omp.rb', line 571

def config_get_raw (p={})
  xmlreq=xml_attr("get_configs",p).to_s()
  begin
    xr=omp_request_xml(xmlreq)
    return xr 
  rescue 
    raise OMPResponseError
  end
  return false
end

#connect ⇒ Object

Low level method - Connect to SSL socket

Usage:

ov.connect()



159
160
161
162
163
164
165
 
# File 'lib/openvas-omp.rb', line 159

def connect
  @plain_socket=TCPSocket.open(@host, @port)
  ssl_context = OpenSSL::SSL::SSLContext.new()
  @socket = OpenSSL::SSL::SSLSocket.new(@plain_socket, ssl_context)
  @socket.sync_close = true
  @socket.connect
end

#debug(level) ⇒ Object

Sets debug level

Usage:

ov.debug(3)



149
150
151
 
# File 'lib/openvas-omp.rb', line 149

def debug (level)
  @debug=level
end

#disconnect ⇒ Object

Low level method - Disconnect SSL socket

Usage:

ov.disconnect()



173
174
175
176
177
 
# File 'lib/openvas-omp.rb', line 173

def disconnect
  if @socket
    @socket.close
  end
end

#logged_in ⇒ Object

check if we’re successful logged in if successful returns true if unsuccessful returns false

Usage:

if ov.logged_in() then puts “logged in” end



330
331
332
333
334
335
336
 
# File 'lib/openvas-omp.rb', line 330

def logged_in
  if @areq == ''
    return false
  else
    return true
  end
end

#login ⇒ Object

login to OpenVAS server. if successful returns authentication XML for further usage if unsuccessful returns empty string

Usage:

ov.login()



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/openvas-omp.rb', line 301

def  
  areq="<authenticate>"+xml_ele("credentials", {"username"=>@user, "password"=>@password}).to_s()+"</authenticate>"
  resp=sendrecv(areq+"<HELP/>")
  # wrap it inside tags, so rexml does not complain
  resp = "<X>"+resp+"</X>"

  begin
    docxml = REXML::Document.new(resp)
    status=docxml.root.elements['authenticate_response'].attributes['status'].to_i()
  rescue
    raise XMLParsingError
  end
  if status == 200
    @areq=areq
  else
    raise OMPAuthError  
  end
end

#logout ⇒ Object

logout from OpenVAS server. it actually just sets internal authentication XML to empty str (as in OMP you have to send username/password each time) (i.e. there is no session id)

Usage:

ov.logout()



347
348
349
350
 
# File 'lib/openvas-omp.rb', line 347

def logout
  disconnect()
  @areq = ''
end

#omp_request_raw(request) ⇒ Object

OMP low level method - Send string request wrapped with authentication XML and return response as string

Usage:

ov.request_xml(“<HELP/”)



359
360
361
362
 
# File 'lib/openvas-omp.rb', line 359

def omp_request_raw (request) 
  resp=sendrecv(@areq+request)
  return resp
end

#omp_request_xml(request) ⇒ Object

OMP low level method - Send string request wrapped with authentication XML and return REXML parsed object

Usage:

rexmlobject = ov.request_xml(“<HELP/”)



371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/openvas-omp.rb', line 371

def omp_request_xml (request) 
  resp=sendrecv(@areq+request)
  resp = "<X>"+resp+"</X>"

  begin
    docxml = REXML::Document.new(resp)
    status=docxml.root.elements['authenticate_response'].attributes['status'].to_i
    if status<200 and status>299
      raise OMPAuthError
    end
    return docxml.root
  rescue
    raise XMLParsingError
  end
end

#report_get_all ⇒ Object

OMP - get report all, returns report

Usage:

pdf_content=ov.report_get_all()



529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
 
# File 'lib/openvas-omp.rb', line 529

def report_get_all ()
begin
  xr=report_get_raw("format"=>"NBE")
  list=Array.new
  xr.elements.each('//get_reports_response/report') do |report|
    td=Hash.new
    td["id"]=target.attributes["id"]
    td["name"]=target.elements["name"].text
    td["comment"]=target.elements["comment"].text
    td["hosts"]=target.elements["hosts"].text
    td["max_hosts"]=target.elements["max_hosts"].text
    td["in_use"]=target.elements["in_use"].text
    list.push td
  end
  return list
rescue 
  raise OMPResponseError
end
end

#report_get_byid(id, format) ⇒ Object

OMP - get report by id and format, returns report (already base64 decoded if needed)

format can be: HTML, NBE, PDF, …

Usage:

pdf_content=ov.report_get_byid(id,“PDF”) File.open(‘report.pdf’, ‘w’) {|f| f.write(pdf_content) }



513
514
515
516
517
518
519
520
521
 
# File 'lib/openvas-omp.rb', line 513

def report_get_byid (id,format)
  decode=Array["HTML","NBE","PDF"]
  xr=report_get_raw("report_id"=>id,"format"=>format)
  resp=xr.elements['get_reports_response'].elements['report'].text
  if decode.include?(format) 
    resp=Base64.decode64(resp)
  end
  return resp
end

#report_get_raw(p = {}) ⇒ Object

OMP - get reports and returns raw rexml object as response

Usage:

rexmlobject=ov.report_get_raw(“format”=>“PDF”)

rexmlobject=ov.report_get_raw( “report_id” => “”, “format”=>“PDF”)



493
494
495
496
497
498
499
500
501
 
# File 'lib/openvas-omp.rb', line 493

def report_get_raw (p={})
  xmlreq=xml_attr("get_reports",p).to_s()
  begin
    xr=omp_request_xml(xmlreq)
  rescue 
    raise OMPResponseError
  end
  return xr
end

#result_get_raw(p = {}) ⇒ Object

OMP - get reports and returns raw rexml object as response

Usage:

rexmlobject=ov.result_get_raw(“notes”=>0)



555
556
557
558
559
560
561
562
563
 
# File 'lib/openvas-omp.rb', line 555

def result_get_raw (p={})
begin
  xmlreq=xml_attr("get_results",p).to_s()
  xr=omp_request_xml(xmlreq)
rescue 
  raise OMPResponseError
end
return xr
end

#sendrecv(tosend) ⇒ Object

Low level method: Send request and receive response - socket

Usage:

ov.connect(); puts ov.sendrecv(“<get_version/>”) ov.disconnect();



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
 
# File 'lib/openvas-omp.rb', line 187

def sendrecv (tosend)
  if not @socket
    connect
  end

  if @debug>3 then
    puts "SENDING: "+tosend
  end
  @socket.puts(tosend)

  @rbuf=''
  size=0
  begin  
    begin
    timeout(@read_timeout) {
        a = @socket.sysread(@bufsize)
        size=a.length
        # puts "sysread #{size} bytes"
        @rbuf << a
    }
    rescue Timeout::Error
      size=0
    rescue EOFError
      raise OMPResponseError
    end
  end while size>=@bufsize
  response=@rbuf
  
  if @debug>3 then
    puts "RECEIVED: "+response
  end
  return response
end

#target_create(p = {}) ⇒ Object

OMP - Create target for scanning

Usage:

target_id = ov.target_create(“name”=>“localhost”, “hosts”=>“127.0.0.1”,“comment”=>“yes”)



394
395
396
397
398
399
400
401
402
403
404
 
# File 'lib/openvas-omp.rb', line 394

def target_create (p={})
  xmlreq=xml_ele("create_target", p).to_s()

  begin
    xr=omp_request_xml(xmlreq)
    id=xr.elements['create_target_response'].attributes['id']
  rescue 
    raise OMPResponseError
  end
  return id
end

#target_delete(id) ⇒ Object

OMP - Delete target

Usage:

ov.target_delete(target_id)



412
413
414
415
416
417
418
419
420
 
# File 'lib/openvas-omp.rb', line 412

def target_delete (id) 
  xmlreq=xml_attr("delete_target",{"target_id" => id}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
  rescue 
    raise OMPResponseError
  end
  return xr
end

#target_get_all(p = {}) ⇒ Object

OMP - Get all targets for scanning and returns array of hashes with following keys: id,name,comment,hosts,max_hosts,in_use

Usage: array_of_hashes = target_get_all()



444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/openvas-omp.rb', line 444

def target_get_all (p={})
  begin
    xr=target_get_raw(p)
    list=Array.new
    xr.elements.each('//get_targets_response/target') do |target|
      td=Hash.new
      td["id"]=target.attributes["id"]
      td["name"]=target.elements["name"].text
      td["comment"]=target.elements["comment"].text
      td["hosts"]=target.elements["hosts"].text
      td["max_hosts"]=target.elements["max_hosts"].text
      td["in_use"]=target.elements["in_use"].text
      list.push td
    end
    return list
  rescue 
    raise OMPResponseError
  end
end

#target_get_byid(id) ⇒ Object 



464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/openvas-omp.rb', line 464

def target_get_byid (id)
  begin
  xr=target_get_raw("target_id"=>id)
  xr.elements.each('//get_targets_response/target') do |target|
    td=Hash.new
    td["id"]=target.attributes["id"]
    td["name"]=target.elements["name"].text
    td["comment"]=target.elements["comment"].text
    td["hosts"]=target.elements["hosts"].text
    td["max_hosts"]=target.elements["max_hosts"].text
    td["in_use"]=target.elements["in_use"].text
    return td
  end
  return list
  rescue 
    raise OMPResponseError
  end
end

#target_get_raw(p = {}) ⇒ Object

OMP - Get target for scanning and returns rexml object

Usage: rexmlobject = target_get_raw(“target_id”=>target_id)



427
428
429
430
431
432
433
434
435
436
 
# File 'lib/openvas-omp.rb', line 427

def target_get_raw (p={})
  xmlreq=xml_attr("get_targets", p).to_s()

  begin
    xr=omp_request_xml(xmlreq)
    return xr
  rescue 
    raise OMPResponseError
  end
end

#task_create(p = {}) ⇒ Object

OMP - creates task and returns id of created task

parameters = name,comment,rcfile,config,target,escalator, schedule

Usage:

config_id=o.config_get().index(“Full and fast”) target_id=o.target_create( “hosts”=>“127.0.0.1”, “comment”=>“t”) task_id=ov.task_create( “target”=>target_id, “config”=>config_id



705
706
707
708
709
710
711
712
713
714
715
 
# File 'lib/openvas-omp.rb', line 705

def task_create (p={}) 
  specials=Array["config","target","escalator","schedule"] 
  ids = Hash.new
  specials.each do |spec|
    if p.has_key?(spec)
      ids[spec]=p[spec]  
      p.delete(spec)
    end 
  end
  return task_create_raw(p,ids)
end

#task_create_raw(p = {}, i = {}) ⇒ Object

OMP - creates task and returns id of created task

Parameters which usually fit in p hash and i hash: p = name,comment,rcfile i = config,target,escalator,schedule

Usage:

task_id=ov.task_create_raw()



680
681
682
683
684
685
686
687
688
689
 
# File 'lib/openvas-omp.rb', line 680

def task_create_raw (p={}, i={}) 
  xmlreq=xml_mix("create_task",p,"id",i).to_s()
  begin
    xr=omp_request_xml(xmlreq)
    id=xr.elements['create_task_response'].attributes['id']
    return id
  rescue 
    raise OMPResponseError
  end
end

#task_delete(task_id) ⇒ Object

OMP - deletes task specified by task_id

Usage:

ov.task_delete(task_id)



723
724
725
726
727
728
729
730
731
 
# File 'lib/openvas-omp.rb', line 723

def task_delete (task_id) 
  xmlreq=xml_attr("delete_task",{"task_id" => task_id}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
  rescue 
    raise OMPResponseError
  end
  return xr
end

#task_finished(id) ⇒ Object

OMP - check if task specified by task_id is finished (it checks if task status is “Done” in OMP)

Usage:

if ov.task_finished(task_id) puts “Task finished” end



822
823
824
825
826
827
828
829
830
831
 
# File 'lib/openvas-omp.rb', line 822

def task_finished (id) 
  xr=task_get_raw("task_id"=>id,"details"=>0)
  xr.elements.each('//get_tasks_response/task') do |task|
    if status=task.elements["status"].text == "Done"
      return true
    else
      return false
    end
  end
end

#task_get_all(p = {}) ⇒ Object

OMP - get all tasks and returns array with hashes with following content: id,name,comment,status,progress,first_report,last_report

Usage:

array_of_hashes=ov.task_get_all()



757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
 
# File 'lib/openvas-omp.rb', line 757

def task_get_all (p={}) 
  xr=task_get_raw(p)
  t=Array.new
  xr.elements.each('//get_tasks_response/task') do |task|
    td=Hash.new
    td["id"]=task.attributes["id"]
    td["name"]=task.elements["name"].text
    td["comment"]=task.elements["comment"].text
    td["status"]=task.elements["status"].text
    td["progress"]=task.elements["progress"].text
    if defined? task.elements["first_report"].elements["report"].attributes["id"] then
    td["firstreport"]=task.elements["first_report"].elements["report"].attributes["id"]
    else
      td["firstreport"]=nil
    end
    if defined? task.elements["last_report"].elements["report"].attributes["id"] then
    td["lastreport"]=task.elements["last_report"].elements["report"].attributes["id"] 
    else
      td["lastreport"]=nil
    end
    t.push td 
  end
  return t
end

#task_get_byid(id) ⇒ Object

OMP - get task specified by task_id and returns hash with following content: id,name,comment,status,progress,first_report,last_report

Usage:

hash=ov.task_get_byid(task_id)



790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
 
# File 'lib/openvas-omp.rb', line 790

def task_get_byid (id) 
  xr=task_get_raw("task_id"=>id,"details"=>0)
  xr.elements.each('//get_tasks_response/task') do |task|
    td=Hash.new
    td["id"]=task.attributes["id"]
    td["name"]=task.elements["name"].text
    td["comment"]=task.elements["comment"].text
    td["status"]=task.elements["status"].text
    td["progress"]=task.elements["progress"].text
    if defined? task.elements["first_report"].elements["report"].attributes["id"] then
    td["firstreport"]=task.elements["first_report"].elements["report"].attributes["id"]
    else
      td["firstreport"]=nil
    end
    if defined? task.elements["last_report"].elements["report"].attributes["id"] then
    td["lastreport"]=task.elements["last_report"].elements["report"].attributes["id"] 
    else
      td["lastreport"]=nil
    end
    return (td)
  end
end

#task_get_raw(p = {}) ⇒ Object

OMP - get task and returns raw rexml object as response

Usage:

rexmlobject=ov.task_get_raw(“details”=>“0”)



739
740
741
742
743
744
745
746
747
 
# File 'lib/openvas-omp.rb', line 739

def task_get_raw (p={}) 
  xmlreq=xml_attr("get_tasks",p).to_s()
  begin
    xr=omp_request_xml(xmlreq)
    return xr
  rescue 
    raise OMPResponseError
  end
end

#task_pause(task_id) ⇒ Object

OMP - pauses task specified by task_id

Usage:

ov.task_pause(task_id)



886
887
888
889
890
891
892
893
894
 
# File 'lib/openvas-omp.rb', line 886

def task_pause (task_id)
  xmlreq=xml_attr("pause_task",{"task_id" => task_id}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
  rescue 
    raise OMPResponseError
  end
  return xr
end

#task_progress(id) ⇒ Object

OMP - check progress of task specified by task_id (OMP returns -1 if task is finished, not started, etc)

Usage:

print “Progress: ” puts ov.task_progress(task_id)



841
842
843
844
845
846
 
# File 'lib/openvas-omp.rb', line 841

def task_progress (id) 
  xr=task_get_raw("task_id"=>id,"details"=>0)
  xr.elements.each('//get_tasks_response/task') do |task|
    return task.elements["progress"].text.to_i()
  end
end

#task_resume_or_start(task_id) ⇒ Object

OMP - resumes (or starts) task specified by task_id

Usage:

ov.task_resume_or_start(task_id)



902
903
904
905
906
907
908
909
910
 
# File 'lib/openvas-omp.rb', line 902

def task_resume_or_start (task_id)
  xmlreq=xml_attr("resume_or_start_task",{"task_id" => task_id}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
  rescue 
    raise OMPResponseError
  end
  return xr
end

#task_start(task_id) ⇒ Object

OMP - starts task specified by task_id

Usage:

ov.task_start(task_id)



854
855
856
857
858
859
860
861
862
 
# File 'lib/openvas-omp.rb', line 854

def task_start (task_id) 
  xmlreq=xml_attr("start_task",{"task_id" => task_id}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
  rescue 
    raise OMPResponseError
  end
  return xr
end

#task_stop(task_id) ⇒ Object

OMP - stops task specified by task_id

Usage:

ov.task_stop(task_id)



870
871
872
873
874
875
876
877
878
 
# File 'lib/openvas-omp.rb', line 870

def task_stop (task_id) 
  xmlreq=xml_attr("stop_task",{"task_id" => task_id}).to_s()
  begin
    xr=omp_request_xml(xmlreq)
  rescue 
    raise OMPResponseError
  end
  return xr
end

#version_get ⇒ Object

get OMP version (you don’t need to be authenticated)

Usage:

ov.version_get()



227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/openvas-omp.rb', line 227

def version_get 
  vreq="<get_version/>"  
  resp=sendrecv(vreq)  
  resp = "<X>"+resp+"</X>"
  begin
    docxml = REXML::Document.new(resp)
    version=''
    version=docxml.root.elements['get_version_response'].elements['version'].text
    return version
  rescue
    raise XMLParsingError 
  end
end

#xml_attr(name, opts = {}) ⇒ Object

produce single XML element with attributes specified as hash low-level function

Usage:

ov.xml_attr()



248
249
250
251
252
253
254
 
# File 'lib/openvas-omp.rb', line 248

def xml_attr(name, opts={})
  xml = REXML::Element.new(name)
  opts.keys.each do |k|
    xml.attributes[k] = opts[k]
  end
  return xml
end

#xml_ele(name, child = {}) ⇒ Object

produce multiple XML elements with text specified as hash low-level function

Usage:

ov.xml_ele()



263
264
265
266
267
268
269
270
 
# File 'lib/openvas-omp.rb', line 263

def xml_ele(name, child={})
  xml = REXML::Element.new(name)
  child.keys.each do |k|
    xml.add_element(k)
    xml.elements[k].text = child[k]
  end
  return xml
end

#xml_mix(name, child, attr, elem) ⇒ Object

produce multiple XML elements with text specified as hash also produce multiple XML elements with attributes low-level function

Usage:

ov.xml_mix()



280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/openvas-omp.rb', line 280

def xml_mix(name, child, attr, elem)
  xml = REXML::Element.new(name)
  child.keys.each do |k|
    xml.add_element(k)
    xml.elements[k].text = child[k]
  end
  elem.keys.each do |k|
    xml.add_element(k)
    xml.elements[k].attributes[attr] = elem[k]
  end
  return xml
end