Merge branch 'main' into issue_5_message_thread

Author: ajnelson-nist

.github/workflows/ci.yml

@@ -24,14 +24,17 @@ jobs:
 
       - name: Install Dependencies
         run: |
-          pip -q install poetry pre-commit
+          pip -q install poetry pre-commit rdflib
           poetry install
 
       - name: Pre-commit Checks
         run: pre-commit run --all-files
 
+      - name: Type Checking
+        run: poetry run mypy case_mapping example.py tests
+
       - name: Unit Tests
-        run: poetry run pytest
+        run: poetry run pytest --doctest-modules
 
       - name: Run Example
         run: poetry run python example.py > case.jsonld
@@ -44,6 +47,11 @@ jobs:
           case-version: "case-1.3.0"
           extension-filter: "jsonld"
 
+      - name: Convert example
+        run: |
+          rdfpipe --output-format turtle case.jsonld > case.ttl
+          test 0 -eq $(grep 'file:' case.ttl | wc -l) || (echo "ERROR:ci.yml:Some graph IRIs do not supply a resolving prefix.  Look for the string 'file:///' in the file case.ttl (created by running 'make check') to see these instances." >&2 ; exit 1)
+
       # Always build the package as a sanity check to ensure no issues with the build system
       # exist as part of the CI process
       - name: Build Package

.gitignore

@@ -19,3 +19,4 @@ __pycache__/
 # Build Artifacts
 build/
 dist/
+case.ttl

Makefile

@@ -34,6 +34,9 @@ all: \
   .venv-pre-commit/var/.pre-commit-built.log \
   case.jsonld
 
+.PHONY: \
+  check-mypy
+
 # This virtual environment is meant to be built once and then persist, even through 'make clean'.
 # If a recipe is written to remove this flag file, it should first run `pre-commit uninstall`.
 .venv-pre-commit/var/.pre-commit-built.log:
@@ -81,7 +84,35 @@ case.jsonld: \
 	    _$@
 	mv _$@ $@
 
+case.ttl: \
+  case.jsonld
+	source venv/bin/activate \
+	  && rdfpipe \
+	    --output-format turtle \
+	    $< \
+	    > _$@
+	source venv/bin/activate \
+	  && case_validate \
+	    _$@
+	@# In instances where graph nodes omit use of a prefix, a 'default' prefix-base is used that incorporates the local directory as a file URL.  This is likely to be an undesired behavior, so for the generated example JSON-LD in the top source directory, check that "file:///" doesn't start any of the graph individuals' IRIs.
+	test \
+	  0 \
+	  -eq \
+	  $$(grep 'file:' _$@ | wc -l) \
+	  || ( echo "ERROR:Makefile:Some graph IRIs do not supply a resolving prefix.  Look for the string 'file:///' in the file _$@ to see these instances." >&2 ; exit 1)
+	mv _$@ $@
+
 check: \
-  all
+  all \
+  check-mypy \
+  case.ttl
+	source venv/bin/activate \
+	  && poetry run pytest --doctest-modules
+
+check-mypy: \
+  .venv.done.log
 	source venv/bin/activate \
-	  && poetry run pytest
+	  && mypy \
+	    case_mapping \
+	    example.py \
+	    tests

case.jsonld

@@ -15,7 +15,8 @@
         "uco-tool": "https://ontology.unifiedcyberontology.org/uco/tool/",
         "uco-types": "https://ontology.unifiedcyberontology.org/uco/types/",
         "uco-vocabulary": "https://ontology.unifiedcyberontology.org/uco/vocabulary/",
-        "xsd": "http://www.w3.org/2001/XMLSchema#"
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
+        "kb": "http://example.org/kb/"
     },
     "@type": "uco-core:Bundle",
     "uco-core:description": "An Example Case File",

case_mapping/base.py

@@ -1,5 +1,6 @@
 import json
 from datetime import datetime
+from typing import Any
 
 from cdo_local_uuid import local_uuid
 
@@ -20,8 +21,35 @@ def wrapper(self, *args, **kwargs):
 
 
 class FacetEntity(dict):
-    def __init__(self):
-        self["@id"] = "kb:" + str(local_uuid())
+    def __init__(
+        self,
+        *args: Any,
+        prefix_iri: str = "http://example.org/kb/",
+        prefix_label: str = "kb",
+        **kwargs: Any,
+    ) -> None:
+        """
+        :param prefix_iri: The IRI to be concatenated with the prefixed name's local part in order to form the node's absolute IRI.
+        :param prefix_label: The prefix separated from the compact IRI's local name by a colon.
+
+        References
+        ==========
+
+        .. [#turtle_prefixed_name] https://www.w3.org/TR/turtle/#prefixed-name
+
+        Examples
+        ========
+
+        When instantiating a ``FacetEntity``, the JSON dictionary's ``@id`` key will start with the object's ``prefix_label``.
+
+        >>> x = FacetEntity()
+        >>> assert x["@id"][0:3] == "kb:"
+        >>> y = FacetEntity(prefix_label="ex")
+        >>> assert y["@id"][0:3] == "ex:"
+        """
+        self.prefix_iri = prefix_iri
+        self.prefix_label = prefix_label
+        self["@id"] = prefix_label + ":" + str(local_uuid())
 
     def __str__(self):
         return json.dumps(self, indent=4)
@@ -159,6 +187,9 @@ def __handle_var_type_errors(var_name, var_val, expected_type):
 
 
 class ObjectEntity(FacetEntity):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
     @unpack_args_array
     def append_facets(self, *args):
         """

case_mapping/directory.py

@@ -1,8 +1,9 @@
+from .base import FacetEntity
 from .case import *
 from .uco import *
 
-submodules = [v for k, v in globals().items() if k[:2] != "__"]
+submodules = [v for k, v in globals().items() if k[:2] != "__" and k != "FacetEntity"]
 
-directory = dict()
+directory: dict[str, type[FacetEntity]] = dict()
 for submodule in submodules:
     directory |= submodule.directory

case_mapping/uco/core.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from ..base import ObjectEntity, unpack_args_array
 
 
@@ -8,12 +10,14 @@ def __init__(
         uco_core_name=None,
         spec_version=None,
         description=None,
-    ):
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
         """
         The main CASE Object for representing a case and its activities and objects.
         """
-        super().__init__()
-        self.build = []
+        super().__init__(*args, **kwargs)
+        self.build = []  # type: ignore
         self["@context"] = {
             "@vocab": "http://caseontology.org/core#",
             "case-investigation": "https://ontology.caseontology.org/case/investigation/",
@@ -31,6 +35,17 @@ def __init__(
             "uco-vocabulary": "https://ontology.unifiedcyberontology.org/uco/vocabulary/",
             "xsd": "http://www.w3.org/2001/XMLSchema#",
         }
+
+        # Assign caller-selectible prefix label and IRI, after checking
+        # for conflicts with hard-coded prefixes.
+        # https://www.w3.org/TR/turtle/#prefixed-name
+        if self.prefix_label in self["@context"]:
+            raise ValueError(
+                "Requested prefix label already in use in hard-coded dictionary: '%s'.  Please revise caller to use another label."
+                % self.prefix_label
+            )
+        self["@context"][self.prefix_label] = self.prefix_iri
+
         self["@type"] = "uco-core:Bundle"
         self._str_vars(
             **{

case_mapping/uco/observable.py

@@ -269,7 +269,10 @@ def __init__(
             }
 
         if hash_method is not None or hash_value is not None or hash_value != "-":
-            data = {"@id": "kb:" + str(local_uuid()), "@type": "uco-types:Hash"}
+            data = {
+                "@id": self.prefix_label + ":" + str(local_uuid()),
+                "@type": "uco-types:Hash",
+            }
             if hash_method is not None:
                 data["uco-types:hashMethod"] = {
                     "@type": "uco-vocabulary:HashNameVocab",
@@ -416,7 +419,7 @@ def __init__(self, browser=None, history_entries=None):
         self["uco-observable:urlHistoryEntry"] = []
         for entry in history_entries:
             history_entry = {}
-            history_entry["@id"] = "kb:" + str(local_uuid())
+            history_entry["@id"] = self.prefix_label + ":" + local_uuid()
             history_entry["@type"] = "uco-observable:URLHistoryEntry"
             for key, var in entry.items():
                 if key in keys_str:
@@ -858,14 +861,14 @@ def __init__(self, **kwargs):
         self["@type"] = "uco-observable:EXIFFacet"
 
         self["uco-observable:exifData"] = {
-            "@id": "kb:" + str(local_uuid()),
+            "@id": self.prefix_label + ":" + str(local_uuid()),
             "@type": "uco-types:ControlledDictionary",
             "uco-types:entry": [],
         }
         for k, v in kwargs.items():
             if v not in ["", " "]:
                 item = {
-                    "@id": "kb:" + str(local_uuid()),
+                    "@id": self.prefix_label + ":" + str(local_uuid()),
                     "@type": "uco-types:ControlledDictionaryEntry",
                     "uco-types:key": k,
                     "uco-types:value": v,
@@ -1357,7 +1360,7 @@ def __init__(
         self._node_reference_vars(**{"uco-observable:participant": participants})
 
         self["uco-observable:messageThread"] = {
-            "@id": "kb:" + str(local_uuid()),
+            "@id": self.prefix_label + ":" + local_uuid(),
             "@type": "uco-types:Thread",
         }
         self["uco-observable:messageThread"]["co:size"] = {

case_mapping/uco/tool.py

@@ -1,9 +1,15 @@
+from typing import Optional
+
 from ..base import ObjectEntity
 
 
 class Tool(ObjectEntity):
     def __init__(
-        self, tool_name=None, tool_version=None, tool_type=None, tool_creator=None
+        self,
+        tool_name=None,
+        tool_version=None,
+        tool_type=None,
+        tool_creator: Optional[ObjectEntity] = None,
     ):
         """
         The Uco tool is a way to define the specifics of a tool used in an investigation

example.py

@@ -2,7 +2,7 @@
 
 import cdo_local_uuid
 
-from case_mapping import case, uco
+from case_mapping import base, case, uco
 
 # This is part of enabling non-random UUIDs for the demonstration
 # output. The other part is handled at call time, and can be seen in
@@ -28,7 +28,7 @@ def _next_timestamp() -> datetime:
 
 # Generate a case bundle and list to hold investigation items
 bundle = uco.core.Bundle(description="An Example Case File")
-investigation_items = []
+investigation_items: list[base.FacetEntity] = []
 
 ###################################
 # An item to be added to the case #

poetry.lock

@@ -23,7 +23,9 @@ python = "^3.9"
 pytz = "^2023.3.post1"
 
 [tool.poetry.dev-dependencies]
+mypy = "^1"
 pytest = "^7.4.2"
+types-pytz = "^2024"
 
 [build-system]
 requires = ["poetry-core"]