nexpose 0.6.5 → 0.7.0

data/lib/nexpose/silo_profile.rb

@@ -0,0 +1,239 @@
+module Nexpose
+
+  class Connection
+    include XMLUtils
+
+    # Retrieve a list of all silos the user is authorized to view or manage.
+    #
+    # @return [Array[SiloProfileSummary]] Array of SiloSummary objects.
+    #
+    def list_silo_profiles
+      r = execute(make_xml('SiloProfileListingRequest'), '1.2')
+      arr = []
+      if r.success
+        r.res.elements.each('SiloProfileListingResponse/SiloProfileSummaries/SiloProfileSummary') do |profile|
+          arr << SiloProfileSummary.parse(profile)
+        end
+      end
+      arr
+    end
+
+    alias_method :silo_profiles, :list_silo_profiles
+
+    # Delete the specified silo profile
+    #
+    # @return Whether or not the delete request succeeded.
+    #
+    def delete_silo_profile(silo_profile_id)
+      r = execute(make_xml('SiloProfileDeleteRequest', {'silo-profile-id' => silo_profile_id}), '1.2')
+      r.success
+    end
+  end
+
+  class SiloProfile
+    attr_accessor :id
+    attr_accessor :name
+    attr_accessor :description
+    attr_accessor :all_licensed_modules
+    attr_accessor :all_global_engines
+    attr_accessor :all_global_report_templates
+    attr_accessor :all_global_scan_templates
+    attr_accessor :global_report_templates
+    attr_accessor :global_scan_engines
+    attr_accessor :global_scan_templates
+    attr_accessor :licensed_modules
+    attr_accessor :restricted_report_formats
+    attr_accessor :restricted_report_sections
+
+    def initialize(&block)
+      instance_eval &block if block_given?
+      @global_report_templates = Array(@global_report_templates)
+      @global_scan_engines = Array(@global_scan_engines)
+      @global_scan_templates = Array(@global_scan_templates)
+      @licensed_modules = Array(@licensed_modules)
+      @restricted_report_formats = Array(@restricted_report_formats)
+      @restricted_report_sections = Array(@restricted_report_sections)
+    end
+
+    def self.copy(connection, id)
+      profile = load(connection, id)
+      profile.id = nil
+      profile.name = nil
+      profile
+    end
+
+    def self.load(connection, id)
+      r = connection.execute(connection.make_xml('SiloProfileConfigRequest', {'silo-profile-id' => id}), '1.2')
+
+      if r.success
+        r.res.elements.each('SiloProfileConfigResponse/SiloProfileConfig') do |config|
+          return SiloProfile.parse(config)
+        end
+      end
+      nil
+    end
+
+    def self.parse(xml)
+      new do |profile|
+        profile.id = xml.attributes['id']
+        profile.name = xml.attributes['name']
+        profile.description = xml.attributes['description']
+        profile.all_licensed_modules = xml.attributes['all-licensed-modules'].to_s.chomp.eql?('true')
+        profile.all_global_engines = xml.attributes['all-global-engines'].to_s.chomp.eql?('true')
+        profile.all_global_report_templates = xml.attributes['all-global-report-templates'].to_s.chomp.eql?('true')
+        profile.all_global_scan_templates = xml.attributes['all-global-scan-templates'].to_s.chomp.eql?('true')
+
+        profile.global_report_templates = []
+        xml.elements.each('GlobalReportTemplates/GlobalReportTemplate') { |template| profile.global_report_templates << template.attributes['name'] }
+
+        profile.global_scan_engines = []
+        xml.elements.each('GlobalScanEngines/GlobalScanEngine') { |engine| profile.global_scan_engines << engine.attributes['name'] }
+
+        profile.global_scan_templates = []
+        xml.elements.each('GlobalScanTemplates/GlobalScanTemplate') { |template| profile.global_scan_templates << template.attributes['name'] }
+
+        profile.licensed_modules = []
+        xml.elements.each('LicensedModules/LicensedModule') { |license_module| profile.licensed_modules << license_module.attributes['name'] }
+
+        profile.restricted_report_formats = []
+        xml.elements.each('RestrictedReportFormats/RestrictedReportFormat') { |format| profile.restricted_report_formats << format.attributes['name'] }
+
+        profile.restricted_report_sections = []
+        xml.elements.each('RestrictedReportSections/RestrictedReportSection') { |section| profile.restricted_report_sections << section.attributes['name'] }
+      end
+    end
+
+    def save(connection)
+      begin
+        update(connection)
+      rescue APIError => error
+        raise error unless (error.message =~ /A silo profile .* does not exist./)
+        create(connection)
+      end
+    end
+
+    # Updates an existing silo profile on a Nexpose console.
+    #
+    # @param [Connection] connection Connection to console where this silo profile will be saved.
+    # @return [String] Silo Profile ID assigned to this configuration, if successful.
+    #
+    def update(connection)
+      xml = connection.make_xml('SiloProfileUpdateRequest')
+      xml.add_element(as_xml)
+      r = connection.execute(xml, '1.2')
+      @id = r.attributes['silo-profile-id'] if r.success
+    end
+
+    # Saves a new silo profile to a Nexpose console.
+    #
+    # @param [Connection] connection Connection to console where this silo profile will be saved.
+    # @return [String] Silo Profile ID assigned to this configuration, if successful.
+    #
+    def create(connection)
+      xml = connection.make_xml('SiloProfileCreateRequest')
+      xml.add_element(as_xml)
+      r = connection.execute(xml, '1.2')
+      @id = r.attributes['silo-profile-id'] if r.success
+    end
+
+    def delete(connection)
+      connection.delete_silo_profile(@id)
+    end
+
+    def as_xml
+      xml = REXML::Element.new('SiloProfileConfig')
+      xml.add_attributes({'id' => @id,
+                          'name' => @name,
+                          'description' => @description,
+                          'all-licensed-modules' => @all_licensed_modules,
+                          'all-global-engines' => @all_global_engines,
+                          'all-global-report-templates' => @all_global_report_templates,
+                          'all-global-scan-templates' => @all_global_scan_templates})
+
+      unless @global_report_templates.empty?
+        templates = xml.add_element('GlobalReportTemplates')
+        @global_report_templates.each do |template|
+          templates.add_element('GlobalReportTemplate', {'name' => template})
+        end
+      end
+
+      unless @global_scan_engines.empty?
+        engines = xml.add_element('GlobalScanEngines')
+        @global_report_templates.each do |engine|
+          engines.add_element('GlobalScanEngine', {'name' => engine})
+        end
+      end
+
+      unless @global_scan_templates.empty?
+        templates = xml.add_element('GlobalScanTemplates')
+        @global_scan_templates.each do |template|
+          templates.add_element('GlobalScanTemplate', {'name' => template})
+        end
+      end
+
+      unless @licensed_modules.empty?
+        licensed_modules = xml.add_element('LicensedModules')
+        @licensed_modules.each do |licensed_module|
+          licensed_modules.add_element('LicensedModule', {'name' => licensed_module})
+        end
+      end
+
+      unless @restricted_report_formats.empty?
+        formats = xml.add_element('RestrictedReportFormats')
+        @restricted_report_formats.each do |format|
+          formats.add_element('RestrictedReportFormat', {'name' => format})
+        end
+      end
+
+      unless @restricted_report_sections.empty?
+        sections = xml.add_element('RestrictedReportSections')
+        @restricted_report_sections.each do |section|
+          sections.add_element('RestrictedReportSection', {'name' => section})
+        end
+      end
+
+      xml
+    end
+
+    def to_xml
+      as_xml.to_s
+    end
+  end
+
+  class SiloProfileSummary
+    attr_reader :id
+    attr_reader :name
+    attr_reader :description
+    attr_reader :global_report_template_count
+    attr_reader :global_scan_engine_count
+    attr_reader :global_scan_template_count
+    attr_reader :licensed_module_count
+    attr_reader :restricted_report_section_count
+    attr_reader :all_licensed_modules
+    attr_reader :all_global_engines
+    attr_reader :all_global_report_templates
+    attr_reader :all_global_scan_templates
+
+
+    def initialize(&block)
+      instance_eval &block if block_given?
+    end
+
+    def self.parse(xml)
+      new do
+        @id = xml.attributes['id']
+        @name = xml.attributes['name']
+        @description = xml.attributes['description']
+        @global_report_template_count = xml.attributes['global-report-template-count']
+        @global_scan_engine_count = xml.attributes['global-scan-engine-count']
+        @global_scan_template_count = xml.attributes['global-scan-template-count']
+        @licensed_module_count = xml.attributes['licensed-module-count']
+        @restricted_report_section_count = xml.attributes['restricted-report-section-count']
+        @all_licensed_modules = xml.attributes['all-licensed-modules']
+        @all_global_engines = xml.attributes['all-global-engines']
+        @all_global_report_templates = xml.attributes['all-global-report-templates']
+        @all_global_scan_templates = xml.attributes['all-global-scan-templates']
+      end
+    end
+  end
+end

