howler-api 3.0.0.dev374__py3-none-any.whl

howler/odm/models/ecs/event.py

@@ -0,0 +1,140 @@
+from howler import odm
+
+EVENT_CATEGORIES = [
+    "authentication",
+    "configuration",
+    "database",
+    "driver",
+    "email",
+    "file",
+    "host",
+    "iam",
+    "intrusion_detection",
+    "malware",
+    "network",
+    "package",
+    "process",
+    "registry",
+    "session",
+    "threat",
+    "web",
+]
+EVENT_KIND = [
+    "alert",
+    "enrichment",
+    "event",
+    "metric",
+    "state",
+    "pipeline_error",
+    "signal",
+]
+EVENT_TYPE = [
+    "access",
+    "admin",
+    "allowed",
+    "change",
+    "connection",
+    "creation",
+    "deletion",
+    "denied",
+    "end",
+    "error",
+    "group",
+    "indicator",
+    "info",
+    "installation",
+    "protocol",
+    "start",
+    "user",
+]
+EVENT_OUTCOME = ["failure", "success", "unknown"]
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="The event fields are used for context information about the log or metric event itself.",
+)
+class Event(odm.Model):
+    action = odm.Optional(odm.Keyword(description="The action captured by the event."))
+    category = odm.Optional(
+        odm.List(
+            odm.Enum(values=EVENT_CATEGORIES),
+            description='Represents the "big buckets" of ECS categories. For example, filtering on '
+            "event.category:process yields all events relating to process activity. This field is closely "
+            "related to event.type, which is used as a subcategory.",
+        )
+    )
+    code = odm.Optional(odm.Keyword(description="Identification code for this event, if one exists."))
+    count = odm.Integer(description="Count of events", optional=True)
+    created = odm.Optional(
+        odm.Date(description="Contains the date/time when the event was first read by an agent, or by your pipeline.")
+    )
+    dataset = odm.Optional(odm.Keyword(description="Name of the dataset."))
+    duration = odm.Optional(odm.Integer(description="Duration of the event in nanoseconds."))
+    end = odm.Optional(
+        odm.Date(description="Contains the date when the event ended or when the activity was last observed.")
+    )
+    hash = odm.Optional(
+        odm.Keyword(
+            description="Hash (perhaps logstash fingerprint) of raw field to be able to demonstrate log integrity."
+        )
+    )
+    id = odm.Optional(odm.Keyword(description="Unique ID to describe the event."))
+    ingested = odm.Date(
+        default="NOW",
+        description="Timestamp when an event arrived in the central data store.",
+    )
+    kind = odm.Optional(
+        odm.Enum(
+            values=EVENT_KIND,
+            description="Gives high-level information about what type of information the event "
+            "contains, without being specific to the contents of the event. ",
+        )
+    )
+    module = odm.Optional(odm.Keyword(description="Name of the module this data is coming from."))
+    original = odm.Optional(
+        odm.Keyword(
+            description="Raw text message of entire event. Used to demonstrate log integrity or where the "
+            "full log message (before splitting it up in multiple parts) may be required, e.g. for reindex."
+        )
+    )
+    outcome = odm.Optional(
+        odm.Enum(
+            values=EVENT_OUTCOME,
+            description="Simply denotes whether the event represents a success or "
+            "a failure from the perspective of the entity that produced the event.",
+        )
+    )
+    provider = odm.Optional(odm.Keyword(description="Source of the event."))
+    reason = odm.Optional(odm.Keyword(description="Reason why this event happened, according to the source."))
+    reference = odm.Optional(
+        odm.Keyword(description="Reference URL linking to additional information about this event.")
+    )
+    risk_score = odm.Optional(odm.Float(description="Risk score or priority of the event (e.g. security solutions)."))
+    risk_score_norm = odm.Optional(
+        odm.Float(description="Normalized risk score or priority of the event, on a scale of 0 to 100.")
+    )
+    sequence = odm.Optional(odm.Integer(description="Sequence number of the event."))
+    severity = odm.Optional(
+        odm.Integer(description="The numeric severity of the event according to your event source.")
+    )
+    start = odm.Optional(
+        odm.Date(description="Contains the date when the event started or when the activity was first observed.")
+    )
+    timezone = odm.Optional(
+        odm.Keyword(
+            description="This field should be populated when the event’s timestamp does not include timezone "
+            "information already (e.g. default Syslog timestamps)."
+        )
+    )
+    type = odm.Optional(
+        odm.List(
+            odm.Enum(values=EVENT_TYPE),
+            description='Represents a categorization "sub-bucket" that, when used along with the event.category '
+            "field values, enables filtering events down to a level appropriate for single visualization.",
+        )
+    )
+    url = odm.Optional(
+        odm.Keyword(description="URL linking to an external system to continue investigation of this event.")
+    )

