2018-04-26 16:08:11 +00:00
|
|
|
require 'swagger/blocks'
|
|
|
|
|
|
|
|
module HostApiDoc
|
|
|
|
include Swagger::Blocks
|
|
|
|
|
2018-05-08 17:38:04 +00:00
|
|
|
HOST_DESC = 'The IP address of the host.'
|
|
|
|
HOST_EXAMPLE = '127.0.0.1'
|
|
|
|
MAC_DESC = 'MAC Address of the host'
|
|
|
|
MAC_EXAMPLE = 'AA:BB:CC:11:22:33'
|
2018-05-22 19:57:21 +00:00
|
|
|
COMM_DESC = 'Unused attribute.'
|
2018-05-08 17:38:04 +00:00
|
|
|
NAME_DESC = 'Hostname of the host.'
|
|
|
|
NAME_EXAMPLE = 'domain_controller'
|
2018-05-22 19:57:21 +00:00
|
|
|
STATE_DESC = 'The last seen connectivity state of this host.'
|
|
|
|
OS_NAME_DESC = 'The name of the operating system.'
|
|
|
|
OS_NAME_EXAMPLE = "'Windows XP', 'Ubuntu', or 'Mac OS X'"
|
|
|
|
OS_FLAVOR_DESC = 'The flavor of operating system.'
|
2018-05-08 17:38:04 +00:00
|
|
|
OS_FLAVOR_EXAMPLE = "'Enterprise', 'Pro', or 'Home'"
|
2018-05-22 19:57:21 +00:00
|
|
|
OS_SP_DESC = 'The service pack version the operating system is running.'
|
2018-05-08 17:38:04 +00:00
|
|
|
OS_SP_EXAMPLE = "'SP2'"
|
2018-05-22 19:57:21 +00:00
|
|
|
OS_LANG_DESC = 'The language the operating system is using.'
|
2018-05-08 17:38:04 +00:00
|
|
|
OS_LANG_EXAMPLE = "'English', 'French', or 'en-US'"
|
2018-05-22 19:57:21 +00:00
|
|
|
OS_FAMILY_DESC = 'The major family the operating system belongs to.'
|
|
|
|
OS_FAMILY_EXAMPLE = "'Windows', 'Linux', or 'OS X'"
|
|
|
|
ARCH_DESC = 'The architecture of the host\'s CPU OR the programming language for virtual machine programming language like Ruby, PHP, and Java.'
|
|
|
|
DETECTED_ARCH_DESC = 'The architecture of the host\'s CPU as detected by `Recog`. If arch is not \'unknown\', this is undefined.'
|
2018-05-08 17:38:04 +00:00
|
|
|
PURPOSE_DESC = 'The main function of the host.'
|
|
|
|
INFO_DESC = 'Customizable information about the host.'
|
|
|
|
COMMENTS_DESC = 'A place for storing notes or findings about the host.'
|
|
|
|
SCOPE_DESC = 'Interface identifier for link-local IPv6.'
|
|
|
|
VIRTUAL_HOST_DESC = 'The name of the virtualization software.'
|
|
|
|
VIRTUAL_HOST_EXAMPLE = "'VMWare', 'QEMU', 'Xen', or 'Docker'"
|
2018-05-22 19:57:21 +00:00
|
|
|
NOTE_COUNT_DESC = 'Cached count of the number of associated notes.'
|
|
|
|
VULN_COUNT_DESC = 'Cached count of the number of associated vulns.'
|
|
|
|
SERVICE_COUNT_DESC = 'Cached count of the number of associated services.'
|
|
|
|
HOST_DETAIL_COUNT_DESC = 'Cached count of the number of associated host details.'
|
|
|
|
EXPLOIT_ATTEMPT_COUNT_DESC = 'Cached count of the number of associated exploit attempts.'
|
|
|
|
CRED_COUNT_DESC = 'Cached count of the number of associated creds.'
|
2018-05-17 21:56:22 +00:00
|
|
|
STATE_ENUM = [ 'alive', 'down', 'unknown' ]
|
|
|
|
ARCH_ENUM = [
|
2018-05-29 17:24:53 +00:00
|
|
|
'armbe',
|
|
|
|
'armle',
|
|
|
|
'cbea',
|
|
|
|
'cbea64',
|
|
|
|
'cmd',
|
|
|
|
'java',
|
2018-05-17 21:56:22 +00:00
|
|
|
'mips',
|
|
|
|
'mipsbe',
|
2018-05-29 17:24:53 +00:00
|
|
|
'mipsle',
|
|
|
|
'php',
|
2018-05-17 21:56:22 +00:00
|
|
|
'ppc',
|
|
|
|
'ppc64',
|
2018-05-29 17:24:53 +00:00
|
|
|
'ruby',
|
2018-05-17 21:56:22 +00:00
|
|
|
'sparc',
|
2018-05-29 17:24:53 +00:00
|
|
|
'tty',
|
|
|
|
'x64',
|
|
|
|
'x86',
|
|
|
|
'x86_64',
|
|
|
|
'',
|
|
|
|
'Unknown'
|
2018-05-17 21:56:22 +00:00
|
|
|
]
|
2018-05-08 17:38:04 +00:00
|
|
|
|
2018-04-26 16:08:11 +00:00
|
|
|
# Swagger documentation for Host model
|
|
|
|
swagger_schema :Host do
|
2018-05-17 21:56:22 +00:00
|
|
|
key :required, [:address, :name]
|
2018-05-22 19:57:21 +00:00
|
|
|
property :id, type: :integer, format: :int32, description: RootApiDoc::ID_DESC
|
2018-05-08 17:38:04 +00:00
|
|
|
property :address, type: :string, description: HOST_DESC, example: HOST_EXAMPLE
|
|
|
|
property :mac, type: :string, description: MAC_DESC, example: MAC_EXAMPLE
|
2018-05-22 19:57:21 +00:00
|
|
|
property :comm, type: :string, description: COMM_DESC
|
2018-05-08 17:38:04 +00:00
|
|
|
property :name, type: :string, description: NAME_DESC, example: NAME_EXAMPLE
|
2018-05-22 19:57:21 +00:00
|
|
|
property :state, type: :string, description: STATE_DESC, enum: STATE_ENUM
|
|
|
|
property :os_name, type: :string, description: OS_NAME_DESC, example: OS_NAME_EXAMPLE
|
|
|
|
property :os_flavor, type: :string, description: OS_FLAVOR_DESC, example: OS_FLAVOR_EXAMPLE
|
|
|
|
property :os_sp, type: :string, description: OS_SP_DESC, example: OS_SP_EXAMPLE
|
|
|
|
property :os_lang, type: :string, description: OS_LANG_DESC, example: OS_LANG_EXAMPLE
|
|
|
|
property :os_family, type: :string, description: OS_FAMILY_DESC, example: OS_FAMILY_EXAMPLE
|
|
|
|
property :arch, type: :string, description: ARCH_DESC, enum: ARCH_ENUM
|
|
|
|
property :detected_arch, type: :string, description: DETECTED_ARCH_DESC
|
|
|
|
property :workspace_id, type: :integer, format: :int32, description: RootApiDoc::WORKSPACE_ID_DESC
|
2018-05-08 17:38:04 +00:00
|
|
|
property :purpose, type: :string, description: PURPOSE_DESC
|
|
|
|
property :info, type: :string, description: INFO_DESC
|
|
|
|
property :comments, type: :string, description: COMMENTS_DESC
|
|
|
|
property :scope, type: :string, description: SCOPE_DESC
|
|
|
|
property :virtual_host, type: :string, description: VIRTUAL_HOST_DESC, example: VIRTUAL_HOST_EXAMPLE
|
2018-05-22 19:57:21 +00:00
|
|
|
property :note_count, type: :integer, format: :int32, description: NOTE_COUNT_DESC
|
|
|
|
property :vuln_count, type: :integer, format: :int32, description: VULN_COUNT_DESC
|
|
|
|
property :service_count, type: :integer, format: :int32, description: SERVICE_COUNT_DESC
|
|
|
|
property :host_detail_count, type: :integer, format: :int32, description: HOST_DETAIL_COUNT_DESC
|
|
|
|
property :exploit_attempt_count, type: :integer, format: :int32, description: EXPLOIT_ATTEMPT_COUNT_DESC
|
|
|
|
property :cred_count, type: :integer, format: :int32, description: CRED_COUNT_DESC
|
|
|
|
property :created_at, type: :string, format: :date_time, description: RootApiDoc::CREATED_AT_DESC
|
|
|
|
property :updated_at, type: :string, format: :date_time, description: RootApiDoc::UPDATED_AT_DESC
|
2018-04-26 16:08:11 +00:00
|
|
|
end
|
|
|
|
|
|
|
|
swagger_path '/api/v1/hosts' do
|
2018-05-02 19:47:17 +00:00
|
|
|
# Swagger documentation for /api/v1/hosts GET
|
2018-04-26 16:08:11 +00:00
|
|
|
operation :get do
|
|
|
|
key :description, 'Return hosts that are stored in the database.'
|
2018-04-30 21:40:07 +00:00
|
|
|
key :tags, [ 'host' ]
|
2018-04-26 16:08:11 +00:00
|
|
|
|
|
|
|
parameter :workspace
|
|
|
|
parameter :non_dead
|
|
|
|
parameter :address
|
|
|
|
|
|
|
|
response 200 do
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'Returns host data.'
|
2018-04-26 16:08:11 +00:00
|
|
|
schema do
|
|
|
|
key :type, :array
|
|
|
|
items do
|
|
|
|
key :'$ref', :Host
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
# Swagger documentation for /api/v1/hosts POST
|
|
|
|
operation :post do
|
|
|
|
key :description, 'Create a host.'
|
2018-04-30 21:40:07 +00:00
|
|
|
key :tags, [ 'host' ]
|
2018-04-26 16:08:11 +00:00
|
|
|
|
|
|
|
parameter do
|
|
|
|
key :in, :body
|
|
|
|
key :name, :body
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'The attributes to assign to the host.'
|
2018-04-26 16:08:11 +00:00
|
|
|
key :required, true
|
|
|
|
schema do
|
2018-05-22 19:57:21 +00:00
|
|
|
property :workspace, type: :string, required: true, description: RootApiDoc::WORKSPACE_POST_EXAMPLE
|
2018-05-08 17:38:04 +00:00
|
|
|
property :host, type: :string, format: :ipv4, required: true, description: HOST_DESC, example: HOST_EXAMPLE
|
|
|
|
property :mac, type: :string, description: MAC_DESC, example: MAC_EXAMPLE
|
|
|
|
property :name, type: :string, description: NAME_DESC, example: NAME_EXAMPLE
|
2018-05-22 19:57:21 +00:00
|
|
|
property :os_name, type: :string, description: OS_NAME_DESC, example: OS_NAME_EXAMPLE
|
|
|
|
property :os_flavor, type: :string, description: OS_FLAVOR_DESC, example: OS_FLAVOR_EXAMPLE
|
|
|
|
property :os_sp, type: :string, description: OS_SP_DESC, example: OS_SP_EXAMPLE
|
|
|
|
property :os_lang, type: :string, description: OS_LANG_DESC, example: OS_LANG_EXAMPLE
|
2018-05-08 17:38:04 +00:00
|
|
|
property :purpose, type: :string, description: PURPOSE_DESC
|
|
|
|
property :info, type: :string, description: INFO_DESC
|
|
|
|
property :comments, type: :string, description: COMMENTS_DESC
|
|
|
|
property :scope, type: :string, description: SCOPE_DESC
|
|
|
|
property :virtual_host, type: :string, description: VIRTUAL_HOST_DESC, example: VIRTUAL_HOST_EXAMPLE
|
|
|
|
# Possible values paired down from rex-arch/lib/rex/arch.rb
|
|
|
|
property :arch do
|
|
|
|
key :type, :string
|
2018-05-22 19:57:21 +00:00
|
|
|
key :description, ARCH_DESC
|
2018-05-17 21:56:22 +00:00
|
|
|
key :enum, ARCH_ENUM
|
2018-05-08 17:38:04 +00:00
|
|
|
end
|
|
|
|
property :state do
|
|
|
|
key :type, :string
|
2018-05-22 19:57:21 +00:00
|
|
|
key :description, STATE_DESC
|
2018-05-17 21:56:22 +00:00
|
|
|
key :enum, STATE_ENUM
|
2018-05-08 17:38:04 +00:00
|
|
|
end
|
2018-04-26 16:08:11 +00:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
response 200 do
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'Successful operation.'
|
2018-04-26 16:08:11 +00:00
|
|
|
schema do
|
|
|
|
key :type, :object
|
|
|
|
key :'$ref', :Host
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
# Swagger documentation for /api/v1/hosts/ DELETE
|
|
|
|
operation :delete do
|
|
|
|
key :description, 'Delete the specified hosts.'
|
2018-04-30 21:40:07 +00:00
|
|
|
key :tags, [ 'host' ]
|
2018-04-26 16:08:11 +00:00
|
|
|
|
|
|
|
parameter :delete_opts
|
|
|
|
|
|
|
|
response 200 do
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'Successful operation.'
|
2018-04-26 16:08:11 +00:00
|
|
|
schema do
|
|
|
|
key :type, :array
|
|
|
|
items do
|
|
|
|
key :'$ref', :Host
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2018-05-08 17:38:04 +00:00
|
|
|
swagger_path '/api/v1/hosts/{id}' do
|
2018-05-02 19:47:17 +00:00
|
|
|
# Swagger documentation for api/v1/hosts/:id GET
|
2018-04-26 16:08:11 +00:00
|
|
|
operation :get do
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'Return specific host that is stored in the database.'
|
2018-04-30 21:40:07 +00:00
|
|
|
key :tags, [ 'host' ]
|
2018-04-26 16:08:11 +00:00
|
|
|
|
|
|
|
parameter :workspace
|
|
|
|
parameter :non_dead
|
|
|
|
parameter :address
|
|
|
|
|
|
|
|
parameter do
|
|
|
|
key :name, :id
|
|
|
|
key :in, :path
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'ID of host to retrieve.'
|
2018-04-26 16:08:11 +00:00
|
|
|
key :required, true
|
|
|
|
key :type, :integer
|
2018-04-26 19:38:16 +00:00
|
|
|
key :format, :int32
|
2018-04-26 16:08:11 +00:00
|
|
|
end
|
|
|
|
|
|
|
|
response 200 do
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'Returns host data.'
|
2018-04-26 16:08:11 +00:00
|
|
|
schema do
|
|
|
|
key :type, :array
|
|
|
|
items do
|
|
|
|
key :'$ref', :Host
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
# Swagger documentation for /api/v1/hosts/:id PUT
|
|
|
|
operation :put do
|
|
|
|
key :description, 'Update the attributes an existing host.'
|
2018-04-30 21:40:07 +00:00
|
|
|
key :tags, [ 'host' ]
|
2018-04-26 16:08:11 +00:00
|
|
|
|
|
|
|
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
|
2018-05-17 21:56:22 +00:00
|
|
|
key :description, 'Successful operation.'
|
2018-04-26 16:08:11 +00:00
|
|
|
schema do
|
|
|
|
key :type, :object
|
|
|
|
key :'$ref', :Host
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|