User API reference — raider 0.2.0a0 documentation

# User API reference

## Main Raider class

class Raider(project=None)

  Main class used as the point of entry.

  The Raider class should be used to access everything else inside Raider. For now it’s still not doing much, but for the future this is where all of the features available to the end user should be.

  application

    An `Application` object with the currently active project.

  config

    A Config object containing all of the necessary settings.

  user

    A User object containing the active user of the active project.

  functions

    A Functions object containing the defined functions of the active project.

  authenticate(username=None)

    Authenticates in the chosen application.

    Runs the authentication process from start to end on the selected application with the specified user.

    Parameters

      username (`Optional`[`str`]) – A string with the username to authenticate. If not specified, the last used user will be selected.

    Return type

      `None`

  property authentication: raider.authentication.Authentication

    Returns the Authentication object

    Return type

      `Authentication`

  fuzz_authentication(flow_name, fuzzing_point, fuzzing_function)

    Fuzz an authentication step.

    Given a flow name, a starting point for fuzzing, and a function to generate the fuzzing strings, run the attack. Unlike `fuzz_function`, it takes into consideration the `NextStage` operations, making it possible to start from the beginning of the authentication process if new tokens are needed.

    Parameters

      - flow_name (`str`) – The name of the `Flow` containing the `Request` which will be fuzzed.

      - fuzzing_point (`str`) – The name given to the `Plugin` inside `Request` which will be fuzzed.

      - fuzzing_function (`Callable`[…, `Any`]) – A callable function, that will be used to generate the strings that will be used for fuzzing. It should accept one argument, which will the value of the plugin before fuzzing. It can be used to build the list of strings to be used for the attack.

    Return type

      `None`

  fuzz_function(function_name, fuzzing_point, fuzzing_function)

    Fuzz a function with an authenticated user.

    Given a function name, a starting point for fuzzing, and a function to generate the fuzzing strings, run the attack.

    Parameters

      - function_name (`str`) – The name of the `Flow` containing the `Request` which will be fuzzed.

      - fuzzing_point (`str`) – The name given to the `Plugin` inside `Request` which will be fuzzed.

      - fuzzing_function (`Callable`[…, `Any`]) – A callable function, that will be used to generate the strings that will be used for fuzzing. It should accept one argument, which will the value of the plugin before fuzzing. It can be used to build the list of strings to be used for the attack.

    Return type

      `None`

  run_function(function)

    Runs a function in the chosen application.

    With the selected application and user run the function from the argument.

    Parameters

      function (`str`) – A string with the function identifier as defined in “_functions” variable.

    Return type

      `None`

## Config

Config class holding global Raider configuration.

class Config

  Class dealing with global Raider configuration.

  A Config object will contain all the information necessary to run Raider. It will define global configurations like the web proxy and the logging level, but also the data defined in the active project configuration files.

  proxy

    An optional string to define the web proxy to relay the traffic through.

  verify

    A boolean flag which will let the requests library know whether to check the SSL certificate or ignore it.

  loglevel

    A string used by the logging library to define the desired logging level.

  user_agent

    A string which will be used as the user agent in HTTP requests.

  active_project

    A string defining the current active project.

  project_config

    A dictionary containing all of the local variables defined in the active project’s hy configuration files.

  logger

    A logging.RootLogger object used for debugging.

  load_project(project=None)

    Loads project settings.

    Goes through all the “.hy” files in the project directory, evaluates them all, and returns the created locals, making them available to the rest of Raider.

    Files are loaded in alphabetical order, and objects created in one of them will be available to the next one, eliminating the need to use imports. This allows the user to split the configuration files however it makes sense, and Raider doesn’t impose any restrictions on those files.

    All “.hy” files in the project directory are evaluated, which could be considered unsafe and could cause all kinds of security issues, but Raider assumes the user knows what they’re doing and will not copy/paste hylang code from untrusted sources.

    Parameters

      project (`Optional`[`str`]) – A string with the name of the project. By default the project is located in “~/.config/raider/”. All “.hy” files from this directory will be executed and the locals that were created during that will be returned.

    Return type

      `Dict`[`str`, `Any`]

    Returns

      A dictionary as returned by the locals() function. It contains all of the locally defined objects in the “.hy” configuration files.

  print_config()

    Prints current configuration.

    Return type

      `None`

  write_config_file()

    Writes global configuration to common.hy.

    Gets the current configuration from the Config object and writes them in hylang format in the “common.hy” file.

    Return type

      `None`

## Application

Application class holding project configuration.

class Application(project=None)

  Class holding all the project related data.

  This class isn’t supposed to be used directly by the user, instead the Raider class should be used, which will deal with the Application class internally.

  name

    A string with the name of the application.

  base_url

    A string with the base URL of the application.

  config

    A Config object with Raider global configuration plus the variables defined in hy configuration files related to the Application.

  users

    A UserStore object generated from the “_users” variable set in the hy configuration files for the project.

  active_user

    A User object pointing to the active user inside the “users” object.

  authentication

    An Authentication object containing all the Flows relevant to the authentication process. It’s created out of the “_authentication” variable from the hy configuration files.

  functions

    A Functions object with all Flows that don’t affect the authentication process. This object is being created out of the “_functions” variable from the hy configuration files.

  authenticate(username=None)

    Authenticates the user.

    Runs all the steps of the authentication process defined in the hy config files for the application.

    Parameters

      username (`Optional`[`str`]) – A string with the user to be authenticated. If not supplied, the last used username will be selected.

    Return type

      `None`

  load_session_file()

    Loads session data.

    If session data was saved with write_session_file() this function can load this data.

    Return type

      `None`

  write_project_file()

    Writes the project settings.

    For now only the active user is saved, so that the next time the project is used, there’s no need to specify the user manually.

    Return type

      `None`

  write_session_file()

    Saves session data.

    Saves user related session data in a file for later use. This includes cookies, headers, and other data extracted using Plugins.

    Return type

      `None`

## Authentication

Authentication class responsible for running the defined stages.

class Authentication(stages)

  Class holding authentication stages.

  This class holds all the information necessary to authenticate. It provides functions to run those authentication steps.

  stages

    A list of Flow objects relevant to the authentication process.

  property current_stage_name: str

    Returns the name of the current stage.

    Return type

      `str`

  get_stage_by_name(name)

    Returns the Flow object given the name.

    Parameters

      name (`str`) – A string with the name of the Flow as defined in the hy configuration files.

    Return type

      `Optional`[`Flow`]

    Returns

      A Flow object matching the name supplied to the function, or None if there are no such object.

  get_stage_index(name)

    Returns the index of the stage given its name.

    Each authentication step is given an index based on its position in the “_authentication” list. This function returns the index of the Flow based on its name.

    Parameters

      name (`str`) – A string with the name of the Flow.

    Return type

      `int`

    Returns

      An integer with the index of the Flow with the specified “name”.

  get_stage_name_by_id(stage_id)

    Returns the stage name given its number.

    Each authentication step is given an index based on its position in the “_authentication” list. This function returns the name of the Flow based on its position in this list.

    Parameters

      stage_id (`int`) – An integer with the index of the stage.

    Return type

      `str`

    Returns

      A string with the name of the Flow in the position “stage_id”.

  run_all(user, config)

    Runs all authentication stages.

    This function will run all authentication stages for the specified User and will take into account the supplied Config for things like the user agent and the web proxy to use.

    Parameters

      - user (`User`) – A User object containing the credentials and where the user specific data will be stored.

      - config (`Config`) – A Config object with the global Raider settings.

    Return type

      `None`

  run_current_stage(user, config)

    Runs the current stage only.

    Authentication class keeps the index of the current stage in the “_current_stage” variable. This function runs only one authentication step indexed by this variable.

    Parameters

      - user (`User`) – A User object containing the credentials and where the user specific data will be stored.

      - config (`Config`) – A Config object with the global Raider settings.

    Return type

      `None`

  run_stage(stage_id, user, config)

    Runs one authentication Stage.

    First, the Flow object of the specified stage is identified, then the related HTTP request is processed, sent, the response is received, and the operations are run on the Flow.

    Parameters

      - stage_id (`Union`[`int`, `str`]) – A string or an integer identifying the authentication stage to run. If it’s a string, it’s the name of the Flow, and if it’s an integer, it’s the index of the Flow object in the “_authentication” variable.

      - user (`User`) – A User object containing the credentials and where the user specific data will be stored.

      - config (`Config`) – A Config object with the global Raider settings.

    Return type

      `Optional`[`str`]

    Returns

      Optionally, this function returns a string with the name of the next Flow in the authentication process.

## Functions

Functions class holding all Flows unrelated to authentication.

