CoCalc provides the best real-time collaborative environment for Jupyter Notebooks, LaTeX documents, and SageMath, scalable from individual users to large groups and classes!

1
import os
2
import sys
3
import argparse
4
import datetime
5

6
try:
7
    import glob
8
except ImportError:
9
    print("Please install glob package")
10
    sys.exit()
11

12
if sys.version_info[0] < 3:
13
    raise Exception("Must be using Python 3")
14

15
parser = argparse.ArgumentParser(description='This script identifies issues with module documentation, including missing documentation, and incorrect file names.  Output is in markdown format.',
16
    prefix_chars='--', )
17
parser.add_argument('-m', '--modules', type=str, default='auxiliary/scanner', help='Choose the modules category to work with. Respect the module category names as in metasploit-framework. Only one category should be passed, e.g. "auxiliary/admin", "exploits/android/browser" or "encoders" are valid entries.')
18
parser.add_argument('--show_all', action="store_true", default=False, help='Show the complete list of items. In default mode, modules with documentation are marked "[x]" and modules without are marked "[ ]". In issues mode, documentation files without module are marked "[ ]" and documentation files with module are marked "[x]".')
19
parser.add_argument('--show_issues', action="store_true", default=False, help='Show the list of documentation files without modules instead of modules without documentation file.')
20
parser.add_argument('-o', '--output', help="Writes to a file.")
21
args = parser.parse_args()
22

23
module_type = args.modules
24
show_all = args.show_all
25
show_issues = args.show_issues
26

27
modules = []
28
docs = []
29
path = os.path.abspath(os.path.join(os.path.realpath(__file__),"..","..",".."))
30

31
if os.path.exists(os.path.join(path, 'modules', module_type)):
32
    list_docs = glob.glob(os.path.join(path,'documentation/modules', module_type, '**/*.md'), recursive=True)
33
    list_modules = glob.glob(os.path.join(path, 'modules', module_type, '**/*.*'),recursive=True)
34
else:
35
    print("Path doesn't exist. Maybe you have passed a wrong module category or maybe there isn't any documentation file yet.")
36
    sys.exit()
37

38
for doc in list_docs:
39
    docs.append(doc.split('.')[0].replace('/documentation/','/'))
40
for module in list_modules:
41
    # skip compiled python code, and python internal use files
42
    if module.split('.')[1] == 'pyc': continue
43
    if '/_' in module.split('.')[0]: continue
44
    modules.append(module.split('.')[0])
45

46
missings = 0
47
problems = 0
48
count = 0
49
root = 'metasploit-framework'
50
url_root = 'https://github.com/rapid7/metasploit-framework/blob/master/modules/'
51

52
if args.output:
53
  o = open(args.output, 'w')
54

55
def print_or_write(line):
56
  if args.output:
57
    o.write("%s\n" %(line))
58
    return
59
  print(line)
60

61
def make_link(line):
62
    # first we wenat to get the extension back
63
    for m in list_modules:
64
      if "%s." %(line) in m:
65
        ext = m
66
        break
67
    link = ext.split("/modules")[1]
68
    #link = ext.replace("/modules", url_root)
69
    return "[%s%s](%s%s)" %(root, line, url_root, link)
70

71
print_or_write('# Documentation Issue Finder\n')
72
print_or_write('Generated: %s\n' %(datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')))
73

74
if not (show_all):
75
    if not (show_issues):
76
        print_or_write('## Modules Without Documentation\n')
77
        for i in sorted(modules):
78
            if i not in docs:
79
                missings += 1
80
                print_or_write('+ [ ] %s' %(make_link(i.split('metasploit-framework')[1])))
81
        print_or_write('\n%s modules have no documentation.' %(missings))
82
    else:
83
        print_or_write('## Docs Without Modules\n')
84
        for i in sorted(docs):
85
            if i not in modules:
86
                problems += 1
87
                print_or_write('+ [ ] %s' %(make_link(i.split('metasploit-framework')[1])))
88
        print_or_write('\n%s doc files do not correspond to any module.' %(problems))
89
else:
90
    count = 0
91
    if not (show_issues):
92
        print_or_write('## Modules Without Documentation\n')
93
        for i in sorted(modules):
94
            if i in docs:
95
                print_or_write('+ [x] %s' %(make_link(i.split('metasploit-framework')[1])))
96
            else:
97
                print_or_write('+ [ ] %s' %(make_link(i.split('metasploit-framework')[1])))
98
                count += 1
99
        print_or_write('\n%s modules out of %s (%d%%) have no documentation.' %(count, len(modules), float(count)/len(modules) * 100.0))
100
    else:
101
        print_or_write('## Docs Without Modules\n')
102
        for i in sorted(docs):
103
            if i in modules:
104
                print_or_write('+ [x] %s' %(make_link(i.split('metasploit-framework')[1])))
105
            else:
106
                print_or_write('+ [ ] %s' %(make_link(i.split('metasploit-framework')[1])))
107
                count += 1
108
        print_or_write('\n%s doc files out of %s do not correspond to any module.' %(count, len(docs)))
109

110
if args.output:
111
  o.close()
112

113