Pre-Hooks

Traceable provides the capability to write pre-hooks. The pre-hooks can be used to carry out multiple tasks, for example, authentication before starting the tests, test setup, and so on. These pre-hooks can be configured to run at multiple levels. For example, you can configure a pre-hook to run before each individual test plugin or test plugin category for the entire scan. For example, in the sample config.yaml file shown below, you can see that a pre-hook runs before the start of the plugin and one specific to a test. The bfla pre-hook shown in the sample config.yaml is for an individual Authorization plugin, while crap_login_prehook is for logging into an application. These pre-hooks are written in Python and used in Traceable CLI.

Note

• Pre-hooks are application-specific. Use the examples as guidance when defining your custom pre-hooks.

• You can capture authentication hook testing logs using logger = logging.getLogger("traceable.ast.testsuite.hookutils.simulate_hooks"), and scan run logs using logger = logging.getLogger("traceable.cli.scan").

What will you learn in this topic?

By the end of this topic, you will be able to:

• Understand the use of hooks in authentication.

• Understand the concept of the crAPI credential pre-hook.

• Understand the concept of the CSRF token pre-hook.

• Understand how to configure pre-hooks.

Sample user config

# This is a sample user config. 
# Copy it to traceable config folder ~/.traceable/config.yaml to apply. 
# This config overrides data in default.yaml.
# Do not make edits to default.yaml as changes will be lost.
scan:
  plugins:
    # Enable prehooks for all plugins
    pre_hooks:
      - crapi_login_prehook
    post_hooks:
      - crapi_login_posthook
    authentication:
      unauthenticated_access:
        pre_hooks:
          # Disable crapi_login_prehook for unauthenticated_access
          - crapi_login_prehook:
              disabled: true
          # Disable crapi_login_posthook for unauthenticated_access
          - crapi_login_posthook:
              disabled: true
    authorization:
        bfla:
          pre_hooks:
            - crapi_creds_prehook
    custom:
      sample_plugin: {}

Make a note of the following that are used in the examples below:

• The authentication hook method is invoked before sending every request.

• You may or may not want to access the authentication endpoint before each request. You can control that behavior using scanctx and pluginctx.

• scanctx is a dictionary scoped per scan. To reuse any value throughout the scan, add that value with the key of your choice and use it whenever it is present. Following is an example:

  Python

  if scanctx.get("token_key") == None:
              token = (make request to obtain token).getToken
              scanctx["token_key] = token
          token = scanctx.get("token_key")

• Similar to scanctx, pluginctx is scoped per plugin. So, a unique dictionary is used per plugin. You can store values at the key level. 

• Hook can add key-value pairs in headers, query parameters, cookies, or the request body. You need to add these to the attributes map. For example,

  • You need to first fetch the attributes from the testcase (which essentially translates to the parameter of the next request) attributes = testcase.get_attributes()

  • To Add Cookie: attributes.set("mutated.http.request.cookie.%s" % (cookie.name), cookie.value)

  • To Add Header: attributes.set("mutated.http.request.header.authorization", "Bearer fnasfjasjfoijfoiefjkewwrw")    

  • To add Query parameter: attributes.set("mutated.http.request.query.authorization", "Bearer fnasfjasjfoijfoiefjkewwrw")     

  • To add body parameter: attributes.set("mutated.http.request.body.authorization", "Bearer fnasfjasjfoijfoiefjkewwrw")

The following two examples are two sample authentication pre-hooks for the OWASP crAPI application. For more information, see crAPI.

crAPI credential pre-hook

The following is a sample pre-hook function in Python:

def sample_traceable_login_prehook(scanctx: ScanContext, pluginctx: PluginContext, testcase: TestCase, **kwargs) -> list[Assertion]:
    attributes = testcase.get_attributes()
    url = urllib.parse.urlparse(
        attributes.get_one("mutated.http.request.url", ""))
    logger.info("Running crapi_login_prehook for plugin %s" % pluginctx.get_plugin())
    if scanctx.get("crapi.role.user", None) is None:
        # Login:
        logger.debug("crapi_login_prehook: Token not found. Creating token")
        u = urllib.parse.urlunparse(
            url._replace(path="/identity/api/auth/login"))
        res = requests.post(u, json={
            "email": "test@example.com",
            "password": "Test!123"
        }, headers={
            "content-type": "application/json",
            "x-traceable-ast": "0,0,0"
        })
        if res.status_code != 200:
            logger.error("Failed to login to crapi, got status %d" %
                         res.status_code)
            return []

        res = res.json()
        scanctx.set("crapi.role.user", res["token"])
    else:
        logger.debug("Already logged in to CRAPI")
    attributes.set("mutated.auth.attribute", "mutated.http.request.header.authorization")
    attributes.set("mutated.role.user", "Bearer %s" % scanctx.get("crapi.role.user"))
    attributes.set("mutated.role.bolauser", "Bearer %s" % scanctx.get("crapi.role.bolauser"))
    logger.debug("Mutated role user: %s" % scanctx.get("crapi.role.user"))
    return []

Explanation

def set_csrf_token_prehook(scanctx: ScanContext, pluginctx: PluginContext, attributes: AttributeList) -> list[Assertion]:
    if not scanctx.get("csrf_token"):
        scanctx.set("csrf_token", "".join(random.sample(string.ascii_lowercase, k=10)))
    attributes.set("mutated.http.request.header.csrf_token", scanctx.get("csrf_token"))
    return []