class Functions(functions)

  Class holding all Flows that don’t affect the authentication.

  This class shouldn’t be used directly by the user, instead the Raider class should be used which will deal with Functions internally.

  functions

    A list of Flow objects with all available functions.

  get_function_by_name(name)

    Gets the function given its name.

    Tries to find the Flow object with the given name, and returns it if it’s found, otherwise returns None.

    Parameters

      name (`str`) – A string with the unique identifier of the function as defined in the Flow.

    Return type

      `Optional`[`Flow`]

    Returns

      A Flow object associated with the name, or None if no such function has been found.

  run(name, user, config)

    Runs a Function.

    Executes the given function, in the context of the specified user, and applies the global Raider configuration.

    Parameters

      - name (`str`) – A string with the name of the function to run.

      - user (`User`) – A User object containing all the data needed to run the function in this user’s context.

      - config (`Config`) – A Config object with the global Raider configuration.

    Return type

      `None`

# Internal API reference

## Request

Request class used to handle HTTP.

class PostBody(data, encoding)

  Holds the POST body data.

  This class was created to enable the user to send the POST body in a different format than the default url encoded. For now only JSON encoding has been implemented.

  encoding

    A string with the desired encoding. For now only “json” is supported. If the encoding is skipped, the request will be url encoded, and the Content-Type will be `application/x-www-form-urlencoded`.

class Request(method, url=None, path=None, cookies=None, headers=None, data=None)

  Class holding the elements of the HTTP request.

  When a Flow object is created, it defines a Request object with the information necessary to create a HTTP request. The “method” attribute is required. One and only one of “url” and “path” is required too. Everything else is optional.

  The Request object can contain Plugins which will be evaluated and its value replaced in the HTTP request.

  method

    A string with the HTTP request method. Only GET and POST is supported for now.

  url

    A string with the URL of the HTTP request. Cannot be used if “path” is used.

  path

    A string with the path of the HTTP request. The base URL is defined in the “_base_url” variable from the hy configuration files of the project. If “path” is defined “url” cannot be used.

  cookies

    A list of Cookie objects to be sent with the HTTP request.

  headers

    A list of Header objects to be sent with the HTTP request.

  data

    A dictionary of Any objects. Can contain strings and Plugins. When a key or a value of the dictionary is a Plugin, it will be evaluated and its value will be used in the HTTP request. If the “method” is GET those values will be put inside the URL parameters, and if the “method” is POST they will be inside the POST request body.

  list_inputs()

    Returns a list of request’s inputs.

    Return type

      `Optional`[`Dict`[`str`, `Plugin`]]

  process_inputs(user, config)

    Process the Request inputs.

    Uses the supplied user data to replace the Plugins in the inputs with their actual value. Returns those values.

    Parameters

      - user (`User`) – A User object containing the user specific data to be used when processing the inputs.

      - config (`Config`) – A Config object with the global Raider configuration.

    Return type

      `Dict`[`str`, `Dict`[`str`, `str`]]

    Returns

      A dictionary with the cookies, headers, and other data created from processing the inputs.

  send(user, config)

    Sends the HTTP request.

    With the given user information, replaces the input plugins with their values, and sends the HTTP request. Returns the response.

    Parameters

      - user (`User`) – A User object with the user specific data to be used when processing inputs.

      - config (`Config`) – A Config object with the global Raider configuration.

    Return type

      `Optional`[`Response`]

    Returns

      A requests.models.Response object with the HTTP response received after sending the generated request.

## Structures

Data structures used in Raider.

class CookieStore(data)

  Class storing the HTTP cookies.

  This class inherits from DataStore, and converts the values into Cookie objects.

  classmethod from_dict(data)

    Creates a CookieStore object from a dictionary.

    Given a dictionary with cookie values, creates a CookieStore object and returns it.

    Parameters

      data (`Optional`[`Dict`[`str`, `str`]]) – A dictionary with cookie values. Those will be mapped in Cookie objects.

    Return type

      `CookieStore`

    Returns

      A CookieStore object containing the cookies created from the supplied dictionary.

  set(cookie)

    Sets the value of a Cookie.

    Given a Cookie object, add or update its value in the CookieStore.

    Parameters

      cookie (`Cookie`) – A Cookie object to be added to the CookieStore

    Return type

      `None`

