stormlibpp 0.1.2__tar.gz → 0.3.0__tar.gz

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: stormlibpp
-Version: 0.1.2
+Version: 0.3.0
 Summary: The stormlibpp Python package
 Author: John Gorman
 License: MIT License

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stormlibpp"
-version = "0.1.2"
+version = "0.3.0"
 description = "The stormlibpp Python package"
 readme = "README.md"
 requires-python = ">=3.11"

stormlibpp-0.3.0/src/stormlibpp/__init__.py

@@ -0,0 +1,38 @@
+"""The stormlibpp Python Package.
+
+StormLib++ provides a number of Python objects to make life as a Synapse/Storm
+developer easier.
+
+StormLib++ provides several useful utility functions in ``utils``.
+
+StormLib++ errors can be found in ``errors``. Each componenent of StormLib++
+uses these errors their own way. Information our how they're used can be found
+in those components.
+
+``StormPkg`` is a helper class that represents a Storm package in memory. It
+can read a package prototype from a default (or configured) location, convert
+it to a package definition, optionally check the Storm code's syntax (enabled
+by default), and store a Python dict containing the Storm package's definition.
+
+``StormPkg`` also provides some helpful properties to describe the Storm
+package's configuration (`cmds`, `mods`, `pkg_guid`, `pkg_name`, `pkg_ver`, `storm`).
+
+There are also several submodules not directly imported by ``stormlibpp`` at
+init. However, some classes/functions from these submodules are. The submodules
+are briefly described below:
+
+- ``telepath`` has methods and classes for working with Telepath endpoints.
+  It currently contains mostly classes for describing standard Telepath API
+  return values.
+
+- ``stormpkg`` defines the ``StormPkg`` class.
+
+"""
+
+__version__ = "0.3.0"
+
+from . import errors
+from . import utils
+from .node import StormNode
+from .stormpkg import StormPkg
+from .telepath import (genDefaultTelepathRetn, TelepathRetn)

stormlibpp-0.3.0/src/stormlibpp/node.py

@@ -0,0 +1,197 @@
+"""Work with storm:node objects in Python."""
+
+
+from types import SimpleNamespace
+from typing import Any, Self, TypedDict
+
+
+NodeForm = str
+"""A valid syn:form value."""
+
+
+class NodeVals(TypedDict):
+    """The items a Node can have in the second part of packed NodeTuple."""
+
+    iden: str
+    nodedata: dict[str, Any]
+    props: dict[str, Any]
+    tags: dict[str, Any]
+    tagprops: dict[str, Any]
+
+
+NodeDef = tuple[NodeForm, str]
+"""A nodes definition, the node's form and primary value."""
+
+NodeTuple = tuple[NodeDef, NodeVals]
+"""A packed node, this is what get's sent from Storm to a Telepath endpoint.
+
+Or what get's returned from a Cortex's Python APIs.
+"""
+
+
+class ItemContainer:
+    """Hold key/value items in a SimpleNamespace.
+
+    Keys must be strings.
+
+    Supports ``obj['item']`` (and ``obj['item'] = 'val'``) notation.
+
+    When "getting" an item with ``__getitem__``, that doesn't exist in the
+    container, ``None`` is returned instead of raising an exception.
+
+    Calling ``dir`` on this object will only return names for items this object
+    "holds" instead of all parts of this object.
+
+    Supports checking if an item is "held" via the ``in`` operator.
+
+    Supports iteration of items in the SimpleNamespace. Each iteration returns
+    a tuple of the item name followed by the item value.
+
+    Implements only magic methods, and all of them operate on the underlying
+    SimpleNamespace. To convert this object to a ``dict`` of the items it holds,
+    call ``vars`` on an instance.
+    """
+
+    def __init__(self, /, **kwargs) -> None:
+        self.__ns = SimpleNamespace(**kwargs)
+    
+    def __contains__(self, __name: str) -> bool:
+        return __name in dir(self)
+
+    @property
+    def __dict__(self):
+        return self.__ns.__dict__
+
+    def __dir__(self) -> list[str]:
+        return [val for val in dir(self.__ns) if not val.startswith("_")]
+
+    def __iter__(self) -> Any:
+        for item in dir(self):
+            yield (item, self[item])
+
+    def __getitem__(self, __name: str) -> Any:
+        return getattr(self.__ns, __name, None)
+
+    def __repr__(self) -> str:
+        return repr(self.__ns).replace("namespace", self.__class__.__name__)
+
+    def __setitem__(self, __name: str, __value: str) -> None:
+        setattr(self.__ns, __name, __value)
+
+
+class Props(ItemContainer):
+    """Properties of a StormNode."""
+
+
+class Tags(ItemContainer):
+    """Tags of a StormNode."""
+
+
+
+class StormNode:
+    """A storm:node Storm object that is in a Python runtime.
+
+    It supports "unpacking" the node into this object, edits to the object, and
+    repacking of the node to be sent back to Storm.
+
+    This node can be created purely from Python code rather than a packed
+    ``storm:node`` object. Use the ``__init__`` directly instead of ``unpack``.
+    This allows the creation of a new node in Python that can be passed back to
+    Storm.
+
+    The intent is to represent an object that can be read from and written back
+    to a Cortex. It isn't meant to provide the same API that a ``storm:node``
+    has in Storm.
+    """
+
+    def __init__(
+        self,
+        form: NodeForm,
+        value: Any,
+        /,
+        iden: str = "",
+        tags: dict = {},
+        props: dict = {},
+        nodedata: dict = {},
+        tagprops: dict = {},
+        **kwargs,
+    ) -> None:
+
+        self._form = form
+        self._value = value
+
+        self._tags = Props(**tags)
+        self._props = Tags(**props)
+
+        self.iden = iden
+        self.nodedata = nodedata
+        self.tagprops = tagprops
+
+        # Not really sure if this is needed, but saving it for now.
+        self._xtras = kwargs
+
+    @property
+    def form(self) -> str:
+        """The form of this Node."""
+
+        return self._form
+
+    @property
+    def value(self) -> str:
+        """The value of this Node."""
+
+        return self._value
+
+    @property
+    def tags(self):
+        """The tags of this Node."""
+
+        return self._tags
+
+    @property
+    def props(self):
+        """The properties of this Node."""
+
+        return self._props
+
+    @property
+    def nodevals(self):
+        """The NodeVals dict this Node would have in a NodeTuple."""
+
+        return NodeVals(
+            iden=self.iden,
+            tagprops=self.tagprops,
+            nodedata=self.nodedata,
+            props=vars(self.props),
+            tags=vars(self.tags),
+        )
+
+    @classmethod
+    def unpack(cls, packedtup: NodeTuple) -> Self:
+        form, name = packedtup[0]
+        vals = NodeVals(**packedtup[1])
+        return cls(
+            form,
+            name,
+            **vals
+        )
+
+    def pack(self) -> NodeTuple:
+        return ((self.form, self.value), self.nodevals)
+
+    def addTag(self, tag, timestamps: tuple = (None, None)) -> None:
+        if tag in self._tags and timestamps != (None, None) and self._tags[tag] != timestamps:
+            self._tags[tag] = timestamps
+        elif tag not in self._tags:
+            self._tags[tag] = timestamps
+
+    def addTags(self, tags, timestamps: tuple = (None, None)) -> None:
+        for tag in tags:
+            self.addTag(tag, timestamps=timestamps)
+
+    def addProp(self, propname: str, propval: Any) -> None:
+        self._props[propname] = propval
+
+    def addProps(self, props: dict[str, Any]) -> None:
+        for propname, propval in props.items():
+            self._props[propname] = propval

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/src/stormlibpp/stormpkg.py

@@ -5,8 +5,11 @@ import json
 import os
 import sys
 
