API Documentation

class vexipy.Document(*, context: str = 'https://openvex.dev/ns/v0.2.0', id: ~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~vexipy._iri.check_iri)], author: str, role: str | None = None, timestamp: ~datetime.datetime = <factory>, last_updated: ~datetime.datetime | None = None, version: int, tooling: str | None = None, statements: ~typing.Tuple[~vexipy.statement.Statement, ...] = ())

A data structure that groups together one or more VEX statements.

Parameters:

context – The URL linking to the OpenVEX context definition. The URL is structured as https://openvex.dev/ns/v[version], where [version] represents the specific version number, such as v0.2.0. If the version is omitted, it defaults to v0.2.0.
id – The IRI identifying the VEX document.
author – Author is the identifier for the author of the VEX statement. This field should ideally be a machine readable identifier such as an IRI, email address, etc. author MUST be an individual or organization. author identity SHOULD be cryptographically associated with the signature of the VEX document or other exchange mechanism.
role – role describes the role of the document author.
timestamp – Timestamp defines the time at which the document was issued.
last_updated – Date of last modification to the document.
version – Version is the document version. It must be incremented when any content within the VEX document changes, including any VEX statements included within the VEX document.
tooling – Tooling expresses how the VEX document and contained VEX statements were generated. It may specify tools or automated processes used in the document or statement generation.
statements – The collection of statements to contain within the document.

append_statements(statement: Statement) → Document

Returns a new Document with the given statement appended to the statements tuple.

Parameters:: statement (Statement) – Statement to append.
Returns:: Updated Document instance.
Return type:: Document

classmethod convert_to_tuple(v: Iterable[Statement]) → Tuple[Statement, ...]

Converts an iterable of statements to a tuple.

Parameters:: v – Iterable of Statement objects.
Returns:: Tuple of Statement objects or None if not provided.

extend_statements(statements: Iterable[Statement]) → Document

Returns a new Document with the given collection of statements extended to the statements tuple.

Parameters:: statements – Iterable of Statement objects to extend.
Returns:: Updated Document instance.

classmethod from_json(json_string: str) → Document

Creates a Document instance from a JSON string.

Parameters:: json_string – JSON string to deserialize.
Returns:: Document instance.

serialize_timestamp(value: datetime) → str

Serializes the timestamp to ISO 8601 string format.

Parameters:: value – The datetime value to serialize.
Returns:: ISO 8601 formatted string.

to_json(**kwargs: Any) → str

Serializes the Document model to a JSON string.

Parameters:: kwargs – Additional keyword arguments for serialization.
Returns:: JSON string representation of the model.

update(**kwargs: Any) → Document

Returns a new Document instance with updated fields and timestamp.

If a timestamp is not provided in kwargs, the new document instance will default to the current UTC time.

Parameters:: kwargs – Fields to update in the model.
Returns:: Updated Document instance.

class vexipy.Product(*, id: Annotated[str, AfterValidator(func=check_iri)] | None = None, identifiers: Dict[str, str] | None = None, hashes: Dict[str, str] | None = None, subcomponents: Tuple[Subcomponent, ...] | None = None)

A logical unit representing a piece of software. The concept is intentionally broad to allow for a wide variety of use cases but generally speaking, anything that can be described in a Software Bill of Materials (SBOM) can be thought of as a product.

Parameters:

id – Optional IRI identifying the component to make it externally referenceable.
identifiers – A map of software identifiers where the key is the type and the value the identifier. OpenVEX favors the use of purl but others are recognized.
hashes – Map of cryptographic hashes of the component. The key is the algorithm name based on the Hash Function Textual Names from IANA.
subcomponents – Tuple of subcomponents included in the component.

append_subcomponents(subcomponent: Subcomponent) → Product

Returns a new Component with the given subcomponent appended.

Parameters:: subcomponent – Subcomponent to append.
Returns:: Updated Component instance.

classmethod convert_to_tuple(v: Iterable[Subcomponent] | None) → Tuple[Subcomponent, ...] | None

Converts an iterable of subcomponents to a tuple.

Parameters:: v – Iterable of Subcomponent objects or None.
Returns:: Tuple of Subcomponent objects or None if not provided.

