macaron.database package

Submodules

macaron.database.database_manager module

This DatabaseManager module handles the sqlite database connection.

class macaron.database.database_manager.DatabaseManager(db_path, base=<class 'macaron.database.database_manager.ORMBase'>)

Bases: object

This class handles and manages the connection to sqlite database during the session.

__init__(db_path, base=<class 'macaron.database.database_manager.ORMBase'>)

Initialize instance.

Parameters:: db_path (str) – The path to the target database.

create_tables()

Automatically create views for all tables known to _base.metadata.

Creates all explicitly declared tables, and creates views proxying all tables beginning with an underscore.

Return type:: None

Note: this is specifically to allow the tables to be loaded into souffle:: https://souffle-lang.github.io/directives#input-directive

class macaron.database.database_manager.cache_return(function)

Bases: Generic[_T, _P]

The decorator to create a singleton DB session.

__init__(function)

clear()

Remove the cached return value.

Return type:: None

macaron.database.db_custom_types module

This module implements SQLAlchemy type for converting date format to RFC3339 string representation.

class macaron.database.db_custom_types.RFC3339DateTime(*args, **kwargs)

Bases: TypeDecorator

SQLAlchemy column type to serialise datetime objects for SQLite in consistent format matching in-toto.

https://docs.sqlalchemy.org/en/20/core/custom_types.html#store-timezone-aware-timestamps-as-timezone-naive-utc https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#sqlalchemy.dialects.sqlite.DATETIME

impl: alias of String

process_bind_param(value, dialect)

Process when storing a datetime object to the SQLite db.

If the timezone of the serialized datetime object is provided, this function preserves it. Otherwise, if the provided datetime is a naive datetime object then UTC is added.

Return type:: None | str

value: None | datetime.datetime: The value being stored

process_result_value(value, dialect)

Process when loading a datetime object from the SQLite db.

If the deserialized datetime has a timezone then return it, otherwise add UTC as its timezone.

Return type:: None | datetime

value: None | str: The value being loaded

class macaron.database.db_custom_types.DBJsonDict(*args, **kwargs)

Bases: TypeDecorator

SQLAlchemy column type to serialize dictionaries.

impl: alias of JSON

process_bind_param(value, dialect)

Process when storing a dict object to the SQLite db.

Return type:: None | dict

value: None | dict: The value being stored

process_result_value(value, dialect)

Process when loading a dict object from the SQLite db.

Return type:: None | dict

value: None | dict: The value being loaded

macaron.database.table_definitions module

ORM Table definitions used by macaron internally.

The current ERD of Macaron is shown below:

For table associated with a check see the check module.

class macaron.database.table_definitions.Analysis(**kwargs)

Bases: ORMBase

ORM Class for the analysis information.

This information pertains to a single invocation of Macaron.

id: Mapped[int]: The primary key.

analysis_time: Mapped[datetime]: The analysis start time.

macaron_version: Mapped[str]: The current version of Macaron.

component: Mapped[list[Component]]: The one-to-many relationship with software components.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.PackageURLMixin

Bases: object

The SQLAlchemy mixin for Package URLs (PURL).

See https://github.com/package-url/purl-spec

TODO: Use the PackageURLMixin from https://github.com/package-url/packageurl-python once it makes a new release (> 0.11.1).

type: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>: A short code to identify the type of the package.

namespace: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>: Package name prefix, such as Maven groupid.

name: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>: Name of the package.

version: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>: Version of the package.

qualifiers: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>: Extra qualifying data for a package such as the name of an OS.

subpath: Mapped[str] = <sqlalchemy.orm.properties.MappedColumn object>: Extra subpath within a package, relative to the package root.

class macaron.database.table_definitions.Component(purl, analysis, repository)

Bases: PackageURLMixin, ORMBase

ORM class for a software component.

id: Mapped[int]: The primary key.

purl: Mapped[str]: The PURL column is for the benefit of Souffle to make it easy to query based on a PURL string.

analysis_id: Mapped[int]: The foreign key to the analysis table.

analysis: Mapped[Analysis]: The many-to-one relationship with an analysis.

repository: Mapped[Repository]: The one-to-one relationship with a repository.

slsalevel: Mapped[SLSALevel]: The one-to-one relationship with a SLSA level.

slsarequirement: Mapped[list[SLSARequirement]]: The one-to-many relationship with SLSA requirements.

checkresult: Mapped[list[MappedCheckResult]]: The one-to-many relationship with the result table.

checkfacts: Mapped[list[CheckFacts]]: The one-to-many relationship with checks.

provenance: Mapped[list[Provenance]]: The one-to-many relationship with provenances.

dependencies: Mapped[list[Component]]: The bidirectional many-to-many relationship for component dependencies.

provenance_subject: Mapped[ProvenanceSubject | None]: The optional one-to-one relationship with a provenance subject in case this component represents a subject in a provenance.

__init__(purl, analysis, repository)

Instantiate the software component using PURL identifier.

Parameters:

purl (str) – The Package URL identifier.
analysis (Analysis) – The corresponding analysis.
repository (Repository | None) – The corresponding repository.

Raises:

InvalidPURLError – If the PURL provided from the user is invalid.

property report_file_name: str

Return the report file name using the PURL string’s name attribute.

Returns:: The report file name.
Return type:: str

property report_file_purl: str

Return the report file name for this component using the PURL string.

Returns:: The report file name.
Return type:: str

property report_dir_name: str

Return the report directory name for this component using the PURL string.

Returns:: The report directory name.
Return type:: str

name: Mapped[str]: Name of the package.

namespace: Mapped[str]: Package name prefix, such as Maven groupid.

qualifiers: Mapped[str]: Extra qualifying data for a package such as the name of an OS.

subpath: Mapped[str]: Extra subpath within a package, relative to the package root.

type: Mapped[str]: A short code to identify the type of the package.

version: Mapped[str]: Version of the package.

class macaron.database.table_definitions.Repository(files=None, **kwargs)

Bases: ORMBase

ORM Class for a repository.

id: Mapped[int]: The primary key.

component_id: Mapped[int]: The foreign key to the software component.

component: Mapped[Component]: The one-to-one relationship with the software component for this repository.

complete_name: Mapped[str]

full_name: Mapped[str]

remote_path: Mapped[str]: The remote URL path to the repo.

branch_name: Mapped[str | None]: The branch name.

release_tag: Mapped[str]: The release tag.

commit_sha: Mapped[str]: The commit sha.

commit_date: Mapped[str]: The commit date.

fs_path: Mapped[str]: The path to the repo on the file system.

__init__(files=None, **kwargs)

Instantiate the repository and set files.

Parameters:: files (list[str] | None) – The files extracted for this repository.

type: Mapped[str]: The PURL type.

owner: Mapped[str]

github.com/owner/name@commit-sha.

Type:: The PURL namespace, which is the owner in pkg

name: Mapped[str]: The PURL name.

class macaron.database.table_definitions.SLSALevel(**kwargs)

Bases: ORMBase

ORM class for the slsa level of a repository.

component_id: Mapped[int]: The primary key.

slsa_level: Mapped[int]: An integer value showing the SLSA level.

reached: Mapped[bool]: A boolean that shows whether the SLSA level has reached or not.

component: Mapped[Component]: A one-to-one relationship with software components.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.SLSARequirement(**kwargs)

Bases: ORMBase

ORM mapping for SLSA requirements a software component satisfies.

id: Mapped[int]

component_id: Mapped[int]: The software component ID.

requirement_name: Mapped[Enum]: The unique SLSA requirement name.

requirement_short_description: Mapped[str]: The short description of the SLSA requirement.

feedback: Mapped[str]: The justification in the check result for a particular requirement.

component: Mapped[Component]: The many-to-one relationship between SLSA requirements and software components.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.MappedCheckResult(**kwargs)

Bases: ORMBase

ORM class for the result of a check, is automatically added for each check.

id: Mapped[int]: The primary key.

check_id: Mapped[str]: The check identifier, e.g., mcn_build_as_code_1.

passed: Mapped[bool]: Shows whether a check has passed or failed.

component_id: Mapped[int]: The foreign key to the software component.

component: Mapped[Component]: A many-to-one relationship with software components.

checkfacts: Mapped[list[CheckFacts]]: A one-to-many relationship with checks.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.CheckFacts(**kwargs)

Bases: ORMBase