data/lib/nexpose/site.rb

@@ -125,14 +125,22 @@ module Nexpose
 
     # Whether or not this site is dynamic.
     # Dynamic sites are created through Asset Discovery Connections.
-    # Modifying their behavior through the API is not recommended.
     attr_accessor :is_dynamic
 
+    # Asset filter criteria if this site is dynamic.
+    attr_accessor :criteria
+
+    # ID of the discovery connection associated with this site if it is dynamic.
+    attr_accessor :discovery_connection_id
+
+    # [Array[TagSummary]] Collection of TagSummary
+    attr_accessor :tags
+
     # Site constructor. Both arguments are optional.
     #
     # @param [String] name Unique name of the site.
     # @param [String] scan_template ID of the scan template to use.
-    def initialize(name = nil, scan_template = 'full-audit')
+    def initialize(name = nil, scan_template = 'full-audit-without-web-spider')
       @name = name
       @scan_template = scan_template
 
@@ -146,6 +154,7 @@ module Nexpose
       @alerts = []
       @exclude = []
       @users = []
+      @tags = []
     end
 
     # Returns true when the site is dynamic.
@@ -153,6 +162,11 @@ module Nexpose
       is_dynamic
     end
 
+    def discovery_connection_id=(value)
+      @is_dynamic = true
+      @discovery_connection_id = value.to_i
+    end
+
     # Adds an asset to this site by host name.
     #
     # @param [String] hostname FQDN or DNS-resolvable host name of an asset.
