bdba-client 0.13.0__py3-none-any.whl

bdba/client.py

@@ -0,0 +1,669 @@
+# SPDX-FileCopyrightText: 2024 SAP SE or an SAP affiliate company and Gardener contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import collections.abc
+import datetime
+import enum
+import functools
+import logging
+import time
+import traceback
+import urllib.parse
+import urllib3.util.retry
+
+import cachecontrol
+import dacite
+import dateutil.parser
+import requests
+
+import bdba.limits
+import bdba.model as bm
+import bdba.util as bu
+
+
+logger = logging.getLogger(__name__)
+
+
+def kebab_to_snake_case_keys(d: dict[str, dict | list | str | int]) -> dict:
+    """
+    Highly opinionated function to convert the BDBA analysis result so that it can be processed by
+    our BDBA model classes. In that, it converts kebab-cased keys recursively into snake_case (as
+    expected by our model classes).
+    """
+    result = {}
+
+    for key, value in d.items():
+        if isinstance(value, dict):
+            value = kebab_to_snake_case_keys(value)
+        elif isinstance(value, list):
+            value = [kebab_to_snake_case_keys(v) if isinstance(v, dict) else v for v in value]
+
+        if not isinstance(key, str):
+            raise TypeError(f'{key=} is expected to be of type "str", but is type "{type(key)}"')
+
+        result[key.replace('-', '_')] = value
+
+    return result
+
+
+class BDBAApiRoutes:
+    """
+    calculates API routes (URLs) for a subset of the URL endpoints exposed by
+    "BDBA"
+
+    Not intended to be instantiated by users of this module
+    """
+
+    def __init__(self, base_url):
+        if base_url is None:
+            raise ValueError(f'{base_url=} must not be None')
+        self._base_url = base_url
+        self._api_url = functools.partial(self._url, 'api')
+        self._rest_url = functools.partial(self._url, 'rest')
+
+    def _url(self, *parts):
+        return bu.urljoin(self._base_url, *parts)
+
+    def apps(self, group_id=None, custom_attribs={}):
+        url = self._api_url('apps')
+        if group_id is not None:
+            url = bu.urljoin(url, str(group_id))
+
+        search_query = ' '.join(['meta:' + str(k) + '=' + str(v) for k, v in custom_attribs.items()])
+        if search_query:
+            url += '?' + urllib.parse.urlencode({'q': search_query})
+
+        return url
+
+    def login(self):
+        return self._url('login') + '/'
+
+    def pdf_report(self, product_id: int):
+        return self._url('products', str(product_id), 'pdf-report')
+
+    def groups(self):
+        return self._api_url('groups')
+
+    def upload(self, file_name):
+        return self._api_url('upload', urllib.parse.quote_plus(file_name))
+
+    def product(self, product_id: int):
+        return self._api_url('product', str(product_id))
+
+    def product_custom_data(self, product_id: int):
+        return self._api_url('product', str(product_id), 'custom-data')
+
+    def rescan(self, product_id):
+        return self._api_url('product', str(product_id), 'rescan')
+
+    def triage(self):
+        return self._api_url('triage', 'vulnerability/')
+
+    def version_override(self):
+        return self._api_url('versionoverride/')
+
+    def api_key(self):
+        return self._api_url('key/')
+
+    def export_product(
+        self,
+        product_id: int | str,
+        sbom_format: bm.BdbaSbomFormat = bm.BdbaSbomFormat.BDIO,
+    ) -> str:
+        url = self._api_url('product', str(product_id), f'?format={sbom_format}')
+        if bm.BdbaSbomFormat(sbom_format) is bm.BdbaSbomFormat.CYCLONEDX:
+            url = f'{url.rstrip("/")}/json'
+        return url
+
+    # ---- "rest" routes (undocumented API)
+
+    def scans(self, product_id: int):
+        return self._rest_url('scans', str(product_id)) + '/'
+
+
+def check_http_code(function):
+    """
+    a decorator that will check on `requests.Response` instances returned by HTTP requests
+    issued with `requests`. In case the response code indicates an error, a warning is logged
+    and a `requests.HTTPError` is raised.
+
+    @param: the function to wrap; should be `requests.<http-verb>`, e.g. requests.get
+    @raises: `requests.HTTPError` if response's status code indicates an error
+    """
+
+    @functools.wraps(function)
+    def http_checker(*args, **kwargs):
+        result = function(*args, **kwargs)
+        if not result.ok:
+            url = kwargs.get('url', None)
+            logger.warning(f'{result.status_code=} - {result.content=}: {url=}')
+        result.raise_for_status()
+        return result
+
+    return http_checker
+
+
+class LoggingRetry(urllib3.util.retry.Retry):
+    def __init__(
+        self,
+        **kwargs,
+    ):
+        defaults = dict(
+            total=3,
+            connect=3,
+            read=3,
+            status=3,
+            redirect=False,
+            status_forcelist=(429, 500, 502, 503, 504),
+            raise_on_status=False,
+            respect_retry_after_header=True,
+            backoff_factor=1.0,
+        )
+
+        super().__init__(**(defaults | kwargs))
+
+    def increment(
+        self,
+        method=None,
+        url=None,
+        response=None,
+        error=None,
+        _pool=None,
+        _stacktrace=None,
+    ):
+        # super().increment will either raise an exception indicating that no retry is to
+        # be performed or return a new, modified instance of this class
+        retry = super().increment(method, url, response, error, _pool, _stacktrace)
+        # Use the Retry history to determine the number of retries.
+        num_retries = len(self.history) if self.history else 0
+        logger.warning(
+            f'{method=} {url=} returned {response=} {error=} {num_retries=} - trying again',
+        )
+        return retry
+
+
+def _mount_default_adapter(
+    session: requests.Session,
+    connection_pool_cache_size=32,  # requests-library default
+    max_pool_size=32,  # requests-library default
+    retry_cfg: urllib3.util.retry.Retry = LoggingRetry(),
+):
+    http_adapter = cachecontrol.CacheControlAdapter(
+        max_retries=retry_cfg,
+        pool_connections=connection_pool_cache_size,
+        pool_maxsize=max_pool_size,
+    )
+
+    session.mount('http://', http_adapter)
+    session.mount('https://', http_adapter)
+
+    return session
+
+
+class BDBAApi:
+    def __init__(
+        self,
+        api_routes: BDBAApiRoutes,
+        token: str,
+        tls_verify: bool = True,
+    ):
+        self._routes = api_routes
+        self._token = token
+        self._tls_verify = tls_verify
+        self._session = requests.Session()
+        _mount_default_adapter(
+            session=self._session,
+        )
+
+    @check_http_code
+    def _request(self, method, *args, **kwargs):
+        if 'headers' in kwargs:
+            headers = kwargs['headers']
+            del kwargs['headers']
+        else:
+            headers = {}
+
+        headers['Authorization'] = f'Bearer {self._token}'
+
+        try:
+            timeout = kwargs.pop('timeout')
+        except KeyError:
+            timeout = (4, 121)
+
+        return functools.partial(
+            method,
+            verify=self._tls_verify,
+            cookies=None,
+            headers=headers,
+            timeout=timeout,
+        )(*args, **kwargs)
+
+    @check_http_code
+    def _get(self, *args, **kwargs):
+        return self._request(self._session.get, *args, **kwargs)
+
+    @check_http_code
+    def _post(self, *args, **kwargs):
+        return self._request(self._session.post, *args, **kwargs)
+
+    @check_http_code
+    def _put(self, *args, **kwargs):
+        return self._request(self._session.put, *args, **kwargs)
+
+    @check_http_code
+    def _delete(self, *args, **kwargs):
+        return self._request(self._session.delete, *args, **kwargs)
+
+    @check_http_code
+    def _patch(self, *args, **kwargs):
+        return self._request(self._session.patch, *args, **kwargs)
+
+    def _metadata_dict(self, custom_attributes):
+        """
+        replaces "invalid" underscore characters (setting metadata fails silently if
+        those are present). Note: dash characters are implcitly converted to underscore
+        by BDBAA. Also, translates `None` to an empty string as header fields with
+        `None` are going to be silently ignored while an empty string is used to remove
+        a metadata attribute
+        """
+        return {
+            'META-' + str(k).replace('_', '-'): v if v is not None else ''
+            for k, v in custom_attributes.items()
+        }
+
+    def upload(
+        self,
+        application_name: str,
+        group_id: str,
+        data: collections.abc.Generator[bytes, None, None],
+        replace_id: int = None,
+        custom_attribs={},
+    ) -> bm.Result:
+        if bdba.limits.fits(application_name, limit=bdba.limits.file_name):
+            name = application_name
+        else:
+            # BDBA raises HTTP 500 error in case the _file_ (!= app) name exceeds 241 characters
+            name = bdba.limits.trim(application_name, limit=bdba.limits.file_name)
+            logger.warning(
+                f'{application_name=} exceeds character limit of {bdba.limits.file_name} and was '
+                f'truncated to {name}',
+            )
+
+        url = self._routes.upload(file_name=name)
+
+        headers = {'Group': str(group_id)}
+        if replace_id:
+            headers['Replace'] = str(replace_id)
+        headers.update(self._metadata_dict(custom_attribs))
+
+        result = (
+            self._put(
+                url=url,
+                headers=headers,
+                data=data,
+            )
+            .json()
+            .get('results', {})
+        )
+
+        return dacite.from_dict(
+            data_class=bm.Result,
+            data=kebab_to_snake_case_keys(result),
+        )
+
+    def delete_product(self, product_id: int):
+        url = self._routes.product(product_id=product_id)
+
+        try:
+            self._delete(
+                url=url,
+            )
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 404:
+                # if the http status is 404 it is fine because the product should be deleted anyway
+                logger.info(f'deletion of product {product_id} failed because it does not exist')
+                return
+            raise e
+
+    def scan_result(self, product_id: int) -> bm.AnalysisResult:
+        url = self._routes.product(product_id=product_id)
+
+        result = (
+            self._get(
+                url=url,
+            )
+            .json()
+            .get('results', {})
+        )
+
+        return dacite.from_dict(
+            data_class=bm.AnalysisResult,
+            data=kebab_to_snake_case_keys(result),
+            config=dacite.Config(
+                cast=[enum.Enum],
+            ),
+        )
+
+    def wait_for_scan_result(
+        self,
+        product_id: int,
+        polling_interval_seconds: int = 60,
+    ) -> bm.AnalysisResult:
+        def scan_finished():
+            result = self.scan_result(product_id=product_id)
+            if result.status is bm.ProcessingStatus.READY:
+                return result
+            elif result.status is bm.ProcessingStatus.FAILED:
+                # failed scans do not contain package infos, raise to prevent side effects
+                raise RuntimeError(f'scan failed; {result.fail_reason=}')
+            else:
+                return False
+
+        result = scan_finished()
+        while not result:
+            # keep polling until result is ready
+            time.sleep(polling_interval_seconds)
+            result = scan_finished()
+        return result
+
+    def list_apps(self, group_id=None, custom_attribs={}) -> list[bm.Product]:
+        # BDBA checks for substring match only.
+        def full_match(analysis_result_attribs):
+            if not custom_attribs:
+                return True
+            for attrib in custom_attribs:
+                # attrib is guaranteed to be a key in analysis_result_attribs at this point
+                if analysis_result_attribs[attrib] != custom_attribs[attrib]:
+                    return False
+            return True
+
+        def _iter_matching_products(url: str):
+            res = self._get(url=url)
+            res.raise_for_status()
+            res = res.json()
+            products: list[dict] = res['products']
+
+            for product in products:
+                if not full_match(product.get('custom_data')):
+                    continue
+                yield dacite.from_dict(
+                    data_class=bm.Product,
+                    data=product,
+                )
+
+            if next_page_url := res.get('next'):
+                yield from _iter_matching_products(url=next_page_url)
+
+        url = self._routes.apps(group_id=group_id, custom_attribs=custom_attribs)
+        return list(_iter_matching_products(url=url))
+
+    def set_metadata(self, product_id: int, custom_attribs: dict):
+        url = self._routes.product_custom_data(product_id=product_id)
+        headers = self._metadata_dict(custom_attribs)
+
+        result = self._post(
+            url=url,
+            headers=headers,
+        )
+        return result.json()
+
+    def metadata(self, product_id: int):
+        url = self._routes.product_custom_data(product_id=product_id)
+
+        result = self._post(
+            url=url,
+            headers={},
+        )
+        return result.json().get('custom_data', {})
+
+    def get_triages(
+        self,
+        component_name: str,
+        component_version: str,
+        vuln_id: str,
+        scope: str,
+        description: str,
+    ):
+        url = self._routes.triage()
+        result = self._get(
+            url=url,
+            params={
+                'component': component_name,
+                'vuln_id': vuln_id,
+                'scope': scope,
+                'version': component_version,
+                'description': description,
+            },
+        ).json()['triages']
+
+        return [
+            dacite.from_dict(
+                data_class=bm.Triage,
+                data=triage_dict,
+                config=dacite.Config(
+                    type_hooks={
+                        datetime.datetime: dateutil.parser.isoparse,
+                    },
+                    cast=[enum.Enum],
+                ),
+            )
+            for triage_dict in result
+        ]
+
+    def add_triage(
+        self,
+        triage: bm.Triage,
+        scope: bm.TriageScope = None,
+        product_id=None,
+        group_id=None,
+        component_version=None,
+    ):
+        """
+        adds an existing BDBA triage to a specified target. The existing triage is usually
+        retrieved from an already uploaded product (which is represented by `AnalysisResult`).
+        This method is offered to support "transporting" existing triages.
+
+        Note that - depending on the effective target scope, the `product_id`, `group_id` formal
+        parameters are either required or forbidden.
+
+        Note that BDBA will only accept triages for matching (component, vulnerabilities,
+        version) tuples. In particular, triages for different component versions will be silently
+        ignored. Explicitly pass `component_version` of target BDBA app (/product) to force
+        BDBA into accepting the given triage.
+
+        @param triage: the triage to "copy"
+        @param scope: if given, overrides the triage's scope
+        @param product_id: target product_id. required iff scope in FN, FH, R
+        @param group_id: target group_id. required iff scope is G(ROUP)
+        @param component_version: overwrite target component version
+        """
+        # if no scope is set, use the one from passed triage
+        scope = scope if scope else triage.scope
+
+        # depending on the scope, different arguments are required
+        if scope == bm.TriageScope.ACCOUNT_WIDE:
+            pass
+        elif scope in (bm.TriageScope.FILE_NAME, bm.TriageScope.FILE_HASH, bm.TriageScope.RESULT):
+            if product_id is None:
+                raise ValueError(f'{product_id=} must not be None')
+        elif scope == bm.TriageScope.GROUP:
+            if group_id is None:
+                raise ValueError(f'{group_id=} must not be None')
+        else:
+            raise NotImplementedError()
+
+        if not component_version:
+            component_version = triage.version
+
+        # "copy" data from existing triage
+        triage_dict = {
+            'component': triage.component,
+            'version': component_version,
+            'vulns': [triage.vuln_id],
+            'scope': triage.scope.value,
+            'reason': triage.reason,
+            'description': triage.description,
+        }
+
+        if product_id:
+            triage_dict['product_id'] = product_id
+
+        if group_id:
+            triage_dict['group_id'] = group_id
+
+        return self.add_triage_raw(triage_dict=triage_dict)
+
+    def add_triage_raw(self, triage_dict: dict):
+        url = self._routes.triage()
+        try:
+            res = self._put(
+                url=url,
+                json=triage_dict,
+            ).json()
+            return res
+        except requests.exceptions.HTTPError as e:
+            resp: requests.Response = e.response
+            logger.warning(f'{url=} {resp.status_code=} {resp.content=} {triage_dict=}')
+            traceback.print_exc()
+            raise e
+
+    # --- "rest" routes (undocumented API)
+    def set_product_name(self, product_id: int, name: str):
+        url = self._routes.product(product_id)
+
+        if bdba.limits.fits(name, limit=bdba.limits.app_name):
+            product_name = name
+        else:
+            product_name = bdba.limits.trim(name, limit=bdba.limits.app_name)
+            logger.warning(
+                f'{name=} exceeds character limit of {bdba.limits.app_name} and was truncated '
+                f'to {product_name}',
+            )
+
+        self._patch(
+            url=url,
+            json={'name': product_name},
+        )
+
+    def rescan(self, product_id: int):
+        url = self._routes.rescan(product_id)
+        self._post(
+            url=url,
+        )
+
+    def set_component_version(
+        self,
+        component_name: str,
+        component_version: str,
+        objects: list[str],
+        scope: bm.VersionOverrideScope = bm.VersionOverrideScope.APP,
+        app_id: int = None,
+        group_id: int = None,
+    ):
+        """
+        @param component_name: component name as reported by bdba
+        @param component_version: version to set as override
+        @param objects: list of sha1-digests (as reported by BDBA)
+        @param scope: see VersionOverrideScope enum
+        """
+        url = self._routes.version_override()
+
+        override_dict = {
+            'component': component_name,
+            'version': component_version,
+            'objects': objects,
+            'scope': scope.value,
+        }
+
+        if scope is bm.VersionOverrideScope.APP:
+            if not app_id:
+                raise RuntimeError('An App ID is required when overriding versions with App scope.')
+            override_dict['app_scope'] = app_id
+        elif scope is bm.VersionOverrideScope.GROUP:
+            if not group_id:
+                raise RuntimeError(
+                    'A Group ID is required when overriding versions with Group scope.',
+                )
+            override_dict['group_scope'] = group_id
+        else:
+            raise NotImplementedError
+
+        return self._put(
+            url=url,
+            json=[override_dict],
+        ).json()
+
+    def pdf_report(self, product_id: int, cvss_version: bm.CVSSVersion = bm.CVSSVersion.V3):
+        url = self._routes.pdf_report(product_id)
+
+        if cvss_version is bm.CVSSVersion.V2:
+            cvss_version_number = 2
+        elif cvss_version is bm.CVSSVersion.V3:
+            cvss_version_number = 3
+        else:
+            raise NotImplementedError(cvss_version)
+
+        response = self._get(
+            url=url,
+            params={'cvss_version': cvss_version_number},
+        )
+
+        return response.content
+
+    def api_key(self) -> dict:
+        return self._get(url=self._routes.api_key())
+
+    def create_key(
+        self,
+        validity_seconds: int,
+        timeout: int = 60,
+    ) -> dict:
+        return self._post(
+            url=self._routes.api_key(),
+            json={'validity': validity_seconds},
+            timeout=timeout,
+        )
+
+    def bdio_export(
+        self,
+        product_id: int | str,
+    ) -> bm.BDIO:
+        url = self._routes.export_product(product_id)
+        response = self._get(url=url)
+        response.raise_for_status()
+
+        raw_data = response.json()
+        return dacite.from_dict(
+            data_class=bm.BDIO,
+            data=dict(
+                **raw_data,
+                id=raw_data.get('@id'),
+                publisher_version=raw_data.get('publisherVersion'),
+                creation_datetime=raw_data.get('creationDateTime'),
+                entries=raw_data.get('@graph'),
+            ),
+        )
+
+    def export_sbom(
+        self,
+        product_id: int | str,
+        sbom_format: bm.BdbaSbomFormat,
+    ) -> dict | bm.BDIO:
+        url = self._routes.export_product(product_id, sbom_format=sbom_format)
+
+        response = self._get(url=url)
+        response_raw = response.json()
+
+        if sbom_format is bm.BdbaSbomFormat.BDIO:
+            return dacite.from_dict(
+                data_class=bm.BDIO,
+                data=dict(
+                    **response_raw,
+                    id=response_raw.get('@id'),
+                    publisher_version=response_raw.get('publisherVersion'),
+                    creation_datetime=response_raw.get('creationDateTime'),
+                    entries=response_raw.get('@graph'),
+                ),
+            )
+        return response_raw

