Finding

sereto.models.finding

FindingGroupModel

Bases: SeretoBaseModel

Representation of a single finding group from findings.toml.

Attributes:

Name	Type	Description
risks		Explicit risks associated with the finding group for specific versions.
findings	list[str]	The list of sub-findings in the format of their unique name to include in the report.
locators	list[LocatorModel]	A list of locators used to find the finding group.
show_locator_types	list[str]	A list of locator types to return from the FindingGroup.locators() property.

Note

This model allows extra fields (via extra="allow") to support plugin-specific data storage. Plugins should use namespaced keys (e.g., yourplugin_var) to avoid collisions with future core fields.

Source code in sereto/models/finding.py

class FindingGroupModel(SeretoBaseModel, extra="allow"):
    """Representation of a single finding group from `findings.toml`.

    Attributes:
        risks: Explicit risks associated with the finding group for specific versions.
        findings: The list of sub-findings in the format of their unique name to include in the report.
        locators: A list of locators used to find the finding group.
        show_locator_types: A list of locator types to return from the FindingGroup.locators() property.

    Note:
        This model allows extra fields (via `extra="allow"`) to support plugin-specific data storage.
        Plugins should use namespaced keys (e.g., `yourplugin_var`) to avoid collisions with future core fields.
    """

    risk: TypeRiskOptional = None
    findings: list[str] = Field(min_length=1)
    locators: list[LocatorModel] = Field(default_factory=list)
    show_locator_types: list[str] = Field(default_factory=get_locator_types)

    @field_validator("findings", mode="after")
    @classmethod
    def unique_finding_names(cls, findings: list[str]) -> list[str]:
        """Ensure that all finding names are unique."""
        if len(findings) != len(set(findings)):
            raise ValueError("finding names must be unique")
        return findings

unique_finding_names(findings) classmethod

Ensure that all finding names are unique.

Source code in sereto/models/finding.py

@field_validator("findings", mode="after")
@classmethod
def unique_finding_names(cls, findings: list[str]) -> list[str]:
    """Ensure that all finding names are unique."""
    if len(findings) != len(set(findings)):
        raise ValueError("finding names must be unique")
    return findings

FindingTemplateFrontmatterModel

Bases: SeretoBaseModel

Representation of the frontmatter of a finding template.

Attributes:

Name	Type	Description
name	str	The name of the sub-finding.
risk	TypeRisk	The risk level of the sub-finding.
keywords	list[str]	A list of keywords used to search for the sub-finding.
variables	list[VarsMetadataModel]	A list of variables used in the sub-finding.

Source code in sereto/models/finding.py

class FindingTemplateFrontmatterModel(SeretoBaseModel):
    """Representation of the frontmatter of a finding template.

    Attributes:
        name: The name of the sub-finding.
        risk: The risk level of the sub-finding.
        keywords: A list of keywords used to search for the sub-finding.
        variables: A list of variables used in the sub-finding.
    """

    name: str
    risk: TypeRisk
    keywords: list[str] = []
    variables: list[VarsMetadataModel] = []

    @classmethod
    @validate_call
    def load_from(cls, path: Path) -> Self:
        """Load FindingTemplateFrontmatterModel from a file."""
        try:
            metadata, _ = frontmatter.parse(path.read_text(encoding="utf-8"), encoding="utf-8")
            return cls.model_validate(metadata)
        except ValidationError as ex:
            raise SeretoValueError(f"invalid template frontmatter in '{path}'") from ex

load_from(path) classmethod

Load FindingTemplateFrontmatterModel from a file.

Source code in sereto/models/finding.py

@classmethod
@validate_call
def load_from(cls, path: Path) -> Self:
    """Load FindingTemplateFrontmatterModel from a file."""
    try:
        metadata, _ = frontmatter.parse(path.read_text(encoding="utf-8"), encoding="utf-8")
        return cls.model_validate(metadata)
    except ValidationError as ex:
        raise SeretoValueError(f"invalid template frontmatter in '{path}'") from ex

FindingsConfigModel

Bases: RootModel[dict[str, FindingGroupModel]]

Model representing the included findings configuration.

The data itself is expected to be a dict where each key is the name of a finding group and the value is a FindingGroupModel.

Source code in sereto/models/finding.py

class FindingsConfigModel(RootModel[dict[str, FindingGroupModel]]):
    """Model representing the included findings configuration.

    The data itself is expected to be a dict where each key is
    the name of a finding group and the value is a FindingGroupModel.
    """

    root: dict[str, FindingGroupModel]

    @field_validator("root", mode="after")
    @classmethod
    def unique_findings(cls, findings: dict[str, FindingGroupModel]) -> dict[str, FindingGroupModel]:
        all_findings: list[str] = []
        for _, group in findings.items():
            all_findings.extend(group.findings)
        if len(all_findings) != len(set(all_findings)):
            raise ValueError("each sub-finding must be included only once")
        return findings

    @classmethod
    @validate_call
    def load_from(cls, file: FilePath) -> Self:
        try:
            with file.open(mode="rb") as f:
                return cls.model_validate(tomllib.load(f))
        except FileNotFoundError:
            raise SeretoPathError(f"file not found at '{file}'") from None
        except PermissionError:
            raise SeretoPathError(f"permission denied for '{file}'") from None
        except ValueError as e:
            raise SeretoValueError("invalid findings.toml") from e

    def items(self) -> ItemsView[str, FindingGroupModel]:
        return self.root.items()

