howler-api 2.13.0.dev329__py3-none-any.whl

howler/odm/models/ecs/process.py

@@ -0,0 +1,216 @@
+from typing import Optional
+
+from howler import odm
+from howler.odm.models.ecs.code_signature import CodeSignature
+from howler.odm.models.ecs.hash import Hashes
+from howler.odm.models.ecs.pe import PE
+from howler.odm.models.ecs.user import ShortUser
+
+
+@odm.model(index=True, store=True, description="Information about the char device.")
+class CharDevice(odm.Model):
+    major = odm.Optional(odm.Integer(description="The major number identifies the driver associated with the device."))
+    minor = odm.Optional(
+        odm.Integer(
+            description="The minor number is used only by the driver specified by the major number; other parts of "
+            "the kernel don't use it, and merely pass it along to the driver."
+        )
+    )
+
+
+@odm.model(index=True, store=True, description="Information about the controlling TTY device.")
+class TTY(odm.Model):
+    char_device = odm.Optional(odm.Compound(CharDevice, description="Information about the char device."))
+
+
+@odm.model(index=True, store=True, description="Thread Information.")
+class Thread(odm.Model):
+    id: Optional[int] = odm.Optional(odm.Integer(description="Thread ID."))
+    name: Optional[str] = odm.Optional(odm.Keyword(description="Thread name."))
+
+
+@odm.model(index=True, store=True, description="Entry Meta-Information.")
+class EntryMeta(odm.Model):
+    type: Optional[str] = odm.Keyword(description="SESSIONNAME from Process Environment Variable", optional=True)
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="These fields contain information about a process.",
+)
+class ParentParentProcess(odm.Model):
+    args = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="Array of process arguments, starting with the absolute path to the executable.",
+        )
+    )
+    args_count = odm.Optional(odm.Integer(description="Length of the process.args array."))
+    code_signature = odm.Optional(
+        odm.Compound(CodeSignature),
+        description="Information about binary code signatures.",
+    )
+    command_line = odm.Optional(
+        odm.Keyword(
+            description="Full command line that started the process, including the absolute path to the "
+            "executable, and all arguments."
+        )
+    )
+    end = odm.Optional(odm.Date(description="The time the process ended."))
+    entity_id = odm.Optional(odm.Keyword(description="OID Hash of the process."))
+    entry_meta: Optional[EntryMeta] = odm.Optional(
+        odm.Compound(EntryMeta),
+        description="Process Meta Information.",
+    )
+    env_vars = odm.Optional(
+        odm.Mapping(
+            odm.Keyword(),
+            description="Environment variables (env_vars) set at the time of the event. May be filtered to "
+            "protect sensitive information.",
+        )
+    )
+    executable = odm.Optional(odm.Keyword(description="Absolute path to the process executable."))
+    exit_code = odm.Optional(odm.Integer(description="The exit code of the process, if this is a termination event."))
+    hash = odm.Optional(odm.Compound(Hashes), description="Hashes, usually file hashes")
+    interactive = odm.Optional(odm.Boolean(description="Whether the process is connected to an interactive shell."))
+    name = odm.Optional(odm.Keyword(description="Process name."))
+    pe = odm.Optional(
+        odm.Compound(PE),
+        description="Windows Portable Executable (PE) metadata.",
+    )
+    pid = odm.Optional(odm.Integer(description="Process id."))
+    same_as_process = odm.Optional(
+        odm.Boolean(
+            description="This boolean is used to identify if a leader process is the same as the top level process."
+        )
+    )
+    start = odm.Optional(odm.Date(description="The time the process started."))
+    title = odm.Optional(odm.Keyword(description="Process title."))
+    uptime = odm.Optional(odm.Integer(description="Seconds the process has been up."))
+    user = odm.Optional(odm.Compound(ShortUser, description="The effective user (euid)."))
+    working_directory = odm.Optional(odm.Keyword(description="The working directory of the process."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="These fields contain information about a process.",
+)
+class ParentProcess(odm.Model):
+    args = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="Array of process arguments, starting with the absolute path to the executable.",
+        )
+    )
+    args_count = odm.Optional(odm.Integer(description="Length of the process.args array."))
+    code_signature = odm.Optional(
+        odm.Compound(CodeSignature),
+        description="Information about binary code signatures.",
+    )
+    command_line = odm.Optional(
+        odm.Keyword(
+            description="Full command line that started the process, including the absolute path to the "
+            "executable, and all arguments."
+        )
+    )
+    end = odm.Optional(odm.Date(description="The time the process ended."))
+    entity_id = odm.Optional(odm.Keyword(description="OID Hash of the process."))
+    entry_meta: Optional[EntryMeta] = odm.Optional(
+        odm.Compound(EntryMeta),
+        description="Process Meta Information.",
+    )
+    env_vars = odm.Optional(
+        odm.Mapping(
+            odm.Keyword(),
+            description="Environment variables (env_vars) set at the time of the event. May be filtered to "
+            "protect sensitive information.",
+        )
+    )
+    executable = odm.Optional(odm.Keyword(description="Absolute path to the process executable."))
+    exit_code = odm.Optional(odm.Integer(description="The exit code of the process, if this is a termination event."))
+    hash = odm.Optional(odm.Compound(Hashes), description="Hashes, usually file hashes")
+    interactive = odm.Optional(odm.Boolean(description="Whether the process is connected to an interactive shell."))
+    name = odm.Optional(odm.Keyword(description="Process name."))
+    parent = odm.Optional(
+        odm.Compound(ParentParentProcess),
+        description="Information about the parent process.",
+    )
+    pe = odm.Optional(
+        odm.Compound(PE),
+        description="Windows Portable Executable (PE) metadata.",
+    )
+    pid = odm.Optional(odm.Integer(description="Process id."))
+    same_as_process = odm.Optional(
+        odm.Boolean(
+            description="This boolean is used to identify if a leader process is the same as the top level process."
+        )
+    )
+    start = odm.Optional(odm.Date(description="The time the process started."))
+    title = odm.Optional(odm.Keyword(description="Process title."))
+    uptime = odm.Optional(odm.Integer(description="Seconds the process has been up."))
+    user = odm.Optional(odm.Compound(ShortUser, description="The effective user (euid)."))
+    working_directory = odm.Optional(odm.Keyword(description="The working directory of the process."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="These fields contain information about a process.",
+)
+class Process(odm.Model):
+    args = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="Array of process arguments, starting with the absolute path to the executable.",
+        )
+    )
+    args_count = odm.Optional(odm.Integer(description="Length of the process.args array."))
+    code_signature = odm.Optional(
+        odm.Compound(CodeSignature),
+        description="Information about binary code signatures.",
+    )
+    command_line = odm.Optional(
+        odm.Keyword(
+            description="Full command line that started the process, including the absolute path to the "
+            "executable, and all arguments."
+        )
+    )
+    end = odm.Optional(odm.Date(description="The time the process ended."))
+    entity_id = odm.Optional(odm.Keyword(description="OID Hash of the process."))
+    entry_meta: Optional[EntryMeta] = odm.Optional(
+        odm.Compound(EntryMeta),
+        description="Process Meta Information.",
+    )
+    env_vars = odm.Optional(
+        odm.Mapping(
+            odm.Keyword(),
+            description="Environment variables (env_vars) set at the time of the event. May be filtered to "
+            "protect sensitive information.",
+        )
+    )
+    executable = odm.Optional(odm.Keyword(description="Absolute path to the process executable."))
+    exit_code = odm.Optional(odm.Integer(description="The exit code of the process, if this is a termination event."))
+    hash = odm.Optional(odm.Compound(Hashes), description="Hashes, usually file hashes")
+    interactive = odm.Optional(odm.Boolean(description="Whether the process is connected to an interactive shell."))
+    name = odm.Optional(odm.Keyword(description="Process name."))
+    parent = odm.Optional(
+        odm.Compound(ParentProcess),
+        description="Information about the parent process.",
+    )
+    pe = odm.Optional(
+        odm.Compound(PE),
+        description="Windows Portable Executable (PE) metadata.",
+    )
+    pid = odm.Optional(odm.Integer(description="Process id."))
+    same_as_process = odm.Optional(
+        odm.Boolean(
+            description="This boolean is used to identify if a leader process is the same as the top level process."
+        )
+    )
+    start = odm.Optional(odm.Date(description="The time the process started."))
+    title = odm.Optional(odm.Keyword(description="Process title."))
+    uptime = odm.Optional(odm.Integer(description="Seconds the process has been up."))
+    user = odm.Optional(odm.Compound(ShortUser, description="The effective user (euid)."))
+    working_directory = odm.Optional(odm.Keyword(description="The working directory of the process."))

