cyvest 2.0.0__tar.gz → 3.1.0__tar.gz

{cyvest-2.0.0 → cyvest-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: cyvest
-Version: 2.0.0
+Version: 3.1.0
 Summary: Cybersecurity investigation model
 Keywords: cybersecurity,investigation,threat-intel,security-analysis
 Author: PakitoSec
@@ -16,7 +16,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Security
 Requires-Dist: click>=8
 Requires-Dist: logurich[click]>=0.1
+Requires-Dist: pydantic>=2.12.5
 Requires-Dist: rich>=13
+Requires-Dist: typing-extensions>=4.15
 Requires-Dist: pyvis>=0.3.2 ; extra == 'visualization'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://github.com/PakitoSec/cyvest
@@ -298,7 +300,8 @@ SAFE checks:
 
 **Root Observable Barrier:**
 
-The root observable (the investigation's entry point with `value="input-data"`) acts as a special barrier to prevent cross-contamination:
+The root observable (the investigation's entry point with `value="root"`) acts as a special barrier to prevent cross-contamination:
+Its key is derived from type + value (e.g. `obs:file:root` or `obs:artifact:root`).
 
 **Barrier as Child** - When root appears as a child of other observables, it is **skipped** in their score calculations.
 
@@ -353,8 +356,8 @@ cyvest merge inv1.json inv2.json -o merged.json -f rich --stats
 # Generate an interactive visualization (requires visualization extra)
 cyvest visualize investigation.json --min-level SUSPICIOUS --group-by-type
 
-# Output the JSON Schema describing serialized investigations
-cyvest schema > schema.json
+# Output the JSON Schema describing serialized investigations and generate types
+uv run cyvest schema -o ./schema/cyvest.schema.json && pnpm -C js/packages/cyvest-js run generate:types
 ```
 
 ## Development

{cyvest-2.0.0 → cyvest-3.1.0}/README.md

@@ -271,7 +271,8 @@ SAFE checks:
 
 **Root Observable Barrier:**
 
-The root observable (the investigation's entry point with `value="input-data"`) acts as a special barrier to prevent cross-contamination:
+The root observable (the investigation's entry point with `value="root"`) acts as a special barrier to prevent cross-contamination:
+Its key is derived from type + value (e.g. `obs:file:root` or `obs:artifact:root`).
 
 **Barrier as Child** - When root appears as a child of other observables, it is **skipped** in their score calculations.
 
@@ -326,8 +327,8 @@ cyvest merge inv1.json inv2.json -o merged.json -f rich --stats
 # Generate an interactive visualization (requires visualization extra)
 cyvest visualize investigation.json --min-level SUSPICIOUS --group-by-type
 
-# Output the JSON Schema describing serialized investigations
-cyvest schema > schema.json
+# Output the JSON Schema describing serialized investigations and generate types
+uv run cyvest schema -o ./schema/cyvest.schema.json && pnpm -C js/packages/cyvest-js run generate:types
 ```
 
 ## Development

{cyvest-2.0.0 → cyvest-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cyvest"
-version = "2.0.0"
+version = "3.1.0"
 description = "Cybersecurity investigation model"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.10"
@@ -11,7 +11,9 @@ authors = [
 dependencies = [
     "click>=8",
     "logurich[click]>=0.1",
+    "pydantic>=2.12.5",
     "rich>=13",
+    "typing-extensions>=4.15",
 ]
 keywords = ["cybersecurity", "investigation", "threat-intel", "security-analysis"]
 classifiers = [

{cyvest-2.0.0 → cyvest-3.1.0}/src/cyvest/__init__.py

@@ -8,12 +8,12 @@ programmatically with automatic scoring, level calculation, and rich reporting c
 from logurich import logger
 
 from cyvest.cyvest import Cyvest
-from cyvest.investigation import InvestigationWhitelist
 from cyvest.levels import Level
-from cyvest.model import CheckScorePolicy, ObservableType, RelationshipDirection, RelationshipType
+from cyvest.model import InvestigationWhitelist
+from cyvest.model_enums import CheckScorePolicy, ObservableType, RelationshipDirection, RelationshipType
 from cyvest.proxies import CheckProxy, ContainerProxy, EnrichmentProxy, ObservableProxy, ThreatIntelProxy
 
-__version__ = "2.0.0"
+__version__ = "3.1.0"
 
 logger.disable("cyvest")
 

{cyvest-2.0.0 → cyvest-3.1.0}/src/cyvest/cli.py

@@ -166,10 +166,10 @@ def merge(inputs: tuple[Path, ...], output: Path, output_format: str, stats: boo
     if stats:
         logger.info("[bold]Merged Investigation Statistics:[/bold]")
         investigation_stats = main_investigation.get_statistics()
-        logger.info(f"  Total Observables: {investigation_stats.get('total_observables', 0)}")
-        logger.info(f"  Total Checks: {investigation_stats.get('total_checks', 0)}")
-        logger.info(f"  Total Threat Intel: {investigation_stats.get('total_threat_intel', 0)}")
-        logger.info(f"  Total Containers: {investigation_stats.get('total_containers', 0)}")
+        logger.info(f"  Total Observables: {investigation_stats.total_observables}")
+        logger.info(f"  Total Checks: {investigation_stats.total_checks}")
+        logger.info(f"  Total Threat Intel: {investigation_stats.total_threat_intel}")
+        logger.info(f"  Total Containers: {investigation_stats.total_containers}")
         logger.info(f"  Global Score: {main_investigation.get_global_score()}")
         logger.info(f"  Global Level: {main_investigation.get_global_level()}\n")
 
@@ -236,7 +236,7 @@ def schema_cmd(output: Path | None) -> None:
     if output:
         output_path = output.resolve()
         output_path.parent.mkdir(parents=True, exist_ok=True)
-        output_path.write_text(json.dumps(schema, indent=2), encoding="utf-8")
+        output_path.write_text(json.dumps(schema, indent=2) + "\n", encoding="utf-8")
         logger.info(f"[green]Schema written to: {output_path}[/green]")
         return
 

{cyvest-2.0.0 → cyvest-3.1.0}/src/cyvest/cyvest.py

@@ -26,10 +26,11 @@ from cyvest.io_serialization import (
     save_investigation_markdown,
     serialize_investigation,
 )
-from cyvest.levels import Level, normalize_level
+from cyvest.levels import Level
 from cyvest.model import Check, CheckScorePolicy, Container, Enrichment, Observable, ThreatIntel
+from cyvest.model_schema import InvestigationSchema, StatisticsSchema
 from cyvest.proxies import CheckProxy, ContainerProxy, EnrichmentProxy, ObservableProxy, ThreatIntelProxy
-from cyvest.score import ScoreMode, normalize_score_mode
+from cyvest.score import ScoreMode
 
 
 class Cyvest:
@@ -54,7 +55,7 @@ class Cyvest:
             root_type: Type of root observable ("file" or "artifact")
             score_mode: Score calculation mode (MAX or SUM)
         """
-        normalized_score_mode = normalize_score_mode(score_mode)
+        normalized_score_mode = ScoreMode.normalize(score_mode)
         self._investigation = Investigation(data, root_type=root_type, score_mode=normalized_score_mode)
 
     def __enter__(self) -> Cyvest:
@@ -214,18 +215,19 @@ class Cyvest:
         Returns:
             The created or existing observable
         """
-        resolved_level = normalize_level(level) if level is not None else Level.INFO
-
-        obs = Observable(
-            obs_type=obs_type,
-            value=value,
-            internal=internal,
-            whitelisted=whitelisted,
-            comment=comment,
-            extra=extra or {},
-            score=Decimal(str(score)) if score is not None else Decimal("0"),
-            level=resolved_level,
-        )
+        obs_kwargs: dict[str, Any] = {
+            "obs_type": obs_type,
+            "value": value,
+            "internal": internal,
+            "whitelisted": whitelisted,
+            "comment": comment,
+            "extra": extra or {},
+        }
+        if score is not None:
+            obs_kwargs["score"] = Decimal(str(score))
+        if level is not None:
+            obs_kwargs["level"] = level
+        obs = Observable(**obs_kwargs)
         # Unwrap tuple - facade returns only Observable, discards deferred relationships
         obs_result, _ = self._investigation.add_observable(obs)
         return self._observable_proxy(obs_result)
@@ -304,17 +306,17 @@ class Cyvest:
         if not observable:
             return None
 
-        resolved_level = normalize_level(level) if level is not None else Level.INFO
-
-        ti = ThreatIntel(
-            source=source,
-            observable_key=observable_key,
-            comment=comment,
-            extra=extra or {},
-            score=Decimal(str(score)),
-            level=resolved_level,
-            taxonomies=taxonomies or [],
-        )
+        ti_kwargs: dict[str, Any] = {
+            "source": source,
+            "observable_key": observable_key,
+            "comment": comment,
+            "extra": extra or {},
+            "score": Decimal(str(score)),
+            "taxonomies": taxonomies or [],
+        }
+        if level is not None:
+            ti_kwargs["level"] = level
+        ti = ThreatIntel(**ti_kwargs)
         result = self._investigation.add_threat_intel(ti, observable)
         return self._threat_intel_proxy(result)
 
@@ -332,7 +334,7 @@ class Cyvest:
         observable = self._investigation.get_observable(observable_key)
         if not observable:
             return None
-        observable.set_level(normalize_level(level))
+        observable.set_level(level)
         return self._observable_proxy(observable)
 
     def observable_finalize_relationships(self) -> None:
@@ -372,19 +374,20 @@ class Cyvest:
         Returns:
             The created check
         """
-        resolved_level = normalize_level(level) if level is not None else Level.NONE
-        resolved_policy = CheckScorePolicy(score_policy) if score_policy is not None else CheckScorePolicy.AUTO
-
-        check = Check(
-            check_id=check_id,
-            scope=scope,
-            description=description,
-            comment=comment,
-            extra=extra or {},
-            score=Decimal(str(score)) if score is not None else Decimal("0"),
-            level=resolved_level,
-            score_policy=resolved_policy,
-        )
+        check_kwargs: dict[str, Any] = {
+            "check_id": check_id,
+            "scope": scope,
+            "description": description,
+            "comment": comment,
+            "extra": extra or {},
+        }
+        if score is not None:
+            check_kwargs["score"] = Decimal(str(score))
+        if level is not None:
+            check_kwargs["level"] = level
+        if score_policy is not None:
+            check_kwargs["score_policy"] = score_policy
+        check = Check(**check_kwargs)
         return self._check_proxy(self._investigation.add_check(check))
 
     def check_get(self, key: str) -> CheckProxy | None:
@@ -532,12 +535,12 @@ class Cyvest:
         """
         return self._investigation.get_global_level()
 
-    def get_statistics(self) -> dict[str, Any]:
+    def get_statistics(self) -> StatisticsSchema:
         """
         Get comprehensive investigation statistics.
 
         Returns:
-            Statistics dictionary
+            Statistics schema with typed fields
         """
         return self._investigation.get_statistics()
 
@@ -626,18 +629,18 @@ class Cyvest:
         """
         return generate_markdown_report(self, include_containers, include_enrichments, include_observables)
 
-    def io_to_dict(self) -> dict[str, Any]:
+    def io_to_dict(self) -> InvestigationSchema:
         """
-        Serialize the investigation to a dictionary.
+        Serialize the investigation to an InvestigationSchema.
 
         Returns:
-            Dictionary representation suitable for JSON export
+            InvestigationSchema instance (use .model_dump() for dict)
 
         Examples:
             >>> cv = Cyvest()
-            >>> data = cv.io_to_dict()
-            >>> print(data.keys())
-            dict_keys(['score', 'level', 'observables', 'checks', ...])
+            >>> schema = cv.io_to_dict()
+            >>> print(schema.score, schema.level)
+            >>> dict_data = schema.model_dump(by_alias=True)
         """
         return serialize_investigation(self)
 
@@ -691,13 +694,17 @@ class Cyvest:
         }
 
     def display_summary(
-        self, show_graph: bool = True, exclude_levels: Level | str | Iterable[Level | str] = Level.NONE
+        self,
+        show_graph: bool = True,
+        exclude_levels: Level | str | Iterable[Level | str] = Level.NONE,
+        show_score_history: bool = False,
     ) -> None:
         display_summary(
             self,
             lambda renderables: logger.rich("INFO", renderables),
             show_graph=show_graph,
             exclude_levels=exclude_levels,
+            show_score_history=show_score_history,
         )
 
     def display_statistics(self) -> None:
@@ -748,13 +755,11 @@ class Cyvest:
         if observable_types is not None:
             obs_types_enum = [ObservableType(t) for t in observable_types]
 
-        normalized_min_level = normalize_level(min_level) if min_level is not None else None
-
         return generate_network_graph(
             self,
             output_dir=output_dir,
             open_browser=open_browser,
-            min_level=normalized_min_level,
+            min_level=min_level,
             observable_types=obs_types_enum,
             physics=physics,
             group_by_type=group_by_type,

{cyvest-2.0.0 → cyvest-3.1.0}/src/cyvest/investigation.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import threading
 from copy import deepcopy
-from dataclasses import dataclass
+from datetime import datetime, timezone
 from decimal import Decimal
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, overload
@@ -17,13 +17,24 @@ from typing import TYPE_CHECKING, Any, Literal, overload
 from logurich import logger
 
 from cyvest import keys
-from cyvest.levels import Level, get_level_from_score, normalize_level
-from cyvest.model import Check, CheckScorePolicy, Container, Enrichment, Observable, ObservableType, ThreatIntel
-from cyvest.score import ScoreEngine, ScoreMode, normalize_score_mode
+from cyvest.level_score_rules import recalculate_level_for_score
+from cyvest.levels import Level, normalize_level
+from cyvest.model import (
+    Check,
+    CheckScorePolicy,
+    Container,
+    Enrichment,
+    InvestigationWhitelist,
+    Observable,
+    ObservableType,
+    ThreatIntel,
+)
+from cyvest.score import ScoreEngine, ScoreMode
 from cyvest.stats import InvestigationStats
 
 if TYPE_CHECKING:
     from cyvest import Cyvest
+    from cyvest.model_schema import InvestigationSchema, StatisticsSchema
 
 
 class SharedInvestigationContext:
@@ -156,15 +167,15 @@ class SharedInvestigationContext:
             # Refresh registries from canonical, post-merge investigation state
             self._observable_registry = {}
             for obs in self._main_investigation.get_all_observables().values():
-                copy = deepcopy(obs)
+                copy = obs.model_copy(deep=True)
                 copy._from_shared_context = True
                 self._observable_registry[obs.key] = copy
 
             self._check_registry = {
-                check.key: deepcopy(check) for check in self._main_investigation.get_all_checks().values()
+                check.key: check.model_copy(deep=True) for check in self._main_investigation.get_all_checks().values()
             }
             self._enrichment_registry = {
-                enrichment.key: deepcopy(enrichment)
+                enrichment.key: enrichment.model_copy(deep=True)
                 for enrichment in self._main_investigation.get_all_enrichments().values()
             }
 
@@ -252,7 +263,7 @@ class SharedInvestigationContext:
         with self._lock:
             obs = self._observable_registry.get(key)
             if obs:
-                copy = deepcopy(obs)
+                copy = obs.model_copy(deep=True)
                 # Mark this as a copy from shared context to prevent misuse in relationships
                 copy._from_shared_context = True
                 return copy
@@ -310,7 +321,7 @@ class SharedInvestigationContext:
         with self._lock:
             check = self._check_registry.get(key)
             if check:
-                return deepcopy(check)
+                return check.model_copy(deep=True)
             return None
 
     @overload
@@ -376,7 +387,7 @@ class SharedInvestigationContext:
         with self._lock:
             enrichment = self._enrichment_registry.get(key)
             if enrichment:
-                return deepcopy(enrichment)
+                return enrichment.model_copy(deep=True)
             return None
 
     def get_global_score(self) -> Decimal:
@@ -461,7 +472,7 @@ class SharedInvestigationContext:
             matches = []
             for obs in self._observable_registry.values():
                 if obs.obs_type == obs_type:
-                    matches.append(deepcopy(obs))
+                    matches.append(obs.model_copy(deep=True))
             return matches
 
     def find_observables_by_value(self, value: str) -> list[Observable]:
@@ -478,7 +489,7 @@ class SharedInvestigationContext:
             matches = []
             for obs in self._observable_registry.values():
                 if obs.value == value:
-                    matches.append(deepcopy(obs))
+                    matches.append(obs.model_copy(deep=True))
             return matches
 
     @overload
@@ -645,20 +656,19 @@ class SharedInvestigationContext:
             save_investigation_markdown(temp_cy, filepath, include_containers, include_enrichments, include_observables)
             return str(Path(filepath).resolve())
 
-    def io_to_dict(self) -> dict[str, Any]:
+    def io_to_dict(self) -> InvestigationSchema:
         """
-        Serialize the shared investigation to a dictionary.
+        Serialize the shared investigation to an InvestigationSchema.
 
         Thread-safe: Uses lock to ensure consistent read of investigation state.
 
         Returns:
-            Dictionary representation suitable for JSON export
+            InvestigationSchema instance (use .model_dump() for dict)
 
         Example:
             >>> shared = SharedInvestigationContext(main_inv)
-            >>> data = shared.io_to_dict()
-            >>> print(data.keys())
-            dict_keys(['score', 'level', 'whitelisted', 'observables', 'checks', ...])
+            >>> schema = shared.io_to_dict()
+            >>> dict_data = schema.model_dump(by_alias=True)
         """
         from cyvest import Cyvest
         from cyvest.io_serialization import serialize_investigation
@@ -704,35 +714,6 @@ class SharedInvestigationContext:
             return str(Path(filepath).resolve())
 
 
-@dataclass
-class InvestigationWhitelist:
-    """Represents a whitelist entry on an investigation."""
-
-    identifier: str
-    name: str
-    justification: str | None = None
-
-    def to_dict(self) -> dict[str, str | None]:
-        """Serialize whitelist entry to a dictionary."""
-        return {
-            "identifier": self.identifier,
-            "name": self.name,
-            "justification": self.justification,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> InvestigationWhitelist:
-        """Construct a whitelist entry from a dictionary."""
-        justification = data.get("justification")
-        if justification is not None:
-            justification = str(justification)
-        return cls(
-            identifier=str(data.get("identifier", "")).strip(),
-            name=str(data.get("name", "")).strip(),
-            justification=justification,
-        )
-
-
 class Investigation:
     """
     Core investigation state and operations.
@@ -774,6 +755,8 @@ class Investigation:
             root_type: Type of root observable ("file" or "artifact")
             score_mode: Score calculation mode (MAX or SUM)
         """
+        self._started_at = datetime.now(timezone.utc)
+
         # Object collections
         self._observables: dict[str, Observable] = {}
         self._checks: dict[str, Check] = {}
@@ -782,7 +765,7 @@ class Investigation:
         self._containers: dict[str, Container] = {}
 
         # Internal components
-        normalized_score_mode = normalize_score_mode(score_mode)
+        normalized_score_mode = ScoreMode.normalize(score_mode)
         self._score_engine = ScoreEngine(score_mode=normalized_score_mode)
         self._stats = InvestigationStats()
         self._whitelists: dict[str, InvestigationWhitelist] = {}
@@ -796,7 +779,7 @@ class Investigation:
 
         self._root_observable = Observable(
             obs_type=obj_type,
-            value="input-data",
+            value="root",
             internal=False,
             whitelisted=False,
             comment="Root observable for investigation",
@@ -843,7 +826,7 @@ class Investigation:
         if existing.extra:
             existing.extra.update(incoming.extra)
         elif incoming.extra:
-            existing.extra = dict().update(incoming.extra)
+            existing.extra = dict(incoming.extra)
 
         # Concatenate comments
         if incoming.comment:
@@ -983,11 +966,8 @@ class Investigation:
         # Take the higher score
         if incoming.score > existing.score:
             existing.score = incoming.score
-            # Recalculate level
-            if not existing._explicit_level:
-                calculated_level = get_level_from_score(existing.score)
-                if calculated_level > existing.level:
-                    existing.level = calculated_level
+            # Recalculate level from new score (SAFE remains sticky against downgrades)
+            existing.level = recalculate_level_for_score(existing.level, existing.score)
 
         # Take the higher level
         if incoming.level > existing.level:
@@ -1578,9 +1558,9 @@ class Investigation:
 
     def get_whitelists(self) -> list[InvestigationWhitelist]:
         """Return a copy of all whitelist entries."""
-        return deepcopy(list(self._whitelists.values()))
+        return [w.model_copy(deep=True) for w in self._whitelists.values()]
 
-    def get_statistics(self) -> dict[str, Any]:
+    def get_statistics(self) -> StatisticsSchema:
         """Get comprehensive investigation statistics."""
         return self._stats.get_summary()