Template - Functions
Last updated
Last updated
Check YouTube for more tutorials: https://youtube.com/@attackforge
UPDATED: Please head over to our new GitHub Support Site for help, examples, tips and tricks: https://github.com/AttackForge/ReportGen
Use this function to declare a variable, which can then be used in other procedures and operators below.
variable - the name of the variable.
variables - other variables. See variables
dynamic variables - used when the variable name is not known ahead of time (in the template). For example:
{$declare[SomeVariable]["Ninja"]}
{$declare["$(SomeVariable)"]["Warrior"]} will translate to {$declare[Ninja]} where "Ninja" is the value of the variable "SomeVariable" and only known at runtime.
value - the value to assign to this variable. Supports:
Example
Declare a new variable 'myVariable' and set a value of 0.
Declare a new variable 'myVariable' and set a value of false.
Declare a new variable 'myVariable' set a value of empty list/array.
Declare a new key 'key1' on an existing Dictionary variable 'myVariable' and set a value of empty list/array.
Declare a new key based on value of another variable 'otherVariable' on an existing Dictionary variable 'myVariable' and set a value of empty list/array.
Use this function to push a value to a variable which has been initialized as an array.
variable - the name of the variable. See $declare.
variables - other variables. See variables
dynamic variables - used when the variable name is not known ahead of time (in the template). For example:
{$declare[SomeVariable]["Ninja"]}
{$push["$(SomeVariable)"]["test"]} will translate to {$push[Ninja]} where "Ninja" is the value of the variable "SomeVariable" and only known at runtime.
Example below will create a new variable that contains the details for each affected asset for SSL Weak Cipher vulnerabilities based on custom tags. Combine with $value to retrieve the affected assets.
Example below will push data to a Dictionary and use $keys to display the data.
Use this function to increment a variable which has a numeric value.
variable - the name of the variable. See $declare.
Example below will create a new variable that increments the total number of vulnerabilities by 1, every time it loops through a new vulnerability. Combine with $value to retrieve the count.
Use this function to decrease a variable which has a numeric value.
variable - the name of the variable. See $declare.
Example below will create a new variable that counts all vulnerabilities except for info vulnerabilities. It decreases the total number of vulnerabilities by 1, every time it loops through a new vulnerability and where the vulnerability priority is Info. Combine with $value to retrieve the count.
Use this function to multiply a variable which has a numeric value.
variable - the name of the variable. See $declare.
Example below will create a new variable 'AmountToCharge' with a default amount of $500. It then checks for a project custom field 'rateToMultiplyCharge' and multiplies 'AmountToCharge' by this amount. Combine with $value to show the amount to charge.
Use this function to get the percentage of two numeric values.
variable - the name of the variable. See $declare.
Use this function to append data to an existing variable.
variable - the name of the variable. See $declare.
Example below will create a new variable, then append the vulnerability title to it.
Use this function to assign a new value for a variable.
variable - the name of the variable. See $declare.
Example below will create a new variable that counts all affected assets for every vulnerability, then prints the count along with the vulnerability name. It uses $assign to reset the counter for every new vulnerability.
Example below will create a new Dictionary variable that counts all affected assets for every vulnerability, then prints the count along with the vulnerability name.
Use this function to retrieve the value for a variable.
variable - the name of the variable. Supports:
variables - see variables
dynamic variables - used when the variable name is not known ahead of time (in the template). For example:
{$declare[SomeVariable]["Ninja"]}
{$value["$(SomeVariable)"]} will translate to {$value[Ninja]} where "Ninja" is the value of the variable "SomeVariable" and only known at runtime.
scope - data contained within the JSON file. See scope
Example below will create a new variable that counts all affected assets for every vulnerability, then prints the count along with the vulnerability name. It resets the counter for each new vulnerability.
Use this function to retrieve the value for a Dictionary. $keys will return the data from a Dictionary in the following format:
Therefore you can access the key using this[0] and value using this[1]. See example below.
The example below uses a Dictionary to store the name of every unique vulnerability along with its total number of affected assets, then prints the data using this function.
You can also use {$keys[this]} on any object, which will return each key/value pair in the object as an array - {this[0]} for the key, and {this[1]} for the value.
Use this function to sort the data within a variable.
key - JSON object key. Omit this value if sorting a string array (just keep colon)
asc - sort data in ascending order
desc - sort data in descending order
To observe the variables available for sorting - use the $help procedure.
Use this function to check if a value exists or does not exist (excludes) within a variable.
To check if data exists:
To check if data does not exist (excludes):
The following example creates a unique list of affected asset names, then prints the list.
The following example checks if a Dictionary "Evidence" has a key "POC" which includes a given POC.
Use this function to include a comment in your template which will not show in your report.
You can include a comment in two separate ways:
Use this function to print diagnostic information to your ReportGen browser console.
Insert this function in the relevant section in your template to se information about variables and scope.
You can add your own labels to help with debugging when you have multiple help functions used in your template.
{$help[some label][var]} - prints diagnostic information for variables
{$help[some label][scope]} - prints diagnostic information for scope
Use this function to create a hyperlink.
Example below will create a new hyperlink based on scope.
Example below will create a new hyperlink based on manually entered in values.
Example below will create a new hyperlink based on the values from other variables.
Use this function to print the current index of the loop you are iterating over:
Use this function to check if you are in the first iteration of a loop.
For example, if you want to add a section heading BEFORE printing the vulnerability titles:
Another example is if you want to check if it IS NOT the first iteration of a loop:
Use this function to check if you are in the last iteration of a loop.
For example, if you want to add an extra line break after every vulnerability title except for the last:
Another example is if you want to check if it IS the last iteration of a loop:
Use this function to perform an equality comparison for a variable against a value.
variable - the name of the variable. See $declare.
Example below will create a new variable that will be used to print a section heading AFFECTED ASSETS: before listing all of the affected assets for every vulnerability. After printing the heading, it assigns the variable to false to prevent it displaying on the next affected asset. After looping through and listing every affected asset, it re-assigns the variable to true so it is printed for the next vulnerability.
Use this function to perform an equality comparison for a variable against a value using a Regular Expression test. Performs a global, case insensitive test.
variable - the name of the variable. See $declare.
value - the value which is used to perform the comparison against this variable. Supports:
Regular Expression - /.../
Use this function to perform a 'less than' comparison for a variable against a number or date.
variable - the name of the variable. See $declare.
Example below will create a new variable that will be used to count all affected assets for every vulnerability, and if there are less than 5 affected assets on a vulnerability - it will print There is less than 5 affected assets for this vulnerability. It resets the counter to 0 after looping on each vulnerability so it is ready for the next vulnerability.
Use this function to perform a 'less than or equal' comparison for a variable against a number.
variable - the name of the variable. See $declare.
Example below will create a new variable that will be used to count all affected assets for every vulnerability, and if there are less than 5 affected assets on a vulnerability - it will print There is 5 or less affected assets for this vulnerability. It resets the counter to 0 after looping on each vulnerability so it is ready for the next vulnerability.
Use this function to perform a 'greater than' comparison for a variable against a number.
variable - the name of the variable. See $declare.
Example below will create a new variable that will be used to count all affected assets for every vulnerability, and if there are more than 5 affected assets on a vulnerability - it will print There are more than 5 affected assets for this vulnerability. It resets the counter to 0 after looping on each vulnerability so it is ready for the next vulnerability.
Use this function to perform a 'greater than or equal' comparison for a variable against a number.
variable - the name of the variable. See $declare.
Example below will create a new variable that will be used to count all affected assets for every vulnerability, and if there are 5 or more affected assets on a vulnerability - it will print There are 5 or more affected assets for this vulnerability. It resets the counter to 0 after looping on each vulnerability so it is ready for the next vulnerability.
Variables can be declared using the $declare function.
Once a variable has been declared, it can be used in other functions as follows:
"$(variable)"
For example, you can declare a new variable with the value of a different variable as follows:
Or you can compare variables again each other:
Functions support passing scope as a value.
Scope is a path/reference to a key within the JSON data structure used by ReportGen.
Scope uses a 'relative path' format, meaning you can traverse up or down the JSON data structure to get to the data you need.
Scope can be accessed as follows:
"%(pathToScopeItem)"
For reference on what to use as pathToScopeItem - please see examples listed below.
!IMPORTANT: Before using scope, we recommend you to first get comfortable with JSON data structures. This will make it easier for you to understand how to access the data you need.
To access the scope you can use the following $help procedure within your template:
Place this function within the area of your template where you would like to see more details on the available scope.
After that, save your template and then open the ReportGen tool and open the browser console.
Run your report and notice that additional diagnostic information relating to your scope is printed in the console.
Example:
In the example above, we are printing the value of the asset name using the $value function.
Because we are calling this function within the affected_assets loop - the immediate scope available is any JSON object keys/values that exist within affected_assets object, for example 'asset' which is the asset name.
Therefore we can access the asset name using "%(asset)".
If you wanted to access the JSON object (affected_asset) instead of the name of the asset, you can use the following:
In the example above, we are printing the value of the vulnerability priority using the $value function.
Because we are calling this function within the affected_assets loop and the data we need - the priority of the vulnerability - is one-level above in the vulnerability JSON object, we will need to traverse up the scope path to the vulnerability object. We can do this by using ../ syntax which will go up a level within the JSON data structure.
Once we are at the vulnerability level, we can access the 'priority' JSON object key. The result is using "%(../priority)" to get the priority.
If you wanted to access the JSON object for the parent (vulnerability) instead of the priority, you can use the following:
In the example above, we are printing the value of the project name using the $value function.
Because we are calling this function within the affected_assets loop and the data we need - the name of the project - is two-levels above in the project JSON object, we will need to traverse up the scope path to the project object. We can do this by using ../../ syntax which will go up two levels within the JSON data structure.
Once we are at the project level, we can access the 'name' key within the project JSON object. The result is using "%(../../project.name)" to get the project name.
Notice that the project JSON object has a number of different keys such as "name", "code" and "created". You can use dot (.) syntax to traverse down the JSON data structure, in the same way you would in object-oriented programming - for example project.name or project.code.
In the example above, we are printing the value of the project custom field 'out_of_scope' using the $value function.
Because we are calling this function within the affected_assets loop and the data we need - the project custom field 'out_of_scope' - is two-levels above in the projectCustomFields JSON object array, we will need to traverse up the scope path to the projectCustomFields object array. We can do this by using ../../ syntax which will go up two levels within the JSON data structure.
Once we are at the projectCustomFields level, note that this key is an array of objects. Therefore, we cannot use syntax such as projectCustomFields.out_of_scope as out_of_scope is not a key in the projectCustomFields object array.
We will need to instead identify which object in the array has the key we need, then use the index of that object.
From the example above, the out_of_scope object is the second (2nd) index in the array. Because this is a JSON structure, indexes start at 0 and count upwards. Therefore the index we need to use is 1.
The result is using "%(../../projectCustomFields[1].out_of_scope)" to traverse up two (2) levels, select the projectCustomFields object array, select object [1] within the array, then select out_of_scope key.
In the example above, we are printing the total number of assets in the project scope using the $value function.
Because we are calling this function at the root (top) level - we can immediately access the testing_summary object which has the data we need - 'assets' key.
Because assets is a string array, it has a length. Therefore we can refer to that length using a .length() operation.
The result is using "%(testing_summary.assets.length())" to select the 'testing_summary' object, select 'assets' string array, and perform a length operation.
You can combine filters in your functions in two ways:
