mainframe.endpoints.report

Attributes

logger
router

Functions

_lookup_package(→ mainframe.models.orm.Scan)	Checks if the package is valid according to our database.
_validate_inspector_url(→ str)	Coalesce inspector_urls from ReportPackageBody and Scan.
_validate_additional_information(body, scan)	Validates the additional_information field.
_validate_pypi(name, version, http_client)
report_package(body, session, auth, httpx_client)	Report a package to PyPI.

Module Contents

mainframe.endpoints.report.logger: structlog.stdlib.BoundLogger

mainframe.endpoints.report.router

mainframe.endpoints.report._lookup_package(name: str, version: str, session: sqlalchemy.orm.Session) → mainframe.models.orm.Scan

Checks if the package is valid according to our database.

Returns:

True if the package exists in the database.

Raises:

HTTPException – 404 Not Found if the name was not found in the database, or the specified name and version was not found in the database. 409 Conflict if another version of the same package has already been reported.

mainframe.endpoints.report._validate_inspector_url(name: str, version: str, body_url: str | None, scan_url: str | None) → str

Coalesce inspector_urls from ReportPackageBody and Scan.

Returns:

The inspector_url for the package.

Raises:

HTTPException – 400 Bad Request if the inspector_url was not passed in body and not found in the database.

mainframe.endpoints.report._validate_additional_information(body: mainframe.models.schemas.ReportPackageBody, scan: mainframe.models.orm.Scan)

Validates the additional_information field.

Returns:

None if body.additional_information is valid.

Raises:

HTTPException – 400 Bad Request if additional_information was required and was not passed

mainframe.endpoints.report._validate_pypi(name: str, version: str, http_client: httpx.Client)

mainframe.endpoints.report.report_package(body: mainframe.models.schemas.ReportPackageBody, session: Annotated[sqlalchemy.orm.Session, Depends(get_db)], auth: Annotated[mainframe.json_web_token.AuthenticationData, Depends(validate_token)], httpx_client: Annotated[httpx.Client, Depends(get_httpx_client)])

Report a package to PyPI.

The optional use_email field can be used to send reports by email. This defaults to False.

There are some restrictions on what packages can be reported. They must: - exist in the database - exist on PyPI - not already be reported

While the inspector_url and additional_information fields are optional in the schema, the API requires you to provide them in certain cases. Some of those are outlined below.

inspector_url and additional_information both must be provided if the package being reported is in a QUEUED or PENDING state. That is, the package has not yet been scanned and therefore has no records for inspector_url or any matched rules

If the package has successfully been scanned (that is, it is in a FINISHED state), and it has been determined to be malicious, then neither inspector_url nor additional_information is required. If the inspector_url is omitted, then it will default to a URL that points to the file with the highest total score.

If the package has successfully been scanned (that is, it is in a FINISHED state), and it has been determined NOT to be malicious (that is, it has no matched rules), then you must provide inspector_url AND additional_information.