Templates

Templates folder

When installing eburger as a python package, the default templates folder is within the path of the package. Exact path is printed when running eburger on a target.

To set a custom templates folder, run eburger -t my_templates_folder/. eburger will then try to load all yaml files within that folder.

Adding a template

If you feel like contributing a template to the community, either for making the blockchain safer, improving your online presence and resume, or for learning and fun, we'd love to see and review your templates.

Another possible use case here, is that you can use the project to create one-time project-specific templates in around 2 minutes - Here's how:

We created a custom GPT specifically designed to generate eburger templates (‼️) see eBurger Templates Generator GPT

Or if you prefer to do it yourself:

1. Open ChatGPT 4 (Will work much better than 3.5)
2. Get a JSON AST of your contract - eburger -f ../ProjectToScan/src/ (output at .eburger/<your-project-and-timestamp>.json
3. Upload or paste (if not that large) the JSON AST of the contract to the ChatGPT chat
4. In the same chat session also paste an existing YAML template from this repo, see under templates/
5. In the same chat session, put this prompt Please understand the YAML structure and apply the same logic to create a new template that will find <WHATEVER YOU CURRENTLY DESIRE, AS TECHNICAL AS POSSIBLE> at the solidity AST JSON format as provided in the file above. Test code locally and ensure it works and return the new YAML template.

Add the new template to the templates folder and eburger again to inspect the results. Normally some tweaks will be required (which is ideal, without the human factor there's no uniqueness to the template), save the new YAML template under your prefered yaml templates folder (see explanation above) and run eburger with the new template to see the results.

YAML Format

To understand best, let's review the structure of a YAML template:

version: 1.0.5 # minimal eburger version required
name: "Name of the insight to create"
severity: "Medium"
precision: "Medium"
description: "Short description"
impact: "The risk this issue introduces"
action-items:
    - "What to do when raised (e.g. continue reviewing xyz, apply immediate fix abc etc.)"
references:
    - "Knowledge related reference"
reports:
    - "Link to an existing report showcasing the impact of the issue"
vulnerable_contracts:
    - "Link to a vulnerable contract this template triggers an issue for"
python: |
    Raw python code

Python utility variables

Some data is set up for you to use within the template from the start.

ast_data - The JSON AST dictionary representing the contract, iterateable and queryable from within the template.

results - A local array to store eburger-formatted result dicts, these will be later parsed as insights. Results are usually AST nodes where the insights should be marked (e.g. in code editors and so).

project_root - Path to the target project's root directory.

Python utility functions

You can call util functions to perform quick operations within the template. For example:

def get_nodes_by_types(
    node: dict,
    node_types: Union[str, list],
    filter_key: str = None,
    filter_value: str = None,
) -> list:
    """
    Finds nodes of specific types within the given node or AST.

    :param node: The node or AST to search.
    :param node_types: The type(s) of nodes to find.
    :param filter_key: A JSON key to find and filter by.
    :param filter_value: filter_key value to search.
    :return: A list of nodes of the specified types.
    """
    ..

In the template, you can use it like so:

results = []
function_definitions = get_nodes_by_types(ast_data, "FunctionDefinition")
for function_definition in function_definitions:
    ...

To see available functions or add/request new ones refer to template_utils.py