@@ -203,7 +217,9 @@ module Nexpose
     def self.load(connection, id)
       r = APIRequest.execute(connection.url,
                              %(<SiteConfigRequest session-id="#{connection.session_id}" site-id="#{id}"/>))
-      parse(r.res)
+      site = parse(r.res)
+      site.load_dynamic_attributes(connection) if site.dynamic?
+      site
     end
 
     # Copy an existing configuration from a Nexpose instance.
@@ -222,13 +238,31 @@ module Nexpose
     end
 
     # Saves this site to a Nexpose console.
+    # If the site is dynamic, connection and asset filter changes must be
+    # saved through the DiscoveryConnection#update_site call.
     #
     # @param [Connection] connection Connection to console where this site will be saved.
     # @return [Fixnum] Site ID assigned to this configuration, if successful.
     #
     def save(connection)
-      r = connection.execute('<SiteSaveRequest session-id="' + connection.session_id + '">' + to_xml + ' </SiteSaveRequest>')
-      @id = r.attributes['site-id'].to_i if r.success
+      if dynamic?
+        raise APIError.new(nil, 'Cannot save a dynamic site without a discovery connection configured.') unless @discovery_connection_id
+
+        new_site = @id == -1
+        save_dynamic_criteria(connection) if new_site
+
+        # Have to retrieve and attach shared creds, or saving will fail.
+        xml = _append_shared_creds_to_xml(connection, as_xml)
+        response = AJAX.post(connection, '/ajax/save_site_config.txml', xml)
+        saved = REXML::XPath.first(REXML::Document.new(response), 'SaveConfig')
+        raise APIError.new(response, 'Failed to save dynamic site.') if saved.nil? || saved.attributes['success'].to_i != 1
+
+        save_dynamic_criteria(connection) unless new_site
+      else
+        r = connection.execute('<SiteSaveRequest session-id="' + connection.session_id + '">' + to_xml + ' </SiteSaveRequest>')
+        @id = r.attributes['site-id'].to_i if r.success
+      end
+      @id
     end
 
     # Delete this site from a Nexpose console.
