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.
Source code in sereto/models/finding.py 
127
128
129
130
131
132
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
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.
    """

    risk: Risk | None = None
    findings: list[str] = Field(min_length=1)
    locators: list[LocatorModel] = Field(default_factory=list)

    @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 
140
141
142
143
144
145
146
147
148
149
150
@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 
152
153
154
155
156
157
158
@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 
32
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
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 
58
59
60
61
62
63
64
65
66
@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 
161
162
163
164
165
166
167
168
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
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

Representation of the frontmatter of a sub-finding included in project.

Attributes:

Name Type Description
name str

The name of the sub-finding.
risk Risk

The risk level of the sub-finding.
category TypeCategoryName

From which category the sub-finding originates.
variables dict[str, Any]

A dictionary of variables used in the sub-finding.
template_path str | None

Relative path to the finding in templates directory.
locators list[LocatorModel]

A list of locators used to find the sub-finding.
Source code in sereto/models/finding.py 
 69
 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
class SubFindingFrontmatterModel(SeretoBaseModel):
    """Representation of the frontmatter of a sub-finding included in project.

    Attributes:
        name: The name of the sub-finding.
        risk: The risk level of the sub-finding.
        category: From which category the sub-finding originates.
        variables: A dictionary of variables used in the sub-finding.
        template_path: Relative path to the finding in templates directory.
        locators: A list of locators used to find the sub-finding.
    """

    name: str
    risk: Risk
    category: TypeCategoryName
    variables: dict[str, Any] = {}
    template_path: str | None = None
    locators: list[LocatorModel] = Field(default_factory=list)

    @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."""
        output = dedent(f"""\
            name = "{self.name}"
            risk = "{self.risk.value}"
            category = "{self.category.lower()}"
        """)

        if self.template_path:
            output += f'template_path = "{self.template_path}"\n'

        output += f"locators = {dump_locators_to_toml(self.locators)}"
        output += "\n\n[variables]\n"
        output += "\n".join(f"{k} = {v!r}" for k, v in self.variables.items())
        return output + "\n"

    @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 
88
89
90
91
92
93
94
95
96
97
98
@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.

Source code in sereto/models/finding.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def dumps_toml(self) -> str:
    """Dump the model to a TOML-formatted string."""
    output = dedent(f"""\
        name = "{self.name}"
        risk = "{self.risk.value}"
        category = "{self.category.lower()}"
    """)

    if self.template_path:
        output += f'template_path = "{self.template_path}"\n'

    output += f"locators = {dump_locators_to_toml(self.locators)}"
    output += "\n\n[variables]\n"
    output += "\n".join(f"{k} = {v!r}" for k, v in self.variables.items())
    return output + "\n"

load_from(path) classmethod

Load FindingFrontmatterModel from a file.

Source code in sereto/models/finding.py 
116
117
118
119
120
121
122
123
124
@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 
17
18
19
20
21
22
23
24
25
26
27
28
29
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.