howler/odm/models/ecs/faas.py

@@ -0,0 +1,24 @@
+from howler import odm
+
+TRIGGER_TYPES = ["http", "pubsub", "datasource", "timer", "other"]
+
+
+@odm.model(index=True, store=True, description="Details about the function trigger.")
+class Trigger(odm.Model):
+    request_id = odm.Optional(odm.Keyword(description="The ID of the trigger request , message, event, etc."))
+    type = odm.Optional(odm.Enum(values=TRIGGER_TYPES, description="The trigger for the function execution."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="The user fields describe information about the function as a "
+    "service (FaaS) that is relevant to the event.",
+)
+class FAAS(odm.Model):
+    coldstart = odm.Optional(odm.Boolean(description="Boolean value indicating a cold start of a function."))
+    execution = odm.Optional(odm.Keyword(description="The execution ID of the current function execution."))
+    id = odm.Optional(odm.Keyword(description="The unique identifier of a serverless function."))
+    name = odm.Optional(odm.Keyword(description="The name of a serverless function."))
+    trigger = odm.Optional(odm.Compound(Trigger, description="Details about the function trigger."))
+    version = odm.Optional(odm.Keyword(description="The version of a serverless function."))

howler/odm/models/ecs/file.py

@@ -0,0 +1,84 @@
+from typing import Optional
+
+from howler import odm
+from howler.odm.models.ecs.code_signature import CodeSignature
+from howler.odm.models.ecs.elf import ELF
+from howler.odm.models.ecs.hash import Hashes
+from howler.odm.models.ecs.pe import PE
+
+# from howler.odm.models.ecs.x509 import X509
+
+FILE_TYPE = ["file", "dir", "symlink"]
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="A file is defined as a set of information that has "
+    "been created on, or has existed on a filesystem.",
+)
+class File(odm.Model):
+    accessed: Optional[str] = odm.Optional(odm.Date(description="Last time the file was accessed."))
+    attributes: Optional[list[str]] = odm.Optional(odm.List(odm.Keyword(), description="Array of file attributes."))
+    created: Optional[str] = odm.Optional(odm.Date(description="File creation time."))
+    ctime: Optional[str] = odm.Optional(odm.Date(description="Last time the file attributes or metadata changed."))
+    device: Optional[str] = odm.Optional(odm.Keyword(description="Device that is the source of the file."))
+    directory: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description="Directory where the file is located. It should include the drive letter, when appropriate."
+        )
+    )
+    drive_letter: Optional[str] = odm.Optional(
+        odm.Keyword(description="Drive letter where the file is located. This field is only relevant on Windows.")
+    )
+    extension: Optional[str] = odm.Optional(odm.Keyword(description="File extension, excluding the leading dot."))
+    fork_name: Optional[str] = odm.Optional(
+        odm.Keyword(description="A fork is additional data associated with a filesystem object.")
+    )
+    gid: Optional[str] = odm.Optional(odm.Keyword(description="Primary group ID (GID) of the file."))
+    group: Optional[str] = odm.Optional(odm.Keyword(description="Primary group name of the file."))
+    inode: Optional[str] = odm.Optional(odm.Keyword(description="Inode representing the file in the filesystem."))
+    mime_type: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description="MIME type should identify the format of the file or stream of "
+            "bytes using IANA official types, where possible."
+        )
+    )
+    mode: Optional[str] = odm.Optional(odm.Keyword(description="Mode of the file in octal representation."))
+    mtime: Optional[str] = odm.Optional(odm.Date(description="Last time the file content was modified."))
+    name: Optional[str] = odm.Optional(
+        odm.Keyword(description="Name of the file including the extension, without the directory.")
+    )
+    owner: Optional[str] = odm.Optional(odm.Keyword(description="File owner’s username."))
+    path: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description="Full path to the file, including the file name. "
+            "It should include the drive letter, when appropriate."
+        )
+    )
+    size: Optional[int] = odm.Integer(description="File size in bytes.", optional=True)
+    target_path: Optional[str] = odm.Optional(odm.Keyword(description="Target path for symlinks."))
+    type: Optional[str] = odm.Optional(odm.Enum(values=FILE_TYPE, description="File type (file, dir, or symlink)."))
+    uid: Optional[str] = odm.Optional(
+        odm.Keyword(description="The user ID (UID) or security identifier (SID) of the file owner.")
+    )
+
+    code_signature: Optional[CodeSignature] = odm.Optional(
+        odm.Compound(
+            CodeSignature,
+            description="These fields contain information about binary code signatures.",
+        )
+    )
+    elf: Optional[ELF] = odm.Optional(
+        odm.Compound(
+            ELF,
+            description="These fields contain Linux Executable Linkable Format (ELF) metadata.",
+        )
+    )
+    hash: Optional[Hashes] = odm.Optional(
+        odm.Compound(
+            Hashes,
+            description="These fields contain Windows Portable Executable (PE) metadata.",
+        )
+    )
+    pe: Optional[PE] = odm.Optional(odm.Compound(PE, description="Hashes, usually file hashes."))

howler/odm/models/ecs/geo.py

@@ -0,0 +1,30 @@
+from howler import odm
+
+
+@odm.model(index=True, store=True, description="Longitude and latitude.")
+class GeoPoint(odm.Model):
+    lon = odm.Float(description="Longitude")
+    lat = odm.Float(description="Latitude")
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Geo fields can carry data about a specific location related to an event.",
+)
+class Geo(odm.Model):
+    city_name = odm.Optional(odm.Keyword(description="City name."))
+    continent_code = odm.Optional(odm.Keyword(description="Two-letter code representing continent’s name."))
+    continent_name = odm.Optional(odm.Keyword(description="Name of the continent."))
+    country_iso_code = odm.Optional(odm.Keyword(description="Country ISO code."))
+    country_name = odm.Optional(odm.Keyword(description="Country name."))
+    location = odm.Optional(odm.Compound(GeoPoint, description="Longitude and latitude."))
+    name = odm.Optional(
+        odm.Keyword(
+            description="User-defined description of a location, at the level " "of granularity they care about."
+        )
+    )
+    postal_code = odm.Optional(odm.Keyword(description="Postal code associated with the location."))
+    region_iso_code = odm.Optional(odm.Keyword(description="Region ISO code."))
+    region_name = odm.Optional(odm.Keyword(description="Region name."))
+    timezone = odm.Optional(odm.Keyword(description="The time zone of the location, such as IANA time zone name."))

howler/odm/models/ecs/group.py

@@ -0,0 +1,18 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="The group fields are meant to represent groups that are relevant to the event.",
+)
+class Group(odm.Model):
+    domain = odm.Optional(odm.Keyword(description="Name of the directory the group is a member of."))
+    id = odm.Optional(odm.Keyword(description="Unique identifier for the group on the system/platform."))
+    name = odm.Optional(odm.Keyword(description="Name of the group."))
+
+
+@odm.model(index=True, store=True, description="Shorter representation of a group.")
+class ShortGroup(odm.Model):
+    id = odm.Optional(odm.Keyword(description="Unique identifier for the group on the system/platform."))
+    name = odm.Optional(odm.Keyword(description="Name of the group."))

howler/odm/models/ecs/hash.py

@@ -0,0 +1,16 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="The hash fields represent different bitwise hash algorithms and their values.",
+)
+class Hashes(odm.Model):
+    md5 = odm.Optional(odm.MD5(description="MD5 hash."))
+    sha1 = odm.Optional(odm.SHA1(description="SHA1 hash."))
+    sha256 = odm.Optional(odm.SHA256(description="SHA256 hash."))
+    sha384 = odm.Optional(odm.ValidatedKeyword(r"^[a-f0-9]{96}$", description="SHA384 hash."))
+    sha512 = odm.Optional(odm.ValidatedKeyword(r"^[a-f0-9]{128}$", description="SHA512 hash."))
+    ssdeep = odm.Optional(odm.SSDeepHash(description="SSDEEP hash."))
+    tlsh = odm.Optional(odm.Keyword(description="TLSH hash."))

