dogesec-commons 1.0.2__py3-none-any.whl

dogesec_commons/stixifier/views.py

@@ -0,0 +1,193 @@
+from .models import Profile
+from drf_spectacular.utils import extend_schema, extend_schema_view, OpenApiParameter
+from drf_spectacular.types import OpenApiTypes
+from ..utils import Pagination, Ordering
+
+from rest_framework import viewsets, response, mixins, exceptions
+from django_filters.rest_framework import DjangoFilterBackend, FilterSet, Filter, BooleanFilter
+from .serializers import DEFAULT_400_ERROR, DEFAULT_404_ERROR, Txt2stixExtractorSerializer
+from django.forms import NullBooleanField
+
+from .serializers import ProfileSerializer
+
+from drf_spectacular.utils import extend_schema, extend_schema_view
+import django.db.models.deletion
+import textwrap
+
+EXTRACTOR_TYPES = ["lookup", "pattern", "ai"]
+
+@extend_schema_view(
+    list=extend_schema(
+        summary="Search profiles",
+        description=textwrap.dedent(
+            """
+            Profiles determine how txt2stix processes the text in each File. A profile consists of extractors. You can search for existing profiles here.
+            """
+        ),
+        responses={400: DEFAULT_400_ERROR, 200: ProfileSerializer},
+    ),
+    retrieve=extend_schema(
+        summary="Get a profile",
+        description=textwrap.dedent(
+            """
+            View the configuration of an existing profile. Note, existing profiles cannot be modified.
+            """
+        ),
+        responses={400: DEFAULT_400_ERROR, 404: DEFAULT_404_ERROR, 200: ProfileSerializer}
+    ),
+    create=extend_schema(
+        summary="Create a new profile",
+        description=textwrap.dedent(
+            """
+            Add a new Profile that can be applied to new Files. A profile consists of extractors. You can find available extractors via their respective endpoints.
+
+            The following key/values are accepted in the body of the request:
+
+            * `name` (required - must be unique)
+            * `identity_id` (optional): a STIX Identity ID that you want to use to create the profile. Pass the full identity ID, e.g. `identity--de9fb9bd-7895-4b23-aa03-49250d9263c9`
+            * `ai_create_attack_flow` (optional, boolean): default is `true`. passing as `true` will prompt the AI model (the same entered for `ai_settings_relationships`) to generate an [Attack Flow](https://center-for-threat-informed-defense.github.io/attack-flow/) for the MITRE ATT&CK extractions to define the logical order in which they are being described. You must pass `--ai_settings_relationships` for this to work.
+            * `ai_summary_provider` (optional, AI provider:model): you can also generate a summary of the files this profile is linked to using an AI model. If not passed, no summary will be generated. Pass in format `"provider:model"` e.g. `"openai:gpt-4o"`.
+            * `ai_content_check_provider` (optional, AI provider:model): Setting a value will get the AI to try and classify the text in the input to 1) determine if it is talking about threat intelligence, and 2) what type of threat intelligence it is talking about. For context, we use this to filter out non-threat intel posts in Obstracts Web (note, we don't filter in this way Stixify Web) using `always_extract` in dogesec_commons to reduce the cost of AI models and make them easier to search through classifications.  You pass `provider:model` (e.g. `"openai:gpt-4o"`) with this flag to determine the AI model you wish to use to perform the check. 
+            * `extract_text_from_image` (required - boolean): whether to convert the images found in a blog to text. Requires a Google Vision key to be set. This is a [file2txt](https://github.com/muchdogesec/file2txt) setting.
+            * `defang` (required - boolean): whether to defang the observables in the blog. e.g. turns `1.1.1[.]1` to `1.1.1.1` for extraction. This is a [file2txt](https://github.com/muchdogesec/file2txt) setting.
+            * `ignore_image_refs` (optional, default `true`): whether to ignore embedded image references. This is a [txt2stix](https://github.com/muchdogesec/txt2stix/) setting.
+            * `ignore_link_refs` (optional, default `true`): whether to ignore embedded link references. This is a [txt2stix](https://github.com/muchdogesec/txt2stix/) setting.
+            * `extractions` (required - at least one extraction ID): can be obtained from the GET Extractors endpoint. This is a [txt2stix](https://github.com/muchdogesec/txt2stix/) setting.
+            * `ai_settings_extractions` (required if AI extraction used, AI provider:model): A list of AI providers and models to be used for extraction in format `["provider:model","provider:model"]` e.g. `["openai:gpt-4o"]`. This is a [txt2stix](https://github.com/muchdogesec/txt2stix/) setting.
+            * `ignore_extraction_boundary` (optional, default `false`): defines if a string boundary can generate multiple extractions (e.g. `url`, `domain`, etc). Setting to `true` will allow multiple extractions from the same string. This is a [txt2stix](https://github.com/muchdogesec/file2txt) setting.
+            * `relationship_mode` (required): either `ai` or `standard`. Required AI provider to be configured if using `ai` mode. This is a [txt2stix](https://github.com/muchdogesec/txt2stix/) setting.
+            * `ai_settings_relationships` (required if AI relationship used, AI provider:model): An AI provider and models to be used for relationship generation in format `"provider:model"` e.g. `"openai:gpt-4o"`. This is a [txt2stix](https://github.com/muchdogesec/txt2stix/) setting.
+            * `generate_pdf` (optional, boolean): default is `false` will generate a PDF of the input if set to true 
+            * `ignore_embedded_relationships` (optional, default: false): boolean, if `true` passed, this will stop ANY embedded relationships from being generated. This applies for all object types (SDO, SCO, SRO, SMO). If you want to target certain object types see `ignore_embedded_relationships_sro` and `ignore_embedded_relationships_sro` flags. This is a [stix2arango](https://github.com/muchdogesec/stix2arango) setting.
+            * `ignore_embedded_relationships_sro` (optional, default: false): boolean, if `true` passed, will stop any embedded relationships from being generated from SRO objects (`type` = `relationship`). This is a [stix2arango](https://github.com/muchdogesec/stix2arango) setting.
+            * `ignore_embedded_relationships_smo` (optional, default: false): boolean, if `true` passed, will stop any embedded relationships from being generated from SMO objects (`type` = `marking-definition`, `extension-definition`, `language-content`). This is a [stix2arango](https://github.com/muchdogesec/stix2arango) setting.
+
+            A profile `id` is generated using a UUIDv5. The namespace used is is set using the `STIXIFIER_NAMESPACE` in dogesec tools, and the `name+identity_id` is used as the value (e.g a namespace of `9779a2db-f98c-5f4b-8d08-8ee04e02dbb5` and value `my profile+identity--de9fb9bd-7895-4b23-aa03-49250d9263c9` would have the `id`: `05004944-0eff-507e-8ef8-9ebdd043a51b`). Note, the name
+
+            You cannot modify a profile once it is created. If you need to make changes, you should create another profile with the changes made. If it is essential that the same `name` + `identity_id` value be used, then you must first delete the profile in order to recreate it.
+            """
+        ),
+        responses={400: DEFAULT_400_ERROR, 200: ProfileSerializer}
+    ),
+    destroy=extend_schema(
+        summary="Delete a profile",
+        description=textwrap.dedent(
+            """
+            Delete an existing profile.
+
+            Note: it is not currently possible to delete a profile that is referenced in an existing object. You must delete the objects linked to the profile first.
+            """
+        ),
+        responses={404: DEFAULT_404_ERROR, 204: None}
+    ),
+)
+class ProfileView(viewsets.ModelViewSet):
+    openapi_tags = ["Profiles"]
+    serializer_class = ProfileSerializer
+    http_method_names = ["get", "post", "delete"]
+    pagination_class = Pagination("profiles")
+    lookup_url_kwarg = 'profile_id'
+    openapi_path_params = [
+        OpenApiParameter(
+            lookup_url_kwarg, location=OpenApiParameter.PATH, type=OpenApiTypes.UUID, description="The `id` of the Profile."
+        )
+    ]
+
+    ordering_fields = ["name", "created"]
+    ordering = "created_descending"
+    filter_backends = [DjangoFilterBackend, Ordering]
+
+    class filterset_class(FilterSet):
+        name = Filter(
+            help_text="Searches Profiles by their `name`. Search is wildcard. For example, `ip` will return Profiles with names `ip-extractions`, `ips`, etc.",
+            lookup_expr="icontains"
+            )
+        identity_id = Filter(
+            help_text="filter the results by the identity that created the Profile. Use a full STIX identity ID, e.g. `identity--de9fb9bd-7895-4b23-aa03-49250d9263c9`"
+        )
+
+    def get_queryset(self):
+        return Profile.objects
+    
+class txt2stixView(mixins.RetrieveModelMixin,
+                           mixins.ListModelMixin, viewsets.GenericViewSet):
+    serializer_class = Txt2stixExtractorSerializer
+    lookup_url_kwarg = "id"
+    
+    def get_queryset(self):
+        return None
+
+    @classmethod
+    def all_extractors(cls, types):
+        return Txt2stixExtractorSerializer.all_extractors(types)
+
+    def get_all(self):
+        raise NotImplementedError("not implemented")
+    
+
+    def list(self, request, *args, **kwargs):
+        page = self.paginate_queryset(list(self.get_all().values()))
+        return self.get_paginated_response(page)
+
+    def retrieve(self, request, *args, **kwargs):
+        items = self.get_all()
+        id_ = self.kwargs.get(self.lookup_url_kwarg)
+        print(id_, self.lookup_url_kwarg, self.kwargs)
+        item = items.get(id_)
+        if not item:
+            return response.Response(dict(message="item not found", code=404), status=404)
+        return response.Response(item)
+
+@extend_schema_view(
+    list=extend_schema(
+        summary="Search Extractors",
+        description=textwrap.dedent(
+            """
+            Extractors are what extract the data from the text which is then converted into STIX objects.
+
+            For more information see [txt2stix](https://github.com/muchdogesec/txt2stix/).
+            """
+        ),
+        responses={400: DEFAULT_400_ERROR, 200: Txt2stixExtractorSerializer},
+    ),
+    retrieve=extend_schema(
+        summary="Get an extractor",
+        description=textwrap.dedent(
+            """
+            Get a specific Extractor.
+            """
+        ),
+        responses={400: DEFAULT_400_ERROR, 404: DEFAULT_404_ERROR, 200: Txt2stixExtractorSerializer},
+    ),
+)
+class ExtractorsView(txt2stixView):
+    openapi_tags = ["Extractors"]
+    lookup_url_kwarg = "extractor_id"
+    openapi_path_params = [
+        OpenApiParameter(
+            lookup_url_kwarg, location=OpenApiParameter.PATH, type=OpenApiTypes.STR, description="The `id` of the Extractor."
+        )
+    ]
+    pagination_class = Pagination("extractors")
+    filter_backends = [DjangoFilterBackend]
+
+
+    class filterset_class(FilterSet):
+        type = Filter(choices=[(extractor, extractor) for extractor in EXTRACTOR_TYPES], help_text="Filter Extractors by their `type`")
+        name = Filter(help_text="Filter extractors by `name`. Is wildcard search so `ip` will return `ipv4`, `ipv6`, etc.)")
+        web_app = BooleanFilter(help_text="filters on `dogesec_web` property in txt2stix filter.\nuse case is, web app can set this to true to only show extractors allowed in web app")
+
+    def get_all(self):
+        types = EXTRACTOR_TYPES
+        if type := self.request.GET.get('type'):
+            types = type.split(',')
+
+        extractors = self.all_extractors(types)
+
+        if name := self.request.GET.get('name', '').lower():
+            extractors = {slug: extractor for slug, extractor in extractors.items() if name in extractor['name'].lower()}
+
+        webapp_filter = NullBooleanField.to_python(..., self.request.GET.get('web_app', ''))
+        if webapp_filter != None:
+            extractors = {slug: extractor for slug, extractor in extractors.items() if extractor.get('dogesec_web') == webapp_filter}
+        return extractors

