tools/dev/msftidy_docs.rb - master - githubmirror/metasploit-framework

tools/dev/msftidy_docs.rb
338 строк9 KB
adfoster-r7
Fix msftidy heading in codeblock edgecase
13 апр 2026, 15:51
13 апр 2026, 15:519dbea3d
#!/usr/bin/env ruby
# -*- coding: binary -*-

#
# Check (recursively) for style compliance violations and other
# tree inconsistencies.
#
# by h00die
#

require 'fileutils'
require 'find'
require 'time'

SUPPRESS_INFO_MESSAGES = !!ENV['MSF_SUPPRESS_INFO_MESSAGES']

class String
  def red
    "\e[1;31;40m#{self}\e[0m"
  end

  def yellow
    "\e[1;33;40m#{self}\e[0m"
  end

  def green
    "\e[1;32;40m#{self}\e[0m"
  end

  def cyan
    "\e[1;36;40m#{self}\e[0m"
  end
end

class MsftidyDoc

  # Status codes
  OK       = 0
  WARNING  = 1
  ERROR    = 2

  # Some compiles regexes
  REGEX_MSF_EXPLOIT = / \< Msf::Exploit/
  REGEX_IS_BLANK_OR_END = /^\s*end\s*$/

  attr_reader :full_filepath, :source, :stat, :name, :status

  def initialize(source_file)
    @full_filepath = source_file
    @module_type = File.dirname(File.expand_path(@full_filepath))[/\/modules\/([^\/]+)/, 1]
    @source  = load_file(source_file)
    @lines   = @source.lines # returns an enumerator
    @status  = OK
    @name    = File.basename(source_file)
  end

  public

  #
  # Display a warning message, given some text and a number. Warnings
  # are usually style issues that may be okay for people who aren't core
  # Framework developers.
  #
  # @return status [Integer] Returns WARNINGS unless we already have an
  # error.
  def warn(txt, line=0) line_msg = (line>0) ? ":#{line}" : ''
    puts "#{@full_filepath}#{line_msg} - [#{'WARNING'.yellow}] #{cleanup_text(txt)}"
    @status = WARNING if @status < WARNING
  end

  #
  # Display an error message, given some text and a number. Errors
  # can break things or are so egregiously bad, style-wise, that they
  # really ought to be fixed.
  #
  # @return status [Integer] Returns ERRORS
  def error(txt, line=0)
    line_msg = (line>0) ? ":#{line}" : ''
    puts "#{@full_filepath}#{line_msg} - [#{'ERROR'.red}] #{cleanup_text(txt)}"
    @status = ERROR if @status < ERROR
  end

  # Currently unused, but some day msftidy will fix errors for you.
  def fixed(txt, line=0)
    line_msg = (line>0) ? ":#{line}" : ''
    puts "#{@full_filepath}#{line_msg} - [#{'FIXED'.green}] #{cleanup_text(txt)}"
  end

  #
  # Display an info message. Info messages do not alter the exit status.
  #
  def info(txt, line=0)
    return if SUPPRESS_INFO_MESSAGES
    line_msg = (line>0) ? ":#{line}" : ''
    puts "#{@full_filepath}#{line_msg} - [#{'INFO'.cyan}] #{cleanup_text(txt)}"
  end

  ##
  #
  # The functions below are actually the ones checking the source code
  #
  ##

  def has_module
    module_filepath = @full_filepath.sub('documentation/','').sub('/exploit/', '/exploits/')
    found = false
    ['.rb', '.py', '.go'].each do |ext|
      if File.file? module_filepath.sub(/.md$/, ext)
        found = true
        break
      end
    end
    unless found
      error("Doc missing module.  Check file name and path(s) are correct. Doc: #{@full_filepath}")
    end
  end

  def check_start_with_vuln_app
    unless @lines.first =~ /^## Vulnerable Application$/
      warn('Docs should start with ## Vulnerable Application')
    end
  end

  def has_h2_headings
    has_vulnerable_application = false
    has_verification_steps = false
    has_scenarios = false
    has_options = false
    has_bad_description = false
    has_bad_intro = false
    has_bad_scenario_sub = false

    @lines.each do |line|
      if line =~ /^## Vulnerable Application$/
        has_vulnerable_application = true
        next
      end

      if line =~ /^## Verification Steps$/ || line =~ /^## Module usage$/
        has_verification_steps = true
        next
      end

      if line =~ /^## Scenarios$/
        has_scenarios = true
        next
      end

      if line =~ /^## Options$/
        has_options = true
        next
      end

      if line =~ /^## Description$/
        has_bad_description = true
        next
      end

      if line =~ /^## (Intro|Introduction)$/
        has_bad_intro = true
        next
      end

      if line =~ /### Version and OS$/
        has_bad_scenario_sub = true
        next
      end
    end

    unless has_vulnerable_application
      warn('Missing Section: ## Vulnerable Application')
    end

    unless has_verification_steps
      warn('Missing Section: ## Verification Steps')
    end

    unless has_scenarios
      warn('Missing Section: ## Scenarios')
    end

    unless has_options
      # INFO because there may be no documentation-worthy options
      info('Missing Section: ## Options')
    end

    if has_bad_description
      warn('Descriptions should be within Vulnerable Application, or an H3 sub-section of Vulnerable Application')
    end

    if has_bad_intro
      warn('Intro/Introduction should be within Vulnerable Application, or an H3 sub-section of Vulnerable Application')
    end

    if has_bad_scenario_sub
      warn('Scenario sub-sections should include the vulnerable application version and OS tested on in an H3, not just ### Version and OS')
    end
  end

  def check_newline_eof
    if @source !~ /(?:\r\n|\n)\z/m
      warn('Please add a newline at the end of the file')
    end
  end

  # This checks that the H2 headings are in the right order. Options are optional.
  def h2_order
    unless @source =~ /^## Vulnerable Application$.+^## (Verification Steps|Module usage)$.+(?:^## Options$.+)?^## Scenarios$/m
      warn('H2 headings in incorrect order.  Should be: Vulnerable Application, Verification Steps/Module usage, Options, Scenarios')
    end
  end

  def line_checks
    idx = 0
    in_codeblock = false
    in_options = false

    @lines.each do |ln|
      idx += 1

      tback = ln.scan('```')
      if tback.length > 0
        if tback.length.even?
          warn("Should use single backquotes (`) for single line literals instead of triple backquotes (```)", idx)
        else
          in_codeblock = !in_codeblock
        end

        if ln =~ /^\s+```/
          warn("Code blocks using triple backquotes (```) should not be indented", idx)
        end
      end

      if ln =~ /## Options/
        in_options = true
      end

      if ln =~ /## Scenarios/ || (in_options && ln =~ /$\s*## /) # we're not in options anymore
        # we set a hard false here because there isn't a guarantee options exists
        in_options = false
      end

      if in_options && ln =~ /^\s*\*\*[a-z]+\*\*$/i # catch options in old format like **command** instead of ### command
        warn("Options should use ### instead of bolds (**)", idx)
      end

      # this will catch either bold or h2/3 universal options.  Defaults aren't needed since they're not unique to this exploit
      if in_options && ln =~ /^\s*[\*#]{2,3}\s*(rhost|rhosts|rport|lport|lhost|srvhost|srvport|ssl|uripath|session|proxies|payload|targeturi)\*{0,2}$/i
        warn('Universal options such as rhost(s), rport, lport, lhost, srvhost, srvport, ssl, uripath, session, proxies, payload, targeturi can be removed.', idx)
      end
      # find spaces at EOL not in a code block which is ``` or starts with four spaces
      if !in_codeblock && ln =~ /[ \t]$/ && !(ln =~ /^    /)
        warn("Spaces at EOL", idx)
      end

      if ln =~ /Example steps in this format/
        warn("Instructional text not removed", idx)
      end

      if !in_codeblock && ln =~ /^# /
        warn("No H1 (#) headers.  If this is code, indent.", idx)
      end

      l = 140
      if ln.rstrip.length > l && !in_codeblock
        warn("Line too long (#{ln.length}).  Consider a newline (which resolves to a space in markdown) to break it up around #{l} characters.", idx)
      end

    end
  end

  #
  # Run all the msftidy checks.
  #
  def run_checks
    has_module
    check_start_with_vuln_app
    has_h2_headings
    check_newline_eof
    h2_order
    line_checks
  end

  private

  def load_file(file)
    f = open(file, 'rb')
    @stat = f.stat
    buf = f.read(@stat.size)
    f.close
    return buf
  end

  def cleanup_text(txt)
    # remove line breaks
    txt = txt.gsub(/[\r\n]/, ' ')
    # replace multiple spaces by one space
    txt.gsub(/\s{2,}/, ' ')
  end
end

##
#
# Main program
#
##

if __FILE__ == $PROGRAM_NAME
  dirs = ARGV

  @exit_status = 0

  if dirs.length < 1
    $stderr.puts "Usage: #{File.basename(__FILE__)} <directory or file>"
    @exit_status = 1
    exit(@exit_status)
  end

  dirs.each do |dir|
    begin
      Find.find(dir) do |full_filepath|
        next if full_filepath =~ /\.git[\x5c\x2f]/
        next unless File.file? full_filepath
        next unless File.extname(full_filepath) == '.md'
        msftidy = MsftidyDoc.new(full_filepath)
        # Executable files are now assumed to be external modules
        # but also check for some content to be sure
        next if File.executable?(full_filepath) && msftidy.source =~ /require ["']metasploit["']/
        msftidy.run_checks
        @exit_status = msftidy.status if (msftidy.status > @exit_status.to_i)
      end
    rescue Errno::ENOENT
      $stderr.puts "#{File.basename(__FILE__)}: #{dir}: No such file or directory"
    end
  end

  exit(@exit_status.to_i)
end