Commits

Tim Tomes  committed 4fca57b

Edited online

  • Participants
  • Parent commits 014f579

Comments (0)

Files changed (1)

 === Output Methods:
 Recon-ng enables the consistent display of output to the user in multiple styles using three different methods. The functions can be called anywhere within a module to present a consistent interface to the user.
 
-* Format and present errors:
-{{{
-#!python
-self.error('<string>')
-}}}
+; Format and present errors:
+: ##self.error('<string>')##
 
 * Format and present normal output:
 {{{
 '[*] This is important output! # green highlights'
 }}}
 
+=== Database Interaction Methods:
+Interacting with the database is easy in Recon-ng. There are core database interaction methods which allow the addition of hosts, contacts, and credentials to the database. There is also a generic query method for all other queries. In each case, the work of setting up the connection, extracting the results, and closing the connection is done for you.
+
+* Add a host to the database and return the affected row count:
+** //host// is the FQDN of the host as a string.
+** //address// is the optional IP address of the host as a string.
+{{{
+#!python
+self.add_host(host[, address=None])
+}}}
+
+* Add a contact to the database and return the affected row count. "fname" is the first name of the contact. "lname" is the last name of the contact. "title" is the job title of the contact. "email" is the optional email address of the contact.
+{{{
+#!python
+self.add_contact(fname, lname, title[, email=None])
+}}}
+
+* Add a credential to the database and return the affected row count. "username" is the username portion of the credential. "password" is the optional password portion of the credential. "hash type" is the optional hash type of the password, if the password is in the form of a hash. "leak" is optional information about the leaked credential.
+{{{
+#!python
+self.add_cred(username[, password=None][, hashtype=None][, leak=None])
+}}}
+
+
+{{{
+#!python
+self.query('<SQL statement>')
+}}}
+> Queries the database and returns the results as a list.
+
+### API Key Management Methods:
+Some Recon-ng modules may require an API key. To prevent having to continually input API keys, Recon-ng provides methods which assist in the key management process. When the user runs a module that requires an API key, the module should use the available methods to achieve the following flow:
+
+1 - Check the local key storage database for a matching key.
+{{{
+#!python
+self.get_key_from_db(key_name)
+}}}
+> Retrieves an API key from the API key storage database. "key_name" is the unique name for the key when stored in the database.
+
+2 - If a key does not exist, prompt the user for an API key.
+{{{
+#!python
+self.get_key_from_user([key_text='API Key'])
+}}}
+> Retrieves an API key from the user. "key_text" is optional text to be used to describe the key when prompting the user.
+
+3 - Store the API key for use in all future requests.
+{{{
+#!python
+self.add_key_to_db(key_name, key_value)
+}}}
+> Adds an API key to the API key storage database. "key_name" is the unique name for the key when stored in the database. "key_value" is the key string to store in the database.
+
+ALL - Condensed flow.
+{{{
+#!python
+self.manage_key(key_name, key_text)
+}}}
+> Automates the API key retrieval and storage process by combining the above methods into the proper flow. "key_name" is the unique name for the key when stored in the database. "key_text" is text to be used to describe the key when prompting the user.
+
+### Web Requests Methods:
+The most important capability of a tool which specializes in web based reconnaissance is the ability to make web requests. Recon-ng relieves the burden of complicated request building logic by providing a custom method for handling web requests.
+
+{{{
+#!python
+self.request(url[, method='GET'], payload={}, headers={}, cookies={}[, redirect=True])
+}}}
+> Makes a web request and returns a response object. "url" is the base URL of the request. "method" is the method of the request. Currently, only "GET" or "POST" are available. "payload" is a dictionary of name:value pairs to be encoded as request parameters. "payload" should be used for "GET" and "POST" methods as the request method will encode and build the request as needed per method. "headers" is a dictionary of name:value pairs to be added as request headers. "cookies" is a dictionary of name:value pairs to be used as request cookies. No cookie jar currently available.
+
+The resulting response object after a successful request allows quick access to all of the information required for further action.
+
+Ex.
+
+{{{
+#!python
+resp = self.request(...)
+resp.url         # The full request url as a string.
+resp.status_code # The response status code as an integer.
+resp.headers     # A dictionary of the response headers.
+resp.encoding    # A string representing the encoding used in the response.
+resp.text        # The response body decoded using the "resp.encoding" charset.
+resp.json        # A JSON object if decoded "resp.text" is valid JSON.
+}}}
+
+Recon-ng attempts to auto detect the charset encoding by analyzing the response headers. If not found, 'utf-8' is used as the default encoding. The encoding property is writable and will effect how the "resp.text" property is decoded. WARNING: This will also effect the ability of Recon-ng to build a JSON object out of "resp.text".