Merge pull request #987 from nexB/api-authentication

Add API authentication, key request and documentation

Author: pombredanne

docs/source/api.rst

@@ -0,0 +1,50 @@
+.. _api:
+
+API overview
+========================
+
+
+Browse the Open API documentation
+------------------------------------
+
+- https://public.vulnerablecode.io/api/docs/ for documentation with Swagger
+- https://public.vulnerablecode.io/api/schema/ for the OpenAPI schema
+
+
+Enable the API key authentication
+------------------------------------
+
+There is a setting VULNERABLECODEIO_REQUIRE_AUTHENTICATION for this. Use it this
+way::
+
+    $ VULNERABLECODEIO_REQUIRE_AUTHENTICATION=1 make run
+
+
+Create an API key-only user
+------------------------------------
+
+This can be done in the admin and from the command line::
+
+    $ ./manage.py create_api_user --email "[email protected]" --first-name="Phil" --last-name "Goel"
+    User [email protected] created with API key: ce8616b929d2adsddd6146346c2f26536423423491
+
+
+Access the API using curl
+-----------------------------
+
+    curl -X GET -H 'Authorization: Token <YOUR TOKEN>' https://public.vulnerablecode.io/api/
+
+
+API endpoints
+---------------
+
+
+There are two primary endpoints:
+
+- packages/: this is the main endpoint where you can lookup vulnerabilities by package.
+
+- vulnerabilities/: to lookup by vulnerabilities
+
+And two secondary endpoints, used to query vulnerability aliases (such as CVEs)
+and vulnerability by CPEs: cpes/ and aliases/
+

docs/source/index.rst

@@ -43,6 +43,7 @@ In this documentation you will find information on:
     reference_framework_overview
     command-line-interface
     importers_link
+    api
 
 .. toctree::
    :maxdepth: 1

requirements.txt

@@ -21,6 +21,7 @@ decorator==5.1.1
 defusedxml==0.7.1
 distro==1.7.0
 Django==4.0.7
+django-crispy-forms==1.10.0
 django-environ==0.8.1
 django-filter==21.1
 django-widget-tweaks==1.4.12
@@ -65,7 +66,7 @@ platformdirs==2.5.1
 pluggy==1.0.0
 pprintpp==0.4.0
 prompt-toolkit==3.0.29
-psycopg2==2.9.3
+psycopg2-binary==2.9.3
 ptyprocess==0.7.0
 pure-eval==0.2.2
 py==1.11.0
@@ -114,3 +115,9 @@ yarl==1.7.2
 zipp==3.8.0
 dateparser==1.1.1
 fetchcode==0.2.0
+
+drf-spectacular-sidecar==2022.10.1
+drf-spectacular==0.24.2
+coreapi==2.3.3
+coreschema==0.0.4
+itypes==1.2.0

setup.cfg

@@ -56,13 +56,18 @@ zip_safe = false
 
 install_requires =
     Django>=4.0.0
-    psycopg2>=2.8.6
+    psycopg2-binary>=2.8.6
     djangorestframework>=3.12.4
     django-filter>=2.4.0
     django-widget-tweaks>=1.4.8
+    django-crispy-forms>=1.10.0
     django-environ>=0.8.0
     gunicorn>=20.1.0
 
+    # for the API doc
+    drf-spectacular[sidecar]>=0.24.2
+    coreapi>=2.3.3
+
     #essentials
     packageurl-python>=0.9.4
     univers>=30.9.0

vulnerabilities/admin.py

@@ -7,8 +7,11 @@
 # See https://aboutcode.org for more information about nexB OSS projects.
 #
 
+from django import forms
 from django.contrib import admin
+from django.core.validators import validate_email
 
+from vulnerabilities.models import ApiUser
 from vulnerabilities.models import Package
 from vulnerabilities.models import PackageRelatedVulnerability
 from vulnerabilities.models import Vulnerability
@@ -41,3 +44,63 @@ class PackageRelatedVulnerabilityAdmin(admin.ModelAdmin):
 @admin.register(VulnerabilitySeverity)
 class VulnerabilitySeverityAdmin(admin.ModelAdmin):
     pass