howler/odm/models/ecs/registry.py

@@ -0,0 +1,26 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Fields related to data written to Windows Registry.",
+)
+class RegistryData(odm.Model):
+    bytes = odm.Optional(odm.Keyword(description="Original bytes written with base64 encoding."))
+    strings = odm.Optional(odm.List(odm.Keyword(), description="Content when writing string types."))
+    type = odm.Optional(odm.Keyword(description="Standard registry type for encoding contents."))
+
+
+@odm.model(index=True, store=True, description="Fields related to Windows Registry operations.")
+class Registry(odm.Model):
+    data = odm.Optional(
+        odm.Compound(
+            RegistryData,
+            description="Fields related to data written to Windows Registry.",
+        )
+    )
+    hive = odm.Optional(odm.Keyword(description="Abbreviated name for the hive."))
+    key = odm.Optional(odm.Keyword(description="Hive-relative path of keys."))
+    path = odm.Optional(odm.Keyword(description="Full path, including hive, key and value."))
+    value = odm.Optional(odm.Keyword(description="Name of the value written."))

howler/odm/models/ecs/related.py

@@ -0,0 +1,45 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="This field set is meant to facilitate pivoting around a piece of data.",
+)
+class Related(odm.Model):
+    hash: list[str] = odm.List(
+        odm.Keyword(),
+        description="All the hashes seen on your event. Populating this field, then using it to search "
+        "for hashes can help in situations where you're unsure what the hash algorithm is "
+        "(and therefore which key name to search).",
+        default=[],
+    )
+    hosts: list[str] = odm.List(
+        odm.Keyword(),
+        description="All hostnames or other host identifiers seen on your event. Example identifiers "
+        "include FQDNs, domain names, workstation names, or aliases.",
+        default=[],
+    )
+    ip: list[str] = odm.List(odm.IP(), description="All of the IPs seen on your event.", default=[])
+    user: list[str] = odm.List(
+        odm.Keyword(),
+        description="All the user names or other user identifiers seen on the event.",
+        default=[],
+    )
+    ids: list[str] = odm.List(
+        odm.Keyword(),
+        description="Any identifier that doesn't fit in other related fields like a GUID.",
+        default=[],
+    )
+
+    # Extra fields not defined in ECS but added for outline purposes
+    id = odm.Optional(odm.Keyword(description="The id related to the event."))
+
+    uri = odm.Optional(odm.List(odm.URI(), description="All of the URIs related to the event."))
+
+    signature = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="All the signatures/rules that were triggered by the event.",
+        )
+    )

