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

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

Library creds

Script Arguments

Functions

Tables

Functions

Parameters

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Parameters

Return value:

See also:

Parameters

Return value:

Parameters

Parameters

Parameters

Return value:

Parameters

Return value:

Parameters

Tables

Fields

Library `creds`