+
+
+class ApiUserCreationForm(forms.ModelForm):
+    """
+    This helps have a simplified creation for API-only users in the admin
+    """
+
+    class Meta:
+        model = ApiUser
+        fields = (
+            "username",
+            "first_name",
+            "last_name",
+        )
+
+    def save(self, commit=True):
+        return ApiUser.objects.create_api_user(
+            username=self.cleaned_data["username"],
+            first_name=self.cleaned_data["first_name"],
+            last_name=self.cleaned_data["last_name"],
+        )
+
+    def clean_username(self):
+        username = self.cleaned_data["username"]
+        validate_email(username)
+        return username
+
+    def save_m2m(self):
+        pass
+
+
+@admin.register(ApiUser)
+class ApiUserAdmin(admin.ModelAdmin):
+    list_display = ("username", "email", "first_name", "last_name", "is_staff")
+    list_filter = ("username", "email", "first_name", "last_name", "is_staff")
+    search_fields = ("username", "email", "first_name", "last_name")
+    fieldsets = (
+        (
+            None,
+            {
+                "fields": (
+                    "username",
+                    "first_name",
+                    "last_name",
+                )
+            },
+        ),
+    )
+
+    add_form = ApiUserCreationForm
+
+    def get_form(self, request, obj=None, **kwargs):
+        """
+        Use special form during user creation
+        """
+        defaults = {}
+        if obj is None:
+            defaults["form"] = self.add_form
+        defaults.update(kwargs)
+        return super().get_form(request, obj, **defaults)

vulnerabilities/api.py

@@ -55,7 +55,7 @@ class Meta:
 
 class VulnSerializerRefsAndSummary(serializers.HyperlinkedModelSerializer):
     """
-    Used for nesting inside package focused APIs.
+    Lookup vulnerabilities references by aliases (such as a CVE).
     """
 
     fixed_packages = MinimalPackageSerializer(
@@ -71,7 +71,7 @@ class Meta:
 
 class MinimalVulnerabilitySerializer(serializers.HyperlinkedModelSerializer):
     """
-    Used for nesting inside package focused APIs.
+    Lookup vulnerabilities by aliases (such as a CVE).
     """
 
     class Meta:
@@ -113,6 +113,10 @@ class Meta:
 
 
 class PackageSerializer(serializers.HyperlinkedModelSerializer):
+    """
+    Lookup software package using Package URLs
+    """
+
     def to_representation(self, instance):
         data = super().to_representation(instance)
         data["unresolved_vulnerabilities"] = data["affected_by_vulnerabilities"]
@@ -138,9 +142,9 @@ def get_fixed_packages(self, package):
             packagerelatedvulnerability__fix=True,
         ).distinct()
 
-    def get_vulnerabilities_for_a_package(self, package, fix):
+    def get_vulnerabilities_for_a_package(self, package, fix) -> dict:
         """
-        Return a queryset of vulnerabilities related to the given `package`.
+        Return a mapping of vulnerabilities data related to the given `package`.
         Return vulnerabilities that affects the `package` if given `fix` flag is False,
         otherwise return vulnerabilities fixed by the `package`.
         """
@@ -159,15 +163,15 @@ def get_vulnerabilities_for_a_package(self, package, fix):
             context={"request": self.context["request"]},
         ).data
 
-    def get_fixed_vulnerabilities(self, package):
+    def get_fixed_vulnerabilities(self, package) -> dict:
         """
-        Return a queryset of vulnerabilities fixed in the given `package`.
+        Return a mapping of vulnerabilities fixed in the given `package`.
         """
         return self.get_vulnerabilities_for_a_package(package=package, fix=True)
 
-    def get_affected_vulnerabilities(self, package):
+    def get_affected_vulnerabilities(self, package) -> dict:
         """
-        Return a queryset of vulnerabilities that affects the given `package`.
+        Return a mapping of vulnerabilities that affects the given `package`.
         """
         return self.get_vulnerabilities_for_a_package(package=package, fix=False)
 
@@ -217,6 +221,10 @@ def filter_purl(self, queryset, name, value):
 
 
 class PackageViewSet(viewsets.ReadOnlyModelViewSet):
