howler-evidence-plugin 0.1.0.dev120__tar.gz

howler_evidence_plugin-0.1.0.dev120/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Canadian Centre for Cyber Security
+
+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.

howler_evidence_plugin-0.1.0.dev120/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: howler-evidence-plugin
+Version: 0.1.0.dev120
+Summary: A howler plugin to add additional nested ECS fields to the Howler ODM
+License: MIT
+License-File: LICENSE
+Author: CCCS
+Author-email: analysis-development@cyber.gc.ca
+Requires-Python: >=3.9.17, <4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# Howler Evidence Plugin
+
+A howler plugin to add additional nested ECS fields to the Howler ODM.
+

howler_evidence_plugin-0.1.0.dev120/README.md

@@ -0,0 +1,3 @@
+# Howler Evidence Plugin
+
+A howler plugin to add additional nested ECS fields to the Howler ODM.

howler_evidence_plugin-0.1.0.dev120/evidence/config.py

@@ -0,0 +1,38 @@
+# mypy: ignore-errors
+import os
+from pathlib import Path
+
+from howler.plugins.config import BasePluginConfig
+from pydantic_settings import SettingsConfigDict
+
+APP_NAME = os.environ.get("APP_NAME", "howler")
+PLUGIN_NAME = "evidence"
+
+root_path = Path("/etc") / APP_NAME.replace("-dev", "").replace("-stg", "")
+
+config_locations = [
+    Path(__file__).parent / "manifest.yml",
+    root_path / "conf" / f"{PLUGIN_NAME}.yml",
+    Path(os.environ.get("HWL_CONF_FOLDER", root_path)) / f"{PLUGIN_NAME}.yml",
+]
+
+
+class EvidenceConfig(BasePluginConfig):
+    "Evidence Plugin Configuration Model"
+
+    model_config = SettingsConfigDict(
+        yaml_file=config_locations,
+        yaml_file_encoding="utf-8",
+        strict=True,
+        env_nested_delimiter="__",
+        env_prefix=f"{PLUGIN_NAME}_",
+    )
+
+
+config = EvidenceConfig()
+
+if __name__ == "__main__":
+    # When executed, the config model will print the default values of the configuration
+    import yaml
+
+    print(yaml.safe_dump(EvidenceConfig().model_dump(mode="json")))  # noqa: T201

howler_evidence_plugin-0.1.0.dev120/evidence/manifest.yml

@@ -0,0 +1,5 @@
+name: evidence
+modules:
+  odm:
+    modify_odm:
+      hit: true

howler_evidence_plugin-0.1.0.dev120/evidence/odm/hit.py

@@ -0,0 +1,31 @@
+from random import randint
+
+import howler.odm as odm
+from howler.common.logging import get_logger
+from howler.odm.models.hit import Hit
+from howler.odm.randomizer import random_model_obj
+
+from evidence.odm.models.evidence import Evidence
+
+logger = get_logger(__file__)
+
+
+def modify_odm(target: odm.Model):
+    "Add additional internal fields to the ODM"
+    logger.info("Modifying ODM with additional fields")
+
+    target.add_namespace(
+        "evidence",
+        odm.List(
+            odm.Compound(Evidence),
+            default=[],
+            description="A list of additional ECS objects.",
+        ),
+    )
+
+
+def generate_useful_hit(hit: Hit) -> Hit:
+    "Add cccs-specific changes to hits on generation"
+    hit.evidence = [random_model_obj(Evidence) for _ in range(randint(1, 3))]
+
+    return ["evidence"], hit

howler_evidence_plugin-0.1.0.dev120/evidence/odm/models/evidence.py

