Building blocks

This page provides an overview of the building blocks for creating your custom templates. See Templating - Jinja2 for details on how the variables can be included in the templates.

This is so far valid for the report.tex.j2 and sow.tex.j2 templates.

Variables

• c: The VersionConfig object for the current version of the project.
• config: The full Config object (most of the time, you should use c instead).
• version: The version of the project.
• project_path: Path object to the project directory.

Useful methods and properties of the VersionConfig

The following methods can be invoked from the c object.

Example usage:

c.filter_targets(category=["dast", "sast"], name="^foo")]
c.filter_dates(type="pentest_ongoing", start="01-Jan-2024", end="31-Jan-2024")
c.filter_people(type="author", email="@foo.bar$")

sereto.config.VersionConfig.filter_targets(category=None, name=None, inverse=False)

Filter targets based on specified criteria.

The regular expressions support the syntax of Python's re module.

Parameters:

Name	Type	Description	Default
category	str | Iterable[str] | None	The category of the target. Can be a single category, a list of categories, or None.	None
name	str | None	Regular expression to match the name of the target.	None
inverse	bool	If True, return the inverse of the usual results.	False

Returns:

Type	Description
list[TargetModel]	A list of targets matching the criteria.

Source code in sereto/config.py

@validate_call
def filter_targets(
    self,
    category: str | Iterable[str] | None = None,
    name: str | None = None,
    inverse: bool = False,
) -> list[TargetModel]:
    """Filter targets based on specified criteria.

    The regular expressions support the syntax of Python's `re` module.

    Args:
        category: The category of the target. Can be a single category, a list of categories, or None.
        name: Regular expression to match the name of the target.
        inverse: If True, return the inverse of the usual results.

    Returns:
        A list of targets matching the criteria.
    """
    if isinstance(category, str):
        category = [category]

    filtered_targets = [
        t
        for t in self.targets
        if (category is None or t.data.category in category) and (name is None or re.search(name, t.data.name))
    ]

    if inverse:
        return [t.data for t in self.targets if t not in filtered_targets]
    return [t.data for t in filtered_targets]

sereto.config.VersionConfig.filter_dates(type=None, start=None, end=None, *, first_date=False, last_date=False, inverse=False)

filter_dates(type: str | DateType | Iterable[str] | Iterable[DateType] | None = ..., start: str | SeretoDate | None = ..., end: str | SeretoDate | None = ..., *, first_date: Literal[True], last_date: Literal[False] = False, inverse: bool = False) -> SeretoDate | None

filter_dates(type: str | DateType | Iterable[str] | Iterable[DateType] | None = ..., start: str | SeretoDate | None = ..., end: str | SeretoDate | None = ..., *, first_date: Literal[False] = False, last_date: Literal[True], inverse: bool = False) -> SeretoDate | None

filter_dates(type: str | DateType | Iterable[str] | Iterable[DateType] | None = ..., start: str | SeretoDate | None = ..., end: str | SeretoDate | None = ..., *, first_date: Literal[False], last_date: Literal[False], inverse: bool = False) -> list[Date]

Filter dates based on specified criteria.

The start and end dates are inclusive. For date ranges, a date is considered matching if it completely overlaps with the specified range.

Parameters:

Name	Type	Description	Default
type	str | DateType | Iterable[str] | Iterable[DateType] | None	The type of the date. Can be DateType, a list of DateTypes, or None.	None
start	str | SeretoDate | None	Only dates on or after this date will be included.	None
end	str | SeretoDate | None	Only dates on or before this date will be included.	None
first_date	bool	If True, return the earliest date matching the criteria. Even for date ranges, only the start date is considered. The type returned is SeretoDate or None.	False
last_date	bool	If True, return the latest date matching the criteria. Even for date ranges, only the end date is considered. The type returned is SeretoDate or None.	False
inverse	bool	If True, return the inverse of the usual results.	False

Returns:

Type	Description
list[Date] | SeretoDate | None	For first_date or last_date = True, returns SeretoDate or None. Otherwise, returns a list[Date].

Source code in sereto/config.py