howler/odm/models/ecs/rule.py

@@ -0,0 +1,51 @@
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Rule fields are used to capture the specifics of any observer or agent "
+    "rules that generate alerts or other notable events.",
+)
+class Rule(odm.Model):
+    author = odm.Optional(
+        odm.Keyword(
+            description="Name, organization, or pseudonym of the author or authors who "
+            "created the rule used to generate this event."
+        )
+    )
+    category = odm.Optional(
+        odm.Keyword(
+            description="A categorization value keyword used by the entity using the "
+            "rule for detection of this event."
+        )
+    )
+    description = odm.Optional(odm.Keyword(description="The description of the rule generating the event."))
+    id = odm.Optional(
+        odm.Keyword(
+            description="A rule ID that is unique within the scope of an agent, observer, "
+            "or other entity using the rule for detection of this event."
+        )
+    )
+    license = odm.Optional(
+        odm.Keyword(
+            description="Name of the license under which the rule used to generate this event is made available."
+        )
+    )
+    name = odm.Optional(odm.Keyword(description="The name of the rule or signature generating the event."))
+    reference = odm.Optional(
+        odm.Keyword(description="Reference URL to additional information about the rule used to generate this event.")
+    )
+    ruleset = odm.Optional(
+        odm.Keyword(
+            description="Name of the ruleset, policy, group, or parent category in which the "
+            "rule used to generate this event is a member."
+        )
+    )
+    uuid = odm.Optional(
+        odm.Keyword(
+            description="A rule ID that is unique within the scope of a set or group of agents, observers, "
+            "or other entities using the rule for detection of this event."
+        )
+    )
+    version = odm.Optional(odm.Keyword(description="The version / revision of the rule being used for analysis."))

howler/odm/models/ecs/server.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description=(
+        "A Server is defined as the responder in a network connection for events regarding sessions, "
+        "connections, or bidirectional flow records."
+    ),
+)
+class Server(odm.Model):
+    ip: Optional[str] = odm.Optional(odm.IP(description="IP address of the server (IPv4 or IPv6)."))
+    address: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description=(
+                "Some event server 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."
+            )
+        )
+    )
+    domain: Optional[str] = odm.Optional(odm.Keyword(description="The domain name of the server system."))

howler/odm/models/ecs/threat.py