@@ -0,0 +1,292 @@
+from howler import odm
+from howler.odm.models.ecs.agent import Agent
+from howler.odm.models.ecs.client import Client
+from howler.odm.models.ecs.cloud import Cloud
+from howler.odm.models.ecs.container import Container
+from howler.odm.models.ecs.dns import DNS
+from howler.odm.models.ecs.email import Email
+from howler.odm.models.ecs.error import Error
+from howler.odm.models.ecs.event import Event
+from howler.odm.models.ecs.faas import FAAS
+from howler.odm.models.ecs.file import File
+from howler.odm.models.ecs.group import Group
+from howler.odm.models.ecs.host import Host
+from howler.odm.models.ecs.http import HTTP
+from howler.odm.models.ecs.interface import Interface
+from howler.odm.models.ecs.network import Network
+from howler.odm.models.ecs.observer import Observer
+from howler.odm.models.ecs.organization import Organization
+from howler.odm.models.ecs.process import Process
+from howler.odm.models.ecs.registry import Registry
+from howler.odm.models.ecs.related import Related
+from howler.odm.models.ecs.rule import Rule
+from howler.odm.models.ecs.server import Server
+from howler.odm.models.ecs.threat import Threat
+from howler.odm.models.ecs.tls import TLS
+from howler.odm.models.ecs.url import URL
+from howler.odm.models.ecs.user import User
+from howler.odm.models.ecs.user_agent import UserAgent
+from howler.odm.models.ecs.vulnerability import Vulnerability
+from howler.odm.models.hit import ECSVersion
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Evidence fields add a list of additional ECS objects.",
+)
+class Evidence(odm.Model):
+    # Base Fields
+    timestamp: str = odm.Date(
+        default="NOW",
+        description="Date/time when the event originated.",
+        reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-base.html",
+    )
+    labels: dict[str, str] = odm.Mapping(
+        odm.Keyword(),
+        default={},
+        description="Custom key/value pairs.",
+        reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-base.html",
+    )
+    tags: list[str] = odm.List(
+        odm.Keyword(),
+        default=[],
+        description="List of keywords used to tag each event.",
+        reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-base.html",
+    )
+    message: str = odm.Keyword(
+        default="",
+        description="Log message for log events, optimized for viewing in a log viewer",
+        reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-base.html",
+    )
+
+    # Field Sets
+    agent: Agent = odm.Optional(
+        odm.Compound(
+            Agent,
+            description="The agent fields contain the data about the software entity, "
+            "if any, that collects, detects, or observes events on a host, or takes measurements on a host.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-agent.html",
+        )
+    )
+    cloud: Cloud = odm.Optional(
+        odm.Compound(
+            Cloud,
+            description="Fields related to the cloud or infrastructure the events are coming from.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-cloud.html",
+        )
+    )
+    container: Container = odm.Optional(
+        odm.Compound(
+            Container,
+            description="Container fields are used for meta information about the specific container "
+            "that is the source of information.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-container.html",
+        )
+    )
+    destination: Client = odm.Optional(
+        odm.Compound(
+            Client,
+            description="Destination fields capture details about the receiver of a network exchange/packet.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-destination.html",
+        )
+    )
+    dns: DNS = odm.Optional(
+        odm.Compound(
+            DNS,
+            description="Fields describing DNS queries and answers.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-dns.html",
+        )
+    )
+    ecs: ECSVersion = odm.Compound(
+        ECSVersion,
+        default={},
+        description="Meta-information specific to ECS.",
+        reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-ecs.html",
+    )
+    error: Error = odm.Optional(
+        odm.Compound(
+            Error,
+            description="These fields can represent errors of any kind.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-error.html",
+        )
+    )
+    event: Event = odm.Optional(
+        odm.Compound(
+            Event,
+            description="The event fields are used for context information about the log or metric event itself.",
+        )
+    )
+    email: Email = odm.Optional(
+        odm.Compound(
+            Email,
+            description="Event details relating to an email transaction.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-event.html",
+        )
+    )
+    faas: FAAS = odm.Optional(
+        odm.Compound(
+            FAAS,
+            description="The user fields describe information about the function as a service "
+            "(FaaS) that is relevant to the event.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-faas.html",
+        )
+    )
+    file: File = odm.Optional(
+        odm.Compound(
+            File,
+            description="A file is defined as a set of information that has been "
+            "created on, or has existed on a filesystem.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-file.html",
+        )
+    )
+    group: Group = odm.Optional(
+        odm.Compound(
+            Group,
+            description="The group fields are meant to represent groups that are relevant to the event.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-group.html",
+        )
+    )
+    host: Host = odm.Optional(
+        odm.Compound(Host),
+        description=(
+            "A host is defined as a general computing instance. ECS host.* fields should be populated with details "
+            "about the host on which the event happened, or from which the measurement was taken. Host types include "
+            "hardware, virtual machines, Docker containers, and Kubernetes nodes."
+        ),
+        reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-host.html",
+    )
+    http: HTTP = odm.Optional(
+        odm.Compound(
+            HTTP,
+            description="Fields related to HTTP activity. Use the url field set to store the url of the request.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-http.html",
+        )
+    )
+    observer: Observer = odm.Optional(
+        odm.Compound(
+            Observer,
+            description=(
+                "Observer is defined as a special network, security, or application device used to detect, obs"
+                "erve, or create network, sercurity, or application event metrics"
+            ),
+        )
+    )
+    interface: Interface = odm.Optional(
+        odm.Compound(
+            Interface,
+            description=(
+                "The interface fields are used to record ingress and egress interface information when reported "
+                "by an observer (e.g. firewall, router, load balancer) in the context of the observer handling a "
+                "network connection. "
+            ),
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-interface.html",
+        )
+    )
+    network: Network = odm.Optional(
+        odm.Compound(
+            Network,
+            description=(
+                "The network is defined as the communication path over which a host or network event happens."
+            ),
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-network.html",
+        )
+    )
+    organization: Organization = odm.Optional(
+        odm.Compound(
+            Organization,
+            description="The organization fields enrich data with information "
+            "about the company or entity the data is associated with.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-organization.html",
+        )
+    )
+    process: Process = odm.Optional(
+        odm.Compound(
+            Process,
+            description="These fields contain information about a process.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-process.html",
+        )
+    )
+    registry: Registry = odm.Optional(
+        odm.Compound(
+            Registry,
+            description="Fields related to Windows Registry operations.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-registry.html",
+        )
+    )
+    related: Related = odm.Optional(
+        odm.Compound(
+            Related,
+            description="Fields related to Windows Registry operations.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-related.html",
+        )
+    )
+    rule: Rule = odm.Optional(
+        odm.Compound(
+            Rule,
+            description="Capture the specifics of any observer or agent rules",
+        )
+    )
+    server: Server = odm.Optional(
+        odm.Compound(Server),
+        description=(
+            "A Server is defined as the responder in a network connection for events regarding sessions, "
+            "connections, or bidirectional flow records."
+        ),
+        reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-server.html",
+    )
+    source: Client = odm.Optional(
+        odm.Compound(
+            Client,
+            description="Source fields capture details about the sender of a network exchange/packet.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-source.html",
+        )
+    )
+    threat: Threat = odm.Optional(
+        odm.Compound(
+            Threat,
+            description="Fields to classify events and alerts according to a threat taxonomy such as the "
+            "MITRE ATT&CK® framework.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-threat.html",
+        )
+    )
+    tls: TLS = odm.Optional(
+        odm.Compound(
+            TLS,
+            description=(
+                "Fields related to a TLS connection. These fields focus on the TLS protocol itself and "
+                "intentionally avoids in-depth analysis of the related x.509 certificate files."
+            ),
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-tls.html",
+        )
+    )
+    url: URL = odm.Optional(
+        odm.Compound(
+            URL,
+            description="URL fields provide support for complete or partial URLs, and "
+            "supports the breaking down into scheme, domain, path, and so on.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-url.html",
+        )
+    )
+    user: User = odm.Optional(
+        odm.Compound(
+            User,
+            description="The user fields describe information about the user that is relevant to the event.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-user.html",
+        )
+    )
+    user_agent: UserAgent = odm.Optional(
+        odm.Compound(
+            UserAgent,
+            description="The user_agent fields normally come from a browser request.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-user_agent.html",
+        )
+    )
+    vulnerability: Vulnerability = odm.Optional(
+        odm.Compound(
+            Vulnerability,
+            description="The vulnerability fields describe information about a vulnerability that "
+            "is relevant to an event.",
+            reference="https://www.elastic.co/guide/en/ecs/8.5/ecs-vulnerability.html",
+        )
+    )

