# frozen_string_literal: true
#
# ronin-vulns - A Ruby library for blind vulnerability testing.
#
# Copyright (c) 2022-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
#
# ronin-vulns is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published
# by the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# ronin-vulns is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with ronin-vulns.  If not, see <https://www.gnu.org/licenses/>.
#

require 'ronin/vulns/lfi'
require 'ronin/vulns/rfi'
require 'ronin/vulns/sqli'
require 'ronin/vulns/ssti'
require 'ronin/vulns/reflected_xss'
require 'ronin/vulns/open_redirect'

module Ronin
  module Vulns
    #
    # Top-level module which scans a URL for all web vulnerabilities.
    #
    # ## Examples
    #
    #     require 'ronin/vulns/url_scanner'
    #
    #     Ronin::Vulns::URLScanner.scan(url) do |vuln|
    #       # ...
    #     end
    #
    #     vuln = Ronin::Vulns::URLScanner.test(url)
    #
    module URLScanner
      #
      # Scans a URL for web vulnerabilities.
      #
      # @param [URI::HTTP, String] url
      #   The URL to test or exploit.
      #
      # @option kwargs [String, Symbol, nil] :query_param
      #   The query param to test or exploit.
      #
      # @option kwargs [String, Symbol, nil] :header_name
      #   The HTTP Header name to test or exploit.
      #
      # @option kwargs [String, Symbol, nil] :cookie_param
      #   The `Cookie:` param name to test or exploit.
      #
      # @option kwargs [String, Symbol, nil] :form_param
      #   The form param name to test or exploit.
      #
      # @option kwargs [Ronin::Support::Network::HTTP, nil] :http
      #   An HTTP session to use for testing the URL.
      #
      # @option kwargs [:copy, :delete, :get, :head, :lock, :mkcol, :move,
      #         :options, :patch, :post, :propfind, :proppatch, :put,
      #         :trace, :unlock] :request_method
      #   The HTTP request mehtod for each request.
      #
      # @option kwargs [String, nil] :user
      #   The user to authenticate as.
      #
      # @option kwargs [String, nil] :password
      #   The password to authenticate with.
      #
      # @option kwargs [Hash{Symbol,String => String}, nil] :headers
      #   Additional HTTP header names and values to add to the request.
      #
      # @option kwargs [String, Hash{String => String}, nil] :cookie
      #   Additional `Cookie` header. If a `Hash` is given, it will be
      #   converted to a `String` using `Ronin::Support::Network::HTTP::Cookie`.
      #
      # @option kwargs [Hash, String, nil] :form_data
      #   The form data that may be sent in the body of the request.
      #
      # @option kwargs [String, nil] :referer
      #   The optional HTTP `Referer` header to send with each request.
      #
      # @param [Hash{Symbol => Object}, false] lfi
      #   Additional options for {LFI.scan}.
      #
      # @option lfi [:unix, :windows, nil] :os (:unix)
      #   Operating System to specifically target.
      #
      # @option lfi [Integer] :depth (6)
      #   Number of directories to escape up.
      #
      # @option lfi [:null_byte, :double_escape, :base64, :rot13, :zlib, nil] :filter_bypass
      #   Specifies which filter bypass technique to use.
      #
      #   * `:null_byte - appends a `%00` null byte to the escaped path.
      #     **Note:* this technique only works on PHP < 5.3.
      #   * `:double_escape` - Double escapes the {LFI#escape_path}
      #     (ex: `....//....//`).
      #   * `:base64` - Base64 encodes the included local file.
      #   * `:rot13` - ROT13 encodes the included local file.
      #   * `:zlib` - Zlib compresses and Base64 encodes the included local
      #     file.
      #
      # @param [Hash{Symbol => Object}, false] rfi
      #   Additional options for {RFI.scan}.
      #
      # @option rfi [:null_byte, :double_encode, nil] :filter_bypass
      #   Specifies which filter bypass technique to use.
      #   * `:double_encode` - will cause the inclusion URL to be URI escaped
      #     twice.
      #   * `:suffix_escape` - escape any appended suffix (ex: `param + ".php"`)
      #     by adding a URI fragment character (`#`) to the end of the RFI
      #     script URL. The fragment component of the URI is not sent to the
      #     web server.
      #   * `:null_byte` - will cause the inclusion URL to be appended with a
      #     `%00` character. **Note:* this technique only works on PHP < 5.3.
      #
      # @option rfi [String, URI::HTTP, nil] :test_script_url
      #   The URL of the RFI test script. If not specified, it will default to
      #   {RFI.test_script_for}.
      #
      # @param [Hash{Symbol => Object}, false] sqli
      #   Additional options for {SQLI.scan}.
      #
      # @option sqli [Boolean] :escape_quote (false)
      #   Specifies whether to escape a quoted string value.
      #
      # @option sqli [Boolean] :escape_parens (false)
      #   Specifies whether to escape parenthesis.
      #
      # @option sqli [Boolean] :terminate (false)
      #   Specifies whether to terminate the SQL statement with `--`.
      #
      # @param [Hash{Symbol => Object}, false] ssti
      #   Additional options for {SSTI.scan}.
      #
      # @option ssti [Proc, nil] :escape
      #   How to escape a given payload. Either a proc that will accept a String
      #   and return a String, or `nil` to indicate that the payload will not
      #   be escaped.
      #
      # @option ssti [(String, String)] :test
      #   The test payload and expected result to check for when testing the URL
      #   for SSTI.
      #
      # @param [Hash{Symbol => Object}, false] reflected_xss
      #   Additional options for {ReflectedXSS.scan}.
      #
      # @param [Hash{Symbol => Object}, false] open_redirect
      #   Additional options for {OpenRedirect.scan}.
      #
      # @option open_redirect [String] :test_url (OpenRedirect.random_test_url)
      #   The desired redirect URL to test the URL with.
      #
      # @yield [vuln]
      #   If a block is given it will be yielded each discovered web
      #   vulnerability.
      #
      # @yieldparam [LFI, RFI, SQLI, SSTI, ReflectedXSS, OpenRedirect] vuln
      #   A discovered web vulnerability in the URL.
      #
      # @return [Array<LFI, RFI, SQLI, SSTI, ReflectedXSS, OpenRedirect>]
      #   All discovered Web vulnerabilities.
      #
      def self.scan(url, lfi:  {},
                         rfi:  {},
                         sqli: {},
                         ssti: {},
                         reflected_xss: {},
                         open_redirect: {},
                         **kwargs,
                         &block)
        vulns = []

        if lfi
          vulns.concat(LFI.scan(url,**kwargs,**lfi,&block))
        end

        if rfi
          vulns.concat(RFI.scan(url,**kwargs,**rfi,&block))
        end

        if sqli
          vulns.concat(SQLI.scan(url,**kwargs,**sqli,&block))
        end

        if ssti
          vulns.concat(SSTI.scan(url,**kwargs,**ssti,&block))
        end

        if reflected_xss
          vulns.concat(ReflectedXSS.scan(url,**kwargs,**reflected_xss,&block))
        end

        if open_redirect
          vulns.concat(OpenRedirect.scan(url,**kwargs,**open_redirect,&block))
        end

        return vulns
      end

      #
      # Tests the URL for a Web vulnerability and returns the first found
      # vulnerability.
      #
      # @param [URI::HTTP, String] url
      #   The URL to test.
      #
      # @param [Hash{Symbol => Object}] kwargs
      #   Additional keyword arguments for {scan}.
      #
      # @return [LFI, RFI, SQLI, SSTI, ReflectedXSS, OpenRedirect, nil]
      #   The first discovered web vulnerability or `nil` if no vulnerabilities
      #   were discovered.
      #
      def self.test(url,**kwargs)
        scan(url,**kwargs) do |vuln|
          return vuln
        end

        return nil
      end
    end
  end
end