+    """
+    Lookup for vulnerable packages by Package URL.
+    """
+
     queryset = Package.objects.all()
     serializer_class = PackageSerializer
     filter_backends = (filters.DjangoFilterBackend,)
@@ -228,7 +236,7 @@ class PackageViewSet(viewsets.ReadOnlyModelViewSet):
     @action(detail=False, methods=["post"], throttle_scope="bulk_search_packages")
     def bulk_search(self, request):
         """
-        See https://github.com/nexB/vulnerablecode/pull/369#issuecomment-796877606 for docs
+        Lookup for vulnerable packages using many Package URLs at once.
         """
         response = []
         purls = request.data.get("purls", []) or []
@@ -260,7 +268,7 @@ def bulk_search(self, request):
     @action(detail=False, methods=["get"], throttle_scope="vulnerable_packages")
     def all(self, request):
         """
-        Return all the vulnerable Package URLs.
+        Return the Package URLs of all packages known to be vulnerable.
         """
         vulnerable_packages = Package.objects.vulnerable().only(*PackageURL._fields).distinct()
         vulnerable_purls = [str(package.purl) for package in vulnerable_packages]
@@ -274,6 +282,10 @@ class Meta:
 
 
 class VulnerabilityViewSet(viewsets.ReadOnlyModelViewSet):
+    """
+    Lookup for vulnerabilities affecting packages.
+    """
+
     def get_fixed_packages_qs(self):
         """
         Filter the packages that fixes a vulnerability
@@ -318,6 +330,10 @@ def filter_cpe(self, queryset, name, value):
 
 
 class CPEViewSet(viewsets.ReadOnlyModelViewSet):
+    """
+    Lookup for vulnerabilities by CPE (https://nvd.nist.gov/products/cpe)
+    """
+
     queryset = Vulnerability.objects.filter(
         vulnerabilityreference__reference_id__startswith="cpe"
     ).distinct()
@@ -330,7 +346,7 @@ class CPEViewSet(viewsets.ReadOnlyModelViewSet):
     @action(detail=False, methods=["post"], throttle_scope="bulk_search_cpes")
     def bulk_search(self, request):
         """
-        This endpoint is used to search for vulnerabilities by more than one CPE.
+        Lookup for vulnerabilities using many CPEs at once.
         """
         cpes = request.data.get("cpes", []) or []
         if not cpes or not isinstance(cpes, list):
@@ -360,6 +376,11 @@ def filter_alias(self, queryset, name, value):
 
 
 class AliasViewSet(viewsets.ReadOnlyModelViewSet):
+    """
+    Lookup for vulnerabilities by vulnerability aliases such as a CVE
+    (https://nvd.nist.gov/general/cve-process).
+    """
+
     queryset = Vulnerability.objects.all()
     serializer_class = VulnerabilitySerializer
     filter_backends = (filters.DjangoFilterBackend,)

vulnerabilities/forms.py

@@ -8,6 +8,9 @@
 #
 
 from django import forms
+from django.core.validators import validate_email
+
+from vulnerabilities.models import ApiUser
 
 
 class PackageSearchForm(forms.Form):
@@ -28,3 +31,36 @@ class VulnerabilitySearchForm(forms.Form):
             attrs={"placeholder": "Vulnerability id or alias such as CVE or GHSA"}
         ),
     )
+
+
+class ApiUserCreationForm(forms.ModelForm):
+    """
+    Support a simplified creation for API-only users directly from the UI.
+    """
+
+    class Meta:
+        model = ApiUser
+        fields = (
+            "email",
+            "first_name",
+            "last_name",
+        )
+
+    def __init__(self, *args, **kwargs):
+        super(ApiUserCreationForm, self).__init__(*args, **kwargs)
+        self.fields["email"].required = True
+
+    def save(self, commit=True):
+        return ApiUser.objects.create_api_user(
+            username=self.cleaned_data["email"],
+            first_name=self.cleaned_data["first_name"],
+            last_name=self.cleaned_data["last_name"],
+        )
+
+    def clean_username(self):
+        username = self.cleaned_data["email"]
+        validate_email(username)
+        return username
+
+    def save_m2m(self):
+        pass