howler/odm/models/ecs/host.py

@@ -0,0 +1,17 @@
+from typing import Optional
+
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description=("A host is defined as a general computing instance."),
+)
+class Host(odm.Model):
+    id: Optional[str] = odm.Optional(odm.Keyword(description="Unique host id. Use Agent ID for HBS."))
+    ip: list[str] = odm.List(odm.IP(), default=[], description="Host ip addresses.")
+    mac: list[str] = odm.List(odm.Keyword(), default=[], description="Host MAC addresses.")
+    name: Optional[str] = odm.Optional(odm.Keyword(description="Name of the host."))
+    domain: Optional[str] = odm.Optional(odm.Keyword(description="Domain the host is a member of."))
+    type: Optional[str] = odm.Optional(odm.Keyword(description="As described by CSP."))

howler/odm/models/ecs/http.py

@@ -0,0 +1,37 @@
+from howler import odm
+
+
+@odm.model(index=True, store=True, description="Defines the body of a request/response.")
+class Body(odm.Model):
+    bytes = odm.Optional(odm.Integer(description="Size in bytes of the body."))
+    content = odm.Optional(odm.Keyword(description="The full HTTP body."))
+
+
+@odm.model(index=True, store=True, description="These fields can represent errors of any kind.")
+class Request(odm.Model):
+    body = odm.Optional(odm.Compound(Body, description="Defines the body of a request"))
+    bytes = odm.Optional(odm.Integer(description="Total size in bytes of the request (body and headers)."))
+    id = odm.Optional(
+        odm.Keyword(
+            description="A unique identifier for each HTTP request to correlate logs between clients "
+            "and servers in transactions."
+        )
+    )
+    method = odm.Optional(odm.Keyword(description="HTTP request method."))
+    mime_type = odm.Optional(odm.Keyword(description="Mime type of the body of the request."))
+    referrer = odm.Optional(odm.Keyword(description="Referrer for this HTTP request."))
+
+
+@odm.model(index=True, store=True, description="These fields can represent errors of any kind.")
+class Response(odm.Model):
+    body = odm.Optional(odm.Compound(Body, description="Defines the body of a response"))
+    bytes = odm.Optional(odm.Integer(description="Total size in bytes of the request (body and headers)."))
+    mime_type = odm.Optional(odm.Keyword(description="Mime type of the body of the request."))
+    status_code = odm.Optional(odm.Integer(description="HTTP response status code."))
+
+
+@odm.model(index=True, store=True, description="These fields can represent errors of any kind.")
+class HTTP(odm.Model):
+    request = odm.Optional(odm.Compound(Request, description="Request data."))
+    response = odm.Optional(odm.Compound(Response, description="Response data."))
+    version = odm.Optional(odm.Keyword(description="HTTP version."))

howler/odm/models/ecs/ingress.py

@@ -0,0 +1,12 @@
+from howler import odm
+from howler.odm.models.ecs.interface import Interface
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Holds information like interface number, name, vlan, and zone to classify ingress traffic",
+)
+class Ingress(odm.Model):
+    zone = odm.Optional(odm.Keyword(description="Network zone of incoming traffic as reported by observer"))
+    interface = odm.Optional(odm.Compound(Interface, description="Ingress Interface"))

howler/odm/models/ecs/interface.py

@@ -0,0 +1,21 @@
+from typing import Optional
+
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    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."
+    ),
+)
+class Interface(odm.Model):
+    id: Optional[int] = odm.Integer(
+        description="Interface ID as reported by an observer (typically SNMP interface ID).", optional=True
+    )
+    name: Optional[str] = odm.Optional(
+        odm.Keyword(description="Name of interface"),
+    )

howler/odm/models/ecs/network.py

@@ -0,0 +1,30 @@
+from typing import Optional
+
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="The network is defined as the communication path over which a host or network event happens.",
+)
+class Network(odm.Model):
+    direction: Optional[str] = odm.Keyword(
+        description=(
+            "The direction of network traffic relative to the host it was collected on. "
+            '(values: "OUTBOUND", "INBOUND", "LISTENING", "UNKNOWN")'
+        ),
+        optional=True,
+    )
+    protocol = odm.Optional(
+        odm.Keyword(
+            description="Application layer protocol in the OSI Model",
+        )
+    )
+    transport = odm.LowerKeyword(
+        description=(
+            "Transport layer protocol of the network traffic. "
+            '(values: "udp", "udp_listener", "tcp", "tcp_listener", "unknown")'
+        ),
+        optional=True,
+    )