This class allows SQLAlchemy to load elements polymorphically, using joined table inheritance.

All tables for checks must inherit this class, these fields are automatically filled in by the analyzer.

See https://docs.sqlalchemy.org/en/20/orm/inheritance.html#joined-table-inheritance

id: Mapped[int]: The primary key.

confidence: Mapped[float]: The confidence score to estimate the accuracy of the check fact. This value should be in the range [0.0, 1.0] with a lower value depicting a lower confidence. Because some analyses used in checks may use heuristics, the results can be inaccurate in certain cases. We use the confidence score to enable the check designer to assign a confidence estimate. This confidence is stored in the database to be used by the policy. This confidence score is also used to decide which evidence should be shown to the user in the HTML/JSON report.

component_id: Mapped[int]: The foreign key to the software component.

component: Mapped[Component]: A many-to-one relationship with software components.

check_result_id: Mapped[int]: The foreign key to the check result.

check_type: Mapped[str]: The column used as a mapper argument for distinguishing checks in polymorphic inheritance.

checkresult: Mapped[MappedCheckResult]: A many-to-one relationship with check results.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.Provenance(**kwargs)

Bases: ORMBase

ORM class for a provenance document.

id: Mapped[int]: The primary key.

component_id: Mapped[int]: The foreign key to the software component.

component: Mapped[Component]: A many-to-one relationship with software components.

version: Mapped[str]: The SLSA version.

release_commit_sha: Mapped[str]: The release tag commit sha.

release_tag: Mapped[str]: The release tag.

provenance_json: Mapped[str]: The provenance payload content in JSON format.

artifact: Mapped[list[ReleaseArtifact]]: A one-to-many relationship with the release artifacts.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.ReleaseArtifact(**kwargs)

Bases: ORMBase

The ORM class for release artifacts.

id: Mapped[int]: The primary key.

name: Mapped[str]: The name of the artifact.

slsa_verified: Mapped[bool]: The SLSA verification result.

provenance_id: Mapped[int]: The foreign key to the SLSA provenance.

provenance: Mapped[Provenance]: A many-to-one relationship with the SLSA provenance.

digests: Mapped[list[HashDigest]]: The one-to-many relationship with the hash digests for this artifact.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.HashDigest(**kwargs)

Bases: ORMBase

ORM class for artifact digests.

id: Mapped[int]: The primary key.

digest: Mapped[str]: The hash digest value.

digest_algorithm: Mapped[str]: The hash digest algorithm.

artifact_id: Mapped[int]: The foreign key to the release artifact.

artifact: Mapped[ReleaseArtifact]: The many-to-one relationship with artifacts.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class macaron.database.table_definitions.ProvenanceSubject(**kwargs)

Bases: ORMBase

A subject in a provenance that matches the user-provided PackageURL.

This subject may be later populated in VSAs during policy verification.

id: Mapped[int]: The primary key.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

component_id: Mapped[int]: The component id of the provenance subject.

component: Mapped[Component]: The required one-to-one relationship with a component.

sha256: Mapped[str]: The SHA256 hash of the subject.

classmethod from_purl_and_provenance(purl, provenance_payload)

Create a ProvenanceSubject entry if there is a provenance subject matching the PURL.

Parameters:

purl (PackageURL) – The PackageURL identifying the software component being analyzed.
provenance_payload (InTotoPayload) – The provenance payload.

Returns:

A ProvenanceSubject entry with the SHA256 digest of the provenance subject matching the given PURL.

Return type:

Self | None

macaron.database.views module

SQLAlchemy View creation.

https://github.com/sqlalchemy/sqlalchemy/wiki/Views

class macaron.database.views.CreateView(name, selectable)

Bases: ExecutableDDLElement

CreateView.

__init__(name, selectable)

class macaron.database.views.DropView(name)

Bases: ExecutableDDLElement

DropView.

__init__(name)

macaron.database.views.view_exists(ddl, target, bind, tables=None, state=None, **kw)

View exists.

Return type:: bool

macaron.database.views.view_doesnt_exist(ddl, target, bind, tables=None, state=None, **kw)

Not view exists.

Return type:: bool

macaron.database.views.create_view(name, metadata, selectable)

Create a view.

Return type:: TableClause