nasldoc 0.2.1 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -13
- data/README.markdown +11 -11
- data/lib/nasldoc.rb +1 -1
- data/lib/nasldoc/cli/application.rb +73 -5
- data/lib/nasldoc/cli/comment.rb +4 -1
- data/lib/nasldoc/templates/file.erb +48 -6
- data/lib/nasldoc/templates/index.erb +1 -1
- metadata +21 -30
- data/Gemfile.lock +0 -17
- data/lib/nasldoc/cli/application.rb.orig +0 -290
- data/lib/nasldoc/cli/application.rb.rej +0 -16
checksums.yaml
CHANGED
@@ -1,15 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
|
5
|
-
data.tar.gz: !binary |-
|
6
|
-
Y2ZkYzUzMGZjZDFlYWE1NDEzODg3NDM5NWEwNWY2ZDU1MDlkMTM0Nw==
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 018bc2a6c15d0274f028720661ad5a6d77f9bd8c
|
4
|
+
data.tar.gz: 7cc54bfe4c54f1f8e3a7a129b342e39aa530deed
|
7
5
|
SHA512:
|
8
|
-
metadata.gz:
|
9
|
-
|
10
|
-
NzgxMjhjYTRkMTk0MzM4MjkzY2IwNmEwNTcxNWU5OTUzYWM0MTVhYzY3NTM3
|
11
|
-
MWNlYTA5YmZlMDM0NDFhYmNjNzdhY2EyODcwMzQ1YzVkNjI5MWU=
|
12
|
-
data.tar.gz: !binary |-
|
13
|
-
N2Q5NGE5N2NlMzRjN2VjNGRhOGVhNTJlYTlmNWRmZmQxZDRjY2I1MDMzNWQx
|
14
|
-
MGJkYmViYTQwZDYyYTRjZjNhOGFjYTQ3NmEyMzk2NGVkY2E1MmM3NGEwMjA4
|
15
|
-
ZGM5NWIzMzg5ODJkZDRmMWZiMjc5NmVlMWE2MGViZDE5NWEwNDk=
|
6
|
+
metadata.gz: 74c2f8090ef9c12c4847f88b7ca1b2886235e34e00ebb5ebacb82db46addb250c866c0ba6d8f04cff35f55b3a33df678576d8446b9d6f35fd4e4447a3809c289
|
7
|
+
data.tar.gz: 73741d08264c9c2b80b4e3c0c0507944c69a6d5031bb986ee97201156e68b42cfdc2fcab302ee9ea3d2ea3cd853a82d1010864344706299a2d4f030eab0fedc9
|
data/README.markdown
CHANGED
@@ -8,29 +8,29 @@ Installation is really easy, all you need to do is gem install!
|
|
8
8
|
|
9
9
|
#Usage
|
10
10
|
|
11
|
-
Using nasldoc is fairly simple just pass it a directory or a single file that you want to generate the documentation for.
|
11
|
+
Using `nasldoc` is fairly simple; just pass it a directory or a single file that you want to generate the documentation for. `nasldoc` is designed to only parse .inc files which special comment markup.
|
12
12
|
|
13
13
|
% nasldoc /opt/nessus/lib/nessus/plugins/
|
14
14
|
|
15
|
-
This will cause a directory called nasldoc
|
15
|
+
This will cause a directory called `nasldoc/` to be created in your current directory. This directory will contain all of the generated HTML documents. After running `nasldoc`, open `index.html` inside of `nasldoc/` and view the documentation.
|
16
16
|
|
17
17
|
#Comment Markup
|
18
18
|
|
19
|
-
|
19
|
+
`nasldoc` comments are inclosed in ## blocks and use special tags to mark items. Currently, there are only 3 tags. Tags can be added in a matter of minutes to the parser.
|
20
20
|
|
21
|
-
|
21
|
+
nasldoc supports several markup tags:
|
22
22
|
|
23
23
|
- @param - used to label named arguments to a function
|
24
24
|
- @anonparam - used to label anonymous arguments to a function
|
25
25
|
- @return - what the function returns
|
26
|
-
- @deprecated -
|
27
|
-
- @nessus -
|
28
|
-
- @category -
|
29
|
-
- @remark -
|
26
|
+
- @deprecated - notation for functions that shouldn't be used
|
27
|
+
- @nessus - minimum Nessus version supported
|
28
|
+
- @category - type of category for the function
|
29
|
+
- @remark - special notes or remarks
|
30
30
|
|
31
31
|
#Function Description Block
|
32
32
|
|
33
|
-
The function description block is free form text from the first ## to the first @tag in the nasldoc body
|
33
|
+
The function description block is free form text from the first ## block to the first @tag in the `nasldoc` body. The lines are split on the # and rejoined with spaces.
|
34
34
|
|
35
35
|
#Example
|
36
36
|
|
@@ -40,7 +40,7 @@ The function description block is free form text from the first ## to the first
|
|
40
40
|
# @param arg1 first number to add
|
41
41
|
# @param arg2 second number to add
|
42
42
|
#
|
43
|
-
# @return
|
43
|
+
# @return the sum of arg1 and arg2
|
44
44
|
##
|
45
45
|
function add(arg1, arg2)
|
46
46
|
{
|
@@ -49,7 +49,7 @@ The function description block is free form text from the first ## to the first
|
|
49
49
|
|
50
50
|
#Templates
|
51
51
|
|
52
|
-
|
52
|
+
`nasldoc` uses the ERB templating engine to make generating the output HTML trivial. Attached is an example of the sidebar; ruby code can be injected to help generate the layout.
|
53
53
|
|
54
54
|
##Example
|
55
55
|
|
data/lib/nasldoc.rb
CHANGED
@@ -51,6 +51,12 @@ module NaslDoc
|
|
51
51
|
|
52
52
|
@overview = nil
|
53
53
|
|
54
|
+
@fn_ns_map = {}
|
55
|
+
@obj_ns_map = {}
|
56
|
+
@obj_fn_map = {}
|
57
|
+
|
58
|
+
@namespaces = []
|
59
|
+
|
54
60
|
@template_dir = Pathname.new(__FILE__).realpath.to_s.gsub('cli/application.rb', 'templates')
|
55
61
|
@asset_dir = Pathname.new(__FILE__).realpath.to_s.gsub('cli/application.rb', 'assets')
|
56
62
|
@current_file = "(unknown)"
|
@@ -77,6 +83,31 @@ module NaslDoc
|
|
77
83
|
base(path).gsub('.', '_') + '.html'
|
78
84
|
end
|
79
85
|
|
86
|
+
# Generates namespace mappings
|
87
|
+
def build_namespace_map(tree, namespaces, fn_map, obj_map, obj_fn_map, level=0, prefix = nil, object = nil)
|
88
|
+
cur_namespace = prefix
|
89
|
+
for node in tree do
|
90
|
+
if(node.class.to_s == "Nasl::Namespace")
|
91
|
+
if(level == 0)
|
92
|
+
namespaces << node.name.name
|
93
|
+
build_namespace_map(node, namespaces, fn_map, obj_map, obj_fn_map, level + 1, node.name.name)
|
94
|
+
else
|
95
|
+
ns = prefix + '::' + node.name.name
|
96
|
+
namespaces << ns
|
97
|
+
build_namespace_map(node, namespaces, fn_map, obj_map, obj_fn_map, level + 1, ns)
|
98
|
+
end
|
99
|
+
elsif(node.class.to_s == "Nasl::Function")
|
100
|
+
fn_map[node.to_s] = cur_namespace
|
101
|
+
if(!object.nil?)
|
102
|
+
obj_fn_map[node.to_s] = object
|
103
|
+
end
|
104
|
+
elsif(node.class.to_s == "Nasl::Object")
|
105
|
+
obj_map[node.to_s] = cur_namespace
|
106
|
+
build_namespace_map(node, namespaces, fn_map, obj_map, obj_fn_map, level + 1, cur_namespace, node.name.name)
|
107
|
+
end
|
108
|
+
end
|
109
|
+
end
|
110
|
+
|
80
111
|
# Compiles a template for each file
|
81
112
|
def build_template name, path=nil
|
82
113
|
path ||= name
|
@@ -105,18 +136,55 @@ module NaslDoc
|
|
105
136
|
return nil
|
106
137
|
end
|
107
138
|
|
139
|
+
# get namespace mapping
|
140
|
+
build_namespace_map(tree, @namespaces, @fn_ns_map, @obj_ns_map, @obj_fn_map)
|
141
|
+
|
108
142
|
# Collect the functions.
|
109
143
|
@functions = Hash.new()
|
110
144
|
tree.all(:Function).map do |fn|
|
111
|
-
@
|
112
|
-
|
113
|
-
|
145
|
+
ns = @fn_ns_map[fn.to_s]
|
146
|
+
show_ns = 0
|
147
|
+
if(fn.fn_type == "normal" and !ns.nil?)
|
148
|
+
show_ns = 1
|
149
|
+
end
|
150
|
+
code_snip = fn.context(nil, false, false)
|
151
|
+
if (!code_snip.nil?)
|
152
|
+
code_snip = code_snip.gsub(/#*$/, "").rstrip
|
153
|
+
end
|
154
|
+
@functions[fn.to_s] = {
|
155
|
+
:name => fn.name.name,
|
156
|
+
:code => code_snip,
|
157
|
+
:params => fn.params.map(&:name),
|
158
|
+
:namespace => ns,
|
159
|
+
:fn_type => fn.fn_type,
|
160
|
+
:show_ns => show_ns,
|
161
|
+
:object => @obj_fn_map[fn.to_s]
|
114
162
|
}
|
115
163
|
@function_count += 1
|
116
164
|
end
|
117
165
|
|
118
|
-
@funcs_prv =
|
119
|
-
@funcs_pub =
|
166
|
+
@funcs_prv = {}
|
167
|
+
@funcs_pub = {}
|
168
|
+
|
169
|
+
for function in tree.all(:Function) do
|
170
|
+
if (defined? function.tokens[0].type and function.tokens[0].type == :PUBLIC)
|
171
|
+
@funcs_pub[function.to_s] = @functions[function.to_s]
|
172
|
+
elsif (defined? function.tokens[0].type and function.tokens[0].type == :PRIVATE)
|
173
|
+
@funcs_prv[function.to_s] = @functions[function.to_s]
|
174
|
+
elsif (function.fn_type == 'obj' and defined? function.tokens[0].type and function.tokens[0].type.nil?)
|
175
|
+
if(obj_fn_map[function.to_s] == function.name.name) # handle constructor
|
176
|
+
@funcs_pub[function.to_s] = @functions[function.to_s]
|
177
|
+
else
|
178
|
+
@funcs_prv[function.to_s] = @functions[function.to_s]
|
179
|
+
end
|
180
|
+
elsif (function.name.name =~ /^_/)
|
181
|
+
@funcs_prv[function.to_s] = @functions[function.to_s]
|
182
|
+
else
|
183
|
+
@funcs_pub[function.to_s] = @functions[function.to_s]
|
184
|
+
end
|
185
|
+
end
|
186
|
+
# @funcs_prv = @functions.select { |n, p| n =~ /^_/ }
|
187
|
+
# @funcs_pub = @functions.reject { |n, p| @funcs_prv.key? n }
|
120
188
|
|
121
189
|
# Collect the globals.
|
122
190
|
@globals = tree.all(:Global).map(&:idents).flatten.map do |id|
|
data/lib/nasldoc/cli/comment.rb
CHANGED
@@ -240,6 +240,7 @@ module NaslDoc
|
|
240
240
|
raise TagFormatException, "Failed to parse the #{tag}'s block for #@name."
|
241
241
|
end
|
242
242
|
block.lstrip!
|
243
|
+
block = block.gsub(/^.*>/, "")
|
243
244
|
|
244
245
|
# Check for previous declarations of this name.
|
245
246
|
if @anonparams.key?(name)
|
@@ -252,6 +253,7 @@ module NaslDoc
|
|
252
253
|
|
253
254
|
hash = self.send(attr + 's')
|
254
255
|
hash[name] = block
|
256
|
+
|
255
257
|
when '@category'
|
256
258
|
unless @categories.empty?
|
257
259
|
raise DuplicateTagException, "The #{tag} tag appears more than once for #@name."
|
@@ -296,7 +298,8 @@ module NaslDoc
|
|
296
298
|
def extract_function(node)
|
297
299
|
# Remember the function name.
|
298
300
|
fn = node.next
|
299
|
-
@function = fn.
|
301
|
+
@function = fn.to_s
|
302
|
+
@fn_type = fn.fn_type
|
300
303
|
|
301
304
|
# Name this comment for use in error messages.
|
302
305
|
@name = "function #@function"
|
@@ -26,6 +26,34 @@
|
|
26
26
|
end
|
27
27
|
%>
|
28
28
|
|
29
|
+
<%
|
30
|
+
def build_fn_name(name, colorize = 0)
|
31
|
+
fn_str = ''
|
32
|
+
if (!@functions[name][:namespace].nil?)
|
33
|
+
if(colorize)
|
34
|
+
fn_str += "<font color='#770877'>" + @functions[name][:namespace] + "</font><b>::</b>"
|
35
|
+
else
|
36
|
+
fn_str += @functions[name][:namespace] + "::"
|
37
|
+
end
|
38
|
+
end
|
39
|
+
if (!@functions[name][:object].nil?)
|
40
|
+
if(colorize)
|
41
|
+
fn_str += "<font color='#B83E0D'>" + @functions[name][:object] + "</font><b>.</b>"
|
42
|
+
else
|
43
|
+
fn_str += @functions[name][:object] + "."
|
44
|
+
end
|
45
|
+
end
|
46
|
+
if(colorize)
|
47
|
+
color = "#50A40B"
|
48
|
+
color = "#086E6E" if @functions[name][:fn_type] == "obj"
|
49
|
+
fn_str += "<font color='#" + color + "'><b>" + @functions[name][:name] + "()</b></font>"
|
50
|
+
else
|
51
|
+
fn_str += @functions[name][:name]
|
52
|
+
end
|
53
|
+
fn_str
|
54
|
+
end
|
55
|
+
%>
|
56
|
+
|
29
57
|
<!DOCTYPE html>
|
30
58
|
<html lang="en">
|
31
59
|
<head>
|
@@ -161,9 +189,9 @@
|
|
161
189
|
<th>Name</th>
|
162
190
|
<th>Summary</th>
|
163
191
|
</tr>
|
164
|
-
|
192
|
+
<% list.each do |name| %>
|
165
193
|
<tr>
|
166
|
-
<td><a href="
|
194
|
+
<td><a href="#<% name %>"><%= name %></a></td>
|
167
195
|
<td><%= safe(comment(name, :global), "", :summary) %></td>
|
168
196
|
</tr>
|
169
197
|
<% end %>
|
@@ -190,9 +218,11 @@
|
|
190
218
|
<th>Name</th>
|
191
219
|
<th>Summary</th>
|
192
220
|
</tr>
|
193
|
-
<% list.keys.
|
221
|
+
<% list.keys.sort_by { |key| [@functions[key][:name]] }.each do |name| %>
|
194
222
|
<tr>
|
195
|
-
<td><a href="#<%= name %>"
|
223
|
+
<td><a href="#<%= build_fn_name(name) %>">
|
224
|
+
<%= build_fn_name(name, 1) %>
|
225
|
+
</a></td>
|
196
226
|
<td><%= safe(comment(name, :function), "", :summary) %></td>
|
197
227
|
</tr>
|
198
228
|
<% end %>
|
@@ -258,7 +288,7 @@
|
|
258
288
|
<% unless list.empty? %>
|
259
289
|
<h1><%= name %> Function Details</h1>
|
260
290
|
<% list.keys.sort.each do |name| %>
|
261
|
-
<h2 id="<%= name %>"><%= name %></h2>
|
291
|
+
<h2 id="<%= build_fn_name(name) %>"><%= @functions[name][:name] %></h2>
|
262
292
|
<% comm = comment(name, :function) %>
|
263
293
|
|
264
294
|
<% unless comm.nil? %>
|
@@ -267,6 +297,16 @@
|
|
267
297
|
<p class="summary"><%= comm.summary %></p>
|
268
298
|
<% end %>
|
269
299
|
|
300
|
+
<% unless @functions[name][:namespace].nil? %>
|
301
|
+
<h3>Namespace</h3>
|
302
|
+
<p class="namespace"><%= @functions[name][:namespace] %></p>
|
303
|
+
<% end %>
|
304
|
+
|
305
|
+
<% unless @functions[name][:object].nil? %>
|
306
|
+
<h3>Object</h3>
|
307
|
+
<p class="object"><%= @functions[name][:object] %></p>
|
308
|
+
<% end %>
|
309
|
+
|
270
310
|
<% unless comm.description.empty? %>
|
271
311
|
<h3>Description</h3>
|
272
312
|
<% comm.description.each do |para| %>
|
@@ -332,7 +372,9 @@
|
|
332
372
|
<h3>Code</h3>
|
333
373
|
<!-- The contents must not have indentation, else formatting is off. -->
|
334
374
|
<pre class="brush: nasl">
|
375
|
+
<% unless @functions[name][:code].nil? %>
|
335
376
|
<%= CGI::escapeHTML(@functions[name][:code]) %>
|
377
|
+
<% end %>
|
336
378
|
</pre>
|
337
379
|
<a href="#top">top</a>
|
338
380
|
<hr>
|
@@ -346,7 +388,7 @@
|
|
346
388
|
<hr>
|
347
389
|
|
348
390
|
<footer>
|
349
|
-
<p>© Tenable Network Security
|
391
|
+
<p>© Tenable Network Security 2018</p>
|
350
392
|
</footer>
|
351
393
|
|
352
394
|
</div><!--/.fluid-container-->
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: nasldoc
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.3.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Jacob Hammack
|
@@ -10,68 +10,62 @@ authors:
|
|
10
10
|
autorequire:
|
11
11
|
bindir: bin
|
12
12
|
cert_chain: []
|
13
|
-
date:
|
13
|
+
date: 2018-06-01 00:00:00.000000000 Z
|
14
14
|
dependencies:
|
15
15
|
- !ruby/object:Gem::Dependency
|
16
16
|
name: rake
|
17
17
|
requirement: !ruby/object:Gem::Requirement
|
18
18
|
requirements:
|
19
|
-
- - ~>
|
19
|
+
- - "~>"
|
20
20
|
- !ruby/object:Gem::Version
|
21
21
|
version: '10.1'
|
22
22
|
type: :development
|
23
23
|
prerelease: false
|
24
24
|
version_requirements: !ruby/object:Gem::Requirement
|
25
25
|
requirements:
|
26
|
-
- - ~>
|
26
|
+
- - "~>"
|
27
27
|
- !ruby/object:Gem::Version
|
28
28
|
version: '10.1'
|
29
29
|
- !ruby/object:Gem::Dependency
|
30
30
|
name: nasl
|
31
31
|
requirement: !ruby/object:Gem::Requirement
|
32
32
|
requirements:
|
33
|
-
- - ~>
|
33
|
+
- - "~>"
|
34
34
|
- !ruby/object:Gem::Version
|
35
35
|
version: '0.2'
|
36
|
-
- -
|
36
|
+
- - ">="
|
37
37
|
- !ruby/object:Gem::Version
|
38
|
-
version:
|
39
|
-
MC4yLjA=
|
38
|
+
version: 0.2.0
|
40
39
|
type: :runtime
|
41
40
|
prerelease: false
|
42
41
|
version_requirements: !ruby/object:Gem::Requirement
|
43
42
|
requirements:
|
44
|
-
- - ~>
|
43
|
+
- - "~>"
|
45
44
|
- !ruby/object:Gem::Version
|
46
45
|
version: '0.2'
|
47
|
-
- -
|
46
|
+
- - ">="
|
48
47
|
- !ruby/object:Gem::Version
|
49
|
-
version:
|
50
|
-
MC4yLjA=
|
48
|
+
version: 0.2.0
|
51
49
|
- !ruby/object:Gem::Dependency
|
52
50
|
name: rainbow
|
53
51
|
requirement: !ruby/object:Gem::Requirement
|
54
52
|
requirements:
|
55
|
-
- - ~>
|
53
|
+
- - "~>"
|
56
54
|
- !ruby/object:Gem::Version
|
57
|
-
version:
|
58
|
-
|
59
|
-
- - ! '>='
|
55
|
+
version: '2.0'
|
56
|
+
- - ">="
|
60
57
|
- !ruby/object:Gem::Version
|
61
|
-
version:
|
62
|
-
Mi4wLjA=
|
58
|
+
version: 2.0.0
|
63
59
|
type: :runtime
|
64
60
|
prerelease: false
|
65
61
|
version_requirements: !ruby/object:Gem::Requirement
|
66
62
|
requirements:
|
67
|
-
- - ~>
|
63
|
+
- - "~>"
|
68
64
|
- !ruby/object:Gem::Version
|
69
|
-
version:
|
70
|
-
|
71
|
-
- - ! '>='
|
65
|
+
version: '2.0'
|
66
|
+
- - ">="
|
72
67
|
- !ruby/object:Gem::Version
|
73
|
-
version:
|
74
|
-
Mi4wLjA=
|
68
|
+
version: 2.0.0
|
75
69
|
description: nasldoc is a NASL documentation generator
|
76
70
|
email:
|
77
71
|
- jhammack@tenable.com
|
@@ -87,7 +81,6 @@ extra_rdoc_files:
|
|
87
81
|
files:
|
88
82
|
- Gemfile
|
89
83
|
- Gemfile.ci
|
90
|
-
- Gemfile.lock
|
91
84
|
- LICENSE
|
92
85
|
- NEWS.markdown
|
93
86
|
- README.markdown
|
@@ -110,8 +103,6 @@ files:
|
|
110
103
|
- lib/nasldoc/assets/js/shCore.js
|
111
104
|
- lib/nasldoc/cli.rb
|
112
105
|
- lib/nasldoc/cli/application.rb
|
113
|
-
- lib/nasldoc/cli/application.rb.orig
|
114
|
-
- lib/nasldoc/cli/application.rb.rej
|
115
106
|
- lib/nasldoc/cli/comment.rb
|
116
107
|
- lib/nasldoc/templates/file.erb
|
117
108
|
- lib/nasldoc/templates/index.erb
|
@@ -126,17 +117,17 @@ require_paths:
|
|
126
117
|
- lib
|
127
118
|
required_ruby_version: !ruby/object:Gem::Requirement
|
128
119
|
requirements:
|
129
|
-
- -
|
120
|
+
- - ">="
|
130
121
|
- !ruby/object:Gem::Version
|
131
122
|
version: '0'
|
132
123
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
133
124
|
requirements:
|
134
|
-
- -
|
125
|
+
- - ">="
|
135
126
|
- !ruby/object:Gem::Version
|
136
127
|
version: 1.8.24
|
137
128
|
requirements: []
|
138
129
|
rubyforge_project: nasldoc
|
139
|
-
rubygems_version: 2.
|
130
|
+
rubygems_version: 2.2.2
|
140
131
|
signing_key:
|
141
132
|
specification_version: 4
|
142
133
|
summary: nasldoc
|
data/Gemfile.lock
DELETED
@@ -1,17 +0,0 @@
|
|
1
|
-
GEM
|
2
|
-
remote: https://rubygems.org/
|
3
|
-
specs:
|
4
|
-
builder (3.2.2)
|
5
|
-
nasl (0.2.0)
|
6
|
-
builder (~> 3.1)
|
7
|
-
rainbow (~> 2.0)
|
8
|
-
rainbow (2.0.0)
|
9
|
-
rake (10.3.2)
|
10
|
-
|
11
|
-
PLATFORMS
|
12
|
-
ruby
|
13
|
-
|
14
|
-
DEPENDENCIES
|
15
|
-
nasl (= 0.2.0)
|
16
|
-
rainbow (= 2.0.0)
|
17
|
-
rake (= 10.3.2)
|
@@ -1,290 +0,0 @@
|
|
1
|
-
################################################################################
|
2
|
-
# Copyright (c) 2011-2014, Tenable Network Security
|
3
|
-
# All rights reserved.
|
4
|
-
#
|
5
|
-
# Redistribution and use in source and binary forms, with or without
|
6
|
-
# modification, are permitted provided that the following conditions are met:
|
7
|
-
#
|
8
|
-
# 1. Redistributions of source code must retain the above copyright notice, this
|
9
|
-
# list of conditions and the following disclaimer.
|
10
|
-
#
|
11
|
-
# 2. Redistributions in binary form must reproduce the above copyright notice,
|
12
|
-
# this list of conditions and the following disclaimer in the documentation
|
13
|
-
# and/or other materials provided with the distribution.
|
14
|
-
#
|
15
|
-
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
16
|
-
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
17
|
-
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
18
|
-
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
19
|
-
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
20
|
-
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
21
|
-
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
22
|
-
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
23
|
-
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
24
|
-
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
25
|
-
################################################################################
|
26
|
-
|
27
|
-
require 'nasldoc/cli/comment'
|
28
|
-
|
29
|
-
module NaslDoc
|
30
|
-
module CLI
|
31
|
-
class Application
|
32
|
-
attr_accessor :error_count
|
33
|
-
|
34
|
-
# Initializes the Application class
|
35
|
-
#
|
36
|
-
# - Sets the default output directory to nasldoc_output/
|
37
|
-
# - Sets the template directory to lib/templates
|
38
|
-
# - Sets the assets directory to lib/assets
|
39
|
-
#
|
40
|
-
def initialize
|
41
|
-
@file_list = Array.new
|
42
|
-
@function_count = 0
|
43
|
-
@error_count = 0
|
44
|
-
@options = Hash.new
|
45
|
-
|
46
|
-
@options[:output_directory] = "nasldoc_ouput/"
|
47
|
-
|
48
|
-
@functions = Array.new
|
49
|
-
@globals = Array.new
|
50
|
-
@includes = Array.new
|
51
|
-
|
52
|
-
@overview = nil
|
53
|
-
|
54
|
-
@template_dir = Pathname.new(__FILE__).realpath.to_s.gsub('cli/application.rb', 'templates')
|
55
|
-
@asset_dir = Pathname.new(__FILE__).realpath.to_s.gsub('cli/application.rb', 'assets')
|
56
|
-
@current_file = "(unknown)"
|
57
|
-
end
|
58
|
-
|
59
|
-
# For ERB Support
|
60
|
-
#
|
61
|
-
# @return ERB Binding for access to instance variables in templates
|
62
|
-
def get_binding
|
63
|
-
binding
|
64
|
-
end
|
65
|
-
|
66
|
-
# Generates the base name for a path
|
67
|
-
#
|
68
|
-
# @return htmlized file name for .inc file
|
69
|
-
def base path
|
70
|
-
File.basename(path, '.inc')
|
71
|
-
end
|
72
|
-
|
73
|
-
# Generates the HTML base name for a path
|
74
|
-
#
|
75
|
-
# @return htmlized file name for .inc file
|
76
|
-
def url path
|
77
|
-
base(path).gsub('.', '_') + '.html'
|
78
|
-
end
|
79
|
-
|
80
|
-
# Compiles a template for each file
|
81
|
-
def build_template name, path=nil
|
82
|
-
path ||= name
|
83
|
-
|
84
|
-
dest = url(path)
|
85
|
-
puts "[**] Creating #{dest}"
|
86
|
-
@erb = ERB.new File.new("#{@template_dir}/#{name}.erb").read, nil, "%"
|
87
|
-
html = @erb.result(get_binding)
|
88
|
-
|
89
|
-
File.open("#{@options[:output_directory]}/#{dest}", 'w+') do |f|
|
90
|
-
f.puts html
|
91
|
-
end
|
92
|
-
end
|
93
|
-
|
94
|
-
# Processes each .inc file and sets instance variables for each template
|
95
|
-
def build_file_page path
|
96
|
-
puts "[*] Processing file: #{path}"
|
97
|
-
@current_file = File.basename(path)
|
98
|
-
contents = File.open(path, "rb") { |f| f.read }
|
99
|
-
|
100
|
-
# Parse the input file.
|
101
|
-
tree = Nasl::Parser.new.parse(contents, path)
|
102
|
-
|
103
|
-
# Collect the functions.
|
104
|
-
@functions = Hash.new()
|
105
|
-
tree.all(:Function).map do |fn|
|
106
|
-
@functions[fn.name.name] = {
|
107
|
-
:code => fn.context(nil, false, false),
|
108
|
-
:params => fn.params.map(&:name)
|
109
|
-
}
|
110
|
-
@function_count += 1
|
111
|
-
end
|
112
|
-
|
113
|
-
@funcs_prv = @functions.select { |n, p| n =~ /^_/ }
|
114
|
-
@funcs_pub = @functions.reject { |n, p| @funcs_prv.key? n }
|
115
|
-
|
116
|
-
# Collect the globals.
|
117
|
-
@globals = tree.all(:Global).map(&:idents).flatten.map do |id|
|
118
|
-
if id.is_a? Nasl::Assignment
|
119
|
-
id.lval.name
|
120
|
-
else
|
121
|
-
id.name
|
122
|
-
end
|
123
|
-
end.sort
|
124
|
-
|
125
|
-
@globs_prv = @globals.select { |n| n =~ /^_/ }
|
126
|
-
@globs_pub = @globals.reject { |n| @globs_prv.include? n }
|
127
|
-
|
128
|
-
# Collect the includes.
|
129
|
-
@includes = tree.all(:Include).map(&:filename).map(&:text).sort
|
130
|
-
|
131
|
-
# Parse the comments.
|
132
|
-
@comments = tree.all(:Comment)
|
133
|
-
puts "[**] #{@comments.size} comment(s) were found"
|
134
|
-
@comments.map! do |comm|
|
135
|
-
begin
|
136
|
-
NaslDoc::CLI::Comment.new(comm, path)
|
137
|
-
rescue CommentException => e
|
138
|
-
# A short message is okay for format errors.
|
139
|
-
puts "[!!!] #{e.class.name} #{e.message}"
|
140
|
-
@error_count += 1
|
141
|
-
nil
|
142
|
-
rescue Exception => e
|
143
|
-
# A detailed message is given for programming errors.
|
144
|
-
puts "[!!!] #{e.class.name} #{e.message}"
|
145
|
-
puts e.backtrace.map{ |l| l.prepend "[!!!!] " }.join("\n")
|
146
|
-
nil
|
147
|
-
end
|
148
|
-
end
|
149
|
-
@comments.compact!
|
150
|
-
@comments.keep_if &:valid
|
151
|
-
puts "[**] #{@comments.size} nasldoc comment(s) were parsed"
|
152
|
-
|
153
|
-
# Find the overview comment.
|
154
|
-
@overview = @comments.select{ |c| c.type == :file }.shift
|
155
|
-
|
156
|
-
build_template "file", path
|
157
|
-
end
|
158
|
-
|
159
|
-
# Builds each page from the file_list
|
160
|
-
def build_file_pages
|
161
|
-
@file_list.each do |f|
|
162
|
-
build_file_page(f)
|
163
|
-
end
|
164
|
-
end
|
165
|
-
|
166
|
-
# Copies required assets to the final build directory
|
167
|
-
def copy_assets
|
168
|
-
puts `cp -vr #{@asset_dir}/* #{@options[:output_directory]}/`
|
169
|
-
end
|
170
|
-
|
171
|
-
# Prints documentation stats to stdout
|
172
|
-
def print_documentation_stats
|
173
|
-
puts "\n\nDocumentation Statistics"
|
174
|
-
puts "Files: #{@file_list.size}"
|
175
|
-
puts "Functions: #{@function_count}"
|
176
|
-
puts "Errors: #{@error_count}"
|
177
|
-
end
|
178
|
-
|
179
|
-
# Removes blacklisted files from the file list
|
180
|
-
def remove_blacklist file_list
|
181
|
-
blacklist = [
|
182
|
-
"apple_device_model_list.inc",
|
183
|
-
"blacklist_dss.inc",
|
184
|
-
"blacklist_rsa.inc",
|
185
|
-
"blacklist_ssl_rsa1024.inc",
|
186
|
-
"blacklist_ssl_rsa2048.inc",
|
187
|
-
"custom_CA.inc",
|
188
|
-
"daily_badip.inc",
|
189
|
-
"daily_badip2.inc",
|
190
|
-
"daily_badurl.inc",
|
191
|
-
"known_CA.inc",
|
192
|
-
"oui.inc",
|
193
|
-
"oval-definitions-schematron.inc",
|
194
|
-
"ovaldi32-rhel5.inc",
|
195
|
-
"ovaldi32-win-dyn-v100.inc",
|
196
|
-
"ovaldi32-win-dyn-v90.inc",
|
197
|
-
"ovaldi32-win-static.inc",
|
198
|
-
"ovaldi64-rhel5.inc",
|
199
|
-
"ovaldi64-win-dyn-v100.inc",
|
200
|
-
"ovaldi64-win-dyn-v90.inc",
|
201
|
-
"ovaldi64-win-static.inc",
|
202
|
-
"plugin_feed_info.inc",
|
203
|
-
"sc_families.inc",
|
204
|
-
"scap_schema.inc",
|
205
|
-
"ssl_known_cert.inc"
|
206
|
-
]
|
207
|
-
|
208
|
-
new_file_list = file_list.dup
|
209
|
-
|
210
|
-
file_list.each_with_index do |file, index|
|
211
|
-
blacklist.each do |bf|
|
212
|
-
if file =~ /#{bf}/
|
213
|
-
new_file_list.delete(file)
|
214
|
-
end
|
215
|
-
end
|
216
|
-
end
|
217
|
-
|
218
|
-
return new_file_list
|
219
|
-
end
|
220
|
-
|
221
|
-
# Parses the command line arguments
|
222
|
-
def parse_args
|
223
|
-
opts = OptionParser.new do |opt|
|
224
|
-
opt.banner = "#{APP_NAME} v#{VERSION}\nTenable Network Security.\njhammack@tenable.com\n\n"
|
225
|
-
opt.banner << "Usage: #{APP_NAME} [options] [file|directory]"
|
226
|
-
|
227
|
-
opt.separator ''
|
228
|
-
opt.separator 'Options'
|
229
|
-
|
230
|
-
opt.on('-o', '--output DIRECTORY', "Directory to output results to, created if it doesn't exit") do |option|
|
231
|
-
@options[:output_directory] = option
|
232
|
-
end
|
233
|
-
|
234
|
-
opt.separator ''
|
235
|
-
opt.separator 'Other Options'
|
236
|
-
|
237
|
-
opt.on_tail('-v', '--version', "Shows application version information") do
|
238
|
-
puts "#{APP_NAME} - #{VERSION}"
|
239
|
-
exit
|
240
|
-
end
|
241
|
-
|
242
|
-
opt.on_tail('-?', '--help', 'Show this message') do
|
243
|
-
puts opt.to_s + "\n"
|
244
|
-
exit
|
245
|
-
end
|
246
|
-
end
|
247
|
-
|
248
|
-
if ARGV.length != 0
|
249
|
-
opts.parse!
|
250
|
-
else
|
251
|
-
puts opts.to_s + "\n"
|
252
|
-
exit
|
253
|
-
end
|
254
|
-
end
|
255
|
-
|
256
|
-
# Main function for running nasldoc
|
257
|
-
def run
|
258
|
-
parse_args
|
259
|
-
|
260
|
-
if File.directory?(ARGV.first) == true
|
261
|
-
pattern = File.join(ARGV.first, '**', '*.inc')
|
262
|
-
@file_list = Dir.glob pattern
|
263
|
-
else
|
264
|
-
@file_list << ARGV.first
|
265
|
-
end
|
266
|
-
|
267
|
-
# Ensure the output directory exists.
|
268
|
-
if File.directory?(@options[:output_directory]) == false
|
269
|
-
Dir.mkdir @options[:output_directory]
|
270
|
-
end
|
271
|
-
|
272
|
-
# Get rid of non-NASL files.
|
273
|
-
@file_list = remove_blacklist(@file_list)
|
274
|
-
|
275
|
-
# Ensure we process files in a consistent order.
|
276
|
-
@file_list.sort! do |a, b|
|
277
|
-
base(a) <=> base(b)
|
278
|
-
end
|
279
|
-
|
280
|
-
puts "[*] Building documentation..."
|
281
|
-
|
282
|
-
build_template "index"
|
283
|
-
build_file_pages
|
284
|
-
copy_assets
|
285
|
-
|
286
|
-
print_documentation_stats
|
287
|
-
end
|
288
|
-
end
|
289
|
-
end
|
290
|
-
end
|
@@ -1,16 +0,0 @@
|
|
1
|
-
--- application.rb
|
2
|
-
+++ application.rb
|
3
|
-
@@ -98,7 +98,12 @@ module NaslDoc
|
4
|
-
contents = File.open(path, "rb") { |f| f.read }
|
5
|
-
|
6
|
-
# Parse the input file.
|
7
|
-
- tree = Nasl::Parser.new.parse(contents, path)
|
8
|
-
+ begin
|
9
|
-
+ tree = Nasl::Parser.new.parse(contents, path)
|
10
|
-
+ rescue Nasl::ParseException, Nasl::TokenException
|
11
|
-
+ puts "[!!!] File '#{path}' couldn't be parsed. It should be added to the blacklist."
|
12
|
-
+ return nil
|
13
|
-
+ end
|
14
|
-
|
15
|
-
# Collect the functions.
|
16
|
-
@functions = Hash.new()
|