Home page logo
/
Intro Reference Guide Book Install Guide
Download Changelog Zenmap GUI Docs
Bug Reports OS Detection Propaganda Related Projects
In the Movies In the News

Sponsors


Library brute

The brute library is an attempt to create a common framework for performing password guessing against remote services.

The library currently attempts to parallelize the guessing by starting a number of working threads. The number of threads can be defined using the brute.threads argument, it defaults to 10.

The library contains the following classes:

  • Engine
** The actual engine doing the brute-forcing .
  • Error
** Class used to return errors back to the engine.
  • Options
** Stores any options that should be used during brute-forcing.

In order to make use of the framework a script needs to implement a Driver class. The Driver class is then to be passed as a parameter to the Engine constructor, which creates a new instance for each guess. The Driver class SHOULD implement the following four methods:

Driver:login = function( self, username, password )
Driver:check = function( self )
Driver:connect = function( self )
Driver:disconnect = function( self )

The login method does not need a lot of explanation. The login function should return two parameters. If the login was successful it should return true and a creds.Account. If the login was a failure it should return false and an Error. The driver can signal the Engine to retry a set of credentials by calling the Error objects setRetry method. It may also signal the Engine to abort all password guessing by calling the Error objects setAbort method.

The following example code demonstrates how the Error object can be used.

-- After a number of incorrect attempts VNC blocks us, so we abort
if ( not(status) and x:match("Too many authentication failures") ) then
  local err = brute.Error:new( data )
  -- signal the engine to abort
  err:setAbort( true )
  return false, err
elseif ( not(status) ) then
  local err = brute.Error:new( "VNC handshake failed" )
  -- This might be temporary, signal the engine to retry
  err:setRetry( true )
  return false, err
end
.
.
.
-- Return a simple error, no retry needed
return false, brute.Error:new( "Incorrect password" )

The purpose of the check method is to be able to determine whether the script has all the information it needs, before starting the brute force. It's the method where you should check, e.g., if the correct database or repository URL was specified or not. On success, the check method returns true, on failure it returns false and the brute force engine aborts.

NOTE: The check method is deprecated and will be removed from all scripts in the future. Scripts should do this check in the action function instead.

The connect method provides the framework with the ability to ensure that the thread can run once it has been dispatched a set of credentials. As the sockets in NSE are limited we want to limit the risk of a thread blocking, due to insufficient free sockets, after it has acquired a username and password pair.

The following sample code illustrates how to implement a sample Driver that sends each username and password over a socket.

Driver = {
  new = function(self, host, port, options)
    local o = {}
    setmetatable(o, self)
    self.__index = self
    o.host = host
    o.port = port
    o.options = options
    return o
  end,
  connect = function( self )
    self.socket = nmap.new_socket()
    return self.socket:connect( self.host, self.port )
  end,
  disconnect = function( self )
    return self.socket:close()
  end,
  check = function( self )
    return true
  end,
  login = function( self, username, password )
    local status, err, data
    status, err = self.socket:send( username .. ":" .. password)
    status, data = self.socket:receive_bytes(1)

    if ( data:match("SUCCESS") ) then
      return true, creds.Account:new(username, password, creds.State.VALID)
    end
    return false, brute.Error:new( "login failed" )
  end,
}

The following sample code illustrates how to pass the Driver off to the brute engine.

action = function(host, port)
  local options = { key1 = val1, key2 = val2 }
  local status, accounts = brute.Engine:new(Driver, host, port, options):start()
  if( not(status) ) then
    return accounts
  end
  return stdnse.format_output( true, accounts )
end

For a complete example of a brute implementation consult the svn-brute.nse or vnc-brute.nse scripts

Author:
"Patrik Karlsson <patrik@cqure.net>"

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

Source: http://nmap.org/svn/nselib/brute.lua

Functions

account_iterator (users, pass, mode)

Iterates over each user and password

activeThreads (self)

Calculates the number of threads that are actually doing any work

checkBoolArg (arg, default)

Checks if a script argument is boolean true or false

credential_iterator (f)

Credential iterator (for default or known user/pass combinations)

doAuthenticate (self)

Does the actual authentication request

get_next_credential (self)

Iterator wrapper used to iterate over all registered iterators

getMessage (self)

Get the error message reported

isAbort (self)

Was the error abortable

isDone (self)

Is the thread done?

isRetry (self)

Is the error recoverable?

new (self, driver, host, port, options)

Creates a new Engine instance

passwords_iterator ()

Default password iterator that uses unpwdb

pw_same_as_user_iterator (users, case)

An iterator that returns the username as password

pw_ucase_iterator (users, passwords, mode, pass)

An iterator that returns the username and uppercase password

pw_user_iterator (users, pass)

Try each user for each password (password in outer loop)

setAbort (self, b)

Set the error as abort all threads

setDone (self, b)

Signals the engine that the thread is done and should be terminated

setMaxThreads (self, max)

Limit the number of worker threads

setMode (self, mode)

Sets the brute mode to either iterate over users or passwords

setOption (self, param, value)

Sets an option parameter

setPasswordIterator (self, passwordIterator)

