From 8010c5822097df4f4aedfbf5498528d5bdbe7ffe Mon Sep 17 00:00:00 2001 From: Erin Bleiweiss Date: Wed, 18 Jul 2018 17:36:31 -0500 Subject: [PATCH] add module documentation to swagger (WIP) --- documentation/api/v1/module_api_doc.rb | 204 ++++++++++++++++++ documentation/api/v1/root_api_doc.rb | 1 + .../http/servlet/api_docs_servlet.rb | 2 + 3 files changed, 207 insertions(+) create mode 100644 documentation/api/v1/module_api_doc.rb diff --git a/documentation/api/v1/module_api_doc.rb b/documentation/api/v1/module_api_doc.rb new file mode 100644 index 0000000000..744371a2c5 --- /dev/null +++ b/documentation/api/v1/module_api_doc.rb @@ -0,0 +1,204 @@ +require 'swagger/blocks' + +module ModuleApiDoc + include Swagger::Blocks + + APP_DESC = 'Filter modules that are client or server attacks. (Accepts strings \'client\' or \'server\'.)' + AUTHOR_DESC = 'Filter modules written by a matching author.' + BID_DESC = 'Filter modules with a matching Bugtraq ID.' + CVE_DESC = 'Filter modules with a matching CVE ID' + EDB_DESC = 'Filter modules with a matching Exploit-DB ID.' + NAME_DESC = 'Filter modules with a matching descriptive name.' + PATH_DESC = 'Filter modules with a matching path name.' + PLATFORM_DESC = 'Filter modules affecting a matching platform, arch, or target.' + PORT_DESC = 'Filter modules with a matching port.' + REF_DESC = 'Filter modules with a matching reference.' + TEXT_DESC = 'Filter modules matching any one of name, full name, description, reference, author, or targets.' + TYPE_DESC = 'Filter modules with a matching type (exploit, auxiliary, payload, etc.).' + FIELDS_DESC = 'Provide a comma-delimited list of metadata fields you would like to return. If left blank, all fields will be returned.' + + TYPE_ENUM = [ + 'auxiliary', + 'encoder', + 'exploit', + 'nop', + 'payload', + 'post', + '' + ] + APP_ENUM = [ + 'client', + 'server', + '' + ] + FIELDS_ENUM = [ + 'name', + 'full_name', + 'disclosure_date', + 'rank', + 'type', + 'description', + 'author', + 'references', + 'is_server', + 'is_client', + 'platform', + 'arch', + 'rport', + 'mod_time', + 'ref_name', + 'path', + 'is_install_path', + 'targets', + '' + ] + + APP_EXAMPLE = 'server' + AUTHOR_EXAMPLE = 'wvu' + BID_EXAMPLE = 'BID-36075' + CVE_EXAMPLE = 'CVE-2017' + EDB_EXAMPLE = 'EDB-24453' + NAME_EXAMPLE = 'eternalblue' + PATH_EXAMPLE = 'eternalblue' + PLATFORM_EXAMPLE = 'android' + PORT_EXAMPLE = '80' + REF_EXAMPLE = 'CVE-2017' + TEXT_EXAMPLE = 'eternalblue' + TYPE_EXAMPLE = 'exploit' + FIELDS_EXAMPLE = 'full_name,type,platform,references' + + + + + # Swagger documentation for Module model + swagger_schema :Module do + property :app, type: :string, description: APP_DESC, example: APP_EXAMPLE, enum: APP_ENUM + property :author, type: :string, description: AUTHOR_DESC, example: AUTHOR_EXAMPLE + property :bid, type: :string, description: BID_DESC, example: BID_EXAMPLE + property :cve, type: :string, description: CVE_DESC, example: CVE_EXAMPLE + property :edb, type: :string, description: EDB_DESC, example: EDB_EXAMPLE + property :name, type: :string, description: NAME_DESC, example: NAME_EXAMPLE + property :path, type: :string, description: PATH_DESC, example: PATH_EXAMPLE + property :platform, type: :string, description: PLATFORM_DESC, example: PLATFORM_EXAMPLE + property :port, type: :string, description: PORT_DESC, example: PORT_EXAMPLE + property :ref, type: :string, description: REF_DESC, example: REF_EXAMPLE + property :text, type: :string, description: TEXT_DESC, example: TEXT_EXAMPLE + property :type, type: :string, description: TYPE_DESC, example: TYPE_EXAMPLE, enum: TYPE_ENUM + property :fields, type: :string, description: FIELDS_DESC, example: FIELDS_EXAMPLE, enum: FIELDS_ENUM + end + + + + swagger_path '/api/v1/modules' do + # Swagger documentation for /api/v1/modules GET + operation :get do + key :description, 'Search Metasploit modules using keyword filters.' + key :tags, [ 'module' ] + + parameter do + key :in, :query + key :name, :app + key :required, false + key :description, APP_DESC + end + + parameter do + key :in, :query + key :name, :author + key :required, false + key :description, AUTHOR_DESC + end + + parameter do + key :in, :query + key :name, :bid + key :required, false + key :description, BID_DESC + end + + parameter do + key :in, :query + key :name, :cve + key :required, false + key :description, CVE_DESC + end + + parameter do + key :in, :query + key :name, :edb + key :required, false + key :description, EDB_DESC + end + + parameter do + key :in, :query + key :name, :name + key :required, false + key :description, NAME_DESC + end + + parameter do + key :in, :query + key :name, :path + key :required, false + key :description, PATH_DESC + end + + parameter do + key :in, :query + key :name, :platform + key :required, false + key :description, PLATFORM_DESC + end + + parameter do + key :in, :query + key :name, :port + key :required, false + key :description, PORT_DESC + end + + parameter do + key :in, :query + key :name, :ref + key :required, false + key :description, REF_DESC + end + + parameter do + key :in, :query + key :name, :text + key :required, false + key :description, TEXT_DESC + end + + parameter do + key :in, :query + key :name, :type + key :required, false + key :description, TYPE_DESC + end + + parameter do + key :in, :query + key :name, :fields + key :required, false + key :description, FIELDS_DESC + end + + + response 200 do + key :description, 'Returns modules matching keywords with appropriate metadata.' + schema do + key :type, :array + items do + key :'$ref', :Module + end + end + end + end + end + + + +end diff --git a/documentation/api/v1/root_api_doc.rb b/documentation/api/v1/root_api_doc.rb index c11f59f263..839bfacaf4 100644 --- a/documentation/api/v1/root_api_doc.rb +++ b/documentation/api/v1/root_api_doc.rb @@ -36,6 +36,7 @@ module RootApiDoc tag name: 'exploit', description: 'Exploit operations.' tag name: 'host', description: 'Host operations.' tag name: 'loot', description: 'Loot operations.' + tag name: 'module', description: 'Module search operations.' tag name: 'msf', description: 'Utility operations around Metasploit Framework.' tag name: 'nmap', description: 'Nmap operations.' tag name: 'note', description: 'Note operations.' diff --git a/lib/msf/core/db_manager/http/servlet/api_docs_servlet.rb b/lib/msf/core/db_manager/http/servlet/api_docs_servlet.rb index 152431c978..ab336b0117 100644 --- a/lib/msf/core/db_manager/http/servlet/api_docs_servlet.rb +++ b/lib/msf/core/db_manager/http/servlet/api_docs_servlet.rb @@ -6,6 +6,7 @@ load 'documentation/api/v1/event_api_doc.rb' load 'documentation/api/v1/exploit_api_doc.rb' load 'documentation/api/v1/host_api_doc.rb' load 'documentation/api/v1/loot_api_doc.rb' +load 'documentation/api/v1/module_api_doc.rb' load 'documentation/api/v1/msf_api_doc.rb' load 'documentation/api/v1/nmap_api_doc.rb' load 'documentation/api/v1/note_api_doc.rb' @@ -47,6 +48,7 @@ module ApiDocsServlet ExploitApiDoc, HostApiDoc, LootApiDoc, + ModuleApiDoc, MsfApiDoc, NmapApiDoc, NoteApiDoc,