From fc079138fdfa1afcb82969eef3fda26772f5801b Mon Sep 17 00:00:00 2001
From: James Barnett <James_Barnett@rapid7.com>
Date: Tue, 15 May 2018 14:34:15 -0500
Subject: [PATCH] Service API doc second pass

---
 documentation/api/v1/service_api_doc.rb | 35 +++++++++++++++++++------
 lib/msf/core/db_manager/service.rb      |  4 ++-
 2 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/documentation/api/v1/service_api_doc.rb b/documentation/api/v1/service_api_doc.rb
index 1f1869fc57..a83d49a1f8 100644
--- a/documentation/api/v1/service_api_doc.rb
+++ b/documentation/api/v1/service_api_doc.rb
@@ -3,18 +3,31 @@ require 'swagger/blocks'
 module ServiceApiDoc
   include Swagger::Blocks
 
+  HOST_DESC = 'The host where this service is running.'
+  HOST_EXAMPLE = '127.0.0.1'
+  PORT_DESC = 'The port this service is listening on.'
+  PORT_EXAMPLE = '443'
+  PROTO_DESC = 'The transport layer protocol this service is using.'
+  PROTO_ENUM = ['tcp', 'udp']
+  NAME_DESC = 'The application layer protocol.'
+  NAME_EXAMPLE = "'ssh', 'mssql', 'smb', etc."
+  STATE_DESC = 'The current listening state of the service.'
+  STATE_ENUM = ['open', 'closed', 'filtered', 'unknown']
+  INFO_DESC = 'Detailed information about the service such as name and version information.'
+  INFO_EXAMPLE = "'ProFTPD 1.3.5', 'WEBrick httpd 1.3.1 Ruby 2.3.4', etc."
+
 # Swagger documentation for Service model
   swagger_schema :Service do
     key :required, [:id, :port, :proto]
     property :id, type: :integer, format: :int32
     property :host_id, type: :integer, format: :int32
+    property :port, type: :string, description: PORT_DESC, example: PORT_EXAMPLE
+    property :proto, type: :string, description: PROTO_DESC, enum: PROTO_ENUM
+    property :name, type: :string, description: NAME_DESC, example: NAME_EXAMPLE
+    property :info, type: :string, description: INFO_DESC, example: INFO_EXAMPLE
+    property :state, type: :string, description: STATE_DESC, enum: STATE_ENUM
     property :created_at, type: :string, format: :date_time
-    property :port, type: :integer, format: :int32
-    property :proto, type: :string, enum: ['tcp','udp']
-    property :state, type: :string
-    property :name, type: :string
     property :updated_at, type: :string, format: :date_time
-    property :info, type: :string
   end
 
   swagger_path '/api/v1/services' do
@@ -44,10 +57,16 @@ module ServiceApiDoc
       parameter do
         key :in, :body
         key :name, :body
-        key :description, 'The attributes to assign to the Service'
+        key :description, 'The attributes to assign to the service'
         key :required, true
         schema do
-          key :'$ref', :Service
+          property :workspace, type: :string, required: true
+          property :host, type: :string, format: :ipv4, required: true, description: HOST_DESC, example: HOST_EXAMPLE
+          property :port, type: :string, required: true, description: PORT_DESC, example: PORT_EXAMPLE
+          property :proto, type: :string, required: true, description: PROTO_DESC, enum: PROTO_ENUM
+          property :name, type: :string, description: NAME_DESC, example: NAME_EXAMPLE
+          property :info, type: :string, description: INFO_DESC, example: INFO_EXAMPLE
+          property :state, type: :string, description: STATE_DESC, enum: STATE_ENUM
         end
       end
 
@@ -79,7 +98,7 @@ module ServiceApiDoc
     end
   end
 
-  swagger_path '/api/v1/services/:id' do
+  swagger_path '/api/v1/services/{id}' do
     # Swagger documentation for api/v1/services/:id GET
     operation :get do
       key :description, 'Return services that are stored in the database.'
diff --git a/lib/msf/core/db_manager/service.rb b/lib/msf/core/db_manager/service.rb
index e67a11bc0a..df33acd750 100644
--- a/lib/msf/core/db_manager/service.rb
+++ b/lib/msf/core/db_manager/service.rb
@@ -48,11 +48,13 @@ module Msf::DBManager::Service
   # +:host+::  the host where this service is running
   # +:port+::  the port where this service listens
   # +:proto+:: the transport layer protocol (e.g. tcp, udp)
+  # +:workspace+:: the workspace for the service
   #
   # opts may contain
   # +:name+::  the application layer protocol (e.g. ssh, mssql, smb)
   # +:sname+:: an alias for the above
-  # +:workspace+:: the workspace for the service
+  # +:info+:: Detailed information about the service such as name and version information
+  # +:state+:: The current listening state of the service (one of: open, closed, filtered, unknown)
   #
   def report_service(opts)
     return if !active