howler_evidence_plugin-0.1.0.dev120/pyproject.toml

@@ -0,0 +1,154 @@
+[project]
+name = "howler-evidence-plugin"
+version = "0.1.0.dev120"
+description = "A howler plugin to add additional nested ECS fields to the Howler ODM"
+authors = [{ name = "CCCS", email = "analysis-development@cyber.gc.ca" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.9.17, <4.0"
+
+######################
+# autoflake settings #
+######################
+[tool.autoflake]
+check = true
+
+##################
+# Black settings #
+##################
+[tool.black]
+line-length = 120
+
+########################
+# coverage.py settings #
+########################
+[tool.coverage.run]
+branch = true
+sigterm = true
+data_file = ".coverage"
+
+[tool.coverage.report]
+exclude_also = [
+    "def __repr__",
+    "if DEBUG:",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@(abc\\.)?abstractmethod]",
+    "if \"pytest\" in sys.modules:",
+]
+
+#################
+# Mypy settings #
+#################
+[tool.mypy]
+warn_unused_configs = true
+ignore_missing_imports = true
+check_untyped_defs = true
+disable_error_code = "no-redef"
+exclude = "test"
+
+[[tool.mypy.overrides]]
+module = "howler.odm.models.*"
+disable_error_code = "assignment"
+
+[[tool.mypy.overrides]]
+module = ["howler.odm.base", "test", "test.*"]
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "howler.security"
+disable_error_code = "attr-defined"
+
+[[tool.mypy.overrides]]
+module = "howler.odm.helper"
+disable_error_code = "union-attr"
+
+[[tool.mypy.overrides]]
+module = "howler.common.classification"
+disable_error_code = "assignment"
+
+[[tool.mypy.overrides]]
+module = "requests"
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "C901",
+    "I",
+    "N",
+    "D1",
+    "D2",
+    "ANN",
+    "S",
+    "T20",
+    "PIE",
+    "FLY",
+    "TRY",
+]
+ignore = [
+    "ANN003",
+    "ANN201",
+    "ANN401",
+    "D100",
+    "D104",
+    "D105",
+    "D107",
+    "D203",
+    "D213",
+    "N818",
+    "S603",
+    "TRY003",
+    "TRY300",
+]
+exclude = ["howler/patched.py"]
+
+[tool.ruff.lint.flake8-annotations]
+ignore-fully-untyped = true
+mypy-init-return = true
+suppress-dummy-args = true
+suppress-none-returning = true
+
+[tool.ruff.lint.per-file-ignores]
+"evidence/**/__init__.py" = ["F401"]
+"evidence/odm/hit.py" = ["S311"]
+"evidence/odm/models/*" = ["D", "ANN", "C901"]
+"test/*" = ["D", "ANN", "S", "N818", "TRY", "PIE", "E402"]
+"build_scripts/*" = ["D", "ANN", "S", "N818", "T20", "TRY"]
+
+[tool.poetry]
+packages = [{ include = "evidence" }]
+
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.11.7"
+mypy = "^1.15.0"
+pre-commit = "^4.2.0"
+howler-api = { path = "../../api" }
+pytest = "^8.3.5"
+mock = "^5.2.0"
+pytest-cov = "^6.1.1"
+coverage = { extras = ["toml"], version = "^7.8.0" }
+diff-cover = "^9.2.4"
+python-dotenv = "^1.1.0"
+
+
+[tool.poetry.group.types.dependencies]
+types-mock = "^5.2.0.20250516"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.scripts]
+type_check = "build_scripts.type_check:main"