dictature 0.9.3__py3-none-any.whl → 0.9.4__py3-none-any.whl

dictature/backend/directory.py

@@ -9,6 +9,11 @@ from .mock import DictatureTableMock, DictatureBackendMock, Value, ValueMode
 
 class DictatureBackendDirectory(DictatureBackendMock):
     def __init__(self, directory: Union[Path, str], dir_prefix: str = 'db_') -> None:
+        """
+        Create a new directory backend
+        :param directory: directory to store the data
+        :param dir_prefix: prefix for the directories of the tables
+        """
         if isinstance(directory, str):
             directory = Path(directory)
         self.__directory = directory

dictature/backend/misp.py

@@ -0,0 +1,126 @@
+from json import dumps, loads
+from re import sub
+from typing import Iterable, Optional
+
+from .mock import DictatureTableMock, DictatureBackendMock, Value, ValueMode
+
+try:
+    from pymisp import PyMISP, MISPEvent, MISPAttribute
+except ImportError as e:
+    raise ImportError("Please install the 'pymisp' package to use the 'DictatureBackendMISP' backend.") from e
+
+
+class DictatureBackendMISP(DictatureBackendMock):
+    def __init__(self, misp: PyMISP, tag_name: str = 'storage:dictature', prefix: str = 'Dictature storage: ') -> None:
+        """
+        Create a new MISP backend
+        :param misp: PyMISP instance
+        :param tag_name: tag name to use for the tables
+        :param prefix: prefix for the event names
+        """
+        self.__misp = misp
+        self.__tag_name = tag_name
+        self.__prefix = prefix
+
+    def keys(self) -> Iterable[str]:
+        for event in self.__misp.search(tags=[self.__tag_name], pythonify=True):
+            name = event.info
+            if not name.startswith(self.__prefix):
+                continue
+            yield name[len(self.__prefix):]
+
+    def table(self, name: str) -> 'DictatureTableMock':
+        return DictatureTableMISP(self.__misp, self.__prefix + name, self.__tag_name)
+
+
+class DictatureTableMISP(DictatureTableMock):
+    def __init__(self, misp: PyMISP, event_description: str, tag: str) -> None:
+        self.__misp = misp
+        self.__event_description = event_description
+        self.__tag = tag
+        self.__event: Optional[MISPEvent] = None
+
+    def keys(self) -> Iterable[str]:
+        for attribute in self.__event_attributes():
+            yield attribute.value
+
+    def drop(self) -> None:
+        self.__misp.delete_event(self.__get_event())
+
+    def create(self) -> None:
+        self.__get_event()
+
+    def set(self, item: str, value: Value) -> None:
+        save_as_json = value.mode != ValueMode.string.value or value.value.startswith('{')
+        save_data = dumps({'value': value.value, 'mode': value.mode}, indent=1) if save_as_json else value.value
+
+        for attribute in self.__event_attributes():
+            if attribute.value == item:
+                attribute.value = item
+                attribute.comment = save_data
+                self.__misp.update_attribute(attribute)
+                break
+        else:
+            attribute = MISPAttribute()
+            attribute.value = item
+            attribute.comment = save_data
+            attribute.type = 'comment'
+            attribute.to_ids = False
+            attribute.disable_correlation = True
+            self.__misp.add_attribute(self.__get_event(), attribute)
+            self.__get_event().attributes.append(attribute)
+
+    def get(self, item: str) -> Value:
+        for attribute in self.__event_attributes():
+            if attribute.value == item:
+                if attribute.comment.startswith('{'):
+                    data = loads(attribute.comment)
+                    return Value(data['value'], data['mode'])
+                return Value(attribute.comment, ValueMode.string.value)
+        raise KeyError(item)
+
+    def delete(self, item: str) -> None:
+        for attribute in self.__event_attributes():
+            if attribute.value == item:
+                # First update the attribute as deletion is not recognized immediately
+                attribute.type = 'other'
+                self.__misp.update_attribute(attribute)
+                self.__misp.delete_attribute(attribute)
+                break
+
+    def __get_event(self) -> MISPEvent:
+        if self.__event is None:
+            for event in self.__misp.search(tags=[self.__tag], eventinfo=self.__event_description, pythonify=True):
+                if event.info == self.__event_description:
+                    self.__event = event
+                    break
+            else:
+                event = MISPEvent()
+                event.info = self.__event_description
+                event.distribution = 0
+                event.threat_level_id = 4
+                event.analysis = 0
+                event.add_tag(self.__tag)
+                self.__misp.add_event(event)
+                self.__event = event
+        return self.__event
+
+    def __event_attributes(self) -> Iterable[MISPAttribute]:
+        for attribute in self.__get_event().attributes:
+            if attribute.type != 'comment' or (hasattr(attribute, 'deleted') and attribute.deleted):
+                continue
+            yield attribute
+
+    @staticmethod
+    def _record_encode(name: str, suffix: str = '.txt') -> str:
+        if name == sub(r'[^\w_. -]', '_', name):
+            return f"d_{name}{suffix}"
+        name = name.encode('utf-8').hex()
+        return f'e_{name}{suffix}'
+
+    @staticmethod
+    def _record_decode(name: str, suffix: str = '.txt') -> str:
+        encoded_name = name[2:-len(suffix) if suffix else len(name)]
+        if name.startswith('d_'):
+            return encoded_name
+        return bytes.fromhex(encoded_name).decode('utf-8')

