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

howler/odm/models/ecs/client.py

@@ -0,0 +1,149 @@
+# mypy: ignore-errors
+from typing import Optional
+
+from howler import odm
+from howler.odm.models.ecs.autonomous_system import AS
+from howler.odm.models.ecs.geo import Geo
+from howler.odm.models.ecs.user import User
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Translated NAT sessions (e.g. internal client to internet).",
+)
+class Nat(odm.Model):
+    ip = odm.Optional(odm.IP(description="Translated IP of source based NAT sessions."))
+    port = odm.Optional(odm.Integer(description="Translated port of source based NAT sessions."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="A client is defined as the initiator of a network connection "
+    "for events regarding sessions, connections, or bidirectional flow records.",
+)
+class OriginalClient(odm.Model):
+    address: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description=(
+                "The original client in a session that has changed clients. Some event client addresses "
+                "are defined ambiguously. The event will sometimes list an IP, a domain or a unix socket. You should"
+                " always store the raw address in the .address field."
+            )
+        )
+    )
+    autonomous_systems: AS = odm.Optional(
+        odm.Compound(
+            AS,
+            description=(
+                "The original client in a session that has changed clients. "
+                "Collection of connected Internal Protocol routing prefixes"
+            ),
+        )
+    )
+    bytes: Optional[int] = odm.Optional(
+        odm.Integer(
+            description=(
+                "The original client in a session that has changed clients. "
+                "Bytes sent from the client to the server."
+            )
+        )
+    )
+    domain: Optional[str] = odm.Optional(
+        odm.Domain(
+            description=(
+                "The original client in a session that has changed clients. " "The domain name of the client system."
+            )
+        )
+    )
+    geo: Geo = odm.Optional(
+        odm.Compound(
+            Geo,
+            description=(
+                "The original client in a session that has changed clients. Geo fields can carry "
+                "data about a specific location related to an event."
+            ),
+        )
+    )
+    ip: Optional[str] = odm.Optional(
+        odm.IP(
+            description=(
+                "The original client in a session that has changed clients. IP address of the " "client (IPv4 or IPv6)."
+            )
+        )
+    )
+    mac: Optional[str] = odm.Optional(
+        odm.MAC(description=("The original client in a session that has changed clients. MAC address of the client."))
+    )
+    nat: Nat = odm.Optional(
+        odm.Compound(
+            Nat,
+            description=(
+                "The original client in a session that has changed clients. Translated NAT sessions (e.g. "
+                "internal client to internet)."
+            ),
+        )
+    )
+    packets: Optional[int] = odm.Optional(
+        odm.Integer(
+            description=(
+                "The original client in a session that has changed clients. Packets sent from the "
+                "destination to the source."
+            )
+        )
+    )
+    port: Optional[int] = odm.Optional(
+        odm.Integer(description="The original client in a session that has changed clients. Port of the client.")
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="A client is defined as the initiator of a network connection "
+    "for events regarding sessions, connections, or bidirectional flow records.",
+)
+class Client(odm.Model):
+    address: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description="Some event client addresses are defined ambiguously. The event will sometimes list an IP, "
+            "a domain or a unix socket. You should always store the raw address in the .address field."
+        )
+    )
+    autonomous_systems: AS = odm.Optional(
+        odm.Compound(
+            AS,
+            description="Collection of connected Internal Protocol routing prefixes",
+        )
+    )
+    bytes: Optional[int] = odm.Optional(odm.Long(description="Bytes sent from the client to the server."))
+    domain: Optional[str] = odm.Optional(odm.Keyword(description="The domain name of the client system."))
+    geo: Geo = odm.Optional(
+        odm.Compound(
+            Geo,
+            description="Geo fields can carry data about a specific location related to an event.",
+        )
+    )
+    ip: Optional[str] = odm.Optional(odm.IP(description="IP address of the client (IPv4 or IPv6)."))
+    mac: Optional[str] = odm.Optional(odm.MAC(description="MAC address of the client."))
+    nat: Nat = odm.Optional(
+        odm.Compound(
+            Nat,
+            description="Translated NAT sessions (e.g. internal client to internet).",
+        )
+    )
+    packets: Optional[int] = odm.Optional(odm.Integer(description="Packets sent from the destination to the source."))
+    port: Optional[int] = odm.Optional(odm.Integer(description="Port of the client."))
+    user: User = odm.Optional(
+        odm.Compound(
+            User,
+            description="The user fields describe information about the user that is relevant to the event.",
+        )
+    )
+    original: OriginalClient = odm.Optional(
+        odm.Compound(
+            OriginalClient,
+            description="Original Client Data.",
+        )
+    )

