ruby-nmap 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/.rspec ADDED
@@ -0,0 +1 @@
1
+ --colour --format documentation
@@ -0,0 +1 @@
1
+ --markup markdown --title 'Ruby Nmap Documentation' --protected --files ChangeLog.md,LICENSE.txt
@@ -0,0 +1,25 @@
1
+ ### 0.2.0 / 2010-10-29
2
+
3
+ * Require nokogiri >= 1.3.0.
4
+ * Require rprogram ~> 0.2.0.
5
+ * Added {Nmap::XML#tasks}.
6
+ * Added {Nmap::Scanner#start_time}.
7
+ * Added {Nmap::ScanTask#duration}.
8
+ * Added {Nmap::Host#start_time}.
9
+ * Added {Nmap::Host#end_time}.
10
+ * Allow `Nmap::Tasks#ports=` to accept port ranges.
11
+ * Omit the `-p` option if no ports are given to {Nmap::Task}.
12
+ * Have the `Nmap::Host#each_*` methods return an `Enumerator` object if no
13
+ block is given.
14
+
15
+ ### 0.1.1 / 2010-01-02
16
+
17
+ * Require RProgram >= 0.1.8.
18
+ * Adds `sudo` and `sudo=` instance methods to {Nmap::Task}.
19
+
20
+ ### 0.1.0 / 2009-11-13
21
+
22
+ * Initial release.
23
+ * Provides a Ruby interface for running Nmap.
24
+ * Provides a Parser for enumerating Nmap XML scan files.
25
+
@@ -0,0 +1,22 @@
1
+ (The MIT License)
2
+
3
+ Copyright (c) 2009-2010 Hal Brodigan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining
6
+ a copy of this software and associated documentation files (the
7
+ 'Software'), to deal in the Software without restriction, including
8
+ without limitation the rights to use, copy, modify, merge, publish,
9
+ distribute, sublicense, and/or sell copies of the Software, and to
10
+ permit persons to whom the Software is furnished to do so, subject to
11
+ the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be
14
+ included in all copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
17
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
20
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
21
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
22
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,63 @@
1
+ # ruby-nmap
2
+
3
+ * [Source](http://github.com/sophsec/ruby-nmap/)
4
+ * [Issues](http://github.com/sophsec/ruby-nmap/issues)
5
+ * [Documentation](http://rubydoc.info/gems/ruby-nmap/file/README.md)
6
+ * Postmodern (postmodern.mod3 at gmail.com)
7
+
8
+ ## Description
9
+
10
+ A Ruby interface to Nmap, the exploration tool and security / port scanner.
11
+
12
+ ## Features
13
+
14
+ * Provides a Ruby interface for running Nmap.
15
+ * Provides a Parser for enumerating Nmap XML scan files.
16
+
17
+ ## Examples
18
+
19
+ Run Nmap from Ruby:
20
+
21
+ require 'nmap/program'
22
+
23
+ Nmap::Program.scan do |nmap|
24
+ nmap.sudo = true
25
+
26
+ nmap.syn_scan = true
27
+ nmap.service_scan = true
28
+ nmap.os_fingerprint = true
29
+ nmap.xml = 'scan.xml'
30
+ nmap.verbose = true
31
+
32
+ nmap.ports = [20,21,22,23,25,80,110,443,512,522,8080,1080]
33
+ nmap.targets = '192.168.1.*'
34
+ end
35
+
36
+ Parse Nmap XML scan files:
37
+
38
+ require 'nmap/xml'
39
+
40
+ Nmap::XML.new('scan.xml') do |xml|
41
+ xml.each_host do |host|
42
+ puts "[#{host.ip}]"
43
+
44
+ host.each_port do |port|
45
+ puts " #{port.number}/#{port.protocol}\t#{port.state}\t#{port.service}"
46
+ end
47
+ end
48
+ end
49
+
50
+ ## Requirements
51
+
52
+ * [nmap](http://www.insecure.org/)
53
+ * [nokogiri](http://nokogiri.rubyforge.org/) >= 1.3.0
54
+ * [rprogram](http://github.com/postmodern/rprogram) ~> 0.2.0
55
+
56
+ ## Install
57
+
58
+ $ sudo gem install ruby-nmap
59
+
60
+ ## License
61
+
62
+ See {file:LICENSE.txt} for license information.
63
+
data/Rakefile CHANGED
@@ -1,28 +1,35 @@
1
- # -*- ruby -*-
2
-
3
1
  require 'rubygems'
4
- require 'hoe'
5
- require './tasks/spec.rb'
6
- require './tasks/yard.rb'
7
-
8
- Hoe.spec 'ruby-nmap' do
9
- self.developer('Postmodern', 'postmodern.mod3@gmail.com')
2
+ require 'rake'
10
3
 
11
- self.readme_file = 'README.rdoc'
12
- self.history_file = 'History.rdoc'
13
- self.remote_rdoc_dir = '/'
4
+ begin
5
+ gem 'ore-tasks', '~> 0.1.2'
6
+ require 'ore/tasks'
14
7
 
15
- self.extra_deps = [
16
- ['nokogiri', '>=1.4.0'],
17
- ['rprogram', '>=0.1.8']
18
- ]
8
+ Ore::Tasks.new
9
+ rescue LoadError => e
10
+ STDERR.puts e.message
11
+ STDERR.puts "Run `gem install ore-tasks` to install 'ore/tasks'."
12
+ end
19
13
 
20
- self.extra_dev_deps = [
21
- ['rspec', '>=1.1.12'],
22
- ['yard', '>=0.2.3.5']
23
- ]
14
+ begin
15
+ gem 'rspec', '~> 2.0.0'
16
+ require 'rspec/core/rake_task'
24
17
 
25
- self.spec_extras = {:has_rdoc => 'yard'}
18
+ RSpec::Core::RakeTask.new
19
+ rescue LoadError => e
20
+ task :spec do
21
+ abort "Please run `gem install rspec` to install RSpec."
22
+ end
26
23
  end
24
+ task :default => :spec
27
25
 
28
- # vim: syntax=ruby
26
+ begin
27
+ gem 'yard', '~> 0.6.0'
28
+ require 'yard'
29
+
30
+ YARD::Rake::YardocTask.new
31
+ rescue LoadError => e
32
+ task :yard do
33
+ abort "Please run `gem install yard` to install YARD."
34
+ end
35
+ end
@@ -0,0 +1,23 @@
1
+ name: ruby-nmap
2
+ summary: A Ruby interface to Nmap.
3
+ description:
4
+ A Ruby interface to Nmap, the exploration tool and security / port
5
+ scanner.
6
+
7
+ license: MIT
8
+ authors: Postmodern
9
+ email: postmodern.mod3@gmail.com
10
+ homepage: http://github.com/sophsec/ruby-nmap
11
+ has_yard: true
12
+
13
+ requirements: nmap, 4.xx or greater
14
+
15
+ dependencies:
16
+ nokogiri: >= 1.3.0
17
+ rprogram: ~> 0.2.0
18
+
19
+ development_dependencies:
20
+ ore: ~> 0.2.1
21
+ ore-tasks: ~> 0.1.2
22
+ rspec: ~> 2.0.0
23
+ yard: ~> 0.6.0
@@ -30,6 +30,30 @@ module Nmap
30
30
  block.call(self) if block
31
31
  end
32
32
 
33
+ #
34
+ # The time the host was first scanned.
35
+ #
36
+ # @return [Time]
37
+ # The time the host was first scanned.
38
+ #
39
+ # @since 0.1.2
40
+ #
41
+ def start_time
42
+ Time.at(@node['starttime'].to_i)
43
+ end
44
+
45
+ #
46
+ # The time the host was last scanned.
47
+ #
48
+ # @return [Time]
49
+ # The time the host was last scanned.
50
+ #
51
+ # @since 0.1.2
52
+ #
53
+ def end_time
54
+ Time.at(@node['endtime'].to_i)
55
+ end
56
+
33
57
  #
34
58
  # Parses the status of the host.
35
59
  #
@@ -54,17 +78,20 @@ module Nmap
54
78
  # @yieldparam [Address] addr
55
79
  # A address of the host.
56
80
  #
57
- # @return [Host]
81
+ # @return [Host, Enumerator]
58
82
  # The host.
83
+ # If no block was given, an enumerator will be returned.
59
84
  #
60
- def each_address(&block)
85
+ def each_address
86
+ return enum_for(:each_address) unless block_given?
87
+
61
88
  @node.xpath("address[@addr]").each do |addr|
62
89
  address = Address.new(
63
90
  addr['addrtype'].to_sym,
64
91
  addr['addr']
65
92
  )
66
93
 
67
- block.call(address) if block
94
+ yield address
68
95
  end
69
96
 
70
97
  return self
@@ -77,7 +104,7 @@ module Nmap
77
104
  # The addresses of the host.
78
105
  #
79
106
  def addresses
80
- Enumerator.new(self,:each_address).to_a
107
+ each_address.to_a
81
108
  end
82
109
 
83
110
  #
@@ -157,12 +184,15 @@ module Nmap
157
184
  # @yieldparam [String] host
158
185
  # A hostname of the host.
159
186
  #
160
- # @return [Host]
187
+ # @return [Host, Enumerator]
161
188
  # The host.
189
+ # If no block was given, an enumerator will be returned.
162
190
  #
163
- def each_hostname(&block)
191
+ def each_hostname
192
+ return enum_for(:each_hostname) unless block_given?
193
+
164
194
  @node.xpath("hostnames/hostname[@name]").each do |host|
165
- block.call(host['name']) if block
195
+ yield host['name']
166
196
  end
167
197
 
168
198
  return self
@@ -175,7 +205,7 @@ module Nmap
175
205
  # The hostnames of the host.
176
206
  #
177
207
  def hostnames
178
- Enumerator.new(self,:each_hostname).to_a
208
+ each_hostname.to_a
179
209
  end
180
210
 
181
211
  #
@@ -205,12 +235,15 @@ module Nmap
205
235
  # @yieldparam [Port] port
206
236
  # A scanned port of the host.
207
237
  #
208
- # @return [Host]
238
+ # @return [Host, Enumerator]
209
239
  # The host.
240
+ # If no block was given, an enumerator will be returned.
210
241
  #
211
- def each_port(&block)
242
+ def each_port
243
+ return enum_for(:each_port) unless block_given?
244
+
212
245
  @node.xpath("ports/port").each do |port|
213
- block.call(create_port(port)) if block
246
+ yield create_port(port)
214
247
  end
215
248
 
216
249
  return self
@@ -223,7 +256,7 @@ module Nmap
223
256
  # The scanned ports of the host.
224
257
  #
225
258
  def ports
226
- Enumerator.new(self,:each_port).to_a
259
+ each_port.to_a
227
260
  end
228
261
 
229
262
  #
@@ -235,12 +268,15 @@ module Nmap
235
268
  # @yieldparam [Port] port
236
269
  # An open scanned port of the host.
237
270
  #
238
- # @return [Host]
271
+ # @return [Host, Enumerator]
239
272
  # The host.
273
+ # If no block was given, an enumerator will be returned.
240
274
  #
241
275
  def each_open_port(&block)
276
+ return enum_for(:each_open_port) unless block_given?
277
+
242
278
  @node.xpath("ports/port[state/@state='open']").each do |port|
243
- block.call(create_port(port)) if block
279
+ yield create_port(port)
244
280
  end
245
281
 
246
282
  return self
@@ -253,7 +289,7 @@ module Nmap
253
289
  # The open ports of the host.
254
290
  #
255
291
  def open_ports
256
- Enumerator.new(self,:each_open_port).to_a
292
+ each_open_port.to_a
257
293
  end
258
294
 
259
295
  #
@@ -265,12 +301,15 @@ module Nmap
265
301
  # @yieldparam [Port] port
266
302
  # An TCP scanned port of the host.
267
303
  #
268
- # @return [Host]
304
+ # @return [Host, Enumerator]
269
305
  # The host.
306
+ # If no block was given, an enumerator will be returned.
270
307
  #
271
- def each_tcp_port(&block)
308
+ def each_tcp_port
309
+ return enum_for(:each_tcp_port) unless block_given?
310
+
272
311
  @node.xpath("ports/port[@protocol='tcp']").each do |port|
273
- block.call(create_port(port)) if block
312
+ yield create_port(port)
274
313
  end
275
314
 
276
315
  return self
@@ -283,7 +322,7 @@ module Nmap
283
322
  # The TCP ports of the host.
284
323
  #
285
324
  def tcp_ports
286
- Enumerator.new(self,:each_tcp_port).to_a
325
+ each_tcp_port.to_a
287
326
  end
288
327
 
289
328
  #
@@ -295,12 +334,15 @@ module Nmap
295
334
  # @yieldparam [Port] port
296
335
  # An UDP scanned port of the host.
297
336
  #
298
- # @return [Host]
337
+ # @return [Host, Enumerator]
299
338
  # The host.
339
+ # If no block was given, an enumerator will be returned.
300
340
  #
301
- def each_udp_port(&block)
341
+ def each_udp_port
342
+ return enum_for(:each_udp_port) unless block_given?
343
+
302
344
  @node.xpath("ports/port[@protocol='udp']").each do |port|
303
- block.call(create_port(port)) if block
345
+ yield create_port(port)
304
346
  end
305
347
 
306
348
  return self
@@ -313,7 +355,7 @@ module Nmap
313
355
  # The UDP ports of the host.
314
356
  #
315
357
  def udp_ports
316
- Enumerator.new(self,:each_udp_port).to_a
358
+ each_udp_port.to_a
317
359
  end
318
360
 
319
361
  #
@@ -8,7 +8,7 @@ module Nmap
8
8
  name_program 'nmap'
9
9
 
10
10
  #
11
- # Finds the +nmap+ program and performs a scan.
11
+ # Finds the `nmap` program and performs a scan.
12
12
  #
13
13
  # @param [Hash{Symbol => Object}] options
14
14
  # Additional options for nmap.
@@ -0,0 +1,65 @@
1
+ module Nmap
2
+ class ScanTask
3
+
4
+ # The name of the scan task
5
+ attr_reader :name
6
+
7
+ # The time the scan task begun
8
+ attr_reader :start_time
9
+
10
+ # The time the scan task ended
11
+ attr_reader :end_time
12
+
13
+ # Extra information on the scan task
14
+ attr_reader :extrainfo
15
+
16
+ #
17
+ # Creates a new ScanTask object.
18
+ #
19
+ # @param [String] name
20
+ # The name of the scan task.
21
+ #
22
+ # @param [Time] start_time
23
+ # The time the scan task begun.
24
+ #
25
+ # @param [Time] end_time
26
+ # The time the scan task ended.
27
+ #
28
+ # @param [String] extrainfo
29
+ # Any extra information relating to the scan task.
30
+ #
31
+ # @since 0.1.2
32
+ #
33
+ def initialize(name,start_time,end_time,extrainfo=nil)
34
+ @name = name
35
+ @start_time = start_time
36
+ @end_time = end_time
37
+ @extrainfo = extrainfo
38
+ end
39
+
40
+ #
41
+ # The duration of the scan task.
42
+ #
43
+ # @return [Integer]
44
+ # The number of seconds it took the scan task to complete.
45
+ #
46
+ # @since 0.1.2
47
+ #
48
+ def duration
49
+ (@end_time - @start_time)
50
+ end
51
+
52
+ #
53
+ # Converts the scan task to a String.
54
+ #
55
+ # @return [String]
56
+ # The String form of the scan task.
57
+ #
58
+ # @since 0.1.2
59
+ #
60
+ def to_s
61
+ "#{@start}: #{@name} (#{@extrainfo})"
62
+ end
63
+
64
+ end
65
+ end