Plugins

Plugins in Raider are pieces of code that are used to get inputs from, and put them in the HTTP Request, and/or to extract some value from the Response. This is used to facilitate the information exchange between Flows. Plugins act as inputs when used inside the Flow’s request attribute, and as outputs when used in the outputs attribute.

Below there’s a list of predefined Plugins. The users are also encouraged to write their own plugins.

Common

Users most often won’t need to use those unless they’re writing their own Plugins. Common Plugins are mostly used as parent classes for other Plugins.

Plugin

Use this class only when creating new Plugins. Either when writing custom plugins in hylang or when adding new plugins to the Raider main code. Check the repository for inspiration.

Plugin objects can be used BOTH as inputs in HTTP Requests and outputs from HTTP Responses.

Plugin’s behaviour can be controlled with following flags:

NEEDS_USERDATA

0x01

NEEDS_RESPONSE

0x02

DEPENDS_ON_OTHER_PLUGINS

0x04

NAME_NOT_KNOWN_IN_ADVANCE

0x08

Combine the flags with boolean OR if you want to set more flags, for example:

class MyPlugin(Plugin):
def __init__(self, name):
    super().__init__(
        name=name,
        function=self.extract_html_tag,
        flags=Plugin.NEEDS_USERDATA|Plugins.NEEDS_RESPONSE,
    )
[...]
class Plugin(name, function=None, value=None, flags=0)[source]

Parent class for all Plugins.

Each Plugin class inherits from here. get_value function should be called when extracting the value from the Plugin, which will then be stored in the value attribute.

Plugin's behaviour can be controlled using following flags:

NEEDS_USERDATA = 0x01

When set, the Plugin will get its value from the user’s data, which will be sent to the function defined here. Use when Plugin's value depends on things defined in the User class, like the username or password.

NEEDS_RESPONSE = 0x02

When set, the Plugin's value can only be extracted from a previous HTTP response.

DEPENDS_ON_OTHER_PLUGINS = 0x04

When set, the Plugin's value can only be extracted from other Plugins. Use this when combining Plugins.

NAME_NOT_KNOWN_IN_ADVANCE = 0x08

When set, the name of the Plugin is not known in advance, and will be set when the Plugin runs. Useful when the name changes and can only be matched with a regex.

name

A String used as an identifier for the Plugin.

function

A Callable which will be called to extract the value of the Plugin when used as an input in a Flow. The function should set self.value and also return it.

name_function

A Callable which will be called to extract the name of the Plugin when it’s not known in advance and the flag NAME_NOT_KNOWN_IN_ADVANCE is set.

plugins

A List of Plugins whose value needs to be extracted first before current Plugin's value can be extracted. Used when the flag DEPENDS_ON_OTHER_PLUGINS is set.

value

A String containing the Plugin's output value to be used as input in the HTTP Requests.

flags

An Integer containing the flags that define the Plugin's behaviour.

__init__(name, function=None, value=None, flags=0)[source]

Initializes a Plugin object.

Creates a Plugin object, holding a function defining how to extract the value.

Parameters
  • name (str) – A String with the unique identifier of the Plugin.

  • function (Optional[Callable[..., Optional[str]]]) – An Optional Callable that will be used to extract the Plugin's value.

  • value (Optional[str]) – An Optional String with the predefined value of the Plugin.

  • flags (int) – An Integer containing the flags that define the Plugin's behaviour. No flags are set by default

get_value(pconfig)[source]

Gets the value from the Plugin.

Depending on the Plugin's flags, extract and return its value.

Parameters

userdata – A Dictionary with the user specific data.

Return type

Optional[str]

Returns

An Optional String with the value of the Plugin. Returns None if no value can be extracted.

extract_value_from_response(response)[source]

Extracts the value of the Plugin from the HTTP response.

If NEEDS_RESPONSE flag is set, the Plugin will extract its value upon receiving the HTTP response, and store it inside the value attribute.

Parameters

response (Optional[Response]) – An requests.models.Response object with the HTTP response.

Return type

None

extract_name_from_response(response)[source]

Extracts the name of the Plugin from the HTTP response.