howler/odm/models/ecs/observer.py

@@ -0,0 +1,45 @@
+from howler import odm
+from howler.odm.models.ecs.egress import Egress
+from howler.odm.models.ecs.ingress import Ingress
+from howler.odm.models.ecs.interface import Interface
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description=(
+        "Observer is defined as a special network, security, or application device used to detect, observe, "
+        "or create network, sercurity, or application event metrics"
+    ),
+)
+class Observer(odm.Model):
+    egress = odm.Optional(
+        odm.Compound(
+            Egress,
+            description="Holds information like interface number, name, vlan, and zone to classify ingress traffic",
+        )
+    )
+    hostname = odm.Optional(odm.Keyword(description="Hostname of the observer"))
+    ingress = odm.Optional(
+        odm.Compound(
+            Ingress,
+            description="Holds information like interface number, name, vlan, and zone to classify ingress traffic",
+        )
+    )
+    interface = odm.Optional(
+        odm.Compound(
+            Interface,
+            description="Interface being observed",
+        )
+    )
+    ip = odm.List(odm.IP(description="IP addresses of the observer."), default=[])
+    mac = odm.List(
+        odm.Keyword(description="Mac addresses of the observer."),
+        default=[],
+    )
+    name = odm.Optional(odm.Keyword(description="Custom name of the observer"))
+    product = odm.Optional(odm.Keyword(description="Product name of the observer"))
+    serial_number = odm.Optional(odm.Keyword(description="Observer serial number"))
+    type = odm.Optional(odm.Keyword(description="Type of the observer the data is coming from"))
+    vendor = odm.Optional(odm.Keyword(description="Vendor name of the observer"))
+    version = odm.Optional(odm.Keyword(description="Observer version"))

howler/odm/models/ecs/organization.py

@@ -0,0 +1,12 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="The organization fields enrich data with information "
+    "about the company or entity the data is associated with.",
+)
+class Organization(odm.Model):
+    id = odm.Optional(odm.Keyword(description="Unique identifier for the organization."))
+    name = odm.Keyword(description="Organization name.")

howler/odm/models/ecs/os.py

@@ -0,0 +1,21 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="The OS fields contain information about the operating system.",
+)
+class OS(odm.Model):
+    family = odm.Optional(odm.Keyword(description="OS family (such as redhat, debian, freebsd, windows)."))
+    full = odm.Optional(odm.Keyword(description="Operating system name, including the version or code name."))
+    kernel = odm.Optional(odm.Keyword(description="Operating system kernel version as a raw string."))
+    name = odm.Optional(odm.Keyword(description="Operating system name, without the version."))
+    platform = odm.Optional(odm.Keyword(description="Operating system platform (such centos, ubuntu, windows)."))
+    type = odm.Optional(
+        odm.Keyword(
+            description="Use the os.type field to categorize the operating "
+            "system into one of the broad commercial families."
+        )
+    )
+    version = odm.Optional(odm.Keyword(description="Operating system version as a raw string."))

howler/odm/models/ecs/pe.py

@@ -0,0 +1,17 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="These fields contain Windows Portable Executable (PE) metadata.",
+)
+class PE(odm.Model):
+    architecture = odm.Optional(odm.Keyword(description="CPU architecture target for the file."))
+    company = odm.Optional(odm.Keyword(description="Internal company name of the file, provided at compile-time."))
+    description = odm.Optional(odm.Keyword(description="Internal description of the file, provided at compile-time."))
+    file_version = odm.Optional(odm.Keyword(description="Internal version of the file, provided at compile-time."))
+    imphash = odm.Optional(odm.Keyword(description="A hash of the imports in a PE file."))
+    original_file_name = odm.Optional(odm.Keyword(description="Internal name of the file, provided at compile-time."))
+    pehash = odm.Optional(odm.Keyword(description="A hash of the PE header and data from one or more PE sections."))
+    product = odm.Optional(odm.Keyword(description="Internal product name of the file, provided at compile-time."))