cyvest 0.1.0__py3-none-any.whl

cyvest/visitors.py

@@ -0,0 +1,332 @@
+from __future__ import annotations
+
+import copy
+from abc import ABC, abstractmethod
+from typing import Any
+
+from logurich import logger
+
+from .check_tree import CheckTree
+from .models import (
+    Container,
+    Enrichment,
+    Level,
+    Model,
+    Observable,
+    ObsType,
+    ResultCheck,
+    Scope,
+    ThreatIntel,
+    get_level_from_score,
+)
+from .observable_registry import ObservableRegistry
+from .report_render import markdown_summary, stdout_from_json
+from .report_serialization import reduce_report_json, report_to_json
+
+
+class Visitor(ABC):
+    def __init__(self, *, graph: bool = False) -> None:
+        super().__init__()
+        self.graph = graph
+        self._stats = {}
+
+    @property
+    def stats(self):
+        return copy.deepcopy(self._stats)
+
+    def init_stat(self, key: str, value: int = 0) -> None:
+        self._stats[key] = value
+
+    def increment_stat(self, key: str, value: int = 1) -> None:
+        self._stats[key] += value
+
+    def decrement_stat(self, key: str, value: int = 1) -> None:
+        self._stats[key] -= value
+
+    def reduce_stats(self, stats: dict) -> dict:
+        for k, v in self._stats.items():
+            if not isinstance(v, int):
+                raise Exception("Reduce Stats can reduce only integers")
+            if stats.get(k):
+                stats[k] += v
+            else:
+                stats[k] = v
+        return stats
+
+    @abstractmethod
+    def visit_threat_intel(self, threat_intel: ThreatIntel) -> ThreatIntel:
+        """Method that returns models"""
+        raise NotImplementedError("missing method check")
+
+    @abstractmethod
+    def visit_observable(self, observable: Observable) -> Observable:
+        """Method that visit an observable"""
+        raise NotImplementedError("missing method visit_observable")
+
+    @abstractmethod
+    def visit_result_check(self, result_check: ResultCheck) -> ResultCheck:
+        """Method that visit a result entry"""
+        raise NotImplementedError("missing method visit_result_check")
+
+    @abstractmethod
+    def visit_container(self, container: Container) -> Container:
+        """Method that visit a result entry"""
+        raise NotImplementedError("missing method visit_container")
+
+    @abstractmethod
+    def visit_enrichment(self, enrichment: Enrichment) -> Enrichment:
+        """Method that visit an enrichment"""
+        raise NotImplementedError("missing method visit_enrichment")
+
+    @abstractmethod
+    def to_json(self):
+        """Method that convert the object to json"""
+        raise NotImplementedError("missing method to_json")
+
+    @abstractmethod
+    def get_check(self, path: str):
+        """Method that convert the object to json"""
+        raise NotImplementedError("missing method get_check")
+
+
+class Report(Visitor):
+    map_stats_suspicious = {
+        ObsType.IP.name: "ips",
+        ObsType.URL.name: "urls",
+        ObsType.DOMAIN.name: "domains",
+        ObsType.FILE.name: "files",
+        Scope.FULL.name: "full",
+        Scope.HEADER.name: "header",
+        Scope.BODY.name: "body",
+        Scope.ATTACHMENT.name: "attachment",
+        "threat_intel": "threat_intels",
+    }
+
+    def __init__(
+        self,
+        json_structure: dict[str, Any] | None = None,
+        linked_reports: dict[str, Report] | None = None,
+        *,
+        graph: bool = False,
+    ) -> None:
+        if linked_reports is None:
+            linked_reports = {}
+        super().__init__(graph=graph)
+        payload = copy.deepcopy(json_structure) if json_structure is not None else self.default_payload()
+        self.json = payload
+        self.linked_reports = linked_reports
+        self._seen_stats = {}
+        self.tree = CheckTree()
+        self.observable_registry = ObservableRegistry()
+        self.observables = self.observable_registry._observables
+        self.enrichments = []
+        self.global_score = 0.0
+        self.global_level = get_level_from_score(self.global_score) or Level.INFO
+        self.annotations: list[dict[str, str]] = []
+        # init statistics
+        for type_data, key in Report.map_stats_suspicious.items():
+            self.init_stat(key)
+            for level in Level:
+                stat_name = self._get_stat(type_data, level)
+                if stat_name is not None:
+                    self.init_stat(stat_name)
+
+    @staticmethod
+    def default_payload() -> dict[str, Any]:
+        return {"checks": {}, "stats": {}, "data": {"header": {}}, "graph": []}
+
+    def __getitem__(self, key):
+        return self.json[key]
+
+    def _get_stat(self, type_data: str, level: Level) -> str:
+        stat_name = Report.map_stats_suspicious.get(type_data)
+        if stat_name is None:
+            return None
+        suffix = ""
+        if level <= Level.NONE:
+            return None
+        if level >= Level.SUSPICIOUS:
+            suffix = f"_{level.name}"
+        return f"{stat_name}{suffix}".lower()
+
+    def get_dot_path(self, obj, path):
+        s_path = path.split(".")
+        struct = obj
+        for p in s_path[:-1]:
+            struct.setdefault(p, {})
+        return struct
+
+    def get(self, path: str, default: Any = None) -> Any:
+        return self.json.get(path, default)
+
+    def get_check(self, path: str) -> Any:
+        node = self.tree.get(path)
+        if isinstance(node, ResultCheck):
+            return node
+        return None
+
+    def get_observable_per_type(self, type: ObsType) -> list[Observable]:
+        return [obs for obs in self.observable_registry.values() if obs.obs_type == type]
+
+    def increment_stat(self, full_key: str, type_data: str, level: Level, model: Model) -> bool:
+        stat_name = self._get_stat(type_data, level)
+        default_stat_name = self._get_stat(type_data, Level.INFO)
+        if stat_name is None:
+            return False
+        if self._seen_stats.get(full_key):
+            # Update
+            old_level = self._seen_stats.get(full_key)
+            old_stat_name = self._get_stat(type_data, old_level)
+            if stat_name and old_stat_name != stat_name and level > old_level:
+                self._seen_stats[full_key] = level
+                logger.debug(
+                    "{}: update stat {} -> {} - default: {} (gen by: {})",
+                    full_key,
+                    old_stat_name,
+                    stat_name,
+                    default_stat_name,
+                    model.generated_by,
+                )
+                if old_stat_name != default_stat_name:
+                    super().decrement_stat(old_stat_name)
+                if stat_name != default_stat_name:
+                    super().increment_stat(stat_name)
+        else:
+            # New
+            logger.debug(
+                "{}: add stat {} - default: {} (gen by: {})", full_key, stat_name, default_stat_name, model.generated_by
+            )
+            if stat_name:
+                super().increment_stat(stat_name)
+            if stat_name != default_stat_name:
+                super().increment_stat(default_stat_name)
+            self._seen_stats[full_key] = level
+        return True
+
+    def get_linked_reports(self, sha256_file: str) -> Report:
+        return self.linked_reports.get(sha256_file)
+
+    def is_whitelisted(self, type: ObsType, value: str) -> bool:
+        full_key = f"{type.name}.{value}"
+        observable = self.observable_registry.get(full_key)
+        return bool(observable and observable.whitelisted)
+
+    def add_annotation(self, name: str, message: str) -> list[dict[str, str]]:
+        annotation = {"name": name, "message": message}
+        self.annotations.append(annotation)
+        return self.annotations
+
+    def has_annotations(self) -> bool:
+        return bool(self.annotations)
+
+    def visit_threat_intel(self, threat_intel: ThreatIntel) -> ThreatIntel:
+        full_key = threat_intel.full_key
+        # Statistic
+        self.increment_stat(full_key, "threat_intel", threat_intel.level, threat_intel)
+        return threat_intel
+
+    def visit_result_check(self, result_check: ResultCheck) -> ResultCheck:
+        full_key = result_check.full_key
+        self.increment_stat(full_key, result_check.scope.name, result_check.level, result_check)
+        rc = self.tree.integrate_result_check(result_check)
+        logger.debug("Integrated ResultCheck [{}] -> score {}", full_key, rc.score)
+        self.global_score = round(self.tree.total_score(), 2)
+        self.global_level = self.tree.highest_level()
+        return rc
+
+    def visit_container(self, container: Container) -> Container:
+        integrated = self.tree.integrate_container(container)
+        self.global_score = round(self.tree.total_score(), 2)
+        self.global_level = self.tree.highest_level()
+        return integrated
+
+    def visit_observable(self, observable: Observable) -> Observable:
+        full_key = f"{observable.obs_type.name}.{observable.obs_value}"
+        self.increment_stat(full_key, observable.obs_type.name, observable.level, observable)
+        ref = self.observable_registry.upsert(observable)
+        if self.is_whitelisted(ref.obs_type, ref.obs_value):
+            ref.whitelisted = True
+        return ref
+
+    def visit_enrichment(self, enrichment: Enrichment) -> Enrichment:
+        enrichment.ref_struct[enrichment.key] = enrichment.data
+        self.enrichments.append(enrichment)
+        return enrichment
+
+    def to_json(self) -> dict[str, Any]:
+        return report_to_json(self)
+
+    def to_stdout_from_json(self, json_data: dict[str, Any]) -> None:
+        stdout_from_json(self, json_data)
+
+    def reduce_json_report(self, json_report: dict[str, Any]) -> dict[str, Any]:
+        return reduce_report_json(json_report)
+
+    def to_markdown_summary(self, json_data: dict[str, Any], exclude_checks: list[str] | None = None) -> str:
+        return markdown_summary(json_data, exclude_checks=exclude_checks)
+
+
+class Action(Visitor):
+    """Minimal visitor that records remediation ideas.
+
+    Projects are encouraged to subclass this visitor and override the
+    ``visit_*`` methods to trigger concrete actions (ticketing, EDR tasks,
+    notifications, ...). The default implementation keeps things simple by
+    logging observables or threat intelligence above a configurable level.
+    """
+
+    def __init__(self, *, level_threshold: Level = Level.SUSPICIOUS, graph: bool = False) -> None:
+        super().__init__(graph=graph)
+        self.level_threshold = level_threshold
+        self.actions: list[dict[str, Any]] = []
+
+    def record_action(
+        self,
+        *,
+        name: str,
+        description: str,
+        impact: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        action = {
+            "name": name,
+            "description": description,
+            "impact": impact,
+            "context": context or {},
+        }
+        logger.info("[ACTION] {} -> {}", name, description)
+        self.actions.append(action)
+        return action
+
+    def visit_threat_intel(self, threat_intel: ThreatIntel) -> ThreatIntel:
+        if threat_intel.level >= self.level_threshold:
+            desc = f"{threat_intel.obs_type.name} {threat_intel.obs_value} flagged as {threat_intel.level.name}"
+            self.record_action(
+                name=f"threat_intel::{threat_intel.name}",
+                description=desc,
+                impact=threat_intel.level.name,
+                context={
+                    "score": threat_intel.score,
+                    "details": threat_intel.details,
+                    "extra": threat_intel.extra,
+                },
+            )
+        return threat_intel
+
+    def visit_observable(self, observable: Observable) -> Observable:
+        return observable
+
+    def visit_result_check(self, result_check: ResultCheck) -> ResultCheck:
+        return result_check
+
+    def visit_container(self, container: Container) -> Container:
+        return container
+
+    def visit_enrichment(self, enrichment: Enrichment) -> Enrichment:
+        return enrichment
+
+    def to_json(self) -> list[dict[str, Any]]:
+        return copy.deepcopy(self.actions)
+
+    def get_check(self, path: str) -> Any:
+        return None

cyvest-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: cyvest
+Version: 0.1.0
+Summary: Cybersecurity investigation model
+Author-email: PakitoSec <jeromep83@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PakitoSec/cyvest
+Project-URL: Repository, https://github.com/PakitoSec/cyvest
+Project-URL: Issues, https://github.com/PakitoSec/cyvest/issues
+Keywords: cybersecurity,incident-response,observability,threat-intelligence,reporting,graph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: logurich>=0.1
+Requires-Dist: rich>=13
+Dynamic: license-file
+
+# Cyvest – Cyber Investigation Model
+
+Reusable investigation domain models, visitor helpers, and reporting utilities for incident responders. Cyvest provides
+a consistent data model for threat intelligence, observables, and result checks while keeping the visitor layer
+extensible for bespoke workflows.
+
+## Features
+
+- Composition-friendly report builder that nests containers and checks.
+- Observable graph with automatic score/level propagation across relationships.
+- Visitor implementations for generating JSON/markdown reports or capturing follow-up actions.
+- Tested patterns for merging external intel feeds (VirusTotal, sandbox runs, allow-lists).
+
+## Installation
+
+Cyvest targets Python 3.10+ and is published on PyPI:
+
+```bash
+uv pip install cyvest
+```
+
+## Quick start
+
+Create a new report with nested containers and observables:
+
+```python
+from cyvest import Level, ObsType, ReportBuilder, Scope
+
+builder = ReportBuilder(graph=True)
+
+with builder.container("body", scope=Scope.BODY) as body:
+    check = body.add_check("url_scan", description="Detected suspicious URL")
+    check.add_observable_chain(
+        [
+            {
+                "obs_type": ObsType.URL,
+                "value": "http://example.test",
+                "intel": {"name": "sandbox", "score": 4, "level": Level.SUSPICIOUS},
+            }
+        ]
+    )
+
+report = builder.build()
+print(report.to_json())
+```
+
+Run the bundled example:
+
+```bash
+uv sync
+uv run python examples/basic_report.py
+```
+
+## Development workflow
+
+Set up dependencies with uv:
+
+```bash
+uv sync
+```
+
+Execute the unit suite:
+
+```bash
+uv run pytest tests
+```
+
+Lint and format using Ruff:
+
+```bash
+uv run ruff check
+uv run ruff format --check
+```
+
+## Graph & model axioms
+
+1. Cyclic graphs on observables or containables are not supported.
+2. Every root containable model must be visited. (Observables may be skipped because parent links are tracked.)
+3. Child observables do not update result checks linked only to their parents.
+4. A `ResultCheck` score cannot be changed by an observable that is mutated elsewhere.
+5. Adding an observable to a `ResultCheck` promotes the check to at least `Level.INFO` (a `Level.NONE` check becomes INFO).
+
+See `examples/` and the tests under `tests/` for more scenarios, including how to subclass the provided visitors to
+integrate your own tooling.

cyvest-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cyvest/__init__.py,sha256=DGa89MSj15F2VmdrC4g8UadNA4A3y95QI46RmGWWmkA,818
+cyvest/builder.py,sha256=j9B-xs5eYDX213RqYxWPzBTNOVE8vMgf1XtXDHaqf4w,5811
+cyvest/check_tree.py,sha256=SzAnnC0OuEOITWS-ptb1sXb9SKGwkvQgeGGApQ5ovF4,4539
+cyvest/models.py,sha256=Dl27Xj0MNKKAqYtS5-_M0s0Rp0EQ_dtIGt41ILNAMuE,26911
+cyvest/observable_registry.py,sha256=1LPTjhw9y_N9TdTX77cnvPJEwKGB-J_roGbl7YdC3K8,2623
+cyvest/report_render.py,sha256=VWWfIvDVn_9pEYy9gGUBcHP1EhAoWvv--WVmmpCNogc,12000
+cyvest/report_serialization.py,sha256=mrDHiW_0gM4JSnYzP3pxNo1HdHVSrYtwYX5EqguX5l8,9069
+cyvest/visitors.py,sha256=LJ1szpNrg0noZxkigvS4ZcVzQPDKM8kBbt2hd02k95E,12115
+cyvest-0.1.0.dist-info/licenses/LICENSE,sha256=EikdGl2Ew1IWY48h_1Ppwfh0QoIxXHQadQDovHSZZdE,1066
+cyvest-0.1.0.dist-info/METADATA,sha256=SuprQJa9USk9YGPrco2NGOFGAJ_6Qp7SyW9IPauCY_w,3367
+cyvest-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cyvest-0.1.0.dist-info/top_level.txt,sha256=IC_VayuEXgD7GqVsyh1h4g8P5WgXJ2ZrbNvdKhnh_Hw,7
+cyvest-0.1.0.dist-info/RECORD,,

cyvest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cyvest-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PakitoSec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cyvest-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cyvest