If NAME_NOT_KNOWN_IN_ADVANCE flag is set, the Plugin will set its name after receiving the HTTP response, and store it inside the name attribute.

Parameters

response (Optional[Response]) – An requests.models.Response object with the HTTP response.

Return type

None

extract_value_from_userdata(pconfig)[source]

Extracts the Plugin value from userdata.

Given a dictionary with the userdata, return its value with the same name as the “name” attribute from this Plugin.

Parameters

data – A Dictionary with user specific data.

Return type

Optional[str]

Returns

An Optional String with the value of the variable found. Returns None if it cannot be extracted.

return_value()[source]

Returns Plugin's value.

This is used when needing a function just to return the value.

Return type

Optional[str]

Returns

An Optional String with the stored value. Returns None if value is empty.

property needs_userdata: bool

Returns True if the NEEDS_USERDATA flag is set.

Return type

bool

property needs_response: bool

Returns True if the NEEDS_RESPONSE flag is set.

Return type

bool

property depends_on_other_plugins: bool

Returns True if the DEPENDS_ON_OTHER_PLUGINS flag is set.

Return type

bool

property name_not_known_in_advance: bool

Returns True if the NAME_NOT_KNOWN_IN_ADVANCE flag is set.

Return type

bool

Parser

The Parser Plugin takes other Plugins as input, parses it, and extracts the piece of information for further use. Parser Plugins can ONLY be used as inputs.

class Parser(name, function, value=None)[source]

Parent class for Parser Plugins.

Use the Parser Plugin when needing to take another Plugin as input, build a data structure out of it, and extracting some parts you’re interested in. The simplest example would be parsing a URL to extract the domain name from it.

name

A String used as an identifier for the Parser.

function

A Callable which will be called to parse the value of parent Plugin and extract the new value. The function should set self.value and also return it.

name_function

A Callable which will be called to extract the name of the Plugin when it’s not known in advance and the flag NAME_NOT_KNOWN_IN_ADVANCE is set. By default not used in Parser Plugin.

plugins

A List of Plugins whose value needs to be extracted first before current Plugin's value can be extracted. Used when the flag DEPENDS_ON_OTHER_PLUGINS is set, which it is by default for Parsers.

value

A String containing the Parser's output value to be used as input in the HTTP Requests.

flags

An Integer containing the flags that define the Plugin's behaviour. By default only the DEPENDS_ON_OTHER_PLUGINS flag is set.

__init__(name, function, value=None)[source]

Initializes the Parser Plugin.

Creates a Parser object, holding a function defining how to parse the parent Plugin in order to extract the value. Only the flag DEPENDS_ON_OTHER_PLUGINS is preset, since it needs to extract the value from other Plugins, and those need to be extracted first.

Parameters
  • name (str) – A String with the unique identifier of the Parser.

  • function (Callable[[], Optional[str]]) – A Callable function that will be used to extract the Parser's value.

  • value (Optional[str]) – A String with the extracted value from the Plugin.

Processor

The Processor Plugin encodes, decodes and otherwise processes other Plugins. Processor Plugins can ONLY be used as inputs.

class Processor(name, function, value=None)[source]

Parent class for Processor Plugins.

Use the Processor Plugin when needing to take another Plugin as input, and modify (process) it to get the needed value. For example by encoding/decoding or doing other kinds of modifications to the value extracted from the parent Plugin.

name

A String used as an identifier for the Processor.

function

A Function which will be called to process the value of the parent Plugin and get the new value. The function should set self.value and also return it.

name_function

A Callable which will be called to extract the name of the Plugin when it’s not known in advance and the flag NAME_NOT_KNOWN_IN_ADVANCE is set. By default not used in Parser Plugin.

plugins

A List of Plugins whose value needs to be extracted first before current Plugin's value can be extracted. Used when the flag DEPENDS_ON_OTHER_PLUGINS is set, which it is by default for Processors.

value

A String containing the Processors's output value to be used as input in the HTTP Requests.

flags

An Integer containing the flags that define the Plugin's behaviour. By default only the flag DEPENDS_ON_OTHER_PLUGINS is set.

__init__(name, function, value=None)[source]

