cyvest 4.4.0__py3-none-any.whl → 5.1.0__py3-none-any.whl

cyvest/model.py

@@ -1,7 +1,7 @@
 """
 Core data models for Cyvest investigation framework.
 
-Defines the base classes for Check, Observable, ThreatIntel, Enrichment, Container,
+Defines the base classes for Check, Observable, ThreatIntel, Enrichment, Tag,
 and InvestigationWhitelist using Pydantic BaseModel.
 """
 
@@ -37,6 +37,18 @@ from cyvest.model_enums import (
 _DEFAULT_SCORE_PLACES = 2
 
 
+class AliasDumpModel(BaseModel):
+    """Base model that defaults to by_alias=True for JSON-compatible serialization."""
+
+    def model_dump(self, *, by_alias: bool = True, **kwargs: Any) -> dict[str, Any]:
+        """Serialize to dict, defaulting to by_alias=True for JSON compatibility."""
+        return super().model_dump(by_alias=by_alias, **kwargs)
+
+    def model_dump_json(self, *, by_alias: bool = True, **kwargs: Any) -> str:
+        """Serialize to JSON string, defaulting to by_alias=True."""
+        return super().model_dump_json(by_alias=by_alias, **kwargs)
+
+
 def _format_score_decimal(value: Decimal | None, *, places: int = _DEFAULT_SCORE_PLACES) -> str:
     if value is None:
         return "-"
@@ -257,7 +269,7 @@ class ThreatIntel(BaseModel):
         return _format_score_decimal(self.score)
 
 
-class Observable(BaseModel):
+class Observable(AliasDumpModel):
     """
     Represents a cyber observable (IP, URL, domain, hash, etc.).
 
@@ -391,8 +403,7 @@ class Check(BaseModel):
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    check_id: str = Field(...)
-    scope: str = Field(...)
+    check_name: str = Field(...)
     description: str = Field(...)
     comment: str = Field(...)
     extra: dict[str, Any] = Field(...)
@@ -442,7 +453,7 @@ class Check(BaseModel):
     def generate_key(self) -> Self:
         """Generate key."""
         if not self.key:
-            self.key = keys.generate_check_key(self.check_id, self.scope)
+            self.key = keys.generate_check_key(self.check_name)
         return self
 
     @field_serializer("score")
@@ -491,27 +502,27 @@ class Enrichment(BaseModel):
         return values
 
 
-class Container(BaseModel):
+class Tag(BaseModel):
     """
-    Groups checks and sub-containers for hierarchical organization.
+    Groups checks for categorical organization.
 
-    Containers allow structuring the investigation into logical sections
-    with aggregated scores and levels.
+    Tags allow structuring the investigation into logical sections
+    with aggregated scores and levels. Hierarchy is automatic based on
+    the ":" delimiter in tag names (e.g., "header:auth:dkim").
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
 
-    path: str
+    name: str
     description: str = ""
     checks: list[Check] = Field(...)
-    sub_containers: dict[str, Container] = Field(...)
     key: str = Field(...)
 
     @model_validator(mode="after")
     def generate_key(self) -> Self:
         """Generate key."""
         if not self.key:
-            self.key = keys.generate_container_key(self.path)
+            self.key = keys.generate_tag_key(self.name)
         return self
 
     @model_validator(mode="before")
@@ -521,63 +532,64 @@ class Container(BaseModel):
             return values
         if "checks" not in values:
             values["checks"] = []
-        if "sub_containers" not in values:
-            values["sub_containers"] = {}
         if "key" not in values:
             values["key"] = ""
         return values
 
+    @field_serializer("checks")
+    def serialize_checks(self, value: list[Check]) -> list[str]:
+        """Serialize checks as keys only."""
+        return [check.key for check in value]
+
     @computed_field(return_type=Decimal)
     @property
-    def aggregated_score(self) -> Decimal:
-        return self.get_aggregated_score()
+    def direct_score(self) -> Decimal:
+        """
+        Calculate the score from direct checks only (no hierarchy).
+
+        For hierarchical aggregation (including descendant tags), use
+        Investigation.get_tag_aggregated_score() or TagProxy.get_aggregated_score().
 
-    @field_serializer("aggregated_score")
-    def serialize_aggregated_score(self, v: Decimal) -> float:
+        Returns:
+            Total score from direct checks
+        """
+        return self.get_direct_score()
+
+    @field_serializer("direct_score")
+    def serialize_direct_score(self, v: Decimal) -> float:
         return float(v)
 
-    def get_aggregated_score(self) -> Decimal:
+    def get_direct_score(self) -> Decimal:
         """
-        Calculate the aggregated score from all checks and sub-containers.
+        Calculate the score from direct checks only.
 
         Returns:
-            Total aggregated score
+            Total score from direct checks
         """
         total = Decimal("0")
-        # Sum scores from direct checks
         for check in self.checks:
             total += check.score
-        # Sum scores from sub-containers
-        for sub in self.sub_containers.values():
-            total += sub.get_aggregated_score()
         return total
 
     @computed_field(return_type=Level)
     @property
-    def aggregated_level(self) -> Level:
+    def direct_level(self) -> Level:
         """
-        Calculate the aggregated level from the aggregated score.
+        Calculate the level from direct checks only (no hierarchy).
+
+        For hierarchical aggregation (including descendant tags), use
+        Investigation.get_tag_aggregated_level() or TagProxy.get_aggregated_level().
 
         Returns:
-            Level based on aggregated score
+            Level based on direct score
         """
-        return self.get_aggregated_level()
-
-    @field_serializer("checks")
-    def serialize_checks(self, value: list[Check]) -> list[str]:
-        """Serialize checks as keys only."""
-        return [check.key for check in value]
-
-    @field_serializer("sub_containers")
-    def serialize_sub_containers(self, value: dict[str, Container]) -> dict[str, Container]:
-        """Serialize sub-containers recursively."""
-        return {key: sub.model_dump() for key, sub in value.items()}
+        return self.get_direct_level()
 
-    def get_aggregated_level(self) -> Level:
+    def get_direct_level(self) -> Level:
         """
-        Calculate the aggregated level from the aggregated score.
+        Calculate the level from direct score only.
 
         Returns:
-            Level based on aggregated score
+            Level based on direct score
         """
-        return get_level_from_score(self.get_aggregated_score())
+        return get_level_from_score(self.get_direct_score())

cyvest/model_schema.py

@@ -19,12 +19,13 @@ from pydantic import BaseModel, ConfigDict, Field, computed_field, field_seriali
 
 from cyvest.levels import Level
 from cyvest.model import (
+    AliasDumpModel,
     AuditEvent,
     Check,
-    Container,
     Enrichment,
     InvestigationWhitelist,
     Observable,
+    Tag,
     ThreatIntel,
     _format_score_decimal,
 )
@@ -50,12 +51,11 @@ class StatisticsSchema(BaseModel):
     observables_by_type_and_level: dict[str, dict[str, Annotated[int, Field(ge=0)]]] = Field(default_factory=dict)
     total_checks: Annotated[int, Field(ge=0)]
     applied_checks: Annotated[int, Field(ge=0)]
-    checks_by_scope: dict[str, list[str]] = Field(default_factory=dict)
     checks_by_level: dict[str, list[str]] = Field(default_factory=dict)
     total_threat_intel: Annotated[int, Field(ge=0)]
     threat_intel_by_source: dict[str, Annotated[int, Field(ge=0)]] = Field(default_factory=dict)
     threat_intel_by_level: dict[str, Annotated[int, Field(ge=0)]] = Field(default_factory=dict)
-    total_containers: Annotated[int, Field(ge=0)]
+    total_tags: Annotated[int, Field(ge=0)]
 
 
 class DataExtractionSchema(BaseModel):
@@ -72,7 +72,7 @@ class DataExtractionSchema(BaseModel):
     )
 
 