bdba/limits.py

@@ -0,0 +1,24 @@
+"""
+(character) limits for BDBA-api
+
+limits are either found by trail and error or from the documentation
+"""
+
+app_name = 255
+file_name = 241
+
+
+def fits(
+    value: str,
+    /,
+    limit: int,
+) -> bool:
+    return len(value) <= limit
+
+
+def trim(
+    value: str,
+    /,
+    limit: int,
+) -> str:
+    return value[:limit]

bdba/model.py

@@ -0,0 +1,288 @@
+# SPDX-FileCopyrightText: 2024 SAP SE or an SAP affiliate company and Gardener contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+import collections.abc
+import dataclasses
+import datetime
+import enum
+import json
+import logging
+import typing
+
+import dacite
+import dateutil.parser
+
+import bdba.util as bu
+
+
+logger = logging.getLogger()
+
+
+class VersionOverrideScope(enum.IntEnum):
+    APP = 1
+    GROUP = 2
+    GLOBAL = 3
+
+
+class ProcessingStatus(enum.StrEnum):
+    BUSY = 'B'
+    READY = 'R'
+    FAILED = 'F'
+
+
+class CVSSVersion(enum.StrEnum):
+    V2 = 'CVSSv2'
+    V3 = 'CVSSv3'
+
+
+class TriageScope(enum.StrEnum):
+    ACCOUNT_WIDE = 'CA'
+    FILE_NAME = 'FN'
+    FILE_HASH = 'FH'
+    RESULT = 'R'
+    GROUP = 'G'
+
+
+class ProcessingMode(enum.StrEnum):
+    RESCAN = 'rescan'
+    FORCE_UPLOAD = 'force_upload'
+
+
+@dataclasses.dataclass
+class Product:
+    product_id: int
+    name: str
+    custom_data: dict[str, str] = dataclasses.field(default_factory=dict)
+
+
+@dataclasses.dataclass
+class Triage:
+    id: int
+    vuln_id: str
+    component: str
+    version: str | None
+    scope: TriageScope
+    reason: str
+    description: str | None
+    modified: datetime.datetime
+    user: dict
+
+    def __repr__(self):
+        return (
+            f'{self.__class__.__name__}: {self.id} ({self.component} {self.version}, '
+            f'{self.vuln_id}, Scope: {self.scope})'
+        )
+
+    def __eq__(self, other):
+        if not isinstance(other, Triage):
+            return False
+        if self.vuln_id != other.vuln_id:
+            return False
+        if self.component != other.component:
+            return False
+        if self.description != other.description:
+            return False
+        return True
+
+    def __hash__(self):
+        return hash((self.vuln_id, self.component, self.description))
+
+
+@dataclasses.dataclass
+class Vulnerability:
+    vuln: dict
+    exact: bool | None
+    triage: list[Triage]
+
+    @property
+    def historical(self):
+        return not self.exact
+
+    @property
+    def cve(self) -> str:
+        return self.vuln.get('cve')
+
+    def cve_severity(
+        self,
+        cvss_version: CVSSVersion = CVSSVersion.V3,
+    ) -> float:
+        if cvss_version is CVSSVersion.V3:
+            return float(self.vuln.get('cvss3_score'))
+        elif cvss_version is CVSSVersion.V2:
+            return float(self.vuln.get('cvss'))
+        else:
+            raise ValueError(f'{cvss_version} not supported')
+
+    @property
+    def cvss(self) -> dict | None:
+        # ignore cvss2_vector for now
+        if not (cvss_vector := self.vuln.get('cvss3_vector')):
+            return None
+
+        return cvss_vector
+
+    @property
+    def summary(self) -> str:
+        return self.vuln.get('summary')
+
+    @property
+    def has_triage(self) -> bool:
+        return bool(self.triage)
+
+    @property
+    def triages(self) -> collections.abc.Generator[Triage, None, None]:
+        if not self.has_triage:
+            return
+
+        yield from self.triage
+
+    @property
+    def okay_to_skip(self) -> bool:
+        """
+        Indiacates whether it is okay to not store this vulnerability and the delivery-db but just
+        ignore it. This is the case if the vulnerability
+        - is declared as historical: package in the detected version is not actually affected
+        - has a missing CVSS or severity: the vulnerability mighth still be in dispute upstream
+        """
+        return self.historical or not self.cvss or not self.cve_severity()
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}: {self.cve}'
+
+
+@dataclasses.dataclass
+class License:
+    name: str
+    type: str | None
+    url: str | None
+
+
+@dataclasses.dataclass
+class ExtendedObject:
+    name: str | None
+    sha1: str | None
+    extended_fullpath: list[dict]
+
+
+@dataclasses.dataclass
+class Component:
+    lib: str
+    version: str | None
+    vulns: list[dict] | None
+    license: License | None
+    licenses: dict | None
+    extended_objects: list[ExtendedObject] = dataclasses.field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return self.lib
+
+    @property
+    def vulnerabilities(self) -> collections.abc.Generator[Vulnerability, None, None]:
+        for vuln in self.vulns or []:
+            if vuln['vuln'].get('cve'):
+                yield dacite.from_dict(
+                    data_class=Vulnerability,
+                    data=vuln,
+                    config=dacite.Config(
+                        type_hooks={
+                            datetime.datetime: dateutil.parser.isoparse,
+                        },
+                        cast=[enum.Enum],
+                    ),
+                )
+
+    @property
+    def iter_licenses(self) -> collections.abc.Generator[License, None, None]:
+        """
+        Wrapper to consume package's licenses and prefer those stored in the `licenses` property
+        over the one in the `license` property. Rationale: BDBA is known to always store the
+        greatest license version under `license`, and the "correct" one under `licenses`.
+        """
+        if not self.licenses:
+            if self.license:
+                yield self.license
+            return
+
+        yield from [
+            dacite.from_dict(
+                data_class=License,
+                data=license_raw,
+            )
+            for license_raw in self.licenses.get('licenses')
+        ]
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}: {self.name} {self.version or "version not detected"}'
+
+
+@dataclasses.dataclass
+class Result:
+    product_id: int
+    report_url: str
+    filename: str | None
+    stale: bool | None
+    rescan_possible: bool | None
+
+    @property
+    def base_url(self) -> str:
+        parsed_url = bu.urlparse(self.report_url)
+        return f'{parsed_url.scheme}://{parsed_url.netloc}'
+
+    @property
+    def display_name(self) -> str:
+        return self.filename or '<None>'
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}: {self.display_name} ({self.product_id})'
+
+
+@dataclasses.dataclass
+class AnalysisResult(Result):
+    group_id: int
+    status: ProcessingStatus
+    name: str | None
+    fail_reason: str | None
+    components: list[Component] = dataclasses.field(default_factory=list)
+    custom_data: dict[str, str] = dataclasses.field(default_factory=dict)
+    binary_bytes: int | None = None
+    scanned_bytes: int | None = None
+
+
+@dataclasses.dataclass
+class BDIO:
+    id: str
+    name: str
+    publisher: str
+    publisher_version: str
+    entries: list[dict[str, typing.Any]]
+
+    def as_blackduck_bytes(self) -> bytes:
+        return json.dumps(
+            {
+                '@id': self.id,
+                'name': self.name,
+                'publisher': self.publisher,
+                'publisherVersion': self.publisher_version,
+                '@graph': self.entries,
+            },
+            indent=2,
+        ).encode('utf-8')
+
+
+#############################################################################
+## upload result model
+
+
+class UploadStatus(enum.IntEnum):
+    SKIPPED = 1
+    PENDING = 2
+    DONE = 4
+
+
+class BdbaSbomFormat(enum.StrEnum):
+    CYCLONEDX = 'cyclonedx'
+    SPDX = 'spdx'
+    BDIO = 'bdio'