@@ -257,6 +291,38 @@ module Nexpose
       Scan.parse(response.res) if response.success
     end
 
+    # Save only the criteria of a dynamic site.
+    #
+    # @param [Connection] nsc Connection to a console.
+    # @return [Fixnum] Site ID.
+    #
+    def save_dynamic_criteria(nsc)
+      params = to_dynamic_map
+      response = AJAX.form_post(nsc, '/data/site/saveSite', params)
+      json = JSON.parse(response)
+      if json['response'] =~ /success/
+        if @id < 1
+          @id = json['entityID'].to_i
+        end
+      else
+        raise APIError.new(response, json['message'])
+      end
+      @id
+    end
+
+    # Retrieve the currrent filter criteria used by a dynamic site.
+    #
+    # @param [Connection] nsc Connection to a console.
+    # @param [Fixnum] site_id ID of an existing site.
+    # @return [Criteria] Current criteria for the site.
+    #
+    def load_dynamic_attributes(nsc)
+      response = AJAX.get(nsc, "/data/site/loadDynamicSite?entityid=#{@id}")
+      json = JSON.parse(response)
+      @discovery_connection_id = json['discoveryConfigs']['id']
+      @criteria = Criteria.parse(json['searchCriteria'])
+    end
+
     include Sanitize
 
     # Generate an XML representation of this site configuration
@@ -269,6 +335,7 @@ module Nexpose
       xml.attributes['name'] = @name
       xml.attributes['description'] = @description
       xml.attributes['riskfactor'] = @risk_factor
+      xml.attributes['isDynamic'] == '1' if dynamic?
 
       unless @users.empty?
         elem = REXML::Element.new('Users')
@@ -309,6 +376,11 @@ module Nexpose
       elem.add_element(sched)
       xml.add_element(elem)
 
+      unless tags.empty?
+        tag_xml = xml.add_element(REXML::Element.new('Tags'))
+        @tags.each { |tag| tag_xml.add_element(tag.as_xml) }
+      end
+
       xml
     end
 
@@ -316,6 +388,19 @@ module Nexpose
       as_xml.to_s
     end
 
+    def to_dynamic_map
+      details = { 'dynamic' => true,
+                  'name' => @name,
+                  'tag' => @description.nil? ? '' : @description,
+                  'riskFactor' => @risk_factor,
+                  # 'vCenter' => @discovery_connection_id,
+                  'searchCriteria' => @criteria.nil? ? { 'operator' => 'AND' } : @criteria.to_map }
+      params = { 'configID' => @discovery_connection_id,
+                 'entityid' => @id > 0 ? @id : false,
+                 'mode' => @id > 0 ? 'edit' : false,
+                 'entityDetails' => details }
+    end
+
     # Parse a response from a Nexpose console into a valid Site object.
     #
     # @param [REXML::Document] rexml XML document to parse.
@@ -370,10 +455,32 @@ module Nexpose
           site.alerts << Alert.parse(alert)
         end
 
+        s.elements.each('Tags/Tag') do |tag|
+          site.tags << TagSummary.parse_xml(tag)
+        end
+
         return site
       end
       nil
     end
+
+    def _append_shared_creds_to_xml(connection, xml)
+      xml_w_creds = AJAX.get(connection, "/ajax/site_config.txml?siteid=#{@id}")
+      cred_xml = REXML::XPath.first(REXML::Document.new(xml_w_creds), 'Site/Credentials')
+      unless cred_xml.nil?
+        creds = REXML::XPath.first(xml, 'Credentials')
+        if creds.nil?
+          xml.add_element(cred_xml)
+        else
+          cred_xml.elements.each do |cred|
+            if cred.attributes['shared'].to_i == 1
+              creds.add_element(cred)
+            end
+          end
+        end
+      end
+      xml
+    end
   end
 
   # Object that represents the summary of a Nexpose Site.

