= Ruby-Nessus

== Description

Ruby-Nessus is a ruby interface for the popular Nessus vulnerability scanner. Ruby-Nessus aims to deliver an easy yet powerful interface for interacting and manipulating Nessus scan results and configurations. Please remember to submit bugs and request features if needed.

More Information:
* Documentation: http://rdoc.info/projects/mephux/ruby-nessus

== Install

Make sure you have gemcutter installed.

  sudo gem update --system
  sudo gem install gemcutter
  gem tumble

Then install Ruby-Nessus

  sudo gem install ruby-nessus

== Usage & Examples

The below example illustrates how easy it really is to iterate of result data.

  require 'ruby-nessus'

  Nessus::XML.new("example.nessus") do |scan|
    puts scan.report_name               # The Nessus Report Title.
    puts scan.runtime                   # The Scan Runtime. #=> 2 hours 23 minutes 12 seconds
    puts scan.host_count                # Host Count.
    puts scan.unique_ports              # All Unique Ports Seen.

    scan.hosts do |host|
      next if host.event_count.zero?    # Next Host If Event Count Is Zero.
      puts host.hostname                # The HostName For The Current Host.
      puts host.event_count             # The Event Count For The Current Host.

      host.events do |event|
        next if event.severity.medium?  # Next Event Is The Event Severity Is Low. (supports high? medium? low?)
        puts event.name if event.name   # The Event Name If Not Blank.
        puts event.port                 # The Event Port. (supports .number, .protocol and .service)
        puts event.severity.in_words    # The Current Event Severity In Words. i.e "High Severity"
        puts event.plugin_id            # The Nessus Plugin ID.
        puts event.data if event.data   # Raw Nessus Plugin Output Data.
      end
    end
  end


You also have the ability to search for particular hostnames. In the near future I plan to add the ability to pass the hosts block a hash of options for more complex searches.

  scan.find_by_hostname("127.0.0.1") do |host|
    
    puts host.scan_start_time
    puts host.scan_stop_time
    puts host.scan_runtime
    
    host.events do |event|
      puts event.severity.in_words
      puts event.port
      puts event.output
    end
    
  end


There are a bunch of convenient methods added to make reporting a bit easier to produce quickly from a raw scan file.

  Nessus::XML.new("blah.nessus") do |scan|

    puts scan.event_percentage_for('low', true) #=> 8%

    puts scan.high_severity_count           # High Severity Event Count
    puts scan.medium_severity_count         # Medium Severity Event Count
    puts scan.low_severity_count            # Low Severity Event Count
    puts scan.informational_severity_count  # Informational Event Count

    puts scan.total_event_count #=> 3411    # Total Event Count
    puts scan.hosts.count #=> 12

    puts scan.policy_name
    puts scan.policy_comments unless scan.policy_comments.empty?
    
    scan.hosts do |host|
      puts host.hostname
        
      # high_severity_events, medium_severity_events and low_severity_events
      host.high_severity_events do |high|
        puts high.port
        puts high.name if high.name
        puts high.data if high.data
      end
      
    end
    
  end
  
== Requirements
* Ruby 1.8 or 1.9
* Nokogiri http://github.com/tenderlove/nokogiri

== Todo
* Add The Ability to parse the scan configuration and plugin options.
* Building XML (.nessus) files configurations
* Add Support For NBE File Formats.
* Add Complex Searching. 

== Note on Patches & Pull Requests 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

== Props

Huge props to postmodern for helping me refactor! Check out his projects:
* http://github.com/postmodern

== Copyright

Copyright (c) 2009 Dustin Willis Webber. See LICENSE for details.