class DataStore(data)

  Class defining a dictionary-like data structure.

  This class was created to hold information relevant to Raider in a structure similar to Python dictionaries.

  __getitem__(key)

    Getter to return an element with the key.

    Return type

      `Any`

  __iter__()

    Iterator to yield the keys.

    Return type

      `Iterator`[`Any`]

  __next__()

    Iterator to get the next element.

    Return type

      `Any`

  __setitem__(key, value)

    Setter to add a new element to DataStore.

    Return type

      `None`

  items()

    Returns a list of tuples containing the keys and values.

    Return type

      `List`[`Tuple`[`Any`, `Any`]]

  list_keys()

    Returns a list of the keys in the DataStore.

    Return type

      `List`[`Any`]

  list_values()

    Returns a list of the values in the DataStore.

    Return type

      `List`[`Any`]

  pop(name)

    Pops an element from the DataStore.

    Return type

      `Any`

  to_dict()

    Returns the DataStore elements as a dictionary.

    Return type

      `Dict`[`Any`, `Any`]

  update(data)

    Updates the DataStore with a new element.

    Return type

      `None`

class HeaderStore(data)

  Class storing the HTTP headers.

  This class inherits from DataStore, and converts the values into Header objects.

  classmethod from_dict(data)

    Creates a HeaderStore object from a dictionary.

    Given a dictionary with header values, creates a HeaderStore object and returns it.

    Parameters

      data (`Optional`[`Dict`[`str`, `str`]]) – A dictionary with header values. Those will be mapped in Header objects.

    Return type

      `HeaderStore`

    Returns

      A HeaderStore object containing the headers created from the supplied dictionary.

  set(header)

    Sets the value of a Header.

    Given a Header object, add or update its value in the HeaderStore.

    Parameters

      header (`Header`) – A Header object to be added to the HeaderStore.

    Return type

      `None`

## User

Classes used for handling users.

class User(username, password, **kwargs)

  Class holding user related information.

  User objects are created inside the UserStore. Each User object contains at least the username and the password. Every time a Plugin generates an output, it is saved in the User object. If the Plugin is a Cookie or a Header, the output will be stored in the the “cookies” and “headers” attributes respectively. Otherwise they’ll be saved inside “data”.

  username

    A string containing the user’s email or username used to log in.

  password

    A string containing the user’s password.

  cookies

    A CookieStore object containing all of the collected cookies for this user. The Cookie plugin only writes here.

  headers

    A HeaderStore object containing all of the collected headers for this user. The Header plugin only writes here.

  data

    A DataStore object containing the rest of the data collected from plugins for this user.

  set_cookie(cookie)

    Sets the cookie for the user.

    Given a Cookie object, update the user’s “cookies” attribute to include this cookie.

    Parameters

      cookie (`Cookie`) – A Cookie Plugin object with the data to be added.

    Return type

      `None`

  set_data(data)

    Sets the data for the user.

    Given a Plugin, update the user’s data attribute to include this data.

    Parameters

      data (`Plugin`) – A Plugin object with the data to be added.

    Return type

      `None`

  set_header(header)

    Sets the header for the user.

    Given a Header object, update the user’s “headers” attribute to include this header.

    Parameters

      header (`Header`) – A Header Plugin object with the data to be added.

    Return type

      `None`

  to_dict()

    Returns this object’s data in a dictionary format.

    Return type

      `Dict`[`str`, `str`]

class UserStore(users, active_user=None)

  Class holding all the users of the Application.

  UserStore inherits from DataStore, and contains the users set up in the “_users” variable from the hy configuration file. Each user is an User object. The data from a UserStore object can be accessed same way like from the DataStore.

  If “_active_user” is set up in the configuration file, this will be the default user. Otherwise, the first user will be the active one.

  active_user

    A string with the currently active user.

  property active: raider.user.User

    Returns the active user as an User object.

    Return type

      `User`

  to_dict()

    Returns the UserStore data in dictionary format.

    Return type

      `Dict`[`str`, `str`]

## utils

Functions that are used within Raider.

create_hy_expression(variable, value)

  Creates a hy expression.

  Raider configuration is saved in hy format, and this function creates the assignments in this format.

  Parameters

    - variable (`str`) – A string with the name of the variable to be created.

    - value (`Union`[`str`, `Dict`[`Any`, `Any`], `List`[`Any`]]) – The value of the variable.

  Return type

    `str`

  Returns

    A string with the valid hy expression.

default_user_agent()

  Gets the default user agent.

  Gets the current version of Raider and creates the user agent string.

  Return type

    `str`

  Returns

    A string with the user agent.

eval_file(filename, shared_locals=None)

  Evaluate hy file.

  This function evaluates all the content inside the supplied hy file, and returns the created locals() so that it can be later used for other files.

  Parameters

    - filename (`str`) – A string with the file name to be evaluated.

    - shared_locals (`Optional`[`Dict`[`str`, `Any`]]) – A dictionary with the locals() that will be considered when evaluating the file.

  Return type

    `Dict`[`str`, `Any`]

  Returns

    A dictionary with the updated locals() after evaluating the hy file.

