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 parallellize 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:
Account
Engine
Error
Options
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 an 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 aquired 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, brute.Account:new(username, password, "OPEN")
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 |
| 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 |
| toString (self) |
Converts an account object to a printable script |
| 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:
- true on success, false on failure
- 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 - 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:
- status true on success else false
- 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:
- status true on success, false on failure
- 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 - toString (self)
-
Converts an account object to a printable script
Parameters
- self:
Return value:
string representation of object - 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