metasploit-gs/documentation/api/v1/credential_api_doc.rb

require 'swagger/blocks'

# TODO: Complete this documentation when the credential model is fully implemented in the API.
module CredentialApiDoc
  include Swagger::Blocks

  ORIGIN_ID_DESC = 'The ID of the origin record associated with this credential.'
  ORIGIN_TYPE = 'The class name within Metasploit::Credential that indicates where this credential came from.'
  PRIVATE_ID_DESC = 'The ID of the Metasploit::Credential::Private record associated with this credential.'
  PUBLIC_ID_DESC = 'The ID of the Metasploit::Credential::Public record associated with this credential.'
  REALM_ID_DESC = 'The ID of the Metasploit::Credential::Realm from where the credential was gathered.'
  LOGINS_COUNT_DESC = 'The number of successful login attempts that were completed using this credential.'
  ORIGIN_TYPE_ENUM = [
      'Metasploit::Credential::Origin::Import',
      'Metasploit::Credential::Origin::Manual',
      'Metasploit::Credential::Origin::Service',
      'Metasploit::Credential::Origin::Session'
  ]

  USERNAME_DESC = 'The username for this credential.'
  USERNAME_EXAMPLE = 'administrator'
  PUBLIC_TYPE_DESC = 'The type of username that this falls into. This is used for searching for similar credentials.'
  PRIVATE_TYPE_DESC = ''
  DATA_DESC = 'The private data for this credential.  The semantic meaning of this data varies based on the type.'
  DATA_EXAMPLE = "'password123', '$1$5nfRD/bA$y7ZZD0NimJTbX9FtvhHJX1', or '$NT$7f8fe03093cc84b267b109625f6bbf4b'"
  JTR_FORMAT_DESC = 'Comma-separated list of the formats for John the ripper to use to try and crack this.'
  JTR_FORMAT_EXAMPLE = 'md5,des,bsdi,crypt'
  PUBLIC_TYPE_ENUM = [ 'Metasploit::Credential::BlankUsername', 'Metasploit::Credential::Username' ]
  PRIVATE_TYPE_ENUM = [
      'Metasploit::Credential::ReplayableHash',
      'Metasploit::Credential::NonreplayableHash',
      'Metasploit::Credential::NTLMHash',
      'Metasploit::Credential::Password',
      'Metasploit::Credential::PasswordHash',
      'Metasploit::Credential::SSHKey',
      'Metasploit::Credential::PostgresMD5',
      'Metasploit::Credential::BlankPassword'
  ]


# Swagger documentation for Credential model
  swagger_schema :Credential do
    key :required, [:origin_id]
    property :id, type: :integer, format: :int32, description: RootApiDoc::ID_DESC
    property :origin_id, type: :integer, format: :int32, description: ORIGIN_ID_DESC
    property :origin_type, type: :string, description: ORIGIN_TYPE, enum: ORIGIN_TYPE_ENUM
    property :private_id, type: :integer, format: :int32, description: PRIVATE_ID_DESC
    property :public_id, type: :integer, format: :int32, description: PUBLIC_ID_DESC
    property :realm_id, type: :integer, format: :int32, description: REALM_ID_DESC
    property :workspace_id, type: :integer, format: :int32, description: RootApiDoc::WORKSPACE_ID_DESC
    property :logins_count, type: :integer, format: :int32, description: LOGINS_COUNT_DESC
    property :logins do
      key :type, :array
      items do
      end
    end
    property :public, '$ref': :Public
    property :private, '$ref': :Private
    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
  end

  swagger_schema :Public do
    key :required, [:username, :type]
    property :id, type: :integer, format: :int32, description: RootApiDoc::ID_DESC
    property :username, type: :string, description: USERNAME_DESC, example: USERNAME_EXAMPLE
    property :type, type: :string, description: PUBLIC_TYPE_DESC, enum: PUBLIC_TYPE_ENUM
    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
  end

  swagger_schema :Private do
    key :required, [:data, :type]
    property :id, type: :integer, format: :int32, description: RootApiDoc::ID_DESC
    property :data, type: :string, description: DATA_DESC, example: DATA_EXAMPLE
    property :type, type: :string, description: PRIVATE_TYPE_DESC, enum: PRIVATE_TYPE_ENUM
    property :jtr_format, type: :string, description: JTR_FORMAT_DESC, example: JTR_FORMAT_EXAMPLE
    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
  end

  swagger_path '/api/v1/credentials' do
    # Swagger documentation for /api/v1/credentials GET
    operation :get do
      key :description, 'Return credentials that are stored in the database.'
      key :tags, [ 'credential' ]

      parameter :workspace

      parameter do
        key :in, :query
        key :name, :svcs
        key :description, 'Only return credentials of the specified service.'
        key :example, "'ssh', 'owa', or 'smb'"
        key :type, :array
        key :required, false
        items do
          key :type, :string
        end
      end

      parameter do
        key :in, :query
        key :name, :type
        key :description, 'The type of credential to return.'
        key :type, :string
        key :required, false
        key :enum, PRIVATE_TYPE_ENUM
      end

      parameter do
        key :in, :query
        key :name, :user
        key :description, 'Only return credentials where the user matches this regex.'
        key :example, 'administrator'
        key :type, :string
        key :required, false
      end

      parameter do
        key :in, :query
        key :name, :pass
        key :description, 'Only return credentials where the password matches this regex.'
        key :example, 'password123'
        key :type, :string
        key :required, false
      end

      response 200 do
        key :description, 'Returns credential data.'
        schema do
          key :type, :array
          items do
            key :'$ref', :Credential
          end
        end
      end
    end

    # Swagger documentation for /api/v1/credentials POST
    operation :post do
      key :description, 'Create a credential.'
      key :tags, [ 'credential' ]

      parameter do
        key :in, :body
        key :name, :body
        key :description, 'The attributes to assign to the credential.'
        key :required, true
        schema do
          key :'$ref', :Credential
        end
      end

      response 200 do
        key :description, 'Successful operation.'
        schema do
          key :type, :object
          key :'$ref', :Credential
        end
      end
    end

    # Swagger documentation for /api/v1/credentials/ DELETE
    operation :delete do
      key :description, 'Delete the specified credentials.'
      key :tags, [ 'credential' ]

      parameter :delete_opts

      response 200 do
        key :description, 'Successful operation.'
        schema do
          key :type, :array
          items do
            key :'$ref', :Credential
          end
        end
      end
    end
  end

  swagger_path '/api/v1/credentials/{id}' do
    # Swagger documentation for api/v1/credentials/:id GET
    operation :get do
      key :description, 'Return credentials that are stored in the database.'
      key :tags, [ 'credential' ]

      parameter :workspace
      parameter :non_dead
      parameter :address

      parameter do
        key :name, :id
        key :in, :path
        key :description, 'ID of credential to retrieve'
        key :required, true
        key :type, :integer
        key :format, :int32
      end

      response 200 do
        key :description, 'Returns credential data'
        schema do
          key :type, :array
          items do
            key :'$ref', :Credential
          end
        end
      end
    end

    #Swagger documentation for /api/v1/credentials/:id PUT
    operation :put do
      key :description, 'Update the attributes an existing credential.'
      key :tags, [ 'credential' ]

      parameter :update_id

      parameter do
        key :in, :body
        key :name, :body
        key :description, 'The updated attributes to overwrite to the credential'
        key :required, true
        schema do
          key :'$ref', :Credential
        end
      end

      response 200 do
        key :description, 'Successful operation'
        schema do
          key :type, :object
          key :'$ref', :Credential
        end
      end
    end
  end
end