You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/tutorial_add_new_importer.rst
+22-22Lines changed: 22 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ Add a new importer
5
5
6
6
This tutorial contains all the things one should know to quickly
7
7
implement an importer.
8
-
A lot of internal sausage about importers could be found inside the
8
+
Many internal details about importers can be found inside the
9
9
:file:`vulnerabilites/importer.py` file.
10
10
Make sure to go through :ref:`importer-overview` before you begin writing one.
11
11
@@ -15,7 +15,7 @@ TL;DR
15
15
#. Create a new :file:`vulnerabilities/importers/{importer_name.py}` file.
16
16
#. Create a new importer subclass inheriting from the ``Importer`` superclass defined in
17
17
``vulnerabilites.importer``. It is conventional to end an importer name with *Importer*.
18
-
#. Specify the importer licence.
18
+
#. Specify the importer license.
19
19
#. Implement the ``advisory_data`` method to process the data source you're writing an importer for.
20
20
#. Add the newly created importer to the importers registry at
21
21
``vulnerabilites/importers/__init__.py``
@@ -45,24 +45,24 @@ VulnerableCode extensively uses Package URLs to identify a package. See the
45
45
AdvisoryData
46
46
^^^^^^^^^^^^^
47
47
48
-
``AdvisoryData`` is an intermediate data-format,
49
-
it is expected, that your importer converts the raw scraped data into ``AdvisoryData`` objects.
50
-
All the fields in ``AdvisoryData`` dataclass are optional, it is the importer's resposibility to
51
-
ensure that it must contain meaningful information about a vulnerability.
48
+
``AdvisoryData`` is an intermediate dataformat:
49
+
it is expected that your importer will convert the raw scraped data into ``AdvisoryData`` objects.
50
+
All the fields in ``AdvisoryData`` dataclass are optional; it is the importer's resposibility to
51
+
ensure that it contains meaningful information about a vulnerability.
52
52
53
53
AffectedPackage
54
54
^^^^^^^^^^^^^^^^
55
55
56
56
``AffectedPackage`` data type is used to store a range of affected versions and a fixed version of a
57
-
given package. For all versionrelated data, `univers <https://github.com/nexB/univers>`_ library
57
+
given package. For all version-related data, `univers <https://github.com/nexB/univers>`_ library
58
58
is used.
59
59
60
60
Univers
61
61
^^^^^^^^
62
62
63
-
`univers <https://github.com/nexB/univers>`_ is a python implementation of the `vers specification <https://github.com/package-url/purl-spec/pull/139>`_.
64
-
It can parse and compare all the package versions and all the ranges.
65
-
From debian, npm, pypi, ruby and more.
63
+
`univers <https://github.com/nexB/univers>`_ is a Python implementation of the `vers specification <https://github.com/package-url/purl-spec/pull/139>`_.
64
+
It can parse and compare all the package versions and all the ranges,
65
+
from debian, npm, pypi, ruby and more.
66
66
It processes all the version range specs and expressions.
67
67
68
68
Importer
@@ -90,24 +90,24 @@ implementing the unimplemented methods.
90
90
Specify the Importer License
91
91
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
92
92
93
-
Importers scrape data off the internet, in order to make sure the data is useable, a license must be
93
+
Importers scrape data off the internet. In order to make sure the data is useable, a license must be
94
94
provided.
95
-
Populate the ``spdx_license_expression`` with appropriate value.
96
-
The SPDX license identifies can be found at https://spdx.org/licenses/
95
+
Populate the ``spdx_license_expression`` with the appropriate value.
96
+
The SPDX license identifiers can be found at https://spdx.org/licenses/.
97
97
98
98
.. note::
99
99
An SPDX license identifier by itself is a valid licence expression. In case you need more complex
expressions, see https://spdx.github.io/spdx-spec/SPDX-license-expressions/
101
101
102
102
Implement the ``advisory_data`` Method
103
103
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
104
104
105
105
The ``advisory_data`` method scrapes the advisories from the data source this importer is targeted
106
106
at.
107
-
It is required to return an *Iterable of AdvisoryData objects*, thus it is a good idea to yield from
108
-
this method after creating each AdvisoryData object
107
+
It is required to return an *Iterable of AdvisoryData objects*, and thus it is a good idea to yield from
108
+
this method after creating each AdvisoryData object.
109
109
110
-
At this point, an example importer will look like:
110
+
At this point, an example importer will look like this:
111
111
112
112
:file:`vulnerabilites/importers/example.py`
113
113
@@ -133,11 +133,11 @@ This importer is only a valid skeleton and does not import anything at all.
133
133
Let us implement another dummy importer that actually imports some data.
134
134
135
135
Here we have a ``dummy_package`` which follows ``NginxVersionRange`` and ``SemverVersion`` for
136
-
version management from `univers <https://github.com/nexB/univers>`_
136
+
version management from `univers <https://github.com/nexB/univers>`_.
137
137
138
138
.. note::
139
139
140
-
It is possible that versioning scheme you are targetting has not yet been implemented in the `univers <https://github.com/nexB/univers>`_ library. If this is the case, you'll need to head over over there and implement one.
140
+
It is possible that the versioning scheme you are targetting has not yet been implemented in the `univers <https://github.com/nexB/univers>`_ library. If this is the case, you'll need to head over there and implement one.
141
141
142
142
.. code-block:: python
143
143
@@ -241,7 +241,7 @@ Congratulations! You've written your first importer.
241
241
Run Your First Importer
242
242
^^^^^^^^^^^^^^^^^^^^^^^^^^
243
243
244
-
If everything went fine, you'll see your importer in the list of available importers
244
+
If everything went well, you'll see your importer in the list of available importers.
245
245
246
246
.. code-block:: console
247
247
:emphasize-lines: 5
@@ -252,7 +252,7 @@ If everything went fine, you'll see your importer in the list of available impor
252
252
vulnerabilities.importers.nginx.NginxImporter
253
253
vulnerabilities.importers.example.ExampleImporter
254
254
255
-
Now, run the importer
255
+
Now, run the importer.
256
256
257
257
.. code-block:: console
258
258
@@ -285,7 +285,7 @@ For more visibility, turn on debug logs in :file:`vulnerablecode/settings.py`.
285
285
},
286
286
}
287
287
288
-
Invoke the import command now and you'll see (in a fresh database)
288
+
Invoke the import command now and you'll see (in a fresh database):
0 commit comments