dogesec_commons/urls.py

@@ -0,0 +1,45 @@
+"""
+URL configuration for dogesec_commons project.
+
+The `urlpatterns` list routes URLs to views. For more information please see:
+    https://docs.djangoproject.com/en/5.1/topics/http/urls/
+Examples:
+Function views
+    1. Add an import:  from my_app import views
+    2. Add a URL to urlpatterns:  path('', views.home, name='home')
+Class-based views
+    1. Add an import:  from other_app.views import Home
+    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
+Including another URLconf
+    1. Import the include() function: from django.urls import include, path
+    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
+"""
+from django.contrib import admin
+from django.urls import include, path
+from rest_framework import routers
+from dogesec_commons.stixifier.views import ExtractorsView, ProfileView
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
+from dogesec_commons.objects import views as arango_views
+router = routers.SimpleRouter(use_regex_path=False)
+
+router.register('profiles', ProfileView, "profile-view")
+# txt2stix views
+router.register('extractors', ExtractorsView, "extractors-view")
+
+## objects
+regex_router = routers.SimpleRouter(use_regex_path=True)
+regex_router.register("", arango_views.ObjectsWithReportsView, "object-view-orig")
+regex_router.register('smos', arango_views.SMOView, "object-view-smo")
+regex_router.register('scos', arango_views.SCOView, "object-view-sco")
+regex_router.register('sros', arango_views.SROView, "object-view-sro")
+regex_router.register('sdos', arango_views.SDOView, "object-view-sdo")
+urlpatterns = [
+    path(f'api/', include(router.urls)),
+    path(f'objects/', include(regex_router.urls)),
+    path('admin/', admin.site.urls),
+
+    # YOUR PATTERNS
+    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
+    # Optional UI:
+    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
+]