bdba/util.py

@@ -0,0 +1,22 @@
+import urllib.parse
+
+
+def urljoin(*parts):
+    if len(parts) == 1:
+        return parts[0]
+    first = parts[0]
+    last = parts[-1]
+    middle = parts[1:-1]
+
+    first = first.rstrip('/')
+    middle = list(map(lambda s: s.strip('/'), middle))
+    last = last.lstrip('/')
+
+    return '/'.join([first] + middle + [last])
+
+
+def urlparse(url: str) -> urllib.parse.ParseResult:
+    if '://' not in url:
+        url = f'x://{url}'
+
+    return urllib.parse.urlparse(url)

bdba_client-0.13.0.dist-info/LICENSE

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

bdba_client-0.13.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.1
+Name: bdba-client
+Version: 0.13.0
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: cachecontrol
+Requires-Dist: dacite
+Requires-Dist: python-dateutil
+Requires-Dist: requests
+

bdba_client-0.13.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+bdba/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bdba/client.py,sha256=-lMuuNcVdYmAa4cxgwEYti6KORjjB4zLa_T6Q1vTEU8,21554
+bdba/limits.py,sha256=yJ30hR0LGoAYkdpjL9N9ZQPxT4gTjFWMZr5m4vl4288,321
+bdba/model.py,sha256=BLJ39x9vg1Ro5DJzzX0-9F6zOVG0lc67g3dasNx766E,7161
+bdba/util.py,sha256=kG1OIHR6H5EAnIw7ZO3cTf1DLsfB5oM1jSKsnDWh6l4,465
+bdba_client-0.13.0.dist-info/LICENSE,sha256=B05uMshqTA74s-0ltyHKI6yoPfJ3zYgQbvcXfDVGFf8,10280
+bdba_client-0.13.0.dist-info/METADATA,sha256=80uCHMpRG0YdadqeKgBxIzF2ip5G9v2sHA9dRExuZ7Q,208
+bdba_client-0.13.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+bdba_client-0.13.0.dist-info/top_level.txt,sha256=EAfeoUT6W8sCNbjXMFLIGgbKNzkFzSswnLgodqNNOxA,5
+bdba_client-0.13.0.dist-info/RECORD,,

bdba_client-0.13.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bdba_client-0.13.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bdba