data/lib/nexpose/tag.rb

@@ -0,0 +1,343 @@
+module Nexpose
+  module_function
+
+  class Connection
+    # Lists all tags
+    #
+    # @return [Array[TagSummary]] List of current tags.
+    #
+    def list_tags
+      tag_summary = []
+      tags = JSON.parse(AJAX.get(self, '/api/2.0/tags'))
+      tags['resources'].each do |json|
+        tag_summary << TagSummary.parse(json)
+      end
+      tag_summary
+    end
+    alias_method :tags, :list_tags
+
+    # Deletes a tag by ID
+    #
+    # @param [Fixnum] tag_id ID of tag to delete
+    #
+    def delete_tag(tag_id)
+      AJAX.delete(self, "/api/2.0/tags/#{tag_id}")
+    end
+
+    # Lists all the tags on an asset
+    #
+    # @param [Fixnum] asset_id of the asset to list the applied tags for
+    # @return [Array[TagSummary]] list of tags on asset
+    #
+    def list_asset_tags(asset_id)
+      tag_summary = []
+      asset_tag = JSON.parse(AJAX.get(self, "/api/2.0/assets/#{asset_id}/tags"))
+      asset_tag['resources'].select { |r| r['asset_ids'].find { |i| i == asset_id } }.each do |json|
+        tag_summary << TagSummary.parse(json)
+      end
+      tag_summary
+    end
+    alias_method :asset_tags, :list_asset_tags
+
+    # Removes a tag from an asset
+    #
+    # @param [Fixnum] asset_id on which to remove tag
+    # @param [Fixnum] tag_id to remove from asset
+    #
+    def remove_tag_from_asset(asset_id, tag_id)
+      AJAX.delete(self, "/api/2.0/assets/#{asset_id}/tags/#{tag_id}")
+    end
+
+    # Lists all the tags on a site
+    #
+    # @param [Fixnum] site_id id of the site to get the applied tags
+    # @return [Array[TagSummary]] list of tags on site
+    #
+    def list_site_tags(site_id)
+      tag_summary = []
+      site_tag = JSON.parse(AJAX.get(self, "/api/2.0/sites/#{site_id}/tags"))
+      site_tag['resources'].each do |json|
+        tag_summary << TagSummary.parse(json)
+      end
+      tag_summary
+    end
+
+    # Removes a tag from a site
+    #
+    # @param [Fixnum] site_id id of the site on which to remove the tag
+    # @param [Fixnum] tag_id id of the tag to remove
+    #
+    def remove_tag_from_site(site_id, tag_id)
+      AJAX.delete(self, "/api/2.0/sites/#{site_id}/tags/#{tag_id}")
+    end
+
+    # Lists all the tags on an asset_group
+    #
+    # @param [Fixnum] asset_group_id id of the group on which tags are listed
+    # @return [Array[TagSummary]] list of tags on asset group
+    #
+    def list_asset_group_tags(asset_group_id)
+      tag_summary = []
+      asset_group_tag = JSON.parse(AJAX.get(self, "/api/2.0/asset_groups/#{asset_group_id}/tags"))
+      asset_group_tag['resources'].each do |json|
+        tag_summary << TagSummary.parse(json)
+      end
+      tag_summary
+    end
+    alias_method :group_tags, :list_asset_group_tags
+    alias_method :asset_group_tags, :list_asset_group_tags
+
+    # Removes a tag from an asset_group
+    #
+    # @param [Fixnum] asset_group_id id of group on which to remove tag
+    # @param [Fixnum] tag_id of the tag to remove from asset group
+    #
+    def remove_tag_from_asset_group(asset_group_id, tag_id)
+      AJAX.delete(self, "/api/2.0/asset_groups/#{asset_group_id}/tags/#{tag_id}")
+    end
+    alias_method :remove_tag_from_group, :remove_tag_from_asset_group
+
+    # Returns the criticality value which takes precedent for an asset
+    #
+    # @param [Fixnum] asset_id id of asset on which criticality tag is selected
+    # @return [String] selected_criticality string of the relevant criticality; nil if not tagged
+    #
+    def selected_criticality_tag(asset_id)
+      selected_criticality = AJAX.get(self, "/data/asset/#{asset_id}/selected-criticality-tag")
+      selected_criticality.empty? ? nil : JSON.parse(selected_criticality)['name']
+    end
+  end
+
+  # Summary value object for tag information
+  #
+  class TagSummary
+
+    # ID of tag
+    attr_accessor :id
+
+    # Name of tag
+    attr_accessor :name
+
+    # One of Tag::Type::Generic
+    attr_accessor :type
+
+    def initialize(name, type, id)
+      @name, @type, @id = name, type, id
+    end
+
+    def self.parse(json)
+      new(json['tag_name'], json['tag_type'], json['tag_id'])
+    end
+
+    def self.parse_xml(xml)
+      new(xml.attributes['name'], xml.attributes['type'], xml.attributes['id'].to_i)
+    end
+
+    # XML representation of the tag summary as required by Site and AssetGroup
+    #
+    # @return [ELEMENT] XML element
+
+    def as_xml
+      xml = REXML::Element.new('Tag')
+      xml.add_attribute('id', @id)
+      xml.add_attribute('name', @name)
+      xml.add_attribute('type', @type)
+      xml
+    end
+  end
+
+  # Tag object containing tag details
+  #
+  class Tag < TagSummary
+    module Type
+      # Criticality tag types
+      module Level
+        VERY_HIGH = 'Very High'
+        HIGH = 'High'
+        MEDIUM = 'Medium'
+        LOW = 'Low'
+        VERY_LOW = 'Very Low'
+      end
+
+      # Tag types
+      module Generic
+        CUSTOM = 'CUSTOM'
+        OWNER = 'OWNER'
+        LOCATION = 'LOCATION'
+        CRITICALITY = 'CRITICALITY'
+      end
+    end
+
+    DEFAULT_COLOR = '#F6F6F6'
+
+    # Creation source
+    attr_accessor :source
+
+    # HEX color code of tag
+    attr_accessor :color
+
+    # Risk modifier
+    attr_accessor :risk_modifier
+
+    # Array containing Site IDs to be associated with tag
+    attr_accessor :site_ids
+
+    # Array containing Asset IDs to be associated with tag
+    attr_accessor :asset_ids
+
+    # Array containing Asset IDs directly associated with the tag
+    attr_accessor :associated_asset_ids
+
+    # Array containing Asset Group IDs to be associated with tag
+    attr_accessor :asset_group_ids
+    alias_method :group_ids, :asset_group_ids
+    alias_method :group_ids=, :asset_group_ids=
+
+    # A TagCriteria
+    attr_accessor :search_criteria
+
+    def initialize(name, type, id = -1)
+      @name, @type, @id = name, type, id
+      @source = 'nexpose-client'
+      @color = @type == Type::Generic::CUSTOM ? DEFAULT_COLOR : nil
+    end
+
+    # Creates and saves a tag to Nexpose console
+    #
+    # @param [Connection] connection Nexpose connection
+    # @return [Fixnum] ID of saved tag
+    #
+    def save(connection)
+      params = to_json
+      if @id == -1
+        uri = AJAX.post(connection, '/api/2.0/tags', params, AJAX::CONTENT_TYPE::JSON)
+        @id = uri.split('/').last.to_i
+      else
+        AJAX.put(connection, "/api/2.0/tags/#{@id}", params, AJAX::CONTENT_TYPE::JSON)
+      end
+      @id
+    end
+
+    # Retrieve detailed description of a single tag
+    #
+    # @param [Connection] connection Nexpose connection
+    # @param [Fixnum] ID of tag to retrieve
+    # @return [Tag] requested tag
+    #
+    def self.load(connection, tag_id)
+      json = JSON.parse(AJAX.get(connection, "/api/2.0/tags/#{tag_id}"))
+      Tag.parse(json)
+    end
+
+    def to_json
+      json = {
+          'tag_name' => @name,
+          'tag_type' => @type,
+          'tag_id' => @id,
+          'attributes' => [
+                            { 'tag_attribute_name' => 'SOURCE',
+                              'tag_attribute_value' => @source }
+                          ],
+          'tag_config' => { 'site_ids' => @site_ids,
+                            'tag_associated_asset_ids' => @associated_asset_ids,
+                            'asset_group_ids' => @asset_group_ids,
+                            'search_criteria' => @search_criteria ? @search_criteria.to_map : nil
+          }
+      }
+      if @type == Type::Generic::CUSTOM
+        json['attributes'] << { 'tag_attribute_name' => 'COLOR', 'tag_attribute_value' => @color }
+      end
+      JSON.generate(json)
+    end
+
+    # Delete this tag from Nexpose console
+    #
+    # @param [Connection] connection Nexpose connection
+    #
+    def delete(connection)
+      connection.delete_tag(@id)
+    end
+
+    def self.parse(json)
+      color = json['attributes'].find { |attr| attr['tag_attribute_name'] == 'COLOR' }
+      color = color['tag_attribute_value'] if color
+      source = json['attributes'].find { |attr| attr['tag_attribute_name'] == 'SOURCE' }
+      source = source['tag_attribute_value'] if source
+      tag = Tag.new(json['tag_name'], json['tag_type'], json['tag_id'])
+      tag.color = color
+      tag.source = source
+      tag.asset_ids = json['asset_ids']
+      if json['tag_config']
+        tag.site_ids = json['tag_config']['site_ids']
+        tag.associated_asset_ids = json['tag_config']['tag_associated_asset_ids']
+        tag.asset_group_ids = json['tag_config']['asset_group_ids']
+        criteria = json['tag_config']['search_criteria']
+        tag.search_criteria =  criteria ? Criteria.parse(criteria) : nil
+      end
+      modifier = json['attributes'].find { |attr| attr['tag_attribute_name'] == 'RISK_MODIFIER' }
+      if modifier
+        tag.risk_modifier = modifier['tag_attribute_value'].to_i
+      end
+      tag
+    end
+
+    # Adds a tag to an asset
+    #
+    # @param [Connection] connection Nexpose connection
+    # @param [Fixnum] asset_id of the asset to be tagged
+    # @return [Fixnum] ID of applied tag
+    #
+    def add_to_asset(connection, asset_id)
+      params = _to_json_for_add
+      uri = AJAX.post(connection, "/api/2.0/assets/#{asset_id}/tags", params, AJAX::CONTENT_TYPE::JSON)
+      @id = uri.split('/').last.to_i
+    end
+
+    # Adds a tag to a site
+    #
+    # @param [Connection] connection Nexpose connection
+    # @param [Fixnum] site_id of the site to be tagged
+    # @return [Fixnum] ID of applied tag
+    #
+    def add_to_site(connection, site_id)
+      params = _to_json_for_add
+      uri = AJAX.post(connection, "/api/2.0/sites/#{site_id}/tags", params, AJAX::CONTENT_TYPE::JSON)
+      @id = uri.split('/').last.to_i
+    end
+
+    # Adds a tag to an asset group
+    #
+    # @param [Connection] connection Nexpose connection
+    # @param [Fixnum] group_id id of the asset group to be tagged
+    # @return [Fixnum] ID of applied tag
+    #
+    def add_to_group(connection, group_id)
+      params = _to_json_for_add
+      uri = AJAX.post(connection, "/api/2.0/asset_groups/#{group_id}/tags", params, AJAX::CONTENT_TYPE::JSON)
+      @id = uri.split('/').last.to_i
+    end
+    alias_method :add_to_asset_group, :add_to_group
+
+    private
+
+    def _to_json_for_add
+      if @id == -1
+        json = {
+            'tag_name' => @name,
+            'tag_type' => @type,
+            'attributes' => [
+                { 'tag_attribute_name' => 'SOURCE',
+                  'tag_attribute_value' => @source }
+            ],
+        }
+        if @type == Tag::Type::Generic::CUSTOM
+          json['attributes'] << { 'tag_attribute_name' => 'COLOR', 'tag_attribute_value' => @color }
+        end
+        params = JSON.generate(json)
+      else
+        params = JSON.generate('tag_id' => @id)
+      end
+      params
+    end
+  end
+end