cyvest 0.1.0__tar.gz

cyvest-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,84 @@
+# 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/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "cyvest"
+version = "0.1.0"
+description = "Cybersecurity investigation model"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "PakitoSec", email = "jeromep83@gmail.com" }
+]
+dependencies = ["logurich>=0.1", "rich>=13"]
+keywords = ["cybersecurity", "incident-response", "observability", "threat-intelligence", "reporting", "graph"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: Security",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/PakitoSec/cyvest"
+Repository = "https://github.com/PakitoSec/cyvest"
+Issues = "https://github.com/PakitoSec/cyvest/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.6",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["cyvest"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"

cyvest-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cyvest-0.1.0/src/cyvest/__init__.py

@@ -0,0 +1,47 @@
+"""Investigation models."""
+
+__all__: list[str]
+__version__ = "0.1.0"
+
+from .builder import ReportBuilder
+from .models import (
+    MAP_LEVEL_DATA,
+    ContainableSLM,
+    Container,
+    Enrichment,
+    Level,
+    Model,
+    Observable,
+    ObsType,
+    ResultCheck,
+    Scope,
+    ScoredLevelModel,
+    ThreatIntel,
+    get_color_level,
+    get_color_score,
+    get_level_from_score,
+)
+from .visitors import Action, Report, Visitor
+
+__all__ = [
+    "Action",
+    "Container",
+    "ContainableSLM",
+    "Enrichment",
+    "Level",
+    "MAP_LEVEL_DATA",
+    "Model",
+    "Observable",
+    "ObsType",
+    "Report",
+    "ResultCheck",
+    "Scope",
+    "ScoredLevelModel",
+    "ThreatIntel",
+    "Visitor",
+    "get_color_level",
+    "get_color_score",
+    "get_level_from_score",
+    "ReportBuilder",
+    "__version__",
+]

cyvest-0.1.0/src/cyvest/builder.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterable, Sequence
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from typing import Any
+
+from .models import ContainableSLM, Container, Level, ResultCheck, Scope
+from .visitors import Report
+
+
+@dataclass
+class _ContainerNode:
+    container: Container
+
+
+class _ContainerContext(AbstractContextManager["BuilderContainerProxy"]):
+    def __init__(self, builder: ReportBuilder, node: _ContainerNode) -> None:
+        self._builder = builder
+        self._node = node
+
+    def __enter__(self) -> BuilderContainerProxy:
+        self._builder._enter_container(self._node)
+        return BuilderContainerProxy(self._builder, self._node)
+
+    def __exit__(self, exc_type, exc, exc_tb) -> None:
+        self._builder._exit_container(self._node)
+
+
+class BuilderContainerProxy:
+    def __init__(self, builder: ReportBuilder, node: _ContainerNode) -> None:
+        self._builder = builder
+        self._node = node
+
+    def add_check(
+        self,
+        path: str,
+        *,
+        identifier: str | None = None,
+        description: str | None = None,
+        level: Level = Level.INFO,
+        score: float = 0.0,
+        details: dict | None = None,
+        observable_chain: Sequence[dict[str, Any]] | None = None,
+    ) -> ResultCheck:
+        return self._builder.add_check(
+            path,
+            scope=self._node.container.scope,
+            identifier=identifier,
+            description=description,
+            level=level,
+            score=score,
+            details=details,
+            observable_chain=observable_chain,
+        )
+
+    def add_existing(self, node: ContainableSLM) -> ContainableSLM:
+        return self._builder.add_existing(node)
+
+    def container(
+        self,
+        path: str,
+        *,
+        scope: Scope | None = None,
+        description: str | None = None,
+        identifier: str | None = None,
+        level: Level = Level.INFO,
+        details: dict | None = None,
+    ) -> _ContainerContext:
+        container_scope = scope or self._node.container.scope
+        return self._builder.container(
+            path,
+            scope=container_scope,
+            description=description,
+            identifier=identifier,
+            level=level,
+            details=details,
+        )
+
+
+class ReportBuilder:
+    """Helper for constructing reports with nested containers and checks."""
+
+    def __init__(self, report: Report | None = None, *, graph: bool = False) -> None:
+        self.report: Report = report or Report(graph=graph)
+        self._stack: list[_ContainerNode] = []
+        self._roots: list[ContainableSLM] = []
+        self._lock = threading.RLock()
+
+    def container(
+        self,
+        path: str,
+        *,
+        scope: Scope,
+        description: str | None = None,
+        identifier: str | None = None,
+        level: Level = Level.INFO,
+        details: dict | None = None,
+    ) -> _ContainerContext:
+        container = Container(
+            path,
+            scope=scope,
+            identifier=identifier,
+            description=description,
+            score=0.0,
+            level=level,
+            details=details,
+        )
+        node = _ContainerNode(container)
+        return _ContainerContext(self, node)
+
+    def add_check(
+        self,
+        path: str,
+        *,
+        scope: Scope | None = None,
+        identifier: str | None = None,
+        description: str | None = None,
+        level: Level = Level.INFO,
+        score: float = 0.0,
+        details: dict | None = None,
+        observable_chain: Sequence[dict[str, Any]] | None = None,
+    ) -> ResultCheck:
+        with self._lock:
+            check_scope = scope
+            if check_scope is None:
+                if not self._stack:
+                    raise ValueError("Scope must be provided when adding a check outside a container context")
+                check_scope = self._stack[-1].container.scope
+            result_check = ResultCheck.create(
+                path,
+                scope=check_scope,
+                identifier=identifier,
+                description=description,
+                level=level,
+                score=score,
+                details=details,
+            )
+            if self._stack:
+                self._stack[-1].container.contain(result_check)
+            else:
+                self._roots.append(result_check)
+        if observable_chain:
+            result_check.add_observable_chain(observable_chain)
+        return result_check
+
+    def build(self) -> Report:
+        with self._lock:
+            roots = list(self._roots)
+            self._roots.clear()
+        for root in roots:
+            root.accept(self.report)
+        return self.report
+
+    def add_existing(self, node: ContainableSLM) -> ContainableSLM:
+        with self._lock:
+            if self._stack:
+                self._stack[-1].container.contain(node)
+            else:
+                self._roots.append(node)
+        return node
+
+    def extend_existing(self, nodes: Iterable[ContainableSLM]) -> None:
+        for node in nodes:
+            self.add_existing(node)
+
+    # Internal helpers -------------------------------------------------
+    def _enter_container(self, node: _ContainerNode) -> None:
+        with self._lock:
+            if self._stack:
+                parent = self._stack[-1].container
+                parent.contain(node.container)
+            else:
+                self._roots.append(node.container)
+            self._stack.append(node)
+
+    def _exit_container(self, node: _ContainerNode) -> None:
+        with self._lock:
+            if not self._stack or self._stack[-1] is not node:
+                raise RuntimeError("Container context stack is inconsistent")
+            self._stack.pop()

cyvest-0.1.0/src/cyvest/check_tree.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from collections import OrderedDict, defaultdict
+from collections.abc import Iterable
+
+from .models import ContainableSLM, Container, Level, ResultCheck
+
+
+class CheckTree:
+    """Canonical structure that stores containers/result checks and keeps their scores in sync."""
+
+    def __init__(self) -> None:
+        self._nodes: dict[str, ContainableSLM] = {}
+        self._roots: dict[str, OrderedDict[str, ContainableSLM]] = defaultdict(OrderedDict)
+
+    def integrate_container(self, container: Container) -> Container:
+        return self._integrate_container(container, seen=set())
+
+    def integrate_result_check(self, result_check: ResultCheck) -> ResultCheck:
+        return self._integrate_result_check(result_check, seen=set())
+
+    def _integrate_container(self, container: Container, seen: set[int]) -> Container:
+        if id(container) in seen:
+            existing = self._nodes.get(container.full_key)
+            if isinstance(existing, Container):
+                return existing
+        seen.add(id(container))
+        parent = container.parent
+        if parent is not None:
+            parent = self._integrate_container(parent, seen)
+            container.set_parent(parent)
+        key = container.full_key
+        existing = self._nodes.get(key)
+        if isinstance(existing, Container):
+            existing.merge_from(container)
+            target = existing
+        else:
+            target = container
+            self._nodes[key] = target
+            if target.parent is not None:
+                target.parent.attach_child(target)
+            else:
+                root_scope = target.scope.name if target.scope else "GLOBAL"
+                self._roots[root_scope][key] = target
+        # integrate children
+        for child in list(container.children):
+            if isinstance(child, Container):
+                child.set_parent(target)
+                self._integrate_container(child, seen)
+            else:
+                child.set_parent(target)
+                self._integrate_result_check(child, seen)
+        target.recompute()
+        self._recompute_upwards(target.parent)
+        return target
+
+    def _integrate_result_check(self, result_check: ResultCheck, seen: set[int]) -> ResultCheck:
+        if id(result_check) in seen:
+            existing = self._nodes.get(result_check.full_key)
+            if isinstance(existing, ResultCheck):
+                return existing
+        seen.add(id(result_check))
+        parent = result_check.parent
+        if parent is not None:
+            parent = self._integrate_container(parent, seen)
+            result_check.set_parent(parent)
+        key = result_check.full_key
+        existing = self._nodes.get(key)
+        if isinstance(existing, ResultCheck):
+            existing.merge_from(result_check)
+            target = existing
+        else:
+            target = result_check
+            self._nodes[key] = target
+            if target.parent is not None:
+                target.parent.attach_child(target)
+            else:
+                scope_name = target.scope.name if target.scope else "GLOBAL"
+                self._roots[scope_name][key] = target
+        self._recompute_upwards(target.parent)
+        return target
+
+    def _recompute_upwards(self, node: Container | None) -> None:
+        current = node
+        while current is not None:
+            current.recompute()
+            current = current.parent
+
+    def get(self, full_key: str) -> ContainableSLM | None:
+        return self._nodes.get(full_key)
+
+    def total_score(self) -> float:
+        return sum(node.score for node in self._nodes.values() if isinstance(node, ResultCheck))
+
+    def highest_level(self) -> Level:
+        highest = Level.INFO
+        for node in self._nodes.values():
+            if node.level > highest:
+                highest = node.level
+        return highest
+
+    def result_checks(self) -> Iterable[ResultCheck]:
+        for node in self._nodes.values():
+            if isinstance(node, ResultCheck):
+                yield node
+
+    def containers(self) -> Iterable[Container]:
+        for node in self._nodes.values():
+            if isinstance(node, Container):
+                yield node
+
+    def roots_for_scope(self, scope_name: str) -> list[ContainableSLM]:
+        return list(self._roots.get(scope_name, {}).values())
+
+    def iter_roots(self) -> Iterable[tuple[str, list[ContainableSLM]]]:
+        for scope_name, nodes in self._roots.items():
+            yield scope_name, list(nodes.values())