macaron.vsa package

Submodules

macaron.vsa.vsa module

VSA schema and generation.

class macaron.vsa.vsa.Vsa

Bases: TypedDict

The Macaron Verification Summary Attestation.

For reference, see:

SLSA.
in-toto.

payloadType: str: The payload type. Following in-toto, this is always application/vnd.in-toto+json.

payload: str: The payload of the VSA, base64 encoded.

class macaron.vsa.vsa.VsaStatement

Bases: TypedDict

The Statement layer of a Macaron VSA.

For reference, see:

in-toto Statement layer specification: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md.

subject: list[dict]: Subjects of the VSA. Each entry is a software component being verified by Macaron. Note: In the current version of Macaron, this field only contains one single software component, identified by a PackageURL.

predicateType: str: Identifier for the type of the Predicate. For Macaron-generated VSAs, this is always https://slsa.dev/verification_summary/v1.

predicate: VsaPredicate: The Predicate of the attestation, providing information about the verification.

class macaron.vsa.vsa.VsaPredicate

Bases: TypedDict

The ‘predicate’ field in the Statement layer of a Macaron VSA.

For reference, see:

in-toto Predicate layer specification: https://github.com/in-toto/attestation/blob/main/spec/v1/predicate.md.
SLSA VSA predicate schema: https://slsa.dev/spec/v1.0/verification_summary#schema.

verifier: Verifier: Identity of the verifier, as a tool carrying out the verification.

timeVerified: str: The timestamp when the verification occurred. The field is a Timestamp.

resourceUri: str: URI that identifies the resource associated with the software component being verified. This field is a ResourceURI. Currently, this has the same value as the subject of the VSA, i.e. the PURL of the software component being verified against.

policy: Policy: The policy that the subject software component was verified against. This field is a ResourceDescriptor.

verificationResult: VerificationResult: The verification result.

verifiedLevels: list: According to SLSA, this field “indicates the highest level of each track verified for the artifact (and not its dependencies), or FAILED if policy verification failed”. We currently leave this list empty.

class macaron.vsa.vsa.Verifier

Bases: TypedDict

The ‘verifier’ field within the Macaron VSA predicate field.

This field provides the identity of the verifier, as well as the versioning details of its components.

id: str: The identity of the verifier as a TypeURI.

version: dict[str, str]: A mapping from components of the verifier and their corresponding versions. At the moment, this field only includes Macaron itself.

class macaron.vsa.vsa.Policy

Bases: TypedDict

The ‘policy’ field within the Macaron VSA predicate field.

This field provides information about the policy used for verification.

content: str: The Souffle Datalog code defining the policy in plain text.

class macaron.vsa.vsa.VerificationResult(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Verification result, which is either ‘PASSED’ or ‘FAILED’.

FAILED = 'FAILED'

PASSED = 'PASSED'

macaron.vsa.vsa.get_common_purl_from_artifact_purls(purl_strs)

Get a single common PackageURL given some artifact PackageURLs.

Assumption: A package may have more than one artifact. If each artifact is identified by a PackageURL, these PackageURLs still share the type, namespace, name, and version values. The common PackageURL contains these values.

Return type:: str | None

macaron.vsa.vsa.create_vsa_statement(passed_components, policy_content)

Construct the Statement layer of the VSA.

Parameters:

subject_purl (str) – The PURL (string) of the subject of the VSA. This identifies the unique software component that the policy applies to.
policy_content (str) – The Souffle policy code defining the policy.
verification_result (VerificationResult) – The verification result of the subject.

Returns:

A Statement layer of the VSA.

Return type:

VsaStatement

macaron.vsa.vsa.get_components_passing_policy(policy_result)

Get the verification result in the form of PURLs and component ids of software artifacts passing the policy.

This is currently done by reading the facts of two relations: component_violates_policy, and component_satisfies_policy from the result of the policy engine.

The result of this function depends on the policy engine result.

If there exist any software component failing the policy, this function returns None.

When all software components in the result pass the policy, if there exist multiple occurrences of the same PURL, this function returns the latest occurrence, which is the one with the highest component id, taking advantage of component ids being auto-incremented.

If there is no PURL in the result, i.e. the policy applies to no software component in the database, this function also returns None.

Parameters:: policy_result (dict) – The result of the policy engine, including two relations: component_violates_policy, and component_satisfies_policy.
Returns:: A dictionary of software components passing the policy, or None if there is any component failing the policy or if there is no software component in the policy engine result. Each key is a PackageURL of the software component, and each value is the corresponding component id of that component.
Return type:: dict[str, int] | None

macaron.vsa.vsa.generate_vsa(policy_content, policy_result)

Generate a VSA, if appropriate, based on the result of the policy engine.

Parameters:

policy_content (str) – The Souffle policy code defining the policy.
policy_result (dict) – The result of the policy engine.

Returns:

The VSA, or None if generating a VSA is not appropriate according to the policy engine result.

Return type:

Vsa | None