extend_subcomponents(subcomponents: Iterable[Subcomponent]) → Product

Returns a new Component with the given collection of subcomponents extended to the subcomponents tuple.

Parameters:: subcomponents – Iterable of Subcomponent objects to extend.
Returns:: Updated Component instance.

class vexipy.Statement(*, id: ~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~vexipy._iri.check_iri)] | None = None, version: int | None = None, vulnerability: ~vexipy.vulnerability.Vulnerability, timestamp: ~datetime.datetime | None = <factory>, last_updated: ~datetime.datetime | None = None, products: ~typing.Tuple[~vexipy.component.Product, ...] | None = None, status: ~vexipy.status.StatusLabel, supplier: str | None = None, status_notes: str | None = None, justification: ~vexipy.status.StatusJustification | None = None, impact_statement: str | None = None, action_statement: str | None = None, action_statement_timestamp: ~datetime.datetime | None = None)

A statement is an assertion made by the document’s author about the impact a vulnerability has on one or more software products. The statement has three key components that are valid at a point in time: status, a vulnerability, and the product to which these apply.

Parameters:

id – Optional IRI identifying the statement to make it externally referenceable.
version – Optional integer representing the statement’s version number. Defaults to zero, required when incremented.
vulnerability – A struct identifying the vulnerability.
timestamp – Timestamp is the time at which the information expressed in the Statement was known to be true. Cascades down from the document, see Inheritance.
last_updated – Timestamp when the statement was last updated.
products – List of product structs that the statement applies to.
status – A VEX statement MUST provide the status of the vulnerabilities with respect to the products and components listed in the statement. status MUST be one of the labels defined by VEX (see Status), some of which have further options and requirements.
supplier – Supplier of the product or subcomponent.
status_notes – A statement MAY convey information about how status was determined and MAY reference other VEX information.
justification – For statements conveying a not_affected status, a VEX statement MUST include either a status justification or an impact_statement informing why the product is not affected by the vulnerability. Justifications are fixed labels defined by VEX.
impact_statement – For statements conveying a not_affected status, a VEX statement MUST include either a status justification or an impact_statement informing why the product is not affected by the vulnerability. An impact statement is a free form text containing a description of why the vulnerability cannot be exploited. This field is not intended to be machine readable so its use is highly discouraged for automated systems.
action_statement – For a statement with “affected” status, a VEX statement MUST include a statement that SHOULD describe actions to remediate or mitigate the vulnerability.
action_statement_timestamp – The timestamp when the action statement was issued.

check_action_statement() → Statement

Validates that an affected status includes an action statement.

Raises:: ValueError – If action statement is missing for a vulnerability with an affected status.
Returns:: The validated Statement instance.

check_review_fields() → Statement

Validates that a not-affected status includes a justification or impact statement. Warns if only an impact statement is provided without justification.

Raises:: ValueError – If status is “NOT_AFFECTED” and both justification and impact statement are not provided.
Returns:: The validated Statement instance.

classmethod convert_to_tuple(v: Iterable[Product] | None) → Tuple[Product, ...] | None

Converts an iterable of Components to a tuple of Components.

Parameters:: v – Iterable of Components or None.
Returns:: Tuple of objects or None if not provided.

classmethod from_json(json_string: str) → Statement

Creates a Statement instance from a JSON string.

Parameters:: json_string – JSON string to deserialize.
Returns:: Statement instance.

serialize_timestamp(value: datetime) → str

Serializes the timestamp to ISO 8601 string format.

Parameters:: value – The datetime value to serialize.
Returns:: ISO 8601 formatted string.

to_json(**kwargs: Any) → str

Serializes the Statement model to a JSON string.

Parameters:: kwargs – Additional keyword arguments for serialization.
Returns:: JSON string representation of the model.

update(**kwargs: Any) → Statement

Returns a new Statement instance with updated fields and timestamp.

If a timestamp is not provided in kwargs, the new document instance will default to the current UTC time.

Parameters:: kwargs – Fields to update in the model.
Returns:: Updated Statement instance.

class vexipy.StatusJustification(value)

Enum representing justifications for a vulnerability status.