Initializes the Processor Plugin.

Creates a Processor object, holding a function defining how to process the parent Plugin to get the value. Only the flag DEPENDS_ON_OTHER_PLUGINS is preset, since it needs to extract the value from other Plugins, and those need to be extracted first.

Parameters
  • name (str) – A String with the unique identifier of the Parser.

  • function (Callable[[], Optional[str]]) – A Callable that will be used to extract the Parsers value.

  • value (Optional[str]) – A String with the extracted value from the Plugin.

Empty

The Empty Plugin is unique in that it contains no function or value. Its only use is when fuzzing but no previous value is needed. Empty Plugin can ONLY be used as inputs.

class Empty(name)[source]

Class for Empty Plugins.

Use the Empty Plugin when you don’t care about the actual value of the Plugin, and only want to have a placeholder to use for fuzzing.

name

A String used as an identifier for the Empty Plugin.

function

A Callable which will be called to process the value of the parent Plugin and get the new value. The function should set self.value and also return it.

name_function

A Callable which will be called to extract the name of the Plugin when it’s not known in advance and the flag NAME_NOT_KNOWN_IN_ADVANCE is set. Not used in Empty Plugin.

plugins

A List of Plugins whose value needs to be extracted first before current Plugin's value can be extracted. Used when the flag DEPENDS_ON_OTHER_PLUGINS is set. Not used in Empty Plugin.

value

A string containing the Processors's output value to be used as input in the HTTP Requests. Not used in Empty Plugin.

flags

An integer containing the flags that define the Plugin's behaviour. Not used in Empty Plugin.

__init__(name)[source]

Initializes the Empty Plugin.

Creates an Empty object without any value. Use it when you don’t need any value for the Plugin and only want to use it as a placeholder for fuzzing.

Parameters

name (str) – A String with the unique identifier of the Parser.

Example:

(setv placeholder (Empty "placeholder"))