eval_project_file(project, filename, shared_locals)

  Evaluate a hy file from a project.

  This function evaluates the specified file inside the project and returns the locals() which are updated after evaluating the file.

  Parameters

    - project (`str`) – A string with the name of the project.

    - filename (`str`) – A string with the file name to be evaluated.

    - shared_locals (`Dict`[`str`, `Any`]) – A dictionary of locals() to be included when evaluating the file.

  Return type

    `Dict`[`str`, `Any`]

  Returns

    A dictionary of locals() updated after evaluating the file.

get_config_dir()

  Gets the configuration directory.

  Returns the path of the directory with the Raider configuration files.

  Return type

    `str`

  Returns

    A string with the path of the configuration directory.

get_config_file(filename)

  Gets the configuration file.

  Given the file name, it returns the path of this file in the Raider configuration directory.

  Parameters

    filename (`str`) – A string with the name of the file to look up for in the main configuration directory.

  Return type

    `str`

  Returns

    A string with the path of the file.

get_project_dir(project)

  Gets the directory of the project.

  Given the name of the project, returns the path to the directory containing the configuration files for this project.

  Parameters

    project (`str`) – A string with the name of the project.

  Return type

    `str`

  Returns

    A string with the path of the directory where the config files for the project are located.

get_project_file(project, filename)

  Gets a file from a project.

  Given the project name and the file name, it returns the path to that file.

  Parameters

    - project (`str`) – A string with the name of the project.

    - filename (`str`) – A string with the file name.

  Return type

    `str`

  Returns

    The path of the file in the project directory.

hy_dict_to_python(hy_dict)

  Converts a hy dictionary to a python dictionary.

  When creating dictionaries in hylang using :parameters they become hy.HyKeyword objects. This function converts them to normal python dictionaries.

  Parameters

    hy_dict (`Dict`[`HyKeyword`, `Any`]) – A dictionary created in hy, which uses hy.HyKeyword instead of simple strings as keys.

  Return type

    `Dict`[`str`, `Any`]

  Returns

    A dictionary with the same elements only with hy.HyKeyword keys converted into normal strings.

import_raider_objects()

  Imports Raider objects to use inside hy configuration files.

  To make Raider objects visible inside hy files without using separate imports, this function does the imports and returns the locals() which is later used when evaluating hy files.

  Return type

    `Dict`[`str`, `Any`]

  Returns

    A dictionary with the locals() containing all the Raider objects that can be used in hy files.

list_projects()

  List existing projects.

  This function returns the list of projects that have been configured in Raider.

  Return type

    `List`[`str`]

  Returns

    A list with the strings of the project found in the configuration directory.

match_tag(html_tag, attributes)

  Tells if a tag matches the search.

  This function checks whether the supplied tag matches the attributes. The attributes is a dictionary, and the values are treated as a regular expression, to allow checking for tags that don’t have a static value.

  Parameters

    - html_tag (`Tag`) – A bs4.element.Tag object with the tag to be checked.

    - attributes (`Dict`[`str`, `str`]) – A dictionary of attributes to check whether they match with the tag.

  Return type

    `bool`

  Returns

    A boolean saying whether the tag matched with the attributes or not.

parse_json_filter(raw)

  Parses a raw JSON filter and returns a list with the items.

  Parameters

    raw (`str`) – A string with the expected JSON filter.

  Return type

    `List`[`str`]

  Returns

    A list with all items found in the filter.

py_dict_to_hy_list(data)

  Converts a python dictionary to a hylang list.

  In hy, dictionaries are created out of lists, and this function converts a normal python dictionary to a list made out of hy symbols that will be later used to create the hy dictionary.

  Parameters

    data (`Dict`[`str`, `Any`]) – A python dictionary with the data to convert.

  Return type

    `List`[`Union`[`HyString`, `HyDict`, `HySymbol`]]

  Returns

    A list with hy objects that can be used to create a hy dictionary.

serialize_hy(form)

  Serializes hy expression.

  This function serializes the supplied hy expression and returns it in a string format, so that it can be later saved in a file.

  Parameters

    form (`Union`[`HyExpression`, `HyDict`, `HyList`, `HySymbol`, `HyInteger`, `HyKeyword`, `HyString`]) – A hy expression to convert to a string.

  Return type

    `str`

  Returns

    A string with the serialized form.