dogesec_commons/utils/__init__.py

@@ -0,0 +1,3 @@
+from .pagination import Pagination
+from .ordering import Ordering
+from .exceptions import custom_exception_handler

dogesec_commons/utils/autoschema.py

@@ -0,0 +1,88 @@
+from typing import List
+from drf_spectacular.openapi import AutoSchema
+from drf_spectacular.plumbing import ComponentRegistry
+from drf_spectacular.utils import _SchemaType, OpenApiResponse, OpenApiExample
+from drf_spectacular.types import OpenApiTypes
+import uritemplate
+
+from dogesec_commons.utils import schemas
+from .serializers import CommonErrorSerializer
+
+from drf_spectacular.contrib.django_filters import DjangoFilterExtension, get_view_model
+class OverrideDjangoFilterExtension(DjangoFilterExtension):
+    priority = 10
+    def get_schema_operation_parameters(self, auto_schema: AutoSchema, *args, **kwargs):
+        model = get_view_model(auto_schema.view)
+        if not model:
+            return self.override(auto_schema, *args, **kwargs)
+        return super().get_schema_operation_parameters(auto_schema, *args, **kwargs)
+    
+    def override(self, autoschema, *args, **kwargs):
+        result = []
+        filterset_class = self.target.get_filterset_class(autoschema.view)
+        if not filterset_class:
+            return self.target.get_schema_operation_parameters(autoschema.view, *args, **kwargs)
+        for field_name, filter_field in filterset_class.base_filters.items():
+            result += self.resolve_filter_field(
+                autoschema, None, filterset_class, field_name, filter_field
+            )
+        return result
+
+
+class CustomAutoSchema(AutoSchema):
+    default_responses = {
+            '404': (schemas.WEBSERVER_404_RESPONSE, ["application/json"]),
+    }
+    def get_tags(self) -> List[str]:
+        if hasattr(self.view, "openapi_tags"):
+            return self.view.openapi_tags
+        return super().get_tags()
+
+    
+    def get_override_parameters(self):
+        params = super().get_override_parameters()
+        path_variables = uritemplate.variables(self.path)
+        for param in getattr(self.view, 'openapi_path_params', []):
+            if param.name in path_variables:
+                params.append(param)
+        return params
+    
+    def _map_serializer_field(self, field, direction, bypass_extensions=False):
+        if getattr(field, 'internal_serializer', None):
+            return super()._map_serializer_field(field.internal_serializer, direction, bypass_extensions)
+        return super()._map_serializer_field(field, direction, bypass_extensions)
+
+
+    def _map_serializer(self, serializer, direction, bypass_extensions=False):
+        if getattr(serializer, "get_schema", None):
+            return serializer.get_schema()
+        return super()._map_serializer(serializer, direction, bypass_extensions)
+    
+
+    def get_operation(self, *args, **kwargs):
+        operation = super().get_operation(*args, **kwargs)
+        if operation:
+            self.add_default_pages(operation)
+        return operation
+
+    def add_default_pages(self, operation):
+        """
+        modify responses to include 404 error for when path parameters don't match specified path. e.g if integer passed instead of a uuid param
+        """
+        responses = operation['responses']
+
+        default_responses = {
+            code: self._get_response_for_code(schema, code, content_type) for code, (schema, content_type) in self.default_responses.items()
+        }
+        for code, content_response in default_responses.items():
+            if code not in responses:
+                responses[code] = content_response
+        return operation
+    
+    def _is_list_view(self, serializer=None) -> bool:
+        if getattr(self.view, 'action', None) == 'list' and getattr(self.view, 'skip_list_view', False):
+            """
+            view.skip_list_view is used for checking if many should be used or not on list() action
+            """
+            return False
+        return super()._is_list_view(serializer)

