Library creds

The credential class stores found credentials in the Nmap registry

The credentials library may be used by scripts to store credentials in a common format in the nmap registry. The Credentials class serves as a primary interface for scripts to the library.

The State table keeps track of possible account states and a corresponding message to return for each state.

The following code illustrates how a script may add discovered credentials to the database:

local c = creds.Credentials:new( {"myapp"}, host, port )
c:add("patrik", "secret", creds.State.VALID )

The following code illustrates how a script can return a table of discovered credentials at the end of execution:

return tostring(creds.Credentials:new({"myapp"}, host, port))

Another script can iterate over credential already discovered by other scripts just by referring to the same tag:

local c = creds.Credentials:new({"myapp", "yourapp"}, host, port)
for cred in c:getCredentials(creds.State.VALID) do
  showContentForUser(cred.user, cred.pass)
end

The following code illustrates how a script may iterate over all discovered credentials:

local c = creds.Credentials:new(creds.ALL_DATA, host, port)
for cred in c:getCredentials(creds.State.VALID) do
  showContentForUser(cred.user, cred.pass)
end

The library also enables users to add credentials through script arguments either globally or per service. These credentials may be retrieved by script through the same functions as any other discovered credentials. Arguments passed using script arguments will be added with the PARAM state. The following code may be used by a scripts to retrieve these credentials:

local c = creds.Credentials:new(creds.ALL_DATA, host, port)
for cred in c:getCredentials(creds.State.PARAM) do
  ... do something ...
end

Any globally added credentials will be made available to all scripts, regardless of what service is being filtered through the host and port arguments when instantiating the Credentials class. Service specific arguments will only be made available to scripts with ports matching the service name. The following two examples illustrate how credentials are added globally and for the http service:

--script-args creds.global='admin:nimda'
--script-args creds.http='webadmin:password'

The service name at this point may be anything and the entry is created dynamically without validating whether the service exists or not.

The credential argument is not documented in this library using the <at>args function as the argument would incorrectly show up in all scripts making use of this library. This would show that credentials could be added to scripts that do not make use of this function. Therefore any scripts that make use of the credentials passing arguments need to have appropriate documentation added to them.

The following code illustrates how a script may save its discovered credentials to a file:

local c = creds.Credentials:new( SCRIPT_NAME, host, port )
c:add("patrik", "secret", creds.State.VALID )
status, err = c:saveToFile("outputname","csv")

Supported output formats are CSV, verbose and plain. In both verbose and plain records are separated by colons. The difference between the two is that verbose includes the credential state. The file extension is automatically added to the filename based on the type requested.

Author:

  • Patrik Karlsson <patrik@cqure.net>

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

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

Script Arguments

creds.global

Credentials to be returned by Credentials.getCredentials regardless of the service.

creds.[service]

Credentials to be returned by Credentials.getCredentials for [service]. E.g. creds.http=admin:password

Functions

Account.__lt (a, b)

Less-than operation for sorting

Account.__tostring (self)

Converts an account object to a printable script

Account.new (self, username, password, state)

Creates a new instance of the Account class

Credentials.__tostring (self, host, port)

Get credentials with optional host and port filter If no filters are supplied all records are returned

Credentials.add (self, user, pass, state)

Add a discovered credential

Credentials.getCredentials (self, state)

Returns a credential iterator

Credentials.getTable (self)

Returns a table of credentials

Credentials.new (self, tags, host, port)

Creates a new instance of the Credentials class

RegStorage.add (self, tags, host, port, service, user, pass, state)

Add credentials to storage

RegStorage.getAll (self)

Returns a credential iterator matching the selected filters

RegStorage.new (self)

Creates a new RegStorage instance

RegStorage.setFilter (self, host, port, state)

Sets the storage filter

Tables

State

Table mapping the different account states to their number

Functions

Account.__lt (a, b)

Less-than operation for sorting

Lexicographic comparison by user, pass, and state

Parameters

a
 
b
 
Account.__tostring (self)

Converts an account object to a printable script

Parameters

self
 

Return value:

string representation of object
Account.new (self, username, password, state)

Creates a new instance of the Account class

Parameters

self
 
username
containing the user's name
password
containing the user's password
state
A creds.State account state

Return value:

A new creds.Account object
Credentials.__tostring (self, host, port)

Get credentials with optional host and port filter If no filters are supplied all records are returned

Parameters

self
 
host
table or string containing the host to filter
port
number containing the port to filter

Return value:

table suitable from stdnse.format_output
Credentials.add (self, user, pass, state)

Add a discovered credential

Parameters

self
 
user
the name of the user
pass
the password of the user
state
of the account
Credentials.getCredentials (self, state)

Returns a credential iterator

Parameters

self
 
state
mask containing values from the State table

Return value:

credential iterator, returning a credential each time it's called. Unless filtered by the state mask all credentials for the host, port match are iterated over. The credential table has the following fields: host - table as received by the action function port - number containing the port number user - string containing the user name pass - string containing the user password state - a state number service - string containing the name of the service tags - table containing tags associated with the credential

See also:

Credentials.getTable (self)

Returns a table of credentials

Parameters

self
 

Return value:

tbl table containing the discovered credentials
Credentials.new (self, tags, host, port)

Creates a new instance of the Credentials class

Parameters

self
 
tags
a table containing tags associated with the credentials
host
table as received by the scripts action method
port
table as received by the scripts action method
RegStorage.add (self, tags, host, port, service, user, pass, state)

Add credentials to storage

Parameters

self
 
tags
a table containing tags associated with the credentials
host
host table, name or ip
port
number containing the port of the service
service
the name of the service
user
the name of the user
pass
the password of the user
state
of the account
RegStorage.getAll (self)

Returns a credential iterator matching the selected filters

Parameters

self
 

Return value:

a credential iterator
RegStorage.new (self)

Creates a new RegStorage instance

Parameters

self
 

Return value:

a new instance
RegStorage.setFilter (self, host, port, state)

Sets the storage filter

Parameters

self
 
host
table containing the host
port
table containing the port
state
table containing the account state

Tables

State

Table mapping the different account states to their number

Also available is the StateMsg table, used to map these numbers to a description.

Fields

LOCKED
Account is locked
VALID
Valid credentials
DISABLED
Account is disabled
CHANGEPW
Valid credentials, password must be changed at next logon
PARAM
Credentials passed to script during Nmap execution
EXPIRED
Valid credentials, account expired
TIME_RESTRICTED
Valid credentials, account cannot log in at current time
HOST_RESTRICTED
Valid credentials, account cannot log in from current host
LOCKED_VALID
Valid credentials, account locked
DISABLED_VALID
Valid credentials, account disabled
HASHED
Hashed valid or invalid credentials