From e433c2f5d8ef3dcf0bca72bfa3e5dab551d04f7d Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Thu, 12 Aug 2021 21:00:54 +0530 Subject: [PATCH] Add doc tests on CI and fix linter errors Signed-off-by: Ayan Sinha Mahapatra --- .github/workflows/docs.yml | 36 +++++++++++++++++++ docs/scripts/doc8_style_check.sh | 0 .../getting-started/docker_installation.rst | 13 +++---- docs/source/getting-started/sources.rst | 2 +- .../source/how-to-guides/add_new_importer.rst | 34 +++++++++--------- 5 files changed, 61 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/docs.yml mode change 100644 => 100755 docs/scripts/doc8_style_check.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..c61e35596 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,36 @@ +name: CI Documentation + +on: [push, pull_request] + +jobs: + build: + runs-on: ubuntu-20.04 + + strategy: + max-parallel: 4 + matrix: + python-version: [3.7] + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + + - name: Give permission to run scripts + run: chmod +x ./docs/scripts/doc8_style_check.sh + + - name: Install Dependencies + working-directory: ./docs + run: pip install -r requirements.txt + + - name: Check Sphinx Documentation build minimally + working-directory: ./docs + run: sphinx-build -E source build + + - name: Check for documentation style errors + working-directory: ./docs + run: ./scripts/doc8_style_check.sh \ No newline at end of file diff --git a/docs/scripts/doc8_style_check.sh b/docs/scripts/doc8_style_check.sh old mode 100644 new mode 100755 diff --git a/docs/source/getting-started/docker_installation.rst b/docs/source/getting-started/docker_installation.rst index 8cc86e2a7..a84aac357 100644 --- a/docs/source/getting-started/docker_installation.rst +++ b/docs/source/getting-started/docker_installation.rst @@ -43,7 +43,8 @@ Run your image as a container At this point, the VulnerableCode app should be running at port ``8000`` on your Docker host. Go to http://localhost:8000/ on a web browser to access the web UI. -Optionally, you can set ``NGINX_PORT`` environment variable in your shell or in the `.env` file to run on a different port than 8000. +Optionally, you can set ``NGINX_PORT`` environment variable in your shell or in the `.env` file +to run on a different port than 8000. .. note:: @@ -58,17 +59,17 @@ Optionally, you can set ``NGINX_PORT`` environment variable in your shell or in .. warning:: Serving VulnerableCode on a network could lead to security issues and there - are several steps that may be needed to secure such a deployment. + are several steps that may be needed to secure such a deployment. Currently, this is not recommendend. Invoke the importers -------------------- -Connect to the Docker container ``bash``. -From here you can access ``manage.py`` and run management commands -to import data as specified in the `Data import <../README.rst#data-import>`_ section and run commands -for the importers from there +Connect to the Docker container ``bash``. +From here you can access ``manage.py`` and run management commands +to import data as specified in the `Data import <../README.rst#data-import>`_ section and +run commands for the importers from there For example: diff --git a/docs/source/getting-started/sources.rst b/docs/source/getting-started/sources.rst index 3ca7bf1e2..3c7acd2e5 100644 --- a/docs/source/getting-started/sources.rst +++ b/docs/source/getting-started/sources.rst @@ -1,4 +1,4 @@ Vulneribility Sources ===================== -.. include:: ../../../SOURCES.rst \ No newline at end of file +.. include:: ../../../SOURCES.rst diff --git a/docs/source/how-to-guides/add_new_importer.rst b/docs/source/how-to-guides/add_new_importer.rst index 78cd55529..96f9f518c 100644 --- a/docs/source/how-to-guides/add_new_importer.rst +++ b/docs/source/how-to-guides/add_new_importer.rst @@ -43,7 +43,7 @@ The Building Blocks A.K.A Prerequisites reference_id: str = "" url: str = "" severities: List[VulnerabilitySeverity] = dataclasses.field(default_factory=list) - + Steps to build an Importer -------------------------- @@ -51,7 +51,7 @@ Steps to build an Importer * **Register an Importer:** To do this go to ``vulnerabilites/importer_yielder.py``, in the ``IMPORTER_REGISTRY`` -list add a dictionary with following data +list add a dictionary with following data .. code:: python @@ -63,7 +63,7 @@ list add a dictionary with following data 'data_source_cfg': {}, } - + **Don't forget to replace and with appropriate strings** @@ -72,7 +72,7 @@ If you know the license of the data you are importing, assign the license field equal to the license of the data in the ``add__importer`` method of the migration script. -* **Create a data source** : +* **Create a data source** : - Go to ``vulnerabilities/importers`` , create a python script, let's call it ``my_importer.py`` @@ -83,25 +83,25 @@ method of the migration script. .. code:: python from typing import Set - + from packageurl import PackageURL import requests - + from vulnerabilities.data_source import Advisory from vulnerabilities.data_source import DataSource - + class ExampleDataSource(DataSource): #This method must be implemented def updated_advisories(self)-> Set[Advisory]: raw_data = self.fetch() advisories = self.to_advisories(raw_data) return self.batch_advisories(advisories) - - #Optional Method, but it is recommended to have fetching separated + + #Optional Method, but it is recommended to have fetching separated def fetch(self): return requests.get("http://examplesecurity.org/api/json").json() - - #Optional Method + + #Optional Method @staticmethod def to_advisories(json_response:dict) -> Set[Advisory]: advisories = [] @@ -113,18 +113,18 @@ method of the migration script. cve_id = entry['cve_id'] safe_purls ={ PackageURL(name=pkg_name, type=pkg_type, - version=version) + version=version) for version in safe_pkg_versions} vuln_purls= {PackageURL(name=pkg_name, type=pkg_type, - version=version) + version=version) for version in vuln_pkg_versions} - - + + advisory = Advisory(vulnerability_id=cve_id,summary='',impacted_package_urls=vuln_purls,resolved_package_urls=safe_purls) advisories.append(advisory) return advisories - + Finally register this ``ExampleDataSource`` in ``vulnerabilities/importers/__init__.py`` by adding the following line @@ -138,4 +138,4 @@ Done, congrats on writing your new importer.Test it via :: ./manage.py migrate - ./manage.py import my_importer \ No newline at end of file + ./manage.py import my_importer