dogesec_commons/utils/exceptions.py

@@ -0,0 +1,28 @@
+from rest_framework.views import exception_handler
+from rest_framework.exceptions import ValidationError, PermissionDenied
+from django.core import exceptions as django_exceptions
+from django.http import JsonResponse, Http404
+import rest_framework.exceptions
+import django.db.models.deletion
+
+
+def custom_exception_handler(exc, context):
+    if isinstance(exc, django_exceptions.ValidationError):
+        exc = ValidationError(detail=exc.messages, code=exc.code)
+    
+    if isinstance(exc, django.db.models.deletion.ProtectedError):
+        return JsonResponse({'code': 403, 'message': "cannot delete object(s) because they are referenced through protected foreign keys.", 'details': {'protected_objects': [str(f) for f in exc.protected_objects]}}, status=403)
+        
+    resp = exception_handler(exc, context)
+    if resp is not None:
+        if isinstance(resp.data, dict) and 'detail' in resp.data:
+                resp.data = resp.data['detail']
+        if isinstance(resp.data, str):
+            resp.data = dict(code=resp.status_code, message=resp.data)
+        if isinstance(resp.data, list):
+            resp.data = dict(code=resp.status_code, details={'detail':resp.data})
+        else:
+            resp.data = dict(code=resp.status_code, details=resp.data)
+        resp.data.setdefault('message', resp.status_text)
+        resp = JsonResponse(data=resp.data, status=resp.status_code)
+    return resp