@@ -0,0 +1,247 @@
+from typing import Optional
+
+from howler import odm
+from howler.odm.models.ecs.file import File
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Information about the subtechnique used by this threat.",
+)
+class Email(odm.Model):
+    address: Optional[str] = odm.Optional(
+        odm.Keyword(),
+        description="Identifies a threat indicator as an email address (irrespective of direction).",
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Information about the subtechnique used by this threat.",
+)
+class SubTechnique(odm.Model):
+    id = odm.Optional(odm.Keyword(description="The id of subtechnique used by this threat."))
+    name = odm.Optional(odm.Keyword(description="Name of the type of subtechnique used by this threat."))
+    reference = odm.Optional(odm.Keyword(description="The reference url of subtechnique used by this threat."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Information about the technique used by this threat.",
+)
+class Technique(odm.Model):
+    id = odm.Optional(odm.Keyword(description="The id of technique  used by this threat."))
+    name = odm.Optional(odm.Keyword(description="Name of the type of technique used by this threat."))
+    reference = odm.Optional(odm.Keyword(description="The reference url of technique used by this threat."))
+    subtechnique = odm.Optional(
+        odm.Compound(
+            SubTechnique,
+            description="Information about the subtechnique used by this threat.",
+        )
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Information about the tactic used by this threat.",
+)
+class Tactic(odm.Model):
+    id = odm.Optional(odm.Keyword(description="The id of tactic used by this threat."))
+    name = odm.Optional(odm.Keyword(description="Name of the type of tactic used by this threat."))
+    reference = odm.Optional(odm.Keyword(description="The reference url of tactic used by this threat."))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Information about the software used by this threat.",
+)
+class Software(odm.Model):
+    alias = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="The alias(es) of the software for a set of related intrusion activity that are "
+            "tracked by a common name in the security community.",
+        )
+    )
+    id = odm.Optional(
+        odm.Keyword(
+            description="The id of the software used by this threat to conduct behavior commonly modeled "
+            "using MITRE ATT&CK®."
+        )
+    )
+    name = odm.Optional(
+        odm.Keyword(
+            description="The name of the software used by this threat to conduct behavior commonly modeled "
+            "using MITRE ATT&CK®."
+        )
+    )
+    platform = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="The platforms of the software used by this threat to conduct behavior commonly "
+            "modeled using MITRE ATT&CK®.",
+        )
+    )
+    reference = odm.Optional(
+        odm.Keyword(
+            description="The reference URL of the software used by this threat to conduct behavior commonly "
+            "modeled using MITRE ATT&CK®."
+        )
+    )
+    type = odm.Optional(
+        odm.Keyword(
+            description="The type of software used by this threat to conduct behavior commonly modeled "
+            "using MITRE ATT&CK®."
+        )
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Information about the group related to this threat.",
+)
+class Group(odm.Model):
+    alias = odm.Optional(
+        odm.List(
+            odm.Keyword(),
+            description="The alias(es) of the group for a set of related intrusion activity that are tracked by "
+            "a common name in the security community.",
+        )
+    )
+    id = odm.Optional(
+        odm.Keyword(
+            description="The id of the group for a set of related intrusion activity that are tracked by a common "
+            "name in the security community."
+        )
+    )
+    name = odm.Optional(
+        odm.Keyword(
+            description="The name of the group for a set of related intrusion activity that are tracked by a common "
+            "name in the security community."
+        )
+    )
+    reference = odm.Optional(
+        odm.Keyword(
+            description="The reference URL of the group for a set of related intrusion activity that are tracked "
+            "by a common name in the security community."
+        )
+    )
+
+
+@odm.model(index=True, store=True, description="Threat feed information.")
+class Feed(odm.Model):
+    dashboard_id = odm.Optional(
+        odm.Keyword(
+            description="The saved object ID of the dashboard belonging to the threat feed for "
+            "displaying dashboard links to threat feeds in Kibana."
+        )
+    )
+    description = odm.Optional(odm.Keyword(description="Description of the threat feed in a UI friendly format."))
+    name = odm.Optional(odm.Keyword(description="The name of the threat feed in UI friendly format."))
+    reference = odm.Optional(
+        odm.Keyword(description="Reference information for the threat feed in a UI friendly format.")
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Object containing associated indicators enriching the event.",
+)
+class Indicator(odm.Model):
+    confidence = odm.Optional(
+        odm.Keyword(
+            description="Identifies the vendor-neutral confidence rating using the None/Low/Medium/High scale defined "
+            "in Appendix A of the STIX 2.1 framework. Vendor-specific confidence scales may be added as custom fields."
+        )
+    )
+    description = odm.Optional(odm.Text(description="Describes the type of action conducted by the threat."))
+    email: Email = odm.Optional(odm.Compound(Email))
+    file: File = odm.Optional(odm.Compound(File))
+    provider = odm.Optional(odm.Keyword(description="The name of the indicator’s provider."))
+    reference = odm.Optional(
+        odm.Keyword(description="Reference URL linking to additional information about this indicator.")
+    )
+    scanner_stats = odm.Integer(
+        description="Count of AV/EDR vendors that successfully detected malicious file or URL.", optional=True
+    )
+
+    sightings = odm.Integer(
+        description="Number of times this indicator was observed conducting threat activity.", optional=True
+    )
+
+    ip: Optional[str] = odm.Optional(
+        odm.IP(description="Identifies a threat indicator as an IP address (irrespective of direction).")
+    )
+    type: Optional[str] = odm.Optional(
+        odm.Keyword(description="Type of indicator as represented by Cyber Observable in STIX 2.0.")
+    )
+    first_seen: Optional[str] = odm.Optional(
+        odm.Date(description="The date and time when intelligence source first reported sighting this indicator.")
+    )
+    last_seen: Optional[str] = odm.Optional(
+        odm.Date(description="The date and time when intelligence source last reported sighting this indicator.")
+    )
+    port: Optional[int] = odm.Integer(description="Identifies a threat indicator as a port number", optional=True)
+
+
+@odm.model(
+    index=True,
+    store=True,
+)
+class Matched(odm.Model):
+    atomic: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description="Identifies the atomic indicator value that matched a extended local envirnment endpoint or network event"  # noqa: E501
+        )
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="List of enrichments",
+)
+class Enrichments(odm.Model):
+    indicator = odm.Optional(odm.Compound(Indicator))
+    matched = odm.Optional(odm.Compound(Matched))
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description="Fields to classify events and alerts according to a threat "
+    "taxonomy such as the MITRE ATT&CK® framework.",
+)
+class Threat(odm.Model):
+    enrichments = odm.Optional(
+        odm.List(odm.Compound(Enrichments, description="List of enrichments marked threats from indicator."))
+    )
+    feed = odm.Optional(odm.Compound(Feed, description="Threat feed information."))
+    framework = odm.Optional(
+        odm.Keyword(
+            description="Name of the threat framework used to further categorize and classify the tactic and "
+            "technique of the reported threat."
+        )
+    )
+    group = odm.Optional(odm.Compound(Group, description="Information about the group related to this threat."))
+    indicator = odm.Optional(
+        odm.Compound(
+            Indicator,
+            description="Object containing associated indicators enriching the event.",
+        )
+    )
+    software = odm.Optional(odm.Compound(Software, description="Information about the software used by this threat."))
+    tactic: Tactic = odm.Optional(odm.Compound(Tactic, description="Information about the tactic used by this threat."))
+    technique: Tactic = odm.Optional(
+        odm.Compound(
+            Tactic,
+            description="Information about the technique used by this threat.",
+        )
+    )