Sets the password iterator

setRetry (self, r)

Set the error as recoverable

setTitle (self, title)

Set an alternate title for the result output (default: Accounts)

setUsernameIterator (self, usernameIterator)

Sets the username iterator

start (self)

Starts the brute-force

threadCount (self)

Returns the number of non-dead threads

user_pw_iterator (users, pass)

Try each password for each user (user in outer loop)

usernames_iterator ()

Default username iterator that uses unpwdb



Functions

account_iterator (users, pass, mode)

Iterates over each user and password

Parameters

  • users: table/function containing list of users
  • pass: table/function containing list of passwords
  • mode: string, should be either 'user' or 'pass' and controls whether the users or passwords are in the 'outer' loop

Return value:

function iterator
activeThreads (self)

Calculates the number of threads that are actually doing any work

Parameters

  • self:

Return value:

count number of threads performing activity
checkBoolArg (arg, default)

Checks if a script argument is boolean true or false

Parameters

  • arg: string containing the name of the argument to check
  • default: boolean containing the default value

Return value:

boolean, true if argument evaluates to 1 or true, else false
credential_iterator (f)

Credential iterator (for default or known user/pass combinations)

Parameters

  • f: file handle to file containing credentials separated by '/'

Return value:

function iterator
doAuthenticate (self)

Does the actual authentication request

Parameters

  • self:

Return values:

  1. true on success, false on failure
  2. response Account on success, Error on failure
get_next_credential (self)

Iterator wrapper used to iterate over all registered iterators

Parameters

  • self:

Return value:

iterator function
getMessage (self)

Get the error message reported

Parameters

  • self:

Return value:

msg string containing the error message
isAbort (self)

Was the error abortable

Parameters

  • self:

Return value:

status true if the driver flagged the engine to abort
isDone (self)

Is the thread done?

Parameters

  • self:

Return value:

status true if done, false if not
isRetry (self)

Is the error recoverable?

Parameters

  • self:

Return value:

status true if the error is recoverable, false if not
new (self, driver, host, port, options)

Creates a new Engine instance

Parameters

  • self:
  • driver:
  • host: table as passed to the action method of the script
  • port: table as passed to the action method of the script
  • options: table containing any script specific options

Return value:

o new Engine instance
passwords_iterator ()

Default password iterator that uses unpwdb

pw_same_as_user_iterator (users, case)

An iterator that returns the username as password

Parameters

  • users: function returning the next user
  • case: string [optional] 'upper' or 'lower', specifies if user and password pairs should be case converted.

Return value:

function iterator
pw_ucase_iterator (users, passwords, mode, pass)

An iterator that returns the username and uppercase password

Parameters

  • users: table containing list of users
  • passwords:
  • mode: string, should be either 'user' or 'pass' and controls whether the users or passwords are in the 'outer' loop
  • pass: table containing list of passwords

Return value:

function iterator
pw_user_iterator (users, pass)

Try each user for each password (password in outer loop)

Parameters

  • users: table/function containing list of users
  • pass: table/function containing list of passwords

Return value:

function iterator
setAbort (self, b)

Set the error as abort all threads

Parameters

  • self:
  • b: boolean true if the engine should abort guessing on all threads
setDone (self, b)

Signals the engine that the thread is done and should be terminated

Parameters

  • self:
  • b: boolean true if done, unset or false if not
setMaxThreads (self, max)

Limit the number of worker threads

Parameters

  • self:
  • max: number containing the maximum number of allowed threads
setMode (self, mode)

Sets the brute mode to either iterate over users or passwords

Parameters

  • self:
  • mode: string containing either "user" or "password"

Return values:

  1. status true on success else false
  2. err string containing the error message on failure

See also:

setOption (self, param, value)

Sets an option parameter

Parameters

  • self:
  • param: string containing the parameter name
  • value: string containing the parameter value
setPasswordIterator (self, passwordIterator)

Sets the password iterator

Parameters

  • self:
  • passwordIterator: function to set as a password iterator
setRetry (self, r)

Set the error as recoverable

Parameters

  • self:
  • r: boolean true if the engine should attempt to retry the credentials, unset or false if not
setTitle (self, title)

Set an alternate title for the result output (default: Accounts)

Parameters

  • self:
  • title: string containing the title value
setUsernameIterator (self, usernameIterator)

Sets the username iterator

Parameters

  • self:
  • usernameIterator: function to set as a username iterator
start (self)

Starts the brute-force

Parameters

  • self:

Return values:

  1. status true on success, false on failure
  2. err string containing error message on failure
threadCount (self)

Returns the number of non-dead threads

Parameters

  • self:

Return value:

count number of non-dead threads
user_pw_iterator (users, pass)

Try each password for each user (user in outer loop)

Parameters

  • users: table/function containing list of users
  • pass: table/function containing list of passwords

Return value:

function iterator
usernames_iterator ()

Default username iterator that uses unpwdb

Nmap Site Navigation

Intro Reference Guide Book Install Guide
Download Changelog Zenmap GUI Docs
Bug Reports OS Detection Propaganda Related Projects
In the Movies In the News
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]