dogesec_commons/utils/filters.py

@@ -0,0 +1,66 @@
+from rest_framework.filters import BaseFilterBackend
+from datetime import datetime, UTC
+from django.forms import DateTimeField
+from django_filters.rest_framework import filters
+
+
+class DatetimeFieldUTC(DateTimeField):
+    def to_python(self, value):
+        value = super().to_python(value)
+        return value and value.astimezone(UTC)
+
+
+class DatetimeFilter(filters.Filter):
+    field_class = DatetimeFieldUTC
+
+
+class MinMaxDateFilter(BaseFilterBackend):
+    min_val = datetime.min
+    max_value = datetime.max
+
+    def get_fields(self, view):
+        out = {}
+        fields = getattr(view, "minmax_date_fields", [])
+        if not isinstance(fields, list):
+            return out
+        for field in fields:
+            out[f"{field}_max"] = field
+            out[f"{field}_min"] = field
+        return out
+
+    def parse_date(self, value):
+        return DatetimeFieldUTC().to_python(value)
+
+    def filter_queryset(self, request, queryset, view):
+        valid_fields = self.get_fields(view)
+        valid_params = [
+            (k, v) for k, v in request.query_params.items() if k in valid_fields
+        ]
+        queries = {}
+        for param, value in valid_params:
+            field_name = valid_fields[param]
+            if param.endswith("_max"):
+                queries[f"{field_name}__lte"] = self.parse_date(value)
+            else:
+                queries[f"{field_name}__gte"] = self.parse_date(value)
+        return queryset.filter(**queries)
+
+    def get_schema_operation_parameters(self, view):
+        parameters = []
+        valid_fields = self.get_fields(view)
+        for query_name, field_name in valid_fields.items():
+            _type = "Maximum"
+            if query_name.endswith("min"):
+                _type = "Minimum"
+            parameter = {
+                "name": query_name,
+                "required": False,
+                "in": "query",
+                "description": f"{_type} value of `{field_name}` to filter by in format `YYYY-MM-DD`.",
+                "schema": {
+                    "type": "string",
+                    "format": "date",
+                },
+            }
+            parameters.append(parameter)
+        return parameters

