class OpenVASOMP::OpenVASOMP
Core class for OMP communication protocol
Public Class Methods
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'
# 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"] login() end end end
Public Instance Methods
OMP - copy config with new name and returns new id
Usage:
new_config_id=config_copy(config_id,“new_name”);
# 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
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);
# 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
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”)
# 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
OMP - get configs and returns hash as response hash=config_name
Usage:
array_of_hashes=ov.config_get_all()
# 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
OMP - get configs and returns rexml object as response
Usage:
rexmldocument=ov.config_get_raw()
# 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
Low level method - Connect to SSL socket
Usage:
ov.connect()
# 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
Sets debug level
Usage:
ov.debug(3)
# File lib/openvas-omp.rb, line 149 def debug (level) @debug=level end
Low level method - Disconnect SSL socket
Usage:
ov.disconnect()
# File lib/openvas-omp.rb, line 173 def disconnect if @socket @socket.close end end
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
# File lib/openvas-omp.rb, line 330 def logged_in if @areq == '' return false else return true end end
login to OpenVAS server. if successful returns authentication XML for further usage if unsuccessful returns empty string
Usage:
ov.login()
# File lib/openvas-omp.rb, line 301 def login 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 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()
# File lib/openvas-omp.rb, line 347 def logout disconnect() @areq = '' end
OMP low level method - Send string request wrapped with authentication XML and return response as string
Usage:
ov.request_xml(“<HELP/”)
# File lib/openvas-omp.rb, line 359 def omp_request_raw (request) resp=sendrecv(@areq+request) return resp end
OMP low level method - Send string request wrapped with authentication XML and return REXML parsed object
Usage:
rexmlobject = ov.request_xml(“<HELP/”)
# 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
OMP - get report all, returns report
Usage:
pdf_content=ov.report_get_all()
# 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
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) }
# 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
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")
# 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
OMP - get reports and returns raw rexml object as response
Usage:
rexmlobject=ov.result_get_raw(“notes”=>0)
# 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
Low level method: Send request and receive response - socket
Usage:
ov.connect(); puts ov.sendrecv(“<get_version/>”) ov.disconnect();
# 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
OMP - Create target for scanning
Usage:
target_id = ov.target_create(“name”=>“localhost”,
"hosts"=>"127.0.0.1","comment"=>"yes")
# 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
OMP - Delete target
Usage:
ov.target_delete(target_id)
# 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
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
()
# 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
# 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
OMP - Get target for scanning and returns rexml object
Usage: rexmlobject = target_get_raw
(“target_id”=>target_id)
# 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
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( {“name”=>“localtarget”, “hosts”=>“127.0.0.1”, “comment”=>“t”}) task_id=ov.task_create( {“name”=>“testlocal”,“comment”=>“test”, “target”=>target_id, “config”=>config_id}
# 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
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()
# 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
OMP - deletes task specified by task_id
Usage:
ov.task_delete(task_id)
# 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
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
# 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
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()
# 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
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)
# 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
OMP - get task and returns raw rexml object as response
Usage:
rexmlobject=ov.task_get_raw(“details”=>“0”)
# 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
OMP - pauses task specified by task_id
Usage:
ov.task_pause(task_id)
# 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
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)
# 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
OMP - resumes (or starts) task specified by task_id
Usage:
ov.task_resume_or_start(task_id)
# 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
OMP - starts task specified by task_id
Usage:
ov.task_start(task_id)
# 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
OMP - stops task specified by task_id
Usage:
ov.task_stop(task_id)
# 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
get OMP version (you don’t need to be authenticated)
Usage:
ov.version_get()
# 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
produce single XML element with attributes specified as hash low-level function
Usage:
ov.xml_attr()
# 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
produce multiple XML elements with text specified as hash low-level function
Usage:
ov.xml_ele()
# 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
produce multiple XML elements with text specified as hash also produce multiple XML elements with attributes low-level function
Usage:
ov.xml_mix()
# 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