dictature/backend/mock.py

@@ -15,27 +15,65 @@ class Value(NamedTuple):
 
 class DictatureBackendMock:
     def keys(self) -> Iterable[str]:
+        """
+        Return all table names
+        :return: all table names
+        """
         raise NotImplementedError("This method should be implemented by the subclass")
 
     def table(self, name: str) -> 'DictatureTableMock':
+        """
+        Create a table object based on the name
+        :param name: name of the table
+        :return: table object
+        """
         raise NotImplementedError("This method should be implemented by the subclass")
 
 
 class DictatureTableMock:
     def keys(self) -> Iterable[str]:
+        """
+        Return all keys in the table
+        :return: all keys in the table
+        """
         raise NotImplementedError("This method should be implemented by the subclass")
 
     def drop(self) -> None:
+        """
+        Delete the table
+        :return: None
+        """
         raise NotImplementedError("This method should be implemented by the subclass")
 
     def create(self) -> None:
+        """
+        Create the table in the backend
+        :return: None
+        """
         raise NotImplementedError("This method should be implemented by the subclass")
 
     def set(self, item: str, value: Value) -> None:
+        """
+        Set a value in the table
+        :param item: key to set
+        :param value: value to set
+        :return: None
+        """
         raise NotImplementedError("This method should be implemented by the subclass")
 
     def get(self, item: str) -> Value:
+        """
+        Get a value from the table
+        :param item: key to get
+        :return: value
+        :raises KeyError: if the key does not exist
+        """
         raise NotImplementedError("This method should be implemented by the subclass")
 
     def delete(self, item: str) -> None:
+        """
+        Delete a value from the table
+        :param item: key to delete
+        :return: None
+        """
         raise NotImplementedError("This method should be implemented by the subclass")

dictature/backend/sqlite.py

@@ -7,6 +7,10 @@ from .mock import DictatureBackendMock, DictatureTableMock, Value, ValueMode
 
 class DictatureBackendSQLite(DictatureBackendMock):
     def __init__(self, file: Union[str, Path]) -> None:
+        """
+        Create a new SQLite backend
+        :param file: file to store the database
+        """
         if isinstance(file, str):
             file = Path(file)
         self.__file = file
@@ -33,7 +37,6 @@ class DictatureBackendSQLite(DictatureBackendMock):
         self.__connection.close()
 
 
-
 class DictatureTableSQLite(DictatureTableMock):
     def __init__(self, parent: "DictatureBackendSQLite", name: str) -> None:
         self.__parent = parent

dictature/dictature.py

@@ -17,30 +17,63 @@ class Dictature:
             value_transformer: MockTransformer = PassthroughTransformer(),
             table_name_transformer: Optional[MockTransformer] = None,
     ) -> None:
+        """
+        Create a new Dictature object
+        :param backend: backend to use
+        :param name_transformer: transformer to use for table and key names
+        :param value_transformer: transformer to use for values
+        :param table_name_transformer: transformer to use for table names, if None, name_transformer is used
+        """
         self.__backend = backend
         self.__table_cache: Dict[str, "DictatureTable"] = {}
         self.__name_transformer = name_transformer
         self.__value_transformer = value_transformer
         self.__table_name_transformer = table_name_transformer or name_transformer
+        self.__cache_size = 4096
 
     def keys(self) -> Set[str]:
+        """
+        Return all table names
+        :return: all table names
+        """
         return set(map(self.__name_transformer.backward, self.__backend.keys()))
 
     def values(self) -> Iterator["DictatureTable"]:
+        """
+        Return all tables
+        :return: all tables
+        """
         return map(lambda x: x[1], self.items())
 
     def items(self) -> Iterator[Tuple[str, "DictatureTable"]]:
+        """
+        Return all tables with their instances
+        :return: all tables with their instances
+        """
         for k in self.keys():
             yield k, self[k]
 
     def to_dict(self) -> Dict[str, Any]:
+        """
+        Return all tables as a dictionary
+        :return: all tables as a dictionary
+        """
         return {k: v.to_dict() for k, v in self.items()}
 
     def __str__(self):
+        """
+        Return all tables as a string
+        :return: all tables as a string
+        """
         return str(self.to_dict())
 
     def __getitem__(self, item: str) -> "DictatureTable":
-        if len(self.__table_cache) > 128:
+        """
+        Get a table by name
+        :param item: name of the table
+        :return: table instance
+        """
+        if len(self.__table_cache) > self.__cache_size:
             del self.__table_cache[choice(list(self.__table_cache.keys()))]
         if item not in self.__table_cache:
             self.__table_cache[item] = DictatureTable(
@@ -52,12 +85,26 @@ class Dictature:
         return self.__table_cache[item]
 
     def __delitem__(self, key: str) -> None:
+        """
+        Delete a table
+        :param key: name of the table
+        :return: None
+        """
         self[key].drop()
 
     def __contains__(self, item: str) -> bool:
+        """
+        Check if a table exists
+        :param item: name of the table
+        :return: True if the table exists, False otherwise
+        """
         return item in self.keys()
 
     def __bool__(self) -> bool:
+        """
+        Check if there are any tables
+        :return: True if there are tables, False otherwise
+        """
         return not not self.keys()
 
 
@@ -69,6 +116,13 @@ class DictatureTable:
             name_transformer: MockTransformer = PassthroughTransformer(),
             value_transformer: MockTransformer = PassthroughTransformer()
     ):
+        """
+        Create a new DictatureTable object
+        :param backend: backend to use
+        :param table_name: name of the table
+        :param name_transformer:  transformer to use for key names
+        :param value_transformer: transformer to use for values
+        """
         self.__backend = backend
         self.__name_transformer = name_transformer
         self.__value_transformer = value_transformer
@@ -76,37 +130,77 @@ class DictatureTable:
         self.__table_created = False
 
     def get(self, item: str, default: Optional[Any] = None) -> Any:
+        """
+        Get a value from the table
+        :param item: key to get
+        :param default: default value to return if the key does not exist
+        :return: value or default
+        """
         try:
             return self[item]
         except KeyError:
             return default
 
     def key_exists(self, item: str) -> bool:
+        """
+        Check if a key exists
+        :param item: key to check
+        :return: True if the key exists, False otherwise
+        """
         self.__create_table()
         return item in self.keys()
 
     def keys(self) -> Set[str]:
+        """
+        Return all keys in the table
+        :return: all keys in the table
+        """
         self.__create_table()
         return set(map(self.__name_transformer.backward, self.__table.keys()))
 
     def values(self) -> Iterator[Any]:
+        """
+        Return all values in the table
+        :return: all values in the table
+        """
         return map(lambda x: x[1], self.items())
 
     def items(self) -> Iterator[Tuple[str, Any]]:
+        """
+        Return all items in the table
+        :return: all items in the table
+        """
         for k in self.keys():
             yield k, self[k]
 
     def drop(self) -> None:
+        """
+        Delete the table
+        :return: None
+        """
         self.__create_table()
         self.__table.drop()
 
     def to_dict(self) -> Dict[str, Any]:
+        """
+        Return all items as a dictionary
+        :return: all items as a dictionary
+        """
         return {k: v for k, v in self.items()}
 
     def __str__(self):
+        """
+        Return all items as a string
+        :return: all items as a string
+        """
         return str(self.to_dict())
 
     def __getitem__(self, item: str) -> Any:
+        """
+        Get a value from the table
+        :param item: key to get
+        :return: value
+        """
         self.__create_table()
         saved_value = self.__table.get(self.__item_key(item))
         mode = ValueMode(saved_value.mode)
@@ -120,6 +214,12 @@ class DictatureTable:
         raise ValueError(f"Unknown mode '{mode}'")
 
     def __setitem__(self, key: str, value: Any) -> None:
+        """
+        Set a value in the table
+        :param key: key to set
+        :param value: value to set
+        :return: None
+        """
         self.__create_table()
         value_mode = ValueMode.string
 
@@ -136,21 +236,44 @@ class DictatureTable:
         self.__table.set(key, Value(value=value, mode=value_mode.value))
 
     def __delitem__(self, key: str) -> None:
+        """
+        Delete a key from the table
+        :param key: key to delete
+        :return: None
+        """
         self.__table.delete(self.__item_key(key))
 
     def __contains__(self, item: str):
+        """
+        Check if a key exists
+        :param item: key to check
+        :return: True if the key exists, False otherwise
+        """
         return item in self.keys()
 
     def __bool__(self) -> bool:
+        """
+        Check if there are any items in the table
+        :return: True if there are items, False otherwise
+        """
         return not not self.keys()
 
     def __create_table(self) -> None:
+        """
+        Create the table if it does not exist
+        :return: None
+        """
         if self.__table_created:
             return
         self.__table.create()
         self.__table_created = True
 
     def __item_key(self, item: str) -> str:
+        """
+        Transform the key for storage
+        :param item: key to transform
+        :return: transformed key
+        """
         if not self.__name_transformer.static:
             for key in self.__table.keys():
                 if self.__name_transformer.backward(key) == item:
@@ -158,6 +281,11 @@ class DictatureTable:
         return self.__name_transformer.forward(item)
 
     def __table_key(self, table_name: str) -> str:
+        """
+        Transform the table name for storage
+        :param table_name: table name to transform
+        :return: transformed table name
+        """
         if not self.__name_transformer.static:
             for key in self.__backend.keys():
                 if self.__name_transformer.backward(key) == table_name:

dictature/transformer/aes.py

@@ -10,6 +10,12 @@ from .mock import MockTransformer
 
 class AESTransformer(MockTransformer):
     def __init__(self, passphrase: str, static_names_mode: bool, salt: str = 'dictature') -> None:
+        """
+        Create a new AES transformer
+        :param passphrase: secret passphrase to encrypt/decrypt the data
+        :param static_names_mode: if True, the transformer will use ECB mode instead of GCM (True decreases security, increases speed)
+        :param salt: salt to use for the key derivation
+        """
         self.__key = scrypt(passphrase, salt, 16, N=2 ** 14, r=8, p=1)
         self.__mode = AES.MODE_GCM if not static_names_mode else AES.MODE_ECB
         self.__static = static_names_mode

dictature/transformer/hmac.py

@@ -5,6 +5,10 @@ from .mock import MockTransformer
 
 class HmacTransformer(MockTransformer):
     def __init__(self, secret: str = 'dictature') -> None:
+        """
+        Perform HMAC on the text.
+        :param secret: secret key to use for HMAC, if not provided works as a simple hash function
+        """
         self.__secret = secret
 
     def forward(self, text: str) -> str:

dictature/transformer/mock.py

@@ -1,9 +1,25 @@
 
 class MockTransformer:
     def forward(self, text: str) -> str:
+        """
+        Transform the text in some way to the data format in data storage
+        :param text: text to transform
+        :return: transformed text
+        """
         raise NotImplementedError("This method should be implemented by the child class")
+
     def backward(self, text: str) -> str:
+        """
+        Transform the data format in data storage to the text
+        :param text: text to transform
+        :return: original text
+        """
         raise NotImplementedError("This method should be implemented by the child class")
+
     @property
     def static(self) -> bool:
+        """
+        Returns True only if when the forward transformation is applied to the same text, the result is always the same
+        :return: True if the transformation is static
+        """
         raise NotImplementedError("This method should be implemented by the child class")

dictature/transformer/passthrough.py

@@ -1,10 +1,17 @@
 from .mock import MockTransformer
 
+
 class PassthroughTransformer(MockTransformer):
+    """
+    Passthrough transformer, does not modify the text.
+    """
+
     def forward(self, text: str) -> str:
         return text
+
     def backward(self, text: str) -> str:
         return text
+
     @property
     def static(self) -> bool:
         return True

dictature/transformer/pipeline.py

@@ -5,6 +5,10 @@ from .mock import MockTransformer
 
 class PipelineTransformer(MockTransformer):
     def __init__(self, transformers: List[MockTransformer]) -> None:
+        """
+        Create a pipeline of transformers. The text is passed through each transformer in the order they are provided.
+        :param transformers: list of transformers to use
+        """
         self.__transformers = transformers
 
     def forward(self, text: str) -> str:

{dictature-0.9.3.dist-info → dictature-0.9.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dictature
-Version: 0.9.3
+Version: 0.9.4
 Summary: dictature -- A generic wrapper around dict-like interface with mulitple backends
 Author-email: Adam Hlavacek <git@adamhlavacek.com>
 Project-URL: Homepage, https://github.com/esoadamo/dictature
@@ -53,6 +53,7 @@ del dictionary['test']  # drops whole table
 Currently, the following backends are supported:
 - `DictatureBackendDirectory`: stores the data in a directory as json files
 - `DictatureBackendSQLite`: stores the data in a SQLite database
+- `DictatureBackendMISP`: stores the data in a MISP instance
 
 ### Transformers
 
@@ -73,3 +74,9 @@ dictionary = Dictature(
     value_transformer=value_transformer
 )
 ```
+
+Currently, the following transformers are supported:
+- `AESTransformer`: encrypts/decrypts the data using AES
+- `HmacTransformer`: signs the data using HMAC or performs hash integrity checks
+- `PassthroughTransformer`: does nothing
+- `PipelineTransformer`: chains multiple transformers

dictature-0.9.4.dist-info/RECORD

@@ -0,0 +1,18 @@
+dictature/__init__.py,sha256=UCPJKHeyirRZ0pCYoyeat-rwXa8pDezOJ3UWCipDdyc,33
+dictature/dictature.py,sha256=VM4RcXftQl2cFY8GxsRl7h3K8tsH7urNoT7GyGsxGuo,9314
+dictature/backend/__init__.py,sha256=d5s6QCJOUzFglVNg8Cqqx_8b61S-AOTGjEUIF6FS69U,149
+dictature/backend/directory.py,sha256=Wf6dtllkqVA70DsnFoFzEHi_-RrTeOwqX5TFU-mYjrk,3451
+dictature/backend/misp.py,sha256=ZT392TkAkoP1fB5ZXjArD1Vsm00hvvq08msCv6QXbh8,4971
+dictature/backend/mock.py,sha256=Bllai6uZ1cRL8mKLbB3YQQo26mxTFepqzGu3FfOL1d4,2183
+dictature/backend/sqlite.py,sha256=zyphYEeLY4eGuBCor16i80_-brdipMpXZ3_kONwErsE,5237
+dictature/transformer/__init__.py,sha256=JIFJpXU6iB9hIUM8L7HL2o9Nqjm_YbMEuQBQC8ZJ6b4,124
+dictature/transformer/aes.py,sha256=ZhC1dT9QpnziErkDLriWLgXDEFNGQW0KG4aqSN2AZpA,1926
+dictature/transformer/hmac.py,sha256=vURsB0HlzRPn_Vkl7lGmZV9OKempQuds8AanmadDxIo,834
+dictature/transformer/mock.py,sha256=7zu65ZqUV_AVRaPSzNd73cVMXixXt31SeuX9OKZxaJQ,948
+dictature/transformer/passthrough.py,sha256=Pt3N6G_Qh6HJ_q75ETL5nfAwYHLB-SjkVwUwbbbMik8,344
+dictature/transformer/pipeline.py,sha256=OaQaJeJ5NpICetJe08r8ontqstsXGuW8jDbKw1zxYs4,842
+dictature-0.9.4.dist-info/LICENSE,sha256=n1U9DKr8sM5EY2QHcvxSGiKTDWUT8MyXsOC79w94MT0,1072
+dictature-0.9.4.dist-info/METADATA,sha256=QklI5x9PnsuJZ-6jIcFskCDxSVveI3le5IJSIh_8E4Q,2826
+dictature-0.9.4.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+dictature-0.9.4.dist-info/top_level.txt,sha256=-RO39WWCF44lqiXhSUcACVqbk6SkgReZTz7ZmHKH3-U,10
+dictature-0.9.4.dist-info/RECORD,,

dictature-0.9.3.dist-info/RECORD

@@ -1,17 +0,0 @@
-dictature/__init__.py,sha256=UCPJKHeyirRZ0pCYoyeat-rwXa8pDezOJ3UWCipDdyc,33
-dictature/dictature.py,sha256=eFjUc5Q1DUXLNqk-UeHzFqWgCZppTsoK3TXCJ1UuCS8,5666
-dictature/backend/__init__.py,sha256=d5s6QCJOUzFglVNg8Cqqx_8b61S-AOTGjEUIF6FS69U,149
-dictature/backend/directory.py,sha256=KVbKS1CibXmY1NsZRWuTE0uC4DXRLOXqYEHxyHJidCc,3266
-dictature/backend/mock.py,sha256=Qd7KSh-qM763Jc7biDf5xYFWdgDax30dUHh2gXWwTZE,1266
-dictature/backend/sqlite.py,sha256=aExNxDtx1kiPrZn-jfCzbpV4alEXyGc6f12tuCJK1tk,5130
-dictature/transformer/__init__.py,sha256=JIFJpXU6iB9hIUM8L7HL2o9Nqjm_YbMEuQBQC8ZJ6b4,124
-dictature/transformer/aes.py,sha256=6H3jNkUpgWBX88BduMzbi9MDSRxMHnWmZZEIJ70BLi0,1601
-dictature/transformer/hmac.py,sha256=pYw6ybUIMoNdU2JFI9ffePr-33ails-CN9J6rFt7RVE,677
-dictature/transformer/mock.py,sha256=osETvYZjlgos0trJy0YvXcmtNy0L6x2h2099t1aHMFc,421
-dictature/transformer/passthrough.py,sha256=63hZCPQMUJa-G6ZKdv_xt2fMiMZpmPoL84PY5eb2ueE,269
-dictature/transformer/pipeline.py,sha256=-2r9FxLXEnk3qpCfXC0qp0KqNC2qkpChCJYEbZAQRYM,642
-dictature-0.9.3.dist-info/LICENSE,sha256=n1U9DKr8sM5EY2QHcvxSGiKTDWUT8MyXsOC79w94MT0,1072
-dictature-0.9.3.dist-info/METADATA,sha256=BPA99McqtwhQxjALGLwrWvaZiqRx3XHnjYZ5tEfxYIk,2478
-dictature-0.9.3.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
-dictature-0.9.3.dist-info/top_level.txt,sha256=-RO39WWCF44lqiXhSUcACVqbk6SkgReZTz7ZmHKH3-U,10
-dictature-0.9.3.dist-info/RECORD,,