Library unpwdb

Username/password database library.

The usernames and passwords functions return multiple values for use with exception handling via nmap.new_try. The first value is the Boolean success indicator, the second value is the closure.

The closures can take an argument of "reset" to rewind the list to the beginning.

To avoid taking a long time against slow services, the closures will stop returning values (start returning nil) after a certain time. The time depends on the timing template level, and is

  • -T3 or less: 10 minutes
  • -T4: 5 minutes
  • -T5: 3 minutes
Time limits are increased by 50% if a custom username or password database is used with the userdb or passdb script arguments. You can control the time limit directly with the unpwdb.timelimit script argument. Use unpwdb.timelimit=0 to disable the time limit.

You can select your own username and/or password database to read from with the script arguments userdb and passdb, respectively. Comments are allowed in these files, prefixed with "#!comment:". Comments cannot be on the same line as a username or password because this leaves too much ambiguity, e.g. does the password in "mypass #!comment: blah" contain a space, two spaces, or do they just separate the password from the comment?

Author:

  • Kris Katterjohn 06/2008

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/unpwdb.lua

Script Arguments

unpwdb.passlimit

The maximum number of passwords passwords will return (default unlimited).

userdb

The filename of an alternate username database. Default: nselib/data/usernames.lst

unpwdb.userlimit

The maximum number of usernames usernames will return (default unlimited).

unpwdb.timelimit

The maximum amount of time that any iterator will run before stopping. The value is in seconds by default and you can follow it with ms, s, m, or h for milliseconds, seconds, minutes, or hours. For example, unpwdb.timelimit=30m or unpwdb.timelimit=.5h for 30 minutes. The default depends on the timing template level (see the module description). Use the value 0 to disable the time limit.

passdb

The filename of an alternate password database. Default: nselib/data/passwords.lst

Example Usage 

  • require("unpwdb")

local usernames, passwords
local try = nmap.new_try()

usernames = try(unpwdb.usernames())
passwords = try(unpwdb.passwords())

for password in passwords do
  for username in usernames do
    -- Do something with username and password.
  end
  usernames("reset")
end

  • nmap --script-args userdb=/tmp/user.lst
nmap --script-args unpwdb.timelimit=10m

Functions

concat_iterators (iter1, iter2)

Returns a new iterator that iterates through its consecutive iterators, basically concatenating them.

filter_iterator (iterator, filter)

Returns a new iterator that filters its results based on the filter.

limited_iterator (iterator, time_limit, count_limit, label)

Wraps time and count limits around an iterator.

passwords (time_limit, count_limit)

Returns a function closure which returns a new password with every call until the password list is exhausted or either limit expires (in which cases it returns nil).

timelimit ()

Returns the suggested number of seconds to attempt a brute force attack

usernames (time_limit, count_limit)

Returns a function closure which returns a new password with every call until the username list is exhausted or either limit expires (in which cases it returns nil).

Functions

concat_iterators (iter1, iter2)

Returns a new iterator that iterates through its consecutive iterators, basically concatenating them.

Parameters

iter1
First iterator to concatenate.
iter2
Second iterator to concatenate.

Return value:

function The concatenated iterators.
filter_iterator (iterator, filter)

Returns a new iterator that filters its results based on the filter.

Parameters

iterator
Iterator that needs to be filtered
filter
Function that returns bool, which serves as a filter

Return value:

function The filtered iterator.
limited_iterator (iterator, time_limit, count_limit, label)

Wraps time and count limits around an iterator.

When either limit expires, starts returning nil. Calling the iterator with an argument of "reset" resets the count.

Parameters

iterator
 
time_limit
Time limit in seconds. Use 0 or nil for no limit.
count_limit
Count limit in seconds. Use 0 or nil for no limit.
label
A string describing the iterator, to be used in verbose print messages.

Return values:

  1. boolean Status.
  2. function The wrapped iterator.
passwords (time_limit, count_limit)

Returns a function closure which returns a new password with every call until the password list is exhausted or either limit expires (in which cases it returns nil).

Parameters

time_limit
Time limit in seconds. Use 0 for no limit.
count_limit
Count limit in seconds. Use 0 for no limit.

Return values:

  1. boolean Status.
  2. function The passwords iterator.
timelimit ()

Returns the suggested number of seconds to attempt a brute force attack

Based on the unpwdb.timelimit script argument, Nmap's timing values (-T4 etc.) and whether or not a user-defined list is used.

You can use the script argument notimelimit to make this function return nil, which means the brute-force should run until the list is empty. If notimelimit is not used, be sure to still check for nil return values on the above two functions in case you finish before the time limit is up.

usernames (time_limit, count_limit)

Returns a function closure which returns a new password with every call until the username list is exhausted or either limit expires (in which cases it returns nil).

Parameters

time_limit
Time limit in seconds. Use 0 for no limit.
count_limit
Count limit in seconds. Use 0 for no limit.

Return values:

  1. boolean Status.
  2. function The usernames iterator.