(setv attack
  (Flow
    (Request.post
      "https://example.com/"
      :data
      {"item" "123"
       "filename" placeholder     ;; Sends empty filename by default.
                                  ;; When fuzzing use the payload string instead.
      }

Basic

Basic Plugins are the most commonly used ones, that don’t depend on other plugins to get its value. Basic Plugins can be used BOTH as inputs and outputs.

Variable

The Variable Plugin extracts the value defined in the User object. Use it to get the username/password or other extra information about the User. Variable Plugins can ONLY be used as inputs.

class Variable(name)[source]

Plugin to extract data from the User

Use this when the value of the plugin should be extracted from the user data. username and password are mandatory and can be accessed with (Variable "username") and (Variable "password") respectively. Other data can be accessed similarly.

name

A string used as an identifier for the Variable Plugin

__init__(name)[source]

Initializes the Variable Plugin.

Creates a Variable object that will return the data from the User object.

Parameters

name (str) – A String with the name of the variable.

Example:

(setv users
      (Users
        [{"admin"                     ;; username
          "password"                  ;; password
          :nickname "admin"           ;; extra optional data
          :email "admin@example.com"}
         {"user1" "password1"
         :attribute "blah"
         :nickname "mynickname"
         :email "abc@example.com"}]))

(setv username (Variable "username"))
(setv password (Variable "password"))
(setv nickname (Variable "nickname"))


(setv login
  (Flow
      (Request.post
        "https://www.example.com/login"
        :data
        {"username" username          ;; Sends the active user's credentials
         "password" password          ;; and the email in the respective fields.
         "email" email}

Prompt

The prompt plugin accepts user input mid-flow. Use it when you don’t know in advance the data you will need to send, like in case of multi-factor authentication (MFA). Prompt Plugins can ONLY be used as inputs.

class Prompt(name)[source]

Plugin to prompt the user for some data.

Use this Plugin when the value cannot be known in advance, for example when asking for multi-factor authentication (MFA) code that is going to be sent over SMS or E-mail.

name

A String used both as an identifier for this Prompt Plugin and as a prompt message on the terminal.

__init__(name)[source]

Initializes the Prompt Plugin.

Creates a Prompt Plugin which will ask the user’s input to get the Plugin's value.

Parameters

name (str) – A String containing the prompt asking the user for input.

get_user_prompt()[source]

Gets the value from user input.

Creates a prompt asking the user for input and stores the value in the Plugin.

Return type

str

Returns

A string with the input received from the user.

Example:

(setv username (Variable "username"))
(setv password (Variable "password"))
(setv mfa_code (Prompt "Input code here:"))      ;; Asks user for the MFA code.

(setv multifactor
  (Flow
      (Request.post
        "https://www.example.com/login"
        :data
        {"username" username
         "password" password
         "otp" mfa_code}             ;; Sends the data from user's input in `otp`.

File

The File plugin sets the plugin’s value to the contents of a provided file and allows string substitution within the content.

class File(path, function=None, flags=0)[source]

Plugin used for getting data from the filesystem.

Use File: Plugin when needing to upload something, or sending a Request with lots of data that would better be stored on the filesystem instead of hyfiles.

name

A String with the Plugin's name. For File objects that’s the path to the file.

function

A Callable which will be called to extract the value of the Plugin when used as an input in a Flow. The function should set self.value and also return it. By default for File Plugins it puts the unmodified contents of the File found in the path.

name_function

A Callable which will be called to extract the name of the Plugin when it’s not known in advance and the flag NAME_NOT_KNOWN_IN_ADVANCE is set. File doesn’t use this.

plugins

A List of Plugins whose value needs to be extracted first before current Cookie's value can be extracted. Used when the flag DEPENDS_ON_OTHER_PLUGINS is set.

value

A string containing the File's output value to be used as input in the HTTP Requests which is just the File contents.

flags

An integer containing the flags that define the Plugin's behaviour. For File :class:`Plugins no flags are set by default.

__init__(path, function=None, flags=0)[source]

Initializes the File Plugin.

Creates a File Plugin, and populates its value with the contents of a File` from the filesystem.

Parameters
  • path (str) – A String with the path of the File.

  • function (Optional[Callable[..., Union[str, bytes, None]]]) – An Optional Callable which is used to get the value of the File on runtime.

  • flags (int) – An integer containing the flags that define the Plugin's behaviour. By default no flag is set.

read_file()[source]

Sets the Plugin's value to the file contents.

Return type

bytes

Returns

A Bytes string containing the raw file contents.

classmethod replace(path, old_value, new_value)[source]

Read a File and replace strings with new ``value``s.

Use this in case the File is a template that needs some part of it replaced with a new string, for example:

If we have the file data.json:

{"data":
   "username": $USERNAME$,
   "nickname": "nickname",
   [...]
}

And we want to replace $USERNAME$ with the real username, we can use:

(File.replace "/path/to/data.json"
   "$USERNAME$"
   "admin")

To replace every instance of $USERNAME$ with our chosen value in new_value.

Parameters
  • path (str) – A String with the path of the File.

  • old_value (str) – A String with the old value to be replaced.

  • new_value (Union[str, int, Plugin]) – A String with the new value to be replaced.

Return type

File

Command

The Command plugin runs shell commands and extracts their output.

class Command(name, command)[source]

Use this to run a shell command and extract the output.

__init__(name, command)[source]

Initializes the Command Plugin.

The specified command will be executed with os.popen() and the output with the stripped last newline, will be saved inside the value.

Parameters
  • name (str) – A unique identifier for the plugin.

  • command (str) – The command to be executed.

run_command()[source]

Runs a command and returns its value.

Given a dictionary with the predefined variables, return the value of the with the same name as the “name” attribute from this Plugin.

Parameters

data – A dictionary with the predefined variables.

Return type

Optional[str]

Returns

A string with the value of the variable found. None if no such variable has been defined.

Example:

(setv mfa_code (Command
                :name "otp"
                :command "pass otp personal/app1"))

Regex

The Regex plugin extracts a matched expression from the HTTP response.

class Regex(name, regex, function=None, flags=2)[source]

Plugin class to extract regular expressions.

This plugin will match the regex provided, and extract the value inside the first matched group. A group is the string that matched inside the brackets.

For example if the regular expression is:

“accessToken”:”([^”]+)”

and the text to match it against contains:

“accessToken”:”0123456789abcdef”

then only the string “0123456789abcdef” will be extracted and saved in the value attribute.

name

A string used as an identifier for the Regex.

regex

A string containing the regular expression to be matched.

__init__(name, regex, function=None, flags=2)[source]

Initializes the Regex Plugin.

Creates a Regex Plugin with the given regular expression, and extracts the matched group given in the “extract” argument, or the first matching group if not specified.

Parameters
  • name (str) – A string with the name of the Plugin.

  • regex (str) – A string containing the regular expression to be matched.

extract_regex_from_response(response)[source]

Extracts regex from a HTTP response.

Return type

Optional[str]

extract_regex_from_plugin()[source]

Extracts regex from a Plugin.

Return type

Optional[str]

extract_regex(text)[source]

Extracts defined regular expression from a text.

Given a text to be searched for matches, return the string inside the group defined in “extract” or the first group if it’s undefined.

Parameters

text (str) – A string containing the text to be searched for matches.

Return type

Optional[str]

Returns

A string with the match from the extracted group. Returns None if there are no matches.

classmethod from_plugin(parent_plugin, regex)[source]

Extracts Regex from another plugin’s value.

Return type

Regex

__str__()[source]

Returns a string representation of the Plugin.

Return type

str

Example:

(setv access_token
      (Regex
        :name "access_token"
        :regex "\"accessToken\":\"([^\"]+)\""))

Html

The Html plugin extracts tags matching attributes specified by the user.

class Html(name, tag, attributes, extract)[source]

This Plugin will find the HTML “tag” containing the specified “attributes” and store the “extract” attribute of the matched tag in its value attribute.

tag

A string defining the HTML tag to look for.

attributes

A dictionary with attributes matching the desired HTML tag. The keys in the dictionary are strings matching the tag’s attributes, and the value``s are treated as regular expressions, to help match tags that don't have a static ``value.

extract

A string defining the HTML tag’s attribute that needs to be extracted and stored inside value.

__init__(name, tag, attributes, extract)[source]

Initializes the Html Plugin.

Creates a Html Plugin with the given “tag” and “attributes”. Stores the “extract” attribute in the plugin’s value.

Parameters
  • name (str) – A string with the name of the Plugin.

  • tag (str) – A string with the HTML tag to look for.

  • attributes (Dict[Keyword, str]) – A hy dictionary with the attributes to look inside HTML tags. The ``value``s of dictionary elements are treated as regular expressions.

  • extract (str) – A string with the HTML tag attribute that needs to be extracted and stored in the Plugin’s object.

extract_html_tag(response)[source]

Extract data from an HTML tag.

Given the HTML text, parses it, iterates through the tags, and find the one matching the attributes. Then it stores the matched value and returns it.

Parameters

text – A string containing the HTML text to be processed.

Return type

Optional[str]

Returns

A string with the match as defined in the Plugin. Returns None if there are no matches.

__str__()[source]

Returns a string representation of the Plugin.

Return type

str

Example:

(setv csrf_token
      (Html
        :name "csrf_token"
        :tag "input"
        :attributes
        {:name "csrf_token"
         :value "^[0-9a-f]{40}$"
         :type "hidden"}
        :extract "value"))

Json

The Json plugin extracts fields from JSON tables.

class Json(name, extract, function=None, flags=2)[source]

The “extract” attribute is used to specify which field to store in the value. Using the dot . character you can go deeper inside the JSON object. To look inside an array, use square brackets [].

Keys with special characters should be written inside double quotes ". Keep in mind that when written inside hyfiles, it’ll already be between double quotes, so you’ll have to escape them with the backslash character \.

Examples

env.production[0].field production.keys[1].x5c[0][1][0]."with space"[3]

extract

A string defining the location of the field that needs to be extracted. For now this is still quite primitive, and cannot access data from JSON arrays.

__init__(name, extract, function=None, flags=2)[source]

Initializes the Json Plugin.

Creates the Json Plugin and extracts the specified field.

Parameters
  • name (str) – A string with the name of the Plugin.

  • extract (str) – A string with the location of the JSON field to extract.

extract_json_from_response(response)[source]

Extracts the json field from a HTTP response.

Return type

Optional[str]

extract_json_from_plugin()[source]

Extracts the json field from a plugin.

Return type

Optional[str]

extract_json_field(text)[source]

Extracts the JSON field from the text.

Given the JSON body as a string, extract the field and store it in the Plugin’s value attribute.

Parameters

text (str) – A string with the JSON body.

Return type

Optional[str]

Returns

A string with the result of extraction. If no such field is found None will be returned.

classmethod from_plugin(parent_plugin, name, extract)[source]

Extracts the JSON field from another plugin’s value.

Return type

Json

__str__()[source]

Returns a string representation of the Plugin.

Return type

str

Modifiers

Alter

The Alter plugin extracts and alters the value of other plugins.

class Alter(parent_plugin, alter_function=None)[source]

If the value extracted from other plugins cannot be used in it’s raw form and needs to be somehow processed, Alter plugin can be used to do that. Initialize it with the original plugin and a function which will process the string and return the modified value.

alter_function

A function which will be given the plugin’s value. It should return a string with the processed value.

__init__(parent_plugin, alter_function=None)[source]

Initializes the Alter Plugin.

Given the original plugin, and a function to alter the data, initialize the object, and get the modified value.

Parameters
  • plugin – The original Plugin where the value is to be found.

  • alter_function (Optional[Callable[[str], Optional[str]]]) – The Function with instructions on how to alter the value.

process_value()[source]

Process the original plugin’s value.

Gives the original plugin’s value to alter_function. Return the processed value and store it in self.value.

Return type

Optional[str]

Returns

A string with the processed value.

classmethod prepend(parent_plugin, string)[source]

Prepend a string to plugin’s value.

Return type

Alter

classmethod append(parent_plugin, string)[source]

Append a string after the plugin’s value

Return type

Alter

classmethod replace(parent_plugin, old_value, new_value)[source]

Replace a substring from plugin’s value with something else.

Return type

Alter

Combine

The Combine plugin concatenates the value of other plugins.

class Combine(*args)[source]

Use to combine the values of plugins.

__init__(*args)[source]

Initialize Combine object.

concatenate_values()[source]

Concatenate the provided values.

This function will concatenate the arguments values. Accepts both strings and plugins.

Return type

str

Parsers

Urlparser

The URLParser plugin parses URLs and extracts elements from it.

class Urlparser(parent_plugin, element)[source]

Parse the URL and extract elements from it.

Use this when needing to extract some piece of information from the URL.

__init__(parent_plugin, element)[source]

Initializes the Parser Plugin.

Creates a Parser object, holding a function defining how to parse the parent Plugin in order to extract the value. Only the flag DEPENDS_ON_OTHER_PLUGINS is preset, since it needs to extract the value from other Plugins, and those need to be extracted first.

Parameters
  • name – A String with the unique identifier of the Parser.

  • function – A Callable function that will be used to extract the Parser's value.

  • value – A String with the extracted value from the Plugin.

parse_url()[source]

Parses the URL and returns the string with the desired element.

Return type

Optional[str]

Processors

Urlencode

The Urlencode plugin URL encodes a processor plugin.

class Urlencode(parent_plugin)[source]

URL Encode the plugin.

__init__(parent_plugin)[source]

Initializes the Urlencode plugin.

urlencode()[source]

URL encodes a plugin’s value.

Return type

str

Urldecode

The Urldecode plugin URL decodes a processor plugin.

class Urldecode(parent_plugin)[source]

URL Decode the plugin.

__init__(parent_plugin)[source]

Initializes the Urldecode plugin.

urldecode()[source]

URL decodes a plugin’s value.

Return type

Optional[str]

B64encode

The B64encode plugin base64 encodes a processor plugin.

B64decode

The B64decode plugin base64 decodes a processor plugin.

class B64decode(parent_plugin)[source]

Base64 Decode the plugin.

__init__(parent_plugin)[source]

Initializes the B64decode plugin.

b64decode()[source]

Base64 decodes a plugin’s value.

Return type

Optional[str]