def filter_dates(
    self,
    type: str | DateType | Iterable[str] | Iterable[DateType] | None = None,
    start: str | SeretoDate | None = None,
    end: str | SeretoDate | None = None,
    *,
    first_date: bool = False,
    last_date: bool = False,
    inverse: bool = False,
) -> list[Date] | SeretoDate | None:
    """Filter dates based on specified criteria.

    The start and end dates are inclusive. For date ranges, a date is considered matching if it completely overlaps
    with the specified range.

    Args:
        type: The type of the date. Can be `DateType`, a list of `DateType`s, or None.
        start: Only dates on or after this date will be included.
        end: Only dates on or before this date will be included.
        first_date: If True, return the earliest date matching the criteria. Even for date ranges, only the start
            date  is considered. The type returned is `SeretoDate` or None.
        last_date: If True, return the latest date matching the criteria. Even for date ranges, only the end date
            is considered. The type returned is `SeretoDate` or None.
        inverse: If True, return the inverse of the usual results.

    Returns:
        For first_date or last_date = True, returns SeretoDate or None. Otherwise, returns a list[Date].
    """
    # Check for invalid parameter combinations
    if first_date and last_date:
        raise SeretoValueError("cannot specify both first_date and last_date")
    if (first_date or last_date) and inverse:
        raise SeretoValueError("cannot specify inverse with first_date or last_date")

    match type:
        case str():
            type = [DateType(type)]
        case Iterable():
            type = [DateType(t) for t in type]
        case None:
            pass

    if isinstance(start, str):
        start = SeretoDate.from_str(start)
    if isinstance(end, str):
        end = SeretoDate.from_str(end)

    filtered_dates = [
        d
        for d in self.dates
        if (type is None or d.type in type)
        and (
            start is None
            or (isinstance(d.date, SeretoDate) and d.date >= start)
            or (isinstance(d.date, DateRange) and d.date.start >= start)
        )
        and (
            end is None
            or (isinstance(d.date, SeretoDate) and d.date <= end)
            or (isinstance(d.date, DateRange) and d.date.end <= end)
        )
    ]

    if first_date:
        single_dates = [d.date.start if isinstance(d.date, DateRange) else d.date for d in filtered_dates]
        return min(single_dates, default=None)

    if last_date:
        single_dates = [d.date.end if isinstance(d.date, DateRange) else d.date for d in filtered_dates]
        return max(single_dates, default=None)

    if inverse:
        return [d for d in self.dates if d not in filtered_dates]
    return filtered_dates

sereto.config.VersionConfig.filter_people(type=None, name=None, business_unit=None, email=None, role=None, inverse=False)

Filter people based on specified criteria.

The regular expressions support the syntax of Python's re module.

Parameters:

Name	Type	Description	Default
type	str | PersonType | Iterable[str] | Iterable[PersonType] | None	The type of the person. Can be a single type, a list of types, or None.	None
name	str | None	Regular expression to match the name of the person.	None
business_unit	str | None	Regular expression to match the business unit of the person.	None
email	str | None	Regular expression to match the email of the person.	None
role	str | None	Regular expression to match the role of the person.	None
inverse	bool	If True, return the inverse of the usual results.	False

Returns:

Type	Description
list[Person]	A list of people matching the criteria.

Source code in sereto/config.py

@validate_call
def filter_people(
    self,
    type: str | PersonType | Iterable[str] | Iterable[PersonType] | None = None,
    name: str | None = None,
    business_unit: str | None = None,
    email: str | None = None,
    role: str | None = None,
    inverse: bool = False,
) -> list[Person]:
    """Filter people based on specified criteria.

    The regular expressions support the syntax of Python's `re` module.

    Args:
        type: The type of the person. Can be a single type, a list of types, or None.
        name: Regular expression to match the name of the person.
        business_unit: Regular expression to match the business unit of the person.
        email: Regular expression to match the email of the person.
        role: Regular expression to match the role of the person.
        inverse: If True, return the inverse of the usual results.

    Returns:
        A list of people matching the criteria.
    """
    match type:
        case str():
            type = [PersonType(type)]
        case Iterable():
            type = [PersonType(t) for t in type]
        case None:
            pass

    filtered_people = [
        p
        for p in self.people
        if (type is None or p.type in type)
        and (name is None or (p.name is not None and re.search(name, p.name)))
        and (business_unit is None or (p.business_unit is not None and re.search(business_unit, p.business_unit)))
        and (email is None or (p.email is not None and re.search(email, p.email)))
        and (role is None or (p.role is not None and re.search(role, p.role)))
    ]

    if inverse:
        return [p for p in self.people if p not in filtered_people]
    return filtered_people

sereto.config.VersionConfig.select_target(categories, selector=None)

Source code in sereto/config.py

@validate_call
def select_target(
    self,
    categories: Iterable[str],
    selector: int | str | None = None,
) -> Target:
    # only single target present
    if selector is None:
        if len(self.targets) != 1:
            raise SeretoValueError(
                f"cannot select target; no selector provided and there are {len(self.targets)} targets present"
            )
        return self.targets[0]

    # by index
    if isinstance(selector, int) or selector.isnumeric():
        ix = selector - 1 if isinstance(selector, int) else int(selector) - 1
        if not (0 <= ix <= len(self.targets) - 1):
            raise SeretoValueError("target index out of range")

        return self.targets[ix]

    # by unique category
    if selector in categories:
        filtered_targets = [t for t in self.targets if t.data.category == selector]
        match len(filtered_targets):
            case 0:
                raise SeretoValueError(f"category {selector!r} does not contain any target")
            case 1:
                return filtered_targets[0]
            case _:
                raise SeretoValueError(
                    f"category {selector!r} contains multiple targets, use unique name when querying"
                )

    # by uname
    filtered_targets = [t for t in self.targets if t.uname == selector]
    if len(filtered_targets) != 1:
        raise SeretoValueError(f"target with uname {selector!r} not found")
    return filtered_targets[0]

There are also the following properties:

sereto.config.VersionConfig.report_sent_date property

Get the report sent date

It has fallback to the review date and last date of the pentest ongoing.

sereto.config.VersionConfig.total_open_risks property

Get the total number of open risks across all risk levels.

sereto.config.VersionConfig.sum_risks property

Get the sum of risks across all targets.