-class InvestigationSchema(BaseModel):
+class InvestigationSchema(AliasDumpModel):
     """
     Schema for a complete serialized investigation.
 
@@ -117,9 +117,9 @@ class InvestigationSchema(BaseModel):
         ...,
         description="Observables keyed by their unique key.",
     )
-    checks: dict[str, list[Check]] = Field(
+    checks: dict[str, Check] = Field(
         ...,
-        description="Checks organized by scope.",
+        description="Checks keyed by their unique key.",
     )
     threat_intels: dict[str, ThreatIntel] = Field(
         ...,
@@ -129,9 +129,9 @@ class InvestigationSchema(BaseModel):
         ...,
         description="Enrichment entries keyed by their unique key.",
     )
-    containers: dict[str, Container] = Field(
+    tags: dict[str, Tag] = Field(
         ...,
-        description="Containers keyed by their unique key.",
+        description="Tags keyed by their unique key.",
     )
     stats: StatisticsSchema = Field(description="Investigation statistics summary.")
     data_extraction: DataExtractionSchema = Field(description="Data extraction metadata.")
@@ -159,6 +159,6 @@ class InvestigationSchema(BaseModel):
         v.setdefault("checks", {})
         v.setdefault("threat_intels", {})
         v.setdefault("enrichments", {})
-        v.setdefault("containers", {})
+        v.setdefault("tags", {})
 
         return v

cyvest/proxies.py

@@ -18,12 +18,12 @@ from cyvest import keys
 from cyvest.levels import Level
 from cyvest.model import (
     Check,
-    Container,
     Enrichment,
     Observable,
     ObservableLink,
     ObservableType,
     Relationship,
+    Tag,
     Taxonomy,
     ThreatIntel,
 )
@@ -282,12 +282,8 @@ class CheckProxy(_ReadOnlyProxy[Check]):
         return check
 
     @property
-    def check_id(self) -> str:
-        return self._read_attr("check_id")
-
-    @property
-    def scope(self) -> str:
-        return self._read_attr("scope")
+    def check_name(self) -> str:
+        return self._read_attr("check_name")
 
     @property
     def description(self) -> str:
@@ -350,18 +346,23 @@ class CheckProxy(_ReadOnlyProxy[Check]):
         self._get_investigation().update_model_metadata("check", self.key, updates, dict_merge=dict_merge)
         return self
 
-    def in_container(self, container: Container | ContainerProxy | str) -> CheckProxy:
-        """Add this check to a container."""
-        if isinstance(container, ContainerProxy):
-            container_key = container.key
-        elif isinstance(container, Container):
-            container_key = container.key
-        elif isinstance(container, str):
-            container_key = container
-        else:
-            raise TypeError("Container must provide a key.")
-
-        self._get_investigation().add_check_to_container(container_key, self.key)
+    def tagged(self, *tags: Tag | TagProxy | str) -> CheckProxy:
+        """Add this check to one or more tags (auto-creates tags from strings)."""
+        investigation = self._get_investigation()
+        for tag in tags:
+            if isinstance(tag, TagProxy):
+                tag_key = tag.key
+            elif isinstance(tag, Tag):
+                tag_key = tag.key
+            elif isinstance(tag, str):
+                # Auto-create tag if it doesn't exist
+                tag_key = keys.generate_tag_key(tag)
+                if investigation.get_tag(tag_key) is None:
+                    investigation.add_tag(Tag(name=tag, checks=[], key=tag_key))
+            else:
+                raise TypeError("Tag must provide a key.")
+
+            investigation.add_check_to_tag(tag_key, self.key)
         return self
 
     def link_observable(
@@ -390,18 +391,18 @@ class CheckProxy(_ReadOnlyProxy[Check]):
         return self
 
 
-class ContainerProxy(_ReadOnlyProxy[Container]):
-    """Read-only proxy over a container."""
+class TagProxy(_ReadOnlyProxy[Tag]):
+    """Read-only proxy over a tag."""
 
     def _resolve(self):
-        container = self._get_investigation().get_container(self.key)
-        if container is None:
-            raise ModelNotFoundError(f"Container '{self.key}' no longer exists in this investigation.")
-        return container
+        tag = self._get_investigation().get_tag(self.key)
+        if tag is None:
+            raise ModelNotFoundError(f"Tag '{self.key}' no longer exists in this investigation.")
+        return tag
 
     @property
-    def path(self) -> str:
-        return self._read_attr("path")
+    def name(self) -> str:
+        return self._read_attr("name")
 
     @property
     def description(self) -> str:
@@ -411,20 +412,26 @@ class ContainerProxy(_ReadOnlyProxy[Container]):
     def checks(self) -> list[Check]:
         return self._read_attr("checks")
 
-    @property
-    def sub_containers(self) -> dict[str, Container]:
-        return self._read_attr("sub_containers")
+    def get_direct_score(self):
+        """Return the direct score (checks in this tag only, no hierarchy)."""
+        return self._call_readonly("get_direct_score")
+
+    def get_direct_level(self):
+        """Return the direct level (from direct score only, no hierarchy)."""
+        return self._call_readonly("get_direct_level")
 
     def get_aggregated_score(self):
-        """Return the aggregated score copy."""
-        return self._call_readonly("get_aggregated_score")
+        """Return the aggregated score including all descendant tags."""
+        tag = self._resolve()
+        return self._get_investigation().get_tag_aggregated_score(tag.name)
 
     def get_aggregated_level(self):
-        """Return the aggregated level copy."""
-        return self._call_readonly("get_aggregated_level")
+        """Return the aggregated level including all descendant tags."""
+        tag = self._resolve()
+        return self._get_investigation().get_tag_aggregated_level(tag.name)
 
-    def add_check(self, check: Check | CheckProxy | str) -> ContainerProxy:
-        """Add a check to this container."""
+    def add_check(self, check: Check | CheckProxy | str) -> TagProxy:
+        """Add a check to this tag."""
         if isinstance(check, CheckProxy):
             check_key = check.key
         elif isinstance(check, Check):
@@ -434,19 +441,10 @@ class ContainerProxy(_ReadOnlyProxy[Container]):
         else:
             raise TypeError("Check must provide a key.")
 
-        self._get_investigation().add_check_to_container(self.key, check_key)
+        self._get_investigation().add_check_to_tag(self.key, check_key)
         return self
 
-    def sub_container(self, path: str, description: str = "") -> ContainerProxy:
-        """Create a sub-container nested beneath this container."""
-        parent = self._resolve()
-        full_path = f"{parent.path}/{path}"
-        sub = Container(path=full_path, description=description)
-        sub = self._get_investigation().add_container(sub)
-        self._get_investigation().add_sub_container(self.key, sub.key)
-        return ContainerProxy(self._get_investigation(), sub.key)
-
-    def __enter__(self) -> ContainerProxy:
+    def __enter__(self) -> TagProxy:
         """Context manager entry returning self."""
         return self
 
@@ -454,11 +452,11 @@ class ContainerProxy(_ReadOnlyProxy[Container]):
         """Context manager exit (no-op)."""
         return None
 
-    def update_metadata(self, *, description: str | None = None) -> ContainerProxy:
-        """Update mutable metadata on the container."""
+    def update_metadata(self, *, description: str | None = None) -> TagProxy:
+        """Update mutable metadata on the tag."""
         if description is None:
             return self
-        self._get_investigation().update_model_metadata("container", self.key, {"description": description})
+        self._get_investigation().update_model_metadata("tag", self.key, {"description": description})
         return self
 
 

cyvest/shared.py

@@ -311,23 +311,23 @@ class SharedInvestigationContext:
         except Exception as e:
             raise ValueError(f"Failed to generate observable key for type='{obs_type}', value='{value}': {e}") from e
 
-    def check_get(self, check_id: str, scope: str) -> Check | None:
-        key = self._check_key(check_id, scope)
+    def check_get(self, check_name: str) -> Check | None:
+        key = self._check_key(check_name)
         return self._lock.run(self._get_check_by_key_unlocked, key)
 
-    async def check_aget(self, check_id: str, scope: str) -> Check | None:
-        key = self._check_key(check_id, scope)
+    async def check_aget(self, check_name: str) -> Check | None:
+        key = self._check_key(check_name)
         return await self._lock.arun(self._get_check_by_key_unlocked, key)
 
     def _get_check_by_key_unlocked(self, key: str) -> Check | None:
         check = self._check_registry.get(key)
         return check.model_copy(deep=True) if check else None
 
-    def _check_key(self, check_id: str, scope: str) -> str:
+    def _check_key(self, check_name: str) -> str:
         try:
-            return keys.generate_check_key(check_id, scope)
+            return keys.generate_check_key(check_name)
         except Exception as e:
-            raise ValueError(f"Failed to generate check key for check_id='{check_id}', scope='{scope}': {e}") from e
+            raise ValueError(f"Failed to generate check key for check_name='{check_name}': {e}") from e
 
     def enrichment_get(self, name: str, context: str = "") -> Enrichment | None:
         key = self._enrichment_key(name, context)
@@ -393,39 +393,39 @@ class SharedInvestigationContext:
 
     def io_to_markdown(
         self,
-        include_containers: bool = False,
+        include_tags: bool = False,
         include_enrichments: bool = False,
         include_observables: bool = True,
     ) -> str:
         return self._lock.run(
             self._io_to_markdown_unlocked,
-            include_containers,
+            include_tags,
             include_enrichments,
             include_observables,
         )
 
     async def aio_to_markdown(
         self,
-        include_containers: bool = False,
+        include_tags: bool = False,
         include_enrichments: bool = False,
         include_observables: bool = True,
     ) -> str:
         return await self._lock.arun(
             self._io_to_markdown_unlocked,
-            include_containers,
+            include_tags,
             include_enrichments,
             include_observables,
         )
 
     def _io_to_markdown_unlocked(
         self,
-        include_containers: bool,
+        include_tags: bool,
         include_enrichments: bool,
         include_observables: bool,
     ) -> str:
         return generate_markdown_report(
             self._main_investigation,
-            include_containers,
+            include_tags,
             include_enrichments,
             include_observables,
         )
@@ -433,14 +433,14 @@ class SharedInvestigationContext:
     def io_save_markdown(
         self,
         filepath: str | Path,
-        include_containers: bool = False,
+        include_tags: bool = False,
         include_enrichments: bool = False,
         include_observables: bool = True,
     ) -> str:
         return self._lock.run(
             self._io_save_markdown_unlocked,
             filepath,
-            include_containers,
+            include_tags,
             include_enrichments,
             include_observables,
         )
@@ -448,14 +448,14 @@ class SharedInvestigationContext:
     async def aio_save_markdown(
         self,
         filepath: str | Path,
-        include_containers: bool = False,
+        include_tags: bool = False,
         include_enrichments: bool = False,
         include_observables: bool = True,
     ) -> str:
         return await self._lock.arun(
             self._io_save_markdown_unlocked,
             filepath,
-            include_containers,
+            include_tags,
             include_enrichments,
             include_observables,
         )
@@ -463,14 +463,14 @@ class SharedInvestigationContext:
     def _io_save_markdown_unlocked(
         self,
         filepath: str | Path,
-        include_containers: bool,
+        include_tags: bool,
         include_enrichments: bool,
         include_observables: bool,
     ) -> str:
         save_investigation_markdown(
             self._main_investigation,
             filepath,
-            include_containers,
+            include_tags,
             include_enrichments,
             include_observables,
         )

cyvest/stats.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from collections import defaultdict
 
 from cyvest.levels import Level
-from cyvest.model import Check, Container, Observable, ThreatIntel
+from cyvest.model import Check, Observable, Tag, ThreatIntel
 from cyvest.model_schema import StatisticsSchema
 
 
@@ -27,7 +27,7 @@ class InvestigationStats:
         self._observables: dict[str, Observable] = {}
         self._checks: dict[str, Check] = {}
         self._threat_intels: dict[str, ThreatIntel] = {}
-        self._containers: dict[str, Container] = {}
+        self._tags: dict[str, Tag] = {}
 
     def register_observable(self, observable: Observable) -> None:
         """