howler/odm/models/ecs/cloud.py

@@ -0,0 +1,141 @@
+from typing import Optional
+
+from howler import odm
+
+
+@odm.model(index=True, store=True, description="Cloud account information.")
+class Account(odm.Model):
+    id: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description="The cloud account or organization id used to identify different entities in a "
+            "multi-tenant environment.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        ),
+    )
+    name: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description="The cloud account name or alias used to identify different entities in a "
+            "multi-tenant environment.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        ),
+    )
+
+
+@odm.model(index=True, store=True, description="Instance information.")
+class Instance(odm.Model):
+    id = odm.Optional(odm.Keyword(description="Instance ID of the host machine."))
+    name = odm.Optional(odm.Keyword(description="Instance name of the host machine."))
+
+
+@odm.model(index=True, store=True, description="Project information.")
+class Project(odm.Model):
+    id = odm.Optional(
+        odm.Keyword(
+            description="The cloud project identifier.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        )
+    )
+    name = odm.Optional(
+        odm.Keyword(
+            description="The cloud project name.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        )
+    )
+
+
+@odm.model(index=True, store=True, description="Machine information.")
+class Machine(odm.Model):
+    type = odm.Optional(odm.Keyword(description="Machine type of the host machine."))
+
+
+@odm.model(index=True, store=True, description="Service information.")
+class Service(odm.Model):
+    name = odm.Optional(
+        odm.Keyword(
+            description="The cloud service name is intended to distinguish services running on different platforms "
+            "within a provider, eg AWS EC2 vs Lambda, GCP GCE vs App Engine, Azure VM vs App Server."
+        )
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Fields related to the cloud or infrastructure the events are coming from.",
+)
+class Cloud(odm.Model):
+    account = odm.Optional(
+        odm.Compound(
+            Account,
+            description="Cloud account information.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        )
+    )
+    availability_zone = odm.Optional(
+        odm.Keyword(
+            description="Availability zone in which this host, resource, or service is located.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        )
+    )
+    instance = odm.Optional(odm.Compound(Instance, description="Instance information."))
+    machine = odm.Optional(odm.Compound(Machine, description="Machine information."))
+    project = odm.Optional(
+        odm.Compound(
+            Project,
+            description="Project information.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        )
+    )
+    provider = odm.Optional(
+        odm.Keyword(description="Name of the cloud provider. Example values are aws, azure, gcp, or digitalocean.")
+    )
+    region = odm.Optional(odm.Keyword(description="Region in which this host, resource, or service is located."))
+    service = odm.Optional(odm.Compound(Service, description="Service information."))
+
+    # Extra fields not defined in ECS but added for outline purposes
+    tenant_id = odm.Optional(
+        odm.Keyword(
+            description="The tenant id associated with this alert.",
+            deprecated=True,
+            deprecated_description=(
+                "Instead of using this more general field, use a platform-specific field. "
+                "For more information, see [Disambiguated Cloud Ontology]"
+                "(https://confluence.devtools.cse-cst.gc.ca/display/DASI2/Disambiguated+Cloud+Ontology)"
+            ),
+        )
+    )

howler/odm/models/ecs/code_signature.py

@@ -0,0 +1,27 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="These fields contain information about binary code signatures.",
+)
+class CodeSignature(odm.Model):
+    digest_algorithm = odm.Optional(
+        odm.Enum(
+            values=["md5", "sha1", "sha256", "sha384", "sha512"],
+            description="The hashing algorithm used to sign the process.",
+        )
+    )
+    exists = odm.Optional(odm.Boolean(description="Boolean to capture if a signature is present."))
+    signing_id = odm.Optional(odm.Keyword(description="The identifier used to sign the process."))
+    status = odm.Optional(odm.Keyword(description="Additional information about the certificate status."))
+    subject_name = odm.Optional(odm.Keyword(description="Subject name of the code signer."))
+    team_id = odm.Optional(odm.Keyword(description="The team identifier used to sign the process."))
+    timestamp = odm.Optional(odm.Date(description="Date and time when the code signature was generated and signed."))
+    trusted = odm.Optional(odm.Boolean(description="Stores the trust status of the certificate chain."))
+    valid = odm.Optional(
+        odm.Boolean(
+            description="Boolean to capture if the digital signature" " is verified against the binary content."
+        )
+    )

howler/odm/models/ecs/container.py

@@ -0,0 +1,32 @@
+from typing import Optional
+
+from howler import odm
+
+
+@odm.model(index=True, store=True, description="Container hashes information.")
+class Hash(odm.Model):
+    all: list[str] = odm.List(
+        odm.Keyword(),
+        description="An array of digests of the image the container was built on.",
+        default=[],
+    )
+
+
+@odm.model(index=True, store=True, description="Information about the container Image.")
+class Image(odm.Model):
+    hash: Optional[Hash] = odm.Optional(odm.Compound(Hash, description="Container hashes information."))
+    name: Optional[str] = odm.Optional(odm.Keyword(description="Name of the image the container was built on."))
+    tag: list[str] = odm.List(odm.Keyword(), description="Container image tags.", default=[])
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Fields related to the cloud or infrastructure the events are coming from.",
+)
+class Container(odm.Model):
+    id = odm.Optional(odm.Keyword(description="Unique container id."))
+    image = odm.Optional(odm.Compound(Image, description="Cloud account information."))
+    labels = odm.Optional(odm.Mapping(odm.Keyword(), description="Image labels."))
+    name = odm.Optional(odm.Keyword(description="Container name."))
+    runtime = odm.Optional(odm.Keyword(description="Runtime managing this container."))

howler/odm/models/ecs/dns.py

@@ -0,0 +1,62 @@
+from howler import odm
+
+
+@odm.model(index=True, store=True, description="An answer section returned by the server.")
+class DNSAnswer(odm.Model):
+    class_ = odm.Optional(odm.Keyword(description="The class of DNS data contained in this resource record."))
+    data = odm.Optional(odm.Keyword(description="The data describing the resource."))
+    name = odm.Optional(odm.Keyword(description="The domain name to which this resource record pertains."))
+    ttl = odm.Optional(
+        odm.Integer(
+            description="The time interval in seconds that this "
+            "resource record may be cached before it should be discarded."
+        )
+    )
+    type = odm.Optional(odm.Keyword(description="The type of data contained in this resource record."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="An object encapsulating the question asked to the server.",
+)
+class DNSQuestion(odm.Model):
+    class_ = odm.Optional(odm.Keyword(description="The class of records being queried."))
+    name = odm.Optional(odm.Keyword(description="The name being queried."))
+    registered_domain = odm.Optional(
+        odm.Domain(description="The highest registered domain, stripped of the subdomain.")
+    )
+    subdomain = odm.Optional(odm.Keyword(description="The subdomain is all of the labels under the registered_domain."))
+    top_level_domain = odm.Optional(
+        odm.Keyword(
+            description="The effective top level domain (eTLD), also known as the "
+            "domain suffix, is the last part of the domain name."
+        )
+    )
+    type = odm.Optional(odm.Keyword(description="The type of record being queried."))
+
+
+@odm.model(index=True, store=True, description="Fields describing DNS queries and answers.")
+class DNS(odm.Model):
+    answers = odm.Optional(
+        odm.List(
+            odm.Compound(DNSAnswer),
+            description="An array containing an object for each answer section returned by the server.",
+        )
+    )
+    header_flags = odm.Optional(odm.List(odm.Keyword(), description="Array of 2 letter DNS header flags."))
+    id = odm.Optional(
+        odm.Keyword(description="The DNS packet identifier assigned by the program that generated the query.")
+    )
+    op_code = odm.Optional(
+        odm.Keyword(description="The DNS operation code that specifies the kind of query in the message.")
+    )
+    question = odm.Optional(
+        odm.Compound(
+            DNSQuestion,
+            description="An object encapsulating the question asked to the server.",
+        )
+    )
+    resolved_ip = odm.Optional(odm.List(odm.IP(), description="Array containing all IPs seen in answers.data."))
+    response_code = odm.Optional(odm.Keyword(description="The DNS response code."))
+    type = odm.Optional(odm.Keyword(description="The type of DNS event captured, query or answer."))

howler/odm/models/ecs/egress.py

@@ -0,0 +1,10 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Holds information like interface number, name, vlan, and zone to classify egress traffic",
+)
+class Egress(odm.Model):
+    zone = odm.Optional(odm.Keyword(description="Network zone of outbound traffic"))

howler/odm/models/ecs/elf.py

@@ -0,0 +1,74 @@
+from howler import odm
+
+
+@odm.model(index=True, store=True, description="Definition of an ELF file segment.")
+class Segment(odm.Model):
+    sections = odm.Optional(odm.Keyword(description="ELF object segment sections."))
+    type = odm.Optional(odm.Keyword(description="ELF object segment type."))
+
+
+@odm.model(index=True, store=True, description="Definition of an ELF file section.")
+class Section(odm.Model):
+    chi2 = odm.Optional(odm.Integer(description="Chi-square probability distribution of the section."))
+    entropy = odm.Optional(odm.Integer(description="Shannon entropy calculation from the section."))
+    flags = odm.Optional(odm.Keyword(description="ELF Section List flags."))
+    name = odm.Optional(odm.Keyword(description="ELF Section List name."))
+    physical_offset = odm.Optional(odm.Keyword(description="ELF Section List offset."))
+    physical_size = odm.Optional(odm.Integer(description="ELF Section List physical size."))
+    type = odm.Optional(odm.Keyword(description="ELF Section List type."))
+    virtual_address = odm.Optional(odm.Integer(description="ELF Section List virtual address."))
+    virtual_size = odm.Optional(odm.Integer(description="ELF Section List virtual size."))
+
+
+@odm.model(index=True, store=True, description="Header information about the ELF file.")
+class Header(odm.Model):
+    abi_version = odm.Optional(odm.Keyword(description="Version of the ELF Application Binary Interface (ABI)."))
+    class_ = odm.Optional(odm.Keyword(description="Header class of the ELF file."))
+    data = odm.Optional(odm.Keyword(description="Data table of the ELF header."))
+    entrypoint = odm.Optional(odm.Integer(description="Header entrypoint of the ELF file."))
+    object_version = odm.Optional(odm.Keyword(description="'0x1' for original ELF files."))
+    os_abi = odm.Optional(odm.Keyword(description="Application Binary Interface (ABI) of the Linux OS."))
+    type = odm.Optional(odm.Keyword(description="Header type of the ELF file."))
+    version = odm.Optional(odm.Keyword(description="Version of the ELF header."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="These fields contain Linux Executable Linkable Format (ELF) metadata.",
+)
+class ELF(odm.Model):
+    architecture = odm.Optional(odm.Keyword(description="Machine architecture of the ELF file."))
+    byte_order = odm.Optional(odm.Keyword(description="Byte sequence of ELF file."))
+    cpu_type = odm.Optional(odm.Keyword(description="CPU type of the ELF file."))
+    creation_date = odm.Optional(odm.Keyword(description="Extracted when possible from the file’s metadata."))
+    exports = odm.List(
+        odm.Keyword(),
+        default=[],
+        description="List of exported element names and types.",
+    )
+    header = odm.Optional(odm.Compound(Header, description="Header information about the ELF file."))
+    imports = odm.Optional(odm.List(odm.Keyword(), description="List of imported element names and types."))
+    sections = odm.Optional(
+        odm.List(
+            odm.Compound(
+                Section,
+                description="An array containing an object for each section of the ELF file.",
+            )
+        )
+    )
+    segments = odm.Optional(
+        odm.List(
+            odm.Compound(
+                Section,
+                description="An array containing an object for each segment of the ELF file.",
+            )
+        )
+    )
+    shared_libraries = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="List of shared libraries used by this ELF object.",
+        )
+    )
+    telfhash = odm.Optional(odm.Keyword(description="telfhash symbol hash for ELF file."))

howler/odm/models/ecs/email.py

@@ -0,0 +1,122 @@
+from howler import odm
+from howler.odm.models.ecs.hash import Hashes
+
+
+@odm.model(index=True, store=True, description="The email Address")
+class Address(odm.Model):
+    address = odm.Email(description="The email address.")
+
+
+@odm.model(index=True, store=True, description="Information about the file sent.")
+class File(odm.Model):
+    extension = odm.Optional(odm.Keyword(description="Attachment file extension, excluding the leading dot."))
+    hash = odm.Optional(odm.Compound(Hashes, description="Hashes, usually file hashes."))
+    mime_type = odm.Optional(odm.Keyword(description="The MIME media type of the attachment."))
+    name = odm.Optional(odm.Keyword(description="Name of the attachment file including the file extension."))
+    size = odm.Optional(odm.Integer(description="Attachment file size in bytes."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="An attachment file sent along with an email message.",
+)
+class Attachment(odm.Model):
+    file = odm.Optional(odm.Compound(File, description="Information about the file sent."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Metadata about the parent email.",
+)
+class ParentEmail(odm.Model):
+    bcc = odm.Optional(odm.Compound(Address, description="The email address of BCC recipient."))
+    cc = odm.Optional(odm.Compound(Address, description="The email address of CC recipient."))
+    from_ = odm.Optional(
+        odm.Compound(
+            Address,
+            description="The email address of the sender, typically " "from the RFC 5322 From: header field.",
+        )
+    )
+    message_id = odm.Optional(
+        odm.Keyword(
+            description="Identifier from the RFC 5322 Message-ID: email header "
+            "that refers to a particular email message."
+        )
+    )
+    origination_timestamp = odm.Optional(odm.Date(description="The date and time the email message was composed."))
+    subject = odm.Optional(odm.Keyword(description="A brief summary of the topic of the message."))
+    to = odm.Optional(odm.Compound(Address, description="The email address of recipient."))
+    source = odm.Optional(odm.IP(description="The ip the email originated from."))
+    destination = odm.Optional(odm.IP(description="The ip the email was sent to."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Event details relating to an email transaction.",
+)
+class Email(odm.Model):
+    attachments = odm.Optional(
+        odm.List(
+            odm.Compound(
+                Attachment,
+                description="A list of objects describing the attachment files sent along with an email message.",
+            )
+        )
+    )
+    bcc = odm.Optional(odm.Compound(Address, description="The email address of BCC recipient."))
+    cc = odm.Optional(odm.Compound(Address, description="The email address of CC recipient."))
+    content_type = odm.Optional(odm.Keyword(description="Information about how the message is to be displayed."))
+    delivery_timestamp = odm.Optional(
+        odm.Date(description="The date and time when the email message " "was received by the service or client.")
+    )
+    direction = odm.Optional(
+        odm.Keyword(description="The direction of the message based on the " "sending and receiving domains.")
+    )
+    from_ = odm.Optional(
+        odm.Compound(
+            Address,
+            description="The email address of the sender, typically " "from the RFC 5322 From: header field.",
+        )
+    )
+    local_id = odm.Optional(
+        odm.Keyword(description="Unique identifier given to the email by the source " "that created the event.")
+    )
+    message_id = odm.Optional(
+        odm.Keyword(
+            description="Identifier from the RFC 5322 Message-ID: email header "
+            "that refers to a particular email message."
+        )
+    )
+    origination_timestamp = odm.Optional(odm.Date(description="The date and time the email message was composed."))
+    reply_to = odm.Optional(
+        odm.Compound(
+            Address,
+            description="The address that replies should be delivered to "
+            "based on the value in the RFC 5322 Reply-To: header.",
+        )
+    )
+    sender = odm.Optional(
+        odm.Compound(
+            Address,
+            description="Per RFC 5322, specifies the address responsible for "
+            "the actual transmission of the message.",
+        )
+    )
+    subject = odm.Optional(odm.Keyword(description="A brief summary of the topic of the message."))
+    to = odm.Optional(odm.Compound(Address, description="The email address of recipient."))
+    x_mailer = odm.Optional(
+        odm.Keyword(
+            description="The name of the application that was used to draft " "and send the original email message."
+        )
+    )
+
+    # Extra fields not defined in ECS but added for outline purposes
+    parent = odm.Optional(
+        odm.Compound(
+            ParentEmail,
+            description="Metadata about the parent email.",
+        )
+    )

howler/odm/models/ecs/error.py

@@ -0,0 +1,14 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description=(
+        "These fields can represent errors of any kind. Use them for errors that happen while "
+        "fetching events or in cases where the event itself contains an error."
+    ),
+)
+class Error(odm.Model):
+    code = odm.Optional(odm.Keyword(description="Identifier specific to the error."))
+    message = odm.Optional(odm.Keyword(description="Error message provided."))