SubFindingFrontmatterModel

Bases: SeretoBaseModel

Frontmatter metadata for a sub-finding included in a project.

Attributes:

Name	Type	Description
name	str	Sub-finding display name.
risk	TypeRisk	Risk classification of the sub-finding.
category	TypeCategoryName	Category from which the sub-finding originates.
variables	dict[str, Any]	Variable values injected into the sub-finding.
template_path	str | None	Relative path to the sub-finding template file.
locators	list[LocatorModel]	A list of locators used to find the sub-finding.
format	FileFormat	The file format of the sub-finding (defaults to markdown).
reported_on	SeretoDate | None	Date the finding was first reported. Only useful if introduced later.

Source code in sereto/models/finding.py

class SubFindingFrontmatterModel(SeretoBaseModel):
    """Frontmatter metadata for a sub-finding included in a project.

    Attributes:
        name: Sub-finding display name.
        risk: Risk classification of the sub-finding.
        category: Category from which the sub-finding originates.
        variables: Variable values injected into the sub-finding.
        template_path: Relative path to the sub-finding template file.
        locators: A list of locators used to find the sub-finding.
        format: The file format of the sub-finding (defaults to markdown).
        reported_on: Date the finding was first reported. Only useful if introduced later.
    """

    name: str
    risk: TypeRisk
    category: TypeCategoryName
    variables: dict[str, Any] = {}
    template_path: str | None = None
    locators: list[LocatorModel] = Field(default_factory=list)
    format: FileFormat = Field(default=FileFormat.md)
    reported_on: SeretoDate | None = None

    def dumps_toml(self) -> str:
        """Dump the model to a TOML-formatted string using a TOML library."""
        # Prepare the data dict in the desired structure
        data: dict[str, Any] = {
            "name": self.name,
            "risk": self.risk.value,
            "category": self.category.lower(),
            "locators": [locator.model_dump(exclude_none=True) for locator in self.locators],
        }
        if self.template_path:
            data["template_path"] = self.template_path
        if len(self.variables) > 0 and any(v is not None for v in self.variables.values()):
            data["variables"] = {k: v for k, v in self.variables.items() if v is not None}

        # Dump to TOML string
        return toml_dumps(data)

    @classmethod
    @validate_call
    def load_from(cls, path: Path) -> Self:
        """Load FindingFrontmatterModel from a file."""
        try:
            metadata, _ = frontmatter.parse(path.read_text(encoding="utf-8"), encoding="utf-8")
            return cls.model_validate(metadata)
        except ValidationError as ex:
            raise SeretoValueError(f"invalid finding frontmatter in '{path}'") from ex

dumps_toml()

Dump the model to a TOML-formatted string using a TOML library.

Source code in sereto/models/finding.py

def dumps_toml(self) -> str:
    """Dump the model to a TOML-formatted string using a TOML library."""
    # Prepare the data dict in the desired structure
    data: dict[str, Any] = {
        "name": self.name,
        "risk": self.risk.value,
        "category": self.category.lower(),
        "locators": [locator.model_dump(exclude_none=True) for locator in self.locators],
    }
    if self.template_path:
        data["template_path"] = self.template_path
    if len(self.variables) > 0 and any(v is not None for v in self.variables.values()):
        data["variables"] = {k: v for k, v in self.variables.items() if v is not None}

    # Dump to TOML string
    return toml_dumps(data)

load_from(path) classmethod

Load FindingFrontmatterModel from a file.

Source code in sereto/models/finding.py

@classmethod
@validate_call
def load_from(cls, path: Path) -> Self:
    """Load FindingFrontmatterModel from a file."""
    try:
        metadata, _ = frontmatter.parse(path.read_text(encoding="utf-8"), encoding="utf-8")
        return cls.model_validate(metadata)
    except ValidationError as ex:
        raise SeretoValueError(f"invalid finding frontmatter in '{path}'") from ex

VarsMetadataModel

Bases: SeretoBaseModel

Source code in sereto/models/finding.py

class VarsMetadataModel(SeretoBaseModel):
    name: str
    description: str
    required: bool = False
    is_list: bool = Field(False, alias="list")
    type: Literal["string", "integer", "boolean"] = "string"

    @property
    def type_annotation(self) -> str:
        """Get description of the variable type and required state."""
        type_annotation = f"list[{self.type}]" if self.is_list else self.type
        required = "required" if self.required else "optional"
        return f"{type_annotation}, {required}"

type_annotation property

Get description of the variable type and required state.