From e524e8fa834d31dbe7a8aa2ffd7a6aa088a899ad Mon Sep 17 00:00:00 2001 From: Paul Hewlett Date: Mon, 21 Mar 2022 10:55:12 +0000 Subject: [PATCH] Minor fixes Problem: Some incorrect documentation. Solution: Fix minor faults in documentation and update sbom release example code. Signed-off-by: User Name --- README.rst | 22 +++++++---- docs/requirements.txt | 28 +++++++------- docs/runner/events_create.rst | 7 ++-- examples/sbom_release.py | 70 ++++++++++++++++++----------------- requirements-dev.txt | 2 + requirements.txt | 4 ++ 6 files changed, 76 insertions(+), 57 deletions(-) diff --git a/README.rst b/README.rst index f92cc17b..76bba144 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,4 @@ + .. _readme: Jitsuin Archivist Client @@ -13,16 +14,23 @@ Installation Use standard python pip utility: -.. code-block:: bash +.. code:: bash python3 -m pip install jitsuin-archivist +If your version of python3 is too old an error of this type or similar will be emitted: + +.. note:: + + ERROR: Could not find a version that satisfies the requirement jitsuin-archivist (from versions: none) + ERROR: No matching distribution found for jitsuiin-archivist + Example ============= One can then use the examples code to create assets (see examples directory): -.. code-block:: python +.. code:: python """Create an asset given url to Archivist and user Token. @@ -138,7 +146,7 @@ or json file. Python ------ -.. code-block:: python +.. code:: python from logging import getLogger from pyaml_env import parse_config @@ -182,7 +190,7 @@ Command Line This functionality is also available from the command line: -.. code-block:: shell +.. code:: shell $ archivist_runner -h @@ -196,7 +204,7 @@ To invoke this command: Execute: -.. code-block:: shell +.. code:: shell $ archivist_runner \ -u https://app.rkvst.io \ @@ -225,7 +233,7 @@ asset or event is confirmed before returning. 'true' which archivist will treat as a boolesn. -.. code-block:: yaml +.. code:: yaml --- # Demonstration of applying a Richness compliance policy to an asset that undergoes @@ -294,7 +302,7 @@ by using dictionary configuration as described here: https://docs.python.org/3/l A recommended minimum configuration would be: -.. code-block:: python +.. code:: python import logging diff --git a/docs/requirements.txt b/docs/requirements.txt index d5302195..8c3770b0 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,18 +1,20 @@ # # this is used for pushing to github pages # -# for development, the correct packages are installed in the builder image. -# -# Duplicate of stanza in builder/Dockerfile-builder +# Duplicate of stanza in ~/requirements-dev.txt. # Make changes in both places -# -sphinx==3.5.4 -sphinx-rtd-theme==0.5.2 +sphinx~=4.3 +sphinx-rtd-theme~=1.0.0 -backoff==1.10.0 -certifi==2020.12.5 -flatten-dict==0.3.0 -iso8601==0.1.13 -requests==2.22.0 -requests-toolbelt==0.9.1 -rfc3339==6.2 +# Duplicate of stanza in ~/requirements.txt. +# Make changes in both places +backoff~=1.11 +certifi +flatten-dict~=0.3 +iso8601~=0.1 +Jinja2~=3.0 +pyaml-env~=1.1 +requests~=2.22 +requests-toolbelt~=0.9 +rfc3339~=6.2 +xmltodict~=0.12.0 diff --git a/docs/runner/events_create.rst b/docs/runner/events_create.rst index 87334a01..ed7dca43 100644 --- a/docs/runner/events_create.rst +++ b/docs/runner/events_create.rst @@ -74,7 +74,7 @@ An example when releasing a software package as an sbom: confirm: true event_attributes: arc_description: ACME Corporation Detector SAAS Released YYYYMMDD.1 - arc_display_type: sbom release + arc_display_type: Software Package Release sbom: filename: functests/test_resources/sbom/gen1.xml content_type: text/xml @@ -100,10 +100,9 @@ An example when releasing a software package as an sbom attachment: confirm: true event_attributes: arc_description: ACME Corporation Detector SAAS Released YYYYMMDD.1 - arc_display_type: sbom release + arc_display_type: Software Package Release attachments: - filename: functests/test_resources/sbom/gen1.xml content_type: text/xml display_name: ACME Generation1 SBOM - type: SBOM_RELEASE - + type: Software Package Release diff --git a/examples/sbom_release.py b/examples/sbom_release.py index 94a0e901..0ac2b9ac 100644 --- a/examples/sbom_release.py +++ b/examples/sbom_release.py @@ -1,3 +1,5 @@ +#!/usr/bin/python3 + """ Test sbom release process """ @@ -16,19 +18,20 @@ filterwarnings("ignore", message="Unverified HTTPS request") +ASSET_NAME = "RKVST SaaS Software Package" + -def sbom_release(arch, release, sbom_filename): # XXX instead of filename may be URL? +def sbom_release(arch, release, sbom_filename): """ Test sbom release process - Because we use create_if_not_exists the software package asset and attachments will persist. + Because we use create_if_not_exists the software package asset will persist. Args: release (str): release string of form YYYYMMDD.N + sbom_filename (str): name of sbom file """ - ASSET_NAME = "RKVST SAAS Software Package" - print(f"##[debug]Creating software package {ASSET_NAME}") asset, existed = arch.assets.create_if_not_exists( @@ -45,25 +48,15 @@ def sbom_release(arch, release, sbom_filename): # XXX instead of filename may b "attributes": { "arc_display_name": ASSET_NAME, "arc_display_type": SBOM_PACKAGE, - "arc_description": "Software Package for RKVST SAAS", - "acme_sbom_license": "www.gnu.org/licenses/gpl.txt", # XXX - "acme_proprietary_secret": "For your eyes only", # XXX + "arc_description": "Software Package for RKVST SaaS", }, - # the attachment should be the RKVST logo? - change accordingly XXX - "attachments": [ - { - "url": ( - "https://raw.githubusercontent.com/jitsuin-inc/archivist-python/" - "main/functests/test_resources/telephone.jpg", - ), - "content_type": "image/jpg", - }, - ], }, confirm=True, ) - print("asset", json_dumps(asset, indent=4)) - print("existed", existed) + print("##[debug]Asset:\n", json_dumps(asset, indent=4)) + print("##[debug]Existed:", existed) + + print("") # Releasing an SBOM event = arch.events.create_from_data( @@ -72,12 +65,12 @@ def sbom_release(arch, release, sbom_filename): # XXX instead of filename may b "operation": "Record", "behaviour": "RecordEvidence", "event_attributes": { - "arc_description": f"Jitsuin Inc RKVST SAAS Released {release}", + "arc_description": f"Jitsuin Inc RKVST SAAS Release {release}", "arc_display_type": SBOM_RELEASE, }, "attachments": [ { - "filename": f"{sbom_filename}", # XXX maybe change to URL? + "filename": f"{sbom_filename}", "content_type": "text/xml", "display_name": f"RKVST {release} SBOM", "type": SBOM_RELEASE, @@ -86,28 +79,39 @@ def sbom_release(arch, release, sbom_filename): # XXX instead of filename may b }, confirm=True, ) - print("release", json_dumps(event, indent=4)) - event = arch.events.list( - asset_id=asset["identity"], - props={"confirmation_status": "CONFIRMED"}, - attrs={"arc_display_type": SBOM_RELEASE}, - ) + print("##[debug]Release:\n", json_dumps(event, indent=4)) + + return (asset, event) def main(): """ main entry point """ + + rkvst_url = getenv("RKVST_URL") + auth = get_auth( - auth_token_filename=getenv("TEST_AUTHTOKEN_FILENAME"), - client_id=getenv("TEST_CLIENT_ID"), - client_secret_filename=getenv("TEST_CLIENT_SECRET_FILENAME"), + auth_token_filename=getenv("AUTHTOKEN_FILENAME"), + client_id=getenv("CLIENT_ID"), + client_secret_filename=getenv("CLIENT_SECRET_FILENAME"), ) - arch = Archivist(getenv("TEST_ARCHIVIST"), auth, verify=False, max_time=300) + arch = Archivist(rkvst_url, auth, verify=False, max_time=300) + + asset, event = sbom_release( + arch, getenv("BUILD_BUILDNUMBER"), getenv("SBOM_FILEPATH") + ) + + rkvst_path = "archivist/v2" + + asset_url = f"{rkvst_url}/{rkvst_path}/{asset['identity']}" + event_url = f"{rkvst_url}/{rkvst_path}/{event['identity']}" - # XXX: change these accordingly - filename may be a url? - sbom_release(arch, "YYYYMMDD.N", "tmp/rkvst_saas_YYYYMMDD.N") + print(f"##vso[task.setvariable variable=RKVST_ASSET_URL]{asset_url}") + print(f"##vso[task.setvariable variable=RKVST_EVENT_URL]{event_url}") + print(f"##[debug]Asset url: {asset_url}") + print(f"##[debug]Event url: {event_url}") if __name__ == "__main__": diff --git a/requirements-dev.txt b/requirements-dev.txt index 4b0f091a..91f453a6 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -12,5 +12,7 @@ pylint~=2.6 twine~=3.4 # documentation +# the file docs/requirements.txt +# must be kept in sync with this file. sphinx~=4.3 sphinx-rtd-theme~=1.0.0 diff --git a/requirements.txt b/requirements.txt index 5cf8ab3b..5b1c218d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,7 @@ +# +# for the published wheel - the file docs/requirements.txt +# must be kept in sync with this file. +# backoff~=1.11 certifi flatten-dict~=0.3