howler/odm/models/ecs/tls.py

@@ -0,0 +1,58 @@
+from typing import Optional
+
+from howler import odm
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description=(
+        "A Server is defined as the responder in a network connection for events regarding sessions, "
+        "connections, or bidirectional flow records."
+    ),
+)
+class Server(odm.Model):
+    ja3s: Optional[str] = odm.Optional(
+        odm.Keyword(description="A hash that identifies servers based on how they perform an SSL/TLS handshake.")
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description=(
+        "A Server is defined as the responder in a network connection for events regarding sessions, "
+        "connections, or bidirectional flow records."
+    ),
+)
+class Client(odm.Model):
+    server_name: Optional[str] = odm.Optional(
+        odm.Keyword(
+            description=(
+                "Also called an SNI, this tells the server which hostname to which the client is "
+                "attempting to connect to. When this value is available, it should get copied to destination.domain."
+            )
+        )
+    )
+    ja3: Optional[str] = odm.Optional(
+        odm.Keyword(description="A hash that identifies clients based on how they perform an SSL/TLS handshake.")
+    )
+
+
+@odm.model(
+    index=True,
+    store=True,
+    description=(
+        "A Server is defined as the responder in a network connection for events regarding sessions, "
+        "connections, or bidirectional flow records."
+    ),
+)
+class TLS(odm.Model):
+    version: Optional[str] = odm.Optional(
+        odm.Keyword(description="Numeric part of the version parsed from the original string.")
+    )
+    version_protocol: Optional[str] = odm.Optional(
+        odm.Keyword(description="Normalized lowercase protocol name parsed from original string.")
+    )
+    client: Client = odm.Optional(odm.Compound(Client))
+    server: Server = odm.Optional(odm.Compound(Server))