Operations — raider 0.2.0a0 documentation

# Operations

Raider operations are pieces of code that will be executed when the HTTP response is received. The most important one is NextStage which controls the authentication flow. But anything can be done with the operations, and Raider allows writing custom ones in hylang to enable users to add functionality that isn’t supported by the main code.

## NextStage

Inside the Authentication object NextStage is used to define the next step of the authentication process. It can also be used inside “action” attributes of the other Operations to allow conditional decision making.

    (NextStage "login")

class NextStage(next_stage)

  Operation defining the next stage.

  Inside the Authentication object NextStage is used to define the next step of the authentication process. It can also be used inside “action” attributes of the other Operations to allow conditional decision making.

  next_stage

    A string with the name of the next stage to be executed.

  __str__()

    Returns a string representation of the Operation.

    Return type

      `str`

## Print

When this Operation is executed, it will print each of its elements in a new line.

    (Print
      "This will be printed first"
      access_token
      "This will be printed on the third line")

    (Print.body)

    (Print.headers)
    (Print.headers "User-agent")

    (Print.cookies)
    (Print.cookies "PHPSESSID")

class Print(*args, flags=0, function=None)

  Operation that prints desired information.

  When this Operation is executed, it will print each of its elements in a new line.

  \*args

    A list of Plugins and/or strings. The plugin’s extracted values will be printed.

  __str__()

    Returns a string representation of the Print Operation.

    Return type

      `str`

  classmethod body()

    Classmethod to print the HTTP response body.

    Return type

      `Print`

  classmethod cookies(cookies=None)

    Classmethod to print the HTTP response cookies.

    Parameters

      cookies (`Optional`[`List`[`str`]]) – A list of strings containing the cookies that needs to be printed.

    Return type

      `Print`

  classmethod headers(headers=None)

    Classmethod to print the HTTP response headers.

    Parameters

      headers (`Optional`[`List`[`str`]]) – A list of strings containing the headers that needs to be printed.

    Return type

      `Print`

  print_items()

    Prints the defined items.

    Return type

      `None`

## Save

When this Operation is executed, it will save its elements in a file.

    (Save "/tmp/access_token" access_token)
    (Save "/tmp/session" session_id :append True)
    (Save.body "/tmp/body")

class Save(filename, plugin=None, save_function=None, flags=0)

  Operation to save information to files.

  filename

    The path to the file where the data should be saved.

  classmethod append(filename, plugin)

    Append to file instead of overwrite.

    Parameters

      - filename (`str`) – Path to the file to append to.

      - plugin (`Plugin`) – The Plugin with the content to write.

    Return type

      `Save`

    Returns

      A Save object which will append data instead of overwrite.

  classmethod body(filename, append=False)

    Save the entire HTTP body.

    If you need to save the entire body instead of extracting some data from it using plugins, use `Save.body`. Given a filename, and optionally a boolean `append`, write the body’s contents into the file.

    Parameters

      - filename (`str`) – The path to the file where to write the data.

      - append (`bool`) – A boolean which when True, will append to existing file instead of overwriting it.

    Return type

      `Save`

    Returns

      A Save object which will save the response body.

  save_to_file(content)

    Saves a string or plugin’s content to a file.

    Given the content (a string or a plugin), open the file and write its contents. If WILL_APPEND was set, append to file instead of overwrite.

    Parameters

      content (`Union`[`str`, `Plugin`, `Response`]) – A string or a Plugin with the data to be written.

    Return type

      `None`

## Error

Operation that will exit Raider and print the error message.

    (Error "Login failed.")

class Error(message)

  Operation that will exit Raider and print the error message.

  message

    A string with the error message to be printed.

  __str__()

    Returns a string representation of the Operation.

    Return type

      `str`

## Http

    (Http
       :status 200
       :action
         (NextStage "login")
       :otherwise
         (NextStage "multi_factor"))

class Http(status, action, otherwise=None)

  Operation that runs actions depending on the HTTP status code.

  A Http object will check if the HTTP response status code matches the code defined in its “status” attribute, and run the Operation inside “action” if it matches or the one inside “otherwise” if not matching.

  status

    An integer with the HTTP status code to be checked.

  action

    An Operation that will be executed if the status code matches.

  otherwise

    An Operation that will be executed if the status code doesn’t match.

  __str__()

    Returns a string representation of the Operation.

    Return type

      `str`

  match_status_code(response)

    Check if the defined status matches the response status code.

    Return type

      `bool`

## Grep

    (Grep
      :regex "TWO_FA_REQUIRED"
      :action
        (NextStage "multi_factor")
      :otherwise
        (Print "Logged in successfully"))

class Grep(regex, action, otherwise=None)

  Operation that runs actions depending on Regex matches.

  A Grep object will check if the HTTP response body matches the regex defined in its “regex” attribute, and run the Operation inside “action” if it matches or the one inside “otherwise” if not matching.

  regex

    A string with the regular expression to be checked.

  action

    An Operation that will be executed if the status code matches.

  otherwise

    An Operation that will be executed if the status code doesn’t match.

  __str__()

    Returns a string representation of the Operation.

    Return type

      `str`

  match_response(response)

    Checks if the response body contains the defined regex.

    Return type

      `bool`

## Writing custom operations

In case the existing operations are not enough, the user can write their own to add the new functionality. Those new operations should be written in the project’s configuration directory in a “.hy” file. To do this, a new class has to be defined, which will inherit from Raider’s Operation class:

class Operation(function, flags=0, action=None, otherwise=None)

  Parent class for all operations.

  Each Operation class inherits from here.

  function

    A callable function to be executed when the operation is run.

  flags

    An integer with the flags which define the behaviour of the Operation. For now only two flags are allowed: NEEDS_RESPONSE and IS_CONDITIONAL. If NEEDS_RESPONSE is set, the HTTP response will be sent to the “function” for further processing. If IS_CONDITIONAL is set, the function should return a boolean, and if the return value is True the Operation inside “action” will be run next, if it’s False, the one from the “otherwise” will be run.

  action

    An Operation object that will be run if the function returns True. Will only be used if the flag IS_CONDITIONAL is set.

  otherwise

    An Operation object that will be run if the function returns False. Will only be used if the flag IS_CONDITIONAL is set.

  property is_conditional: bool

    Returns True if the IS_CONDITIONAL flag is set.

    Return type

      `bool`

  property needs_response: bool

    Returns True if the NEEDS_RESPONSE flag is set.

    Return type

      `bool`

  run(response)

    Runs the Operation.

    Runs the defined Operation, considering the “flags” set.

    Parameters

      response (`Response`) – A requests.models.Response object with the HTTP response to be passed to the operation’s “function”.

    Return type

      `Optional`[`str`]

    Returns

      An optional string with the name of the next stage.

  run_conditional(response)

    Runs a conditional operation.

    If the IS_CONDITIONAL flag is set, run the Operation’s “function” and if True runs the “action” next, if it’s False runs the “otherwise” Operation instead.

    Parameters

      response (`Response`) – A requests.models.Response object with the HTTP response to be passed to the operation’s “function”.

    Return type

      `Optional`[`str`]

    Returns

      An optional string with the name of the next stage.

  property will_append: bool

    Returns True if the WILL_APPEND flag is set.

    Return type

      `bool`