Skip to content

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.
Source code in sereto/models/finding.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
class FindingGroupModel(SeretoBaseModel):
    """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.
    """

    risk: Risk | None = 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("risk", mode="before")
    @classmethod
    def load_risk(cls, risk: Any) -> Risk | None:
        """Convert risk to correct type."""
        match risk:
            case Risk() | None:
                return risk
            case str():
                return Risk(risk)
            case _:
                raise ValueError("invalid risk type")

    @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

load_risk(risk) classmethod

Convert risk to correct type.

Source code in sereto/models/finding.py 
148
149
150
151
152
153
154
155
156
157
158
@field_validator("risk", mode="before")
@classmethod
def load_risk(cls, risk: Any) -> Risk | None:
    """Convert risk to correct type."""
    match risk:
        case Risk() | None:
            return risk
        case str():
            return Risk(risk)
        case _:
            raise ValueError("invalid risk type")

unique_finding_names(findings) classmethod

Ensure that all finding names are unique.

Source code in sereto/models/finding.py 
160
161
162
163
164
165
166
@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 Risk

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 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
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: Risk
    keywords: list[str] = []
    variables: list[VarsMetadataModel] = []

    @field_validator("risk", mode="before")
    @classmethod
    def convert_risk_type(cls, risk: Any) -> Risk:
        match risk:
            case Risk():
                return risk
            case str():
                return Risk(risk)
            case _:
                raise ValueError("unsupported type for Risk")

    @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")
            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 
59
60
61
62
63
64
65
66
67
@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")
        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 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
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 Risk

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 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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: Risk
    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

    @field_validator("risk", mode="before")
    @classmethod
    def convert_risk_type(cls, risk: Any) -> Risk:
        """Convert risk to Risk enum."""
        match risk:
            case Risk():
                return risk
            case str():
                return Risk(risk)
            case _:
                raise ValueError("unsupported type for Risk")

    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")
            return cls.model_validate(metadata)
        except ValidationError as ex:
            raise SeretoValueError(f"invalid finding frontmatter in '{path}'") from ex

convert_risk_type(risk) classmethod

Convert risk to Risk enum.

Source code in sereto/models/finding.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
@field_validator("risk", mode="before")
@classmethod
def convert_risk_type(cls, risk: Any) -> Risk:
    """Convert risk to Risk enum."""
    match risk:
        case Risk():
            return risk
        case str():
            return Risk(risk)
        case _:
            raise ValueError("unsupported type for Risk")

dumps_toml()

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

Source code in sereto/models/finding.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
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 
122
123
124
125
126
127
128
129
130
@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")
        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 
18
19
20
21
22
23
24
25
26
27
28
29
30
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.