dogesec_commons/utils/ordering.py

@@ -0,0 +1,47 @@
+from django.conf import settings
+from rest_framework import pagination, response
+from rest_framework.filters import OrderingFilter
+from django.utils.encoding import force_str
+from rest_framework import response
+
+class Ordering(OrderingFilter):
+    ordering_param = "sort"
+
+    def get_ordering(self, request, queryset, view):
+        params = request.query_params.get(self.ordering_param)
+        ordering_mapping = self.get_ordering_mapping(queryset, view)
+        if params:
+            fields = [ordering_mapping.get(param.strip()) for param in params.split(',') if param.strip() in ordering_mapping]
+            ordering = self.remove_invalid_fields(queryset, fields, view, request)
+            if ordering:
+                return ordering
+        return self.get_default_ordering(view)
+
+    def get_ordering_mapping(self, queryset, view):
+        valid_fields = self.get_valid_fields(queryset, view)
+        mapping = {}
+        for k, v in valid_fields:
+            mapping[f"{k}_descending"] = f"-{v}"
+            mapping[f"{k}_ascending"]  = v
+        return mapping
+    
+
+    def get_schema_operation_parameters(self, view):
+        return [
+            {
+                'name': self.ordering_param,
+                'required': False,
+                'in': 'query',
+                'description': force_str(self.ordering_description),
+                'schema': {
+                    'type': 'string',
+                    'enum': list(self.get_ordering_mapping(None, view).keys())
+                },
+            },
+        ]
+    
+    def get_default_ordering(self, view):
+        ordering = getattr(view, 'ordering', None)
+        if isinstance(ordering, str):
+            return (self.get_ordering_mapping(None, view).get(ordering),)
+        return None

dogesec_commons/utils/pagination.py

@@ -0,0 +1,81 @@
+import contextlib
+from django.conf import settings
+from rest_framework import pagination, response
+from rest_framework import response
+from rest_framework.exceptions import NotFound
+from django.core.paginator import Page as DjangoPage, InvalidPage
+
+
+class Pagination(pagination.PageNumberPagination):
+    max_page_size = settings.MAXIMUM_PAGE_SIZE
+    page_size = settings.DEFAULT_PAGE_SIZE
+    page_size_query_param = 'page_size'
+    def __init__(self, results_key) -> None:
+        self.results_key = results_key
+        super().__init__()
+
+    def paginate_queryset(self, queryset, request, view=None):
+        with contextlib.suppress(NotFound):
+            return super().paginate_queryset(queryset, request, view)
+        self.page = DjangoPage([], -1, self)
+        return []
+    
+    def paginate_queryset(self, queryset, request, view=None):
+        """
+        Paginate a queryset if required, either returning a
+        page object, or `None` if pagination is not configured for this view.
+        """
+        self.request = request
+        page_size = self.get_page_size(request)
+        if not page_size:
+            return None
+
+        paginator = self.django_paginator_class(queryset, page_size)
+        page_number = self.get_page_number(request, paginator)
+
+        try:
+            self.page = paginator.page(page_number)
+        except InvalidPage as exc:
+            if isinstance(page_number, str):
+                page_number = int(page_number) if page_number.isdigit() else -1
+            self.page = DjangoPage([], page_number, paginator)
+
+        return list(self.page)
+    
+    def get_paginated_response(self, data):
+        
+        return response.Response({
+            'page_size': self.get_page_size(self.request),
+            'page_number': self.page.number,
+            'page_results_count': len(self.page),
+            'total_results_count': self.page.paginator.count,
+            self.results_key: data,
+        })
+
+    def get_paginated_response_schema(self, schema):
+        return {
+            'type': 'object',
+            'required': ['total_results_count', self.results_key],
+            'properties': {
+                'page_size': {
+                    'type': 'integer',
+                    'example': self.max_page_size,
+                },
+                'page_number': {
+                    'type': 'integer',
+                    'example': 3,
+                },
+                'page_results_count': {
+                    'type': 'integer',
+                    'example': self.max_page_size,
+                },
+                'total_results_count': {
+                    'type': 'integer',
+                    'example': 3,
+                },
+                self.results_key: schema,
+            },
+        }
+
+    def __call__(self, *args, **kwargs):
+        return self.__class__(results_key=self.results_key)

dogesec_commons/utils/schemas.py

@@ -0,0 +1,27 @@
+from drf_spectacular.utils import OpenApiResponse, OpenApiExample
+from .serializers import CommonErrorSerializer
+
+
+HTTP404_EXAMPLE = OpenApiExample("http-404", {"message": "resource not found", "code": 404})
+HTTP400_EXAMPLE = OpenApiExample("http-400", {"message": "request not understood", "code": 400})
+
+WEBSERVER_404_RESPONSE = OpenApiResponse(CommonErrorSerializer, description="webserver's HTML 404 page", examples=[OpenApiExample('404-page', {"code": 404, "message": "non-existent page"})])
+WEBSERVER_500_RESPONSE = OpenApiResponse(CommonErrorSerializer, description="webserver's HTML 500 page", examples=[OpenApiExample('500-page', {"code": 500, "message": "internal server error"})])
+
+
+DEFAULT_400_RESPONSE = OpenApiResponse(
+    CommonErrorSerializer,
+    "The server did not understand the request",
+    [
+        HTTP400_EXAMPLE
+    ],
+)
+
+
+DEFAULT_404_RESPONSE = OpenApiResponse(
+    CommonErrorSerializer,
+    "Resource not found",
+    [
+        HTTP404_EXAMPLE
+    ],
+)

dogesec_commons/utils/serializers.py

@@ -0,0 +1,47 @@
+import logging
+from rest_framework import serializers
+
+from django.core.exceptions import ObjectDoesNotExist
+from django.utils.translation import gettext_lazy as _
+
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import extend_schema_field
+
+
+
+class RelatedObjectField(serializers.RelatedField):
+    lookup_key = 'pk'
+    default_error_messages = {
+        'required': _('This field is required.'),
+        'does_not_exist': _('Invalid {lookup_key} "{lookup_value}" - object does not exist.'),
+        'incorrect_type': _('Incorrect type. Expected valid {lookup_key} value, received "{lookup_value}", type: {data_type}.'),
+    }
+    def __init__(self, /, serializer, use_raw_value=False, **kwargs):
+        self.internal_serializer: serializers.Serializer = serializer
+        self.use_raw_value = use_raw_value
+        super().__init__(**kwargs)
+
+    def to_internal_value(self, data):
+        try:
+            instance = self.get_queryset().get(**{self.lookup_key: data})
+            if self.use_raw_value:
+                return data
+            return instance
+        except ObjectDoesNotExist as e:
+            self.fail('does_not_exist', lookup_value=data, lookup_key=self.lookup_key)
+        except BaseException as e:
+            logging.exception(e)
+            self.fail('incorrect_type', data_type=type(data), lookup_value=data, lookup_key=self.lookup_key)
+        
+    def to_representation(self, value):
+        return self.internal_serializer.to_representation(value)
+
+
+@extend_schema_field(OpenApiTypes.ANY)
+class AnyField(serializers.Field):
+    pass
+
+class CommonErrorSerializer(serializers.Serializer):
+    message = serializers.CharField(required=False)
+    code    = serializers.IntegerField(required=True)
+    details = serializers.JSONField(required=False)

dogesec_commons/wsgi.py

@@ -0,0 +1,16 @@
+"""
+WSGI config for dogesec_commons project.
+
+It exposes the WSGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/5.1/howto/deployment/wsgi/
+"""
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'dogesec_commons.settings')
+
+application = get_wsgi_application()