Members:: COMPONENT_NOT_PRESENT: The component is not present in the product. VULNERABLE_CODE_NOT_PRESENT: The vulnerable code is not present in the component. VULNERABLE_CODE_NOT_IN_EXECUTE_PATH: The vulnerable code is not in the execution path. VULNERABLE_CODE_CANNOT_BE_CONTROLLED_BY_ADVERSARY: The vulnerable code cannot be controlled by an adversary. INLINE_MITIGATIONS_ALREADY_EXIST: Inline mitigations already exist for the vulnerability.

class vexipy.StatusLabel(value)

Enum representing the status of a vulnerability for a component.

Members:: NOT_AFFECTED: The component is not affected by the vulnerability. AFFECTED: The component is affected by the vulnerability. FIXED: The vulnerability has been fixed in the component. UNDER_INVESTIGATION: The vulnerability is under investigation.

class vexipy.Subcomponent(*, id: Annotated[str, AfterValidator(func=check_iri)] | None = None, identifiers: Dict[str, str] | None = None, hashes: Dict[str, str] | None = None)

A logical unit representing a piece of software. The concept is intentionally broad to allow for a wide variety of use cases but generally speaking, anything that can be described in a Software Bill of Materials (SBOM) can be thought of as a product.

Parameters:

id – Optional IRI identifying the component to make it externally referenceable.
identifiers – A map of software identifiers where the key is the type and the value the identifier. OpenVEX favors the use of purl but others are recognized.
hashes – Map of cryptographic hashes of the component. The key is the algorithm name based on the Hash Function Textual Names from IANA.

classmethod from_json(json_string: str) → Subcomponent

Creates a Subcomponent instance from a JSON string.

Parameters:: json_string – JSON string to deserialize.
Returns:: Subcomponent instance.

classmethod hashes_valid(value: mappingproxy[str, str] | None) → mappingproxy[str, str] | None

Validates that all hash keys are valid.

Parameters:: value – Read-only mapping of hashes.
Raises:: ValueError – If invalid hash keys are present.
Returns:: Validated mapping or None.

classmethod identifiers_valid(value: mappingproxy[str, str] | None) → mappingproxy[str, str] | None

Validates that all identifier keys are valid.

Parameters:: value – Read-only mapping of identifiers.
Raises:: ValueError – If invalid identifier keys are present.
Returns:: Validated mapping or None.

classmethod make_data_readonly(v: Mapping[str, str] | None) → mappingproxy[str, str] | None

Converts a mapping to a read-only MappingProxyType.

Parameters:: v – Mapping of strings or None.
Returns:: Read-only mapping or None if not provided.

to_json(**kwargs: Any) → str

Serializes the Subcomponent model to a JSON string.

Parameters:: kwargs – Additional keyword arguments for serialization.
Returns:: JSON string representation of the model.

update(**kwargs: Any) → Product

Returns a new Component instance with updated fields.

Parameters:: kwargs – Fields to update in the model.
Returns:: Updated Component instance.

class vexipy.Vulnerability(*, id: Annotated[str, AfterValidator(func=check_iri)] | None = None, name: str, description: str | None = None, aliases: Tuple[str, ...] | None = None)

Represents a vulnerability with optional aliases and description.

Parameters:

id – The unique identifier for the vulnerability (in IRI form).
name – The name of the vulnerability.
description – A description of the vulnerability.
aliases – Aliases for the vulnerability.

classmethod convert_to_tuple(v: Iterable[str] | None) → Tuple[str, ...] | None

Converts an optional iterable parameter to a tuple.

Parameters:: v – Iterable of strings or None.
Returns:: Tuple of aliases or None if not provided.

classmethod from_json(json_string: str) → Vulnerability

Creates a Vulnerability instance from a JSON string.

Parameters:: json_string – JSON string to deserialize.
Returns:: Vulnerability instance.

to_json(**kwargs: Any) → str

Serializes the Vulnerability model to a JSON string.

Parameters:: kwargs – Additional keyword arguments for serialization with Pydantic’s model_dump_json.
Returns:: JSON string representation of the model.

update(**kwargs: Any) → Vulnerability

Returns a new Vulnerability instance with updated fields.

Parameters:: kwargs – Fields to update in the model.
Returns:: Updated Vulnerability instance.