cyvest 2.0.0__tar.gz → 3.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: cyvest
-Version: 2.0.0
+Version: 3.0.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
@@ -353,8 +355,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.0.0}/README.md

@@ -326,8 +326,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.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cyvest"
-version = "2.0.0"
+version = "3.0.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.0.0}/src/cyvest/__init__.py

@@ -8,12 +8,17 @@ 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 (
+    CheckScorePolicy,
+    InvestigationWhitelist,
+    ObservableType,
+    RelationshipDirection,
+    RelationshipType,
+)
 from cyvest.proxies import CheckProxy, ContainerProxy, EnrichmentProxy, ObservableProxy, ThreatIntelProxy
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"
 
 logger.disable("cyvest")
 

{cyvest-2.0.0 → cyvest-3.0.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.0.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,8 +215,6 @@ 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,
@@ -224,7 +223,7 @@ class Cyvest:
             comment=comment,
             extra=extra or {},
             score=Decimal(str(score)) if score is not None else Decimal("0"),
-            level=resolved_level,
+            level=level if level is not None else Level.INFO,
         )
         # Unwrap tuple - facade returns only Observable, discards deferred relationships
         obs_result, _ = self._investigation.add_observable(obs)
@@ -304,15 +303,13 @@ 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,
+            level=level if level is not None else Level.INFO,
             taxonomies=taxonomies or [],
         )
         result = self._investigation.add_threat_intel(ti, observable)
@@ -332,7 +329,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,9 +369,6 @@ 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,
@@ -382,8 +376,8 @@ class Cyvest:
             comment=comment,
             extra=extra or {},
             score=Decimal(str(score)) if score is not None else Decimal("0"),
-            level=resolved_level,
-            score_policy=resolved_policy,
+            level=level if level is not None else Level.NONE,
+            score_policy=score_policy if score_policy is not None else CheckScorePolicy.AUTO,
         )
         return self._check_proxy(self._investigation.add_check(check))
 
@@ -532,12 +526,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 +620,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)
 
@@ -748,13 +742,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.0.0}/src/cyvest/investigation.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 
 import threading
 from copy import deepcopy
-from dataclasses import dataclass
 from decimal import Decimal
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, overload
@@ -18,12 +17,22 @@ 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.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 +165,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 +261,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 +319,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 +385,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 +470,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 +487,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 +654,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 +712,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.
@@ -782,7 +761,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] = {}
@@ -843,7 +822,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:
@@ -1578,9 +1557,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()
 

{cyvest-2.0.0 → cyvest-3.0.0}/src/cyvest/io_rich.py

@@ -176,11 +176,11 @@ def display_summary(
 
     stats = cv.get_statistics()
     stat_items = [
-        ("Total Observables", stats.get("total_observables", 0)),
-        ("Internal Observables", stats.get("internal_observables", 0)),
-        ("External Observables", stats.get("external_observables", 0)),
-        ("Whitelisted Observables", stats.get("whitelisted_observables", 0)),
-        ("Total Threat Intel", stats.get("total_threat_intel", 0)),
+        ("Total Observables", stats.total_observables),
+        ("Internal Observables", stats.internal_observables),
+        ("External Observables", stats.external_observables),
+        ("Whitelisted Observables", stats.whitelisted_observables),
+        ("Total Threat Intel", stats.total_threat_intel),
     ]
 
     for stat_name, stat_value in stat_items:
@@ -301,8 +301,8 @@ def display_statistics(cv: Cyvest, rich_print: Callable[[Any], None]) -> None:
     obs_table.add_column("SUSPICIOUS", justify="right", style="orange3")
     obs_table.add_column("MALICIOUS", justify="right", style="red")
 
-    obs_by_type_level = stats.get("observables_by_type_and_level", {})
-    for obs_type, count in stats.get("observables_by_type", {}).items():
+    obs_by_type_level = stats.observables_by_type_and_level
+    for obs_type, count in stats.observables_by_type.items():
         levels = obs_by_type_level.get(obs_type, {})
         obs_table.add_row(
             obs_type.upper(),
@@ -321,19 +321,19 @@ def display_statistics(cv: Cyvest, rich_print: Callable[[Any], None]) -> None:
     check_table.add_column("Scope", style="cyan")
     check_table.add_column("Count", justify="right")
 
-    for scope, count in stats.get("checks_by_scope", {}).items():
+    for scope, count in stats.checks_by_scope.items():
         check_table.add_row(scope, str(count))
 
     rich_print(check_table)
 
     # Threat intel statistics
-    if stats.get("total_threat_intel", 0) > 0:
+    if stats.total_threat_intel > 0:
         rich_print("")
         ti_table = Table(title="Threat Intelligence Statistics")
         ti_table.add_column("Source", style="cyan")
         ti_table.add_column("Count", justify="right")
 
-        for source, count in stats.get("threat_intel_by_source", {}).items():
+        for source, count in stats.threat_intel_by_source.items():
             ti_table.add_row(source, str(count))
 
         rich_print(ti_table)

cyvest-3.0.0/src/cyvest/io_schema.py

@@ -0,0 +1,35 @@
+"""
+JSON Schema definition for serialized Cyvest investigations.
+
+The schema mirrors the structure emitted by `serialize_investigation` in
+`cyvest.io_serialization` so consumers can validate exports or generate
+typed bindings.
+
+This module uses Pydantic's `model_json_schema(mode='serialization')` to generate
+schemas that match the actual serialized output (respecting field_serializer decorators).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cyvest.model_schema import InvestigationSchema
+
+
+def get_investigation_schema() -> dict[str, Any]:
+    """
+    Get the JSON Schema for serialized investigations.
+
+    Generates a JSON Schema (Draft 2020-12) that describes the output of
+    `serialize_investigation()`. The schema uses Pydantic's `model_json_schema`
+    with `mode='serialization'`, which respects field_serializer decorators and
+    matches the actual `model_dump()` output structure.
+
+    The returned schema automatically includes all referenced entity types
+    (Observable, Check, ThreatIntel, Enrichment, Container, InvestigationWhitelist)
+    in the `$defs` section.
+
+    Returns:
+        dict[str, Any]: Schema dictionary compliant with JSON Schema Draft 2020-12.
+    """
+    return InvestigationSchema.model_json_schema(mode="serialization", by_alias=True)