+import synapse.common as s_common
+import synapse.exc as s_exc
+import synapse.tools.genpkg as s_genpkg
+
 from . import errors
-from . import s_common, s_exc, s_genpkg
 from . import utils
 
 
@@ -50,6 +53,10 @@ class StormPkg:
 
     - Stores the package definition ``dict`` in the ``pkdef`` property.
 
+    - If ``check_syntax`` is True, all Storm code that is loaded in the ``pkdef``
+      is passed to Synapse's Storm parser to check for Storm syntax errors.
+      Any errors are raised as a ``StormPkgSyntaxError`` exception.
+
     Parameters
     ----------
     check_syntax : bool, optional
@@ -62,6 +69,9 @@ class StormPkg:
 
     Properties
     ----------
+    default_name : str
+        The Yaml basename used if ``proto_name`` is empty (not set).
+        Set to the value of ``self.__class__.__name__.lower()``.
     pkgdef : dict
         The loaded Storm package definition.
     proto_dir : str
@@ -71,12 +81,11 @@ class StormPkg:
         at init, finding the object this resolves to in ``sys.modules``,
         and reading the module's ``__file__``. Then joining this file's
         dir name with the value ``pkgproto``.
-    proto_name : str | None
+    proto_name : str
         A class property containing the name of the Storm package's proto
         Yaml file (without extension). Subclasses may override this class
         property to set a custom proto Yaml file basename. If they don't,
-        this property is automatically set to the value of
-        ``self.__class__.__name__.lower()``.
+        this property is automatically set to the value of ``self.default_name``.
 
     Raises
     ------
@@ -84,16 +93,19 @@ class StormPkg:
         If the package proto either has an invalid schema or bad value.
     StormPkgNoProtoError
         If the proto Yaml file cannot be loaded. This can happen if the file name
-        will not match ``name``/``pkg_name`` but ``proto_name`` is not passed.
+        will not match ``self.default_name`` but ``proto_name`` is not set.
     StormPkgResolveError
         If the default package proto dir cannot be resolved. This can be the case
         if a `StormPkg` is created and doesn't expect to use the default proto dir
         but a custom ``proto_dir`` is not passed.
+    StormPkgSyntaxError
+        If ``check_syntax`` is True and the Storm code in this package has syntax errors.
     RuntimeError
         If this class is instantiated directly and not subclassed.
     """
 
     proto_name: str | None = None
+    """The basename of this Storm package's Yaml proto file."""
 
     def __init__(
         self,
@@ -103,6 +115,10 @@ class StormPkg:
         if StormPkg not in self.__class__.__bases__:
             raise RuntimeError("StormPkg must be subclassed.")
 
+        self.default_name = self.__class__.__name__.lower()
+        if not self.proto_name:
+            self.proto_name = self.default_name
+
         if proto_dir:
             self.proto_dir = proto_dir
         else:
@@ -119,10 +135,10 @@ class StormPkg:
                 "pkgproto",
             )
 
-        if not self.proto_name:
-            self.proto_name = self.__class__.__name__.lower()
-
-        self.proto = os.path.join(self.proto_dir, f"{self.proto_name}.yaml",)
+        self.proto = os.path.join(
+            self.proto_dir,
+            f"{self.proto_name}.yaml",
+        )
 
         self.pkgdef = self._load_proto()
         """A Python dict containing the full Storm package definition."""
@@ -156,15 +172,6 @@ class StormPkg:
 
         return pkgdef
 
-    def _search_def(self, primkey: str, seckey: str) -> list[str]:
-        """Search the modules or commands of the pkgdef for a secondary key."""
-
-        vals = []
-        for val in self.pkgdef.get(primkey, []):
-            if seckey in val:
-                vals.append(val[seckey])
-        return vals
-
     def asdict(self):
         """Return this objects full Storm package definition as a Python dict.
 
@@ -193,19 +200,19 @@ class StormPkg:
                     f"syntax error: {err}"
                 ) from err
 
-    def cmds(self) -> list[str]:
-        """The commands this package defines."""
+    def cmds(self) -> list[dict]:
+        """The full definitions of the commands this package defines."""
 
-        return self._search_def("commands", "name")
+        return self.pkgdef.get("commands", [])
 
-    def mods(self) -> list[str]:
-        """The modules this package defines."""
+    def mods(self) -> list[dict]:
+        """The full definitions of the modules this package defines."""
 
-        return self._search_def("modules", "name")
+        return self.pkgdef.get("modules", [])
 
     def storm(self) -> dict[str, str]:
         """The Storm code this package defines.
-        
+
         Returns
         -------
         dict[str, str]
@@ -213,10 +220,37 @@ class StormPkg:
         """
 
         storm = {}
-        for mod in self.pkgdef.get("modules", []):
-            if "name" in mod and "storm" in mod:
-                storm[mod["name"]] = mod["storm"]
-        for cmd in self.pkgdef.get("commands", []):
-            if "name" in cmd and "storm" in cmd:
-                storm[cmd["name"]] = cmd["storm"]
+        for item in self.cmds() + self.mods():
+            if "name" in item and "storm" in item:
+                storm[item["name"]] = item["storm"]
         return storm
+
+    @property
+    def cmdnames(self) -> list[str]:
+        """The names of the commands this package defines, if any."""
+
+        return [cmd.get("name") for cmd in self.cmds() if "name" in cmd]
+
+    @property
+    def modnames(self) -> list[str]:
+        """The names of the modules this package defines, if any."""
+
+        return [mod.get("name") for mod in self.mods() if "name" in mod]
+
+    @property
+    def pkg_guid(self) -> str:
+        """The package's guid, None if not set."""
+
+        return self.pkgdef.get("guid")
+
+    @property
+    def pkg_name(self) -> str:
+        """The package's name, None if not set."""
+
+        return self.pkgdef.get("name")
+
+    @property
+    def pkg_ver(self) -> str:
+        """The package's version, None if not set."""
+
+        return self.pkgdef.get("version")

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/src/stormlibpp/telepath.py

@@ -36,3 +36,8 @@ def genDefaultTelepathRetn(obj=TelepathRetn, /, default_data=None) -> TelepathRe
     """
 
     return obj(status=True, mesg="", data=default_data)
+
+
+class BoolRetn(TelepathRetn):
+    """A TelepathRetn where ``data`` is a boolean value."""
+    data: bool

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/src/stormlibpp/utils.py

@@ -3,8 +3,10 @@
 
 import os
 
+import synapse.exc as s_exc
+import synapse.lib.parser as s_parser
+
 from . import errors
-from . import s_exc, s_parser
 
 
 def absjoin(*paths: str) -> str:
@@ -12,7 +14,7 @@ def absjoin(*paths: str) -> str:
 
     Parameters
     ----------
-    *paths : str
+    paths : list[str]
         The path strings to join together, as would be passed to ``os.path.join``.
 
     Returns

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/src/stormlibpp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: stormlibpp
-Version: 0.1.2
+Version: 0.3.0
 Summary: The stormlibpp Python package
 Author: John Gorman
 License: MIT License

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/src/stormlibpp.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 src/stormlibpp/__init__.py
 src/stormlibpp/errors.py
+src/stormlibpp/node.py
 src/stormlibpp/stormpkg.py
 src/stormlibpp/telepath.py
 src/stormlibpp/utils.py
@@ -11,6 +12,7 @@ src/stormlibpp.egg-info/SOURCES.txt
 src/stormlibpp.egg-info/dependency_links.txt
 src/stormlibpp.egg-info/requires.txt
 src/stormlibpp.egg-info/top_level.txt
+tests/test_node.py
 tests/test_stormpkg.py
 tests/test_telepath.py
 tests/test_utils.py

stormlibpp-0.3.0/tests/test_node.py

@@ -0,0 +1,43 @@
+"""Tests for stormlibpp.node."""
+
+
+import stormlibpp
+
+
+PACKED_NODE = (('it:app:yara:rule', '5d0292d99a7da59a3a119e193f140143'), {'iden': '57ce731580ed6976b608e87dfc7f2ece81790f2cb8cdaf958013c738b28cd56e', 'tags': {'test': (None, None), 'test.tag': (None, None)}, 'props': {'.created': 1687720565352, 'text': 'rule dummy { condition: true }', 'name': 'dummy', 'enabled': 1}, 'tagprops': {}, 'nodedata': {}})
+
+
+class TestNode:
+
+    def test_packing(self):
+        node = stormlibpp.StormNode.unpack(PACKED_NODE)
+        assert node.pack() == PACKED_NODE
+
+    def test_add_tags(self):
+        tags = ["#test.othertag", "#atag"]
+        node = stormlibpp.StormNode.unpack(PACKED_NODE)
+        node.addTags(tags)
+
+        for tag in tags:
+            assert tag in node.tags
+
+        assert dir(node.tags) == [item[0] for item in iter(node.tags)]
+
+    def test_add_props(self):
+        props = {'prop': 'test', 'other': 'value'}
+        node = stormlibpp.StormNode.unpack(PACKED_NODE)
+        node.addProps(props)
+
+        for prop in props:
+            assert prop in node.props
+
+        for propname, propval in node.props:
+            if propname in props:
+                assert props[propname] == propval
+
+    def test_values(self):
+        node = stormlibpp.StormNode.unpack(PACKED_NODE)
+        
+        assert node.form == PACKED_NODE[0][0]
+        assert node.value == PACKED_NODE[0][1]
+        assert node.nodevals == PACKED_NODE[1]

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/tests/test_stormpkg.py

@@ -47,6 +47,7 @@ class TestStormPkg:
 
         assert isinstance(test.asdict(), dict)
         assert isinstance(othertest.pkgdef, dict)
+        assert "othertest.lib" in othertest.modnames
 
     def test_storm_parse(self):
         class BadStorm(stormlibpp.StormPkg):
@@ -59,4 +60,4 @@ class TestStormPkg:
         class BadStorm(stormlibpp.StormPkg):
             pass
 
-        assert "badstorm" in BadStorm(check_syntax=False).cmds()
+        assert "badstorm" in BadStorm(check_syntax=False).cmdnames

{stormlibpp-0.1.2 → stormlibpp-0.3.0}/tests/test_telepath.py

@@ -16,3 +16,11 @@ class TestTelepathRetn:
     def test_gen_telepath_ret_opts(self):
         ret = stormlibpp.genDefaultTelepathRetn(SubTeleRet, default_data="default")
         assert ret == dict(status=True, mesg="", data="default")
+
+
+class TestCustomRetns:
+    def test_gen_boolretn(self):
+        ret = stormlibpp.genDefaultTelepathRetn(
+            stormlibpp.telepath.BoolRetn, default_data=False
+        )
+        assert ret == dict(status=True, mesg="", data=False)

stormlibpp-0.1.2/src/stormlibpp/__init__.py

@@ -1,25 +0,0 @@
-"""The stormlibpp Python Package.
-
-StormLib++ provides a number of Python objects to make life as a Synapse/Storm
-developer easier.
-
-It also exposes a few of Synapses submodles with the following name mappings::
-
-    synapse.common -> s_common
-    synapse.exc -> s_exc
-    synapse.genpkg -> s_genpkg
-
-"""
-
-__version__ = "0.1.2"
-
-
-import synapse.common as s_common
-import synapse.exc as s_exc
-import synapse.tools.genpkg as s_genpkg
-import synapse.lib.parser as s_parser
-
-from . import errors
-from . import utils
-from .stormpkg import StormPkg
-from .telepath import (genDefaultTelepathRetn, TelepathRetn)