[doc] Rha/add sphinx doc (#87)

* Add docstrings to api

* Add more docstrings for api jobs

* More docstrings

* More docstring update

Author: rhaist

pycti/connector/opencti_connector.py

@@ -19,6 +19,19 @@ class ConnectorType(Enum):
 
 
 class OpenCTIConnector:
+    """Main class for OpenCTI connector
+
+    :param connector_id: id for the connector (valid uuid4)
+    :type connector_id: str
+    :param connector_name: name for the connector
+    :type connector_name: str
+    :param connector_type: valid OpenCTI connector type (see `ConnectorType`)
+    :type connector_type: str
+    :param scope: connector scope
+    :type scope: str
+    :raises ValueError: if the connector type is not valid
+    """
+
     def __init__(
         self, connector_id: str, connector_name: str, connector_type: str, scope: str
     ):
@@ -29,7 +42,12 @@ def __init__(
             raise ValueError("Invalid connector type: " + connector_type)
         self.scope = scope.split(",")
 
-    def to_input(self):
+    def to_input(self) -> dict:
+        """connector input to use in API query
+
+        :return: dict with connector data
+        :rtype: dict
+        """
         return {
             "input": {
                 "id": self.id,

pycti/connector/opencti_connector_helper.py

@@ -469,7 +469,15 @@ def stix2_get_embedded_objects(self, item) -> dict:
             "created_by_ref": created_by_ref,
         }
 
-    def stix2_get_entity_objects(self, entity):
+    def stix2_get_entity_objects(self, entity) -> list:
+        """process a stix2 entity
+
+        :param entity: valid stix2 entity
+        :type entity:
+        :return: entity objects as list
+        :rtype: list
+        """
+
         items = [entity]
         # Get embedded objects
         embedded_objects = self.stix2_get_embedded_objects(entity)
@@ -482,7 +490,15 @@ def stix2_get_entity_objects(self, entity):
 
         return items
 
-    def stix2_get_relationship_objects(self, relationship):
+    def stix2_get_relationship_objects(self, relationship) -> list:
+        """get a list of relations for a stix2 relationship object
+
+        :param relationship: valid stix2 relationship
+        :type relationship:
+        :return: list of relations objects
+        :rtype: list
+        """
+
         items = [relationship]
         # Get source ref
         if relationship["source_ref"] in self.cache_index:
@@ -503,7 +519,15 @@ def stix2_get_relationship_objects(self, relationship):
 
         return items
 
-    def stix2_get_report_objects(self, report):
+    def stix2_get_report_objects(self, report) -> list:
+        """get a list of items for a stix2 report object
+
+        :param report: valid stix2 report object
+        :type report:
+        :return: list of items for a stix2 report object
+        :rtype: list
+        """
+
         items = [report]
         # Add all object refs
         for object_ref in report["object_refs"]:
@@ -516,7 +540,15 @@ def stix2_get_report_objects(self, report):
         return items
 
     @staticmethod
-    def stix2_deduplicate_objects(items):
+    def stix2_deduplicate_objects(items) -> list:
+        """deduplicate stix2 items
+
+        :param items: valid stix2 items
+        :type items:
+        :return: de-duplicated list of items
+        :rtype: list
+        """
+
         ids = []
         final_items = []
         for item in items:
@@ -527,6 +559,14 @@ def stix2_deduplicate_objects(items):
 
     @staticmethod
     def stix2_create_bundle(items):
+        """create a stix2 bundle with items
+
+        :param items: valid stix2 items
+        :type items:
+        :return: JSON of the stix2 bundle
+        :rtype:
+        """
+
         bundle = {
             "type": "bundle",
             "id": "bundle--" + str(uuid.uuid4()),
@@ -536,7 +576,17 @@ def stix2_create_bundle(items):
         return json.dumps(bundle)
 
     @staticmethod
-    def check_max_tlp(tlp, max_tlp):
+    def check_max_tlp(tlp, max_tlp) -> list:
+        """check the allowed TLP levels for a TLP string
+
+        :param tlp: string for TLP level to check
+        :type tlp: str
+        :param max_tlp: the highest allowed TLP level
+        :type max_tlp: str
+        :return: list of allowed TLP levels
+        :rtype: list
+        """
+
         allowed_tlps = ["TLP:WHITE"]
         if max_tlp == "TLP:RED":
             allowed_tlps = ["TLP:WHITE", "TLP:GREEN", "TLP:AMBER", "TLP:RED"]

pycti/utils/constants.py

@@ -6,8 +6,11 @@
 
 class ObservableTypes(Enum):
     """These are the possible values for OpenCTI's observable types.
-    Use in conjuction with the STIX custom property 'x_opencti_observable_type'.
+
+    Use in conjunction with the STIX custom property `x_opencti_observable_type`.
+
     ref: https://github.com/OpenCTI-Platform/opencti/blob/8854c2576dc17da9da54e54b116779bd2131617c/opencti-front/src/private/components/report/ReportAddObservable.js
+
     NOTE: should this be a mapping between the stix2 SDO objects (i.e. stix2/v20/sdo.py)?
     """
 
@@ -69,8 +72,7 @@ def has_value(cls, value):
 
 
 class CustomProperties:
-    """These are the custom properies used by OpenCTI.
-
+    """These are the custom properties used by OpenCTI.
     """
 
     # internal id used by OpenCTI - this will be auto generated

pycti/utils/opencti_stix2.py

@@ -45,10 +45,26 @@ def unknown_type(self, stix_object):
             'Unknown object type "' + stix_object["type"] + '", doing nothing...',
         )
 
-    def convert_markdown(self, text):
+    def convert_markdown(self, text) -> str:
+        """converts input text to markdown style code annotation
+
+        :param text: input text
+        :type text: str
+        :return: sanitized text with markdown style code annotation
+        :rtype: str
+        """
+
         return text.replace("<code>", "`").replace("</code>", "`")
 
     def format_date(self, date):
+        """converts multiple input date formats to OpenCTI style dates
+
+        :param date: input date
+        :type date:
+        :return: OpenCTI style date
+        :rtype: datetime
+        """
+
         if isinstance(date, datetime.date):
             return date.isoformat(timespec="milliseconds").replace("+00:00", "Z")
         if date is not None:
@@ -64,15 +80,33 @@ def format_date(self, date):
                 .replace("+00:00", "Z")
             )
 
-    def filter_objects(self, uuids, objects):
+    def filter_objects(self, uuids: list, objects: list) -> list:
+        """filters objects based on UUIDs
+
+        :param uuids: list of UUIDs
+        :type uuids: list
+        :param objects: list of objects to filter
+        :type objects: list
+        :return: list of filtered objects
+        :rtype: list
+        """
+
         result = []
         if objects is not None:
-            for object in objects:
-                if "id" in object and object["id"] not in uuids:
-                    result.append(object)
+            for item in objects:
+                if "id" in item and item["id"] not in uuids:
+                    result.append(item)
         return result
 
-    def pick_aliases(self, stix_object):
+    def pick_aliases(self, stix_object) -> list:
+        """check stix2 object for multiple aliases and return a list
+
+        :param stix_object: valid stix2 object
+        :type stix_object:
+        :return: list of aliases
+        :rtype: list
+        """
+
         # Add aliases
         if CustomProperties.ALIASES in stix_object:
             return stix_object[CustomProperties.ALIASES]
@@ -85,8 +119,18 @@ def pick_aliases(self, stix_object):
         return None
 
     def check_max_marking_definition(
-        self, max_marking_definition_entity, entity_marking_definitions
-    ):
+        self, max_marking_definition_entity: str, entity_marking_definitions: list
+    ) -> bool:
+        """checks if a list of marking definitions conforms with a given max level
+
+        :param max_marking_definition_entity: the maximum allowed marking definition level
+        :type max_marking_definition_entity: str, optional
+        :param entity_marking_definitions: list of entities to check
+        :type entity_marking_definitions: list
+        :return: `True` if the list conforms with max marking definition
+        :rtype: bool
+        """
+
         # Max is not set, return True
         if max_marking_definition_entity is None:
             return True
@@ -111,7 +155,19 @@ def check_max_marking_definition(
                 return True
         return False
 
-    def import_bundle_from_file(self, file_path, update=False, types=None):
+    def import_bundle_from_file(self, file_path: str, update=False, types=None) -> List:
+        """import a stix2 bundle from a file
+
+        :param file_path: valid path to the file
+        :type file_path: str
+        :param update: whether to updated data in the database, defaults to False
+        :type update: bool, optional
+        :param types: list of stix2 types, defaults to None
+        :type types: list, optional
+        :return: list of imported stix2 objects
+        :rtype: List
+        """
+
         if types is None:
             types = []
         if not os.path.isfile(file_path):
@@ -124,12 +180,34 @@ def import_bundle_from_file(self, file_path, update=False, types=None):
         return self.import_bundle(data, update, types)
 
     def import_bundle_from_json(self, json_data, update=False, types=None) -> List:
+        """import a stix2 bundle from JSON data
+
+        :param json_data: JSON data
+        :type json_data:
+        :param update: whether to updated data in the database, defaults to False
+        :type update: bool, optional
+        :param types: list of stix2 types, defaults to None
+        :type types: list, optional
+        :return: list of imported stix2 objects
+        :rtype: List
+        """
+
         if types is None:
             types = []
         data = json.loads(json_data)
         return self.import_bundle(data, update, types)
 
-    def extract_embedded_relationships(self, stix_object, types=None):
+    def extract_embedded_relationships(self, stix_object, types=None) -> dict:
+        """extracts embedded relationship objects from a stix2 entity
+
+        :param stix_object: valid stix2 object
+        :type stix_object:
+        :param types: list of stix2 types, defaults to None
+        :type types: list, optional
+        :return: embedded relationships as dict
+        :rtype: dict
+        """
+
         # Created By Ref
         created_by_ref_id = None
         if "created_by_ref" in stix_object:
@@ -381,7 +459,19 @@ def extract_embedded_relationships(self, stix_object, types=None):
             "reports": reports,
         }
 
-    def import_object(self, stix_object, update=False, types=None):
+    def import_object(self, stix_object, update=False, types=None) -> list:
+        """import a stix2 object
+
+        :param stix_object: valid stix2 object
+        :type stix_object:
+        :param update: whether to updated data in the database, defaults to False
+        :type update: bool, optional
+        :param types: list of stix2 types, defaults to None
+        :type types: list, optional
+        :return: list of imported stix2 objects
+        :rtype: list
+        """
+
         self.opencti.log(
             "info",
             "Importing a " + stix_object["type"] + " (id: " + stix_object["id"] + ")",