Finish documenting host endpoints

lib/msf/core/db_manager/http/servlet/api_docs_servlet.rb

@@ -26,6 +26,65 @@ module ApiDocsServlet
     key :basePath, '/api/v1'
     key :consumes, ['application/json']
     key :produces, ['application/json']
+
+    #################################
+    #
+    # Global parameters
+    #
+    #################################
+    parameter :workspace do
+      key :name, :workspace
+      key :in, :query
+      key :description, 'The workspace from which the data should be gathered from.'
+      key :required, true
+      key :type, :string
+    end
+
+    parameter :update_id do
+      key :name, :id
+      key :in, :path
+      key :description, 'ID of the object to update'
+      key :required, true
+      key :type, :integer
+      key :format, :int32
+    end
+
+    parameter :delete_opts do
+      key :in, :body
+      key :name, :delete_opts
+      key :description, 'The IDs of the objects you want to delete.'
+      key :required, true
+      schema do
+        key :required, [:ids]
+        property :ids do
+          key :type, :array
+          items do
+            key :type, :integer
+          end
+        end
+      end
+    end
+
+    #################################
+    #
+    # Host related parameters
+    #
+    #################################
+    parameter :non_dead do
+      key :name, :non_dead
+      key :in, :query
+      key :description, 'true to return only hosts which are up, false for all hosts.'
+      key :required, false
+      key :type, :boolean
+    end
+
+    parameter :address do
+      key :name, :address
+      key :in, :query
+      key :description, 'Return hosts matching the given IP address.'
+      key :required, false
+      key :type, :string
+    end
   end
 
   private

lib/msf/core/db_manager/http/servlet/host_servlet.rb

@@ -22,59 +22,62 @@ module HostServlet
   private
   #######
 
-  # Swagger documentation for /api/v1/hosts
+  # Swagger documentation for Host model
+  swagger_schema :Host do
+    key :required, [:id, :name]
+    property :id, type: :integer, format: :int32
+    property :created_at, type: :string, format: :date_time
+    property :address, type: :string
+    property :mac, type: :string
+    property :comm, type: :string
+    property :name, type: :string
+    property :state, type: :string
+    property :os_name, type: :string
+    property :os_flavor, type: :string
+    property :os_sp, type: :string
+    property :os_lang, type: :string
+    property :arch, type: :string
+    property :workspace_id, type: :integer, format: :int32
+    property :updated_at, type: :string, format: :date_time
+    property :purpose, type: :string
+    property :info, type: :string
+    property :comments, type: :string
+    property :scope, type: :string
+    property :virtual_host, type: :string
+    property :note_count, type: :integer, format: :int32
+    property :vuln_count, type: :integer, format: :int32
+    property :service_count, type: :integer, format: :int32
+    property :host_detail_count, type: :integer, format: :int32
+    property :exploit_attempt_count, type: :integer, format: :int32
+    property :cred_count, type: :integer, format: :int32
+    property :detected_arch, type: :string
+    property :os_family, type: :string
+  end
+
+  # Swagger documentation for /api/v1/hosts GET
   swagger_path HostServlet.api_path do
     operation :get do
       key :description, 'Return hosts that are stored in the database.'
 
-      parameter do
-        key :name, :workspace
-        key :in, :query
-        key :description, 'The workspace from which the hosts should be gathered from'
-        key :required, true
-        key :type, :string
-      end
-
-      parameter do
-        key :name, :non_dead
-        key :in, :query
-        key :description, 'true to return only hosts which are up, false for all hosts.'
-        key :required, false
-        key :type, :boolean
-      end
-
-      parameter do
-        key :name, :address
-        key :in, :query
-        key :description, 'Return hosts matching the given IP address.'
-        key :required, false
-        key :type, :string
-      end
+      parameter :workspace
+      parameter :non_dead
+      parameter :address
 
       response 200 do
         key :description, 'Returns host data'
         schema do
           key :type, :array
           items do
-            #key :'$ref', :Host
-          end
-        end
-      end
-
-      response :default do
-        key :description, 'test'
-        schema do
-          key :type, :array
-          items do
-
+            key :'$ref', :Host
           end
         end
       end
     end
   end
 
-  # Swagger documentation for api/v1/hosts/:id
-  swagger_path HostServlet.api_path_with_id do
+  # Swagger documentation for api/v1/hosts/:id GET
+  # Removing the question marks since Swagger doesn't like them
+  swagger_path HostServlet.api_path_with_id.gsub('?','') do
     operation :get do
       key :description, 'Return hosts that are stored in the database.'
 
@@ -96,24 +99,13 @@ module HostServlet
         schema do
           key :type, :array
           items do
-            #key :'$ref', :Host
-          end
-        end
-      end
-
-      response :default do
-        key :description, 'test'
-        schema do
-          key :type, :array
-          items do
-
+            key :'$ref', :Host
           end
         end
       end
     end
   end
 
-
   def self.get_host
     lambda {
       begin
@@ -128,12 +120,31 @@ module HostServlet
     }
   end
 
-  #
-  # @api [post] /api/v1/hosts
-  # description: Create a host with the given attributes.
-  # parameters:
-  #   - (query) workspace {String} The workspace from which the hosts should be gathered from
-  #
+  # Swagger documentation for /api/v1/hosts POST
+  swagger_path HostServlet.api_path do
+    operation :post do
+      key :description, 'Create a host.'
+
+      parameter do
+        key :in, :body
+        key :name, :body
+        key :description, 'The attributes to assign to the host'
+        key :required, true
+        schema do
+          key :'$ref', :Host
+        end
+      end
+
+      response 200 do
+        key :description, 'Successful operation'
+        schema do
+          key :type, :object
+          key :'$ref', :Host
+        end
+      end
+    end
+  end
+
   def self.report_host
     lambda {
       begin
@@ -147,6 +158,33 @@ module HostServlet
     }
   end
 
+  # Swagger documentation for /api/v1/hosts/:id PUT
+  swagger_path HostServlet.api_path_with_id.gsub('?','') do
+    operation :put do
+      key :description, 'Update the attributes an existing host.'
+
+      parameter :update_id
+
+      parameter do
+        key :in, :body
+        key :name, :body
+        key :description, 'The updated attributes to overwrite to the host'
+        key :required, true
+        schema do
+          key :'$ref', :Host
+        end
+      end
+
+      response 200 do
+        key :description, 'Successful operation'
+        schema do
+          key :type, :object
+          key :'$ref', :Host
+        end
+      end
+    end
+  end
+
   def self.update_host
     lambda {
       begin
@@ -161,6 +199,25 @@ module HostServlet
     }
   end
 
+  # Swagger documentation for /api/v1/hosts/ DELETE
+  swagger_path HostServlet.api_path.gsub('?','') do
+    operation :delete do
+      key :description, 'Delete the specified hosts.'
+
+      parameter :delete_opts
+
+      response 200 do
+        key :description, 'Successful operation'
+        schema do
+          key :type, :array
+          items do
+            key :'$ref', :Host
+          end
+        end
+      end
+    end
+  end
+
   def self.delete_host
     lambda {
       begin