@@ -56,14 +56,14 @@ class InvestigationStats:
         """
         self._threat_intels[ti.key] = ti
 
-    def register_container(self, container: Container) -> None:
+    def register_tag(self, tag: Tag) -> None:
         """
-        Register a container for statistics tracking.
+        Register a tag for statistics tracking.
 
         Args:
-            container: Container to track
+            tag: Tag to track
         """
-        self._containers[container.key] = container
+        self._tags[tag.key] = tag
 
     def get_observable_count_by_type(self) -> dict[str, int]:
         """
@@ -142,30 +142,6 @@ class InvestigationStats:
         """
         return sum(1 for obs in self._observables.values() if obs.whitelisted)
 
-    def get_check_count_by_scope(self) -> dict[str, int]:
-        """
-        Get count of checks by scope.
-
-        Returns:
-            Dictionary mapping scope to count
-        """
-        counts: dict[str, int] = defaultdict(int)
-        for check in self._checks.values():
-            counts[check.scope] += 1
-        return dict(counts)
-
-    def get_check_keys_by_scope(self) -> dict[str, list[str]]:
-        """
-        Get check keys grouped by scope.
-
-        Returns:
-            Dictionary mapping scope to list of check keys
-        """
-        keys: dict[str, list[str]] = defaultdict(list)
-        for check in self._checks.values():
-            keys[check.scope].append(check.key)
-        return dict(keys)
-
     def get_check_count_by_level(self) -> dict[Level, int]:
         """
         Get count of checks by level.
@@ -241,14 +217,14 @@ class InvestigationStats:
             counts[ti.level] += 1
         return dict(counts)
 
-    def get_container_count(self) -> int:
+    def get_tag_count(self) -> int:
         """
-        Get total number of containers.
+        Get total number of tags.
 
         Returns:
-            Total container count
+            Total tag count
         """
-        return len(self._containers)
+        return len(self._tags)
 
     def get_checks_by_level(self, level: Level) -> list[Check]:
         """
@@ -307,10 +283,9 @@ class InvestigationStats:
             },
             total_checks=self.get_total_check_count(),
             applied_checks=self.get_applied_check_count(),
-            checks_by_scope=self.get_check_keys_by_scope(),
             checks_by_level={str(k): v for k, v in self.get_check_keys_by_level().items()},
             total_threat_intel=self.get_threat_intel_count(),
             threat_intel_by_source=self.get_threat_intel_count_by_source(),
             threat_intel_by_level={str(k): v for k, v in self.get_threat_intel_count_by_level().items()},
-            total_containers=self.get_container_count(),
+            total_tags=self.get_tag_count(),
         )