Configuration reference

The connector has a plethora of configuration options, allowing for detailed customisation in searching and enrichment. There are some settings you have to set (there are no defaults, like usernames and passwords), and there are some settings you should read about and possibly adjust, since they greatly affect the behaviour of the connector.

Main configuration

pydantic settings Config

Complete connector configuration

Settings are grouped together in relevant objects, like search, enrich and opencti. Every setting may also be loaded from environment variables, where the setting name is capitalised and prefixed by WAZUH_ or a prefixed specified by its group (WAZUH_SEARCH_, WAZUH_ENRICH_, OPENCTI_ etc.).

Config:

  • env_prefix: str = WAZUH_

  • env_file: str = .env

  • validate_assignment: bool = True

Fields:
field agents_as_systems: bool = True

Whether a STIX identity (type system) should be created for every agent referenced in sightings and incidents. If set to false, system_name will be used instead.

field app_url: Url [Required]

URL used to create links to the Wazuh dashboard

Constraints:

  • allowed_schemes = [‘http’, ‘https’]

Validated by:

  • parse_http_url

  • validate_http_url

field author_name: str = 'Wazuh'

Name used for the STIX identity (type system) that will be used as author for all created entities

field bundle_abort_limit: int | None = 500

Number of STIX entities that should cause further processing to abort. If the connector produces a large number of STIX entities during enrichment, this setting may be used as a safe guard to prevent littering OpenCTI with a lot of noise.

See also

Consider adjusting which entities to enrich to lower the number of bundles produced through enrichment.

Constraints:

  • gt = 0

field connector: ConnectorConfig [Optional]

OpenCTI connector-specific configuration

field create_agent_hostname_observable: bool = True

Whether to create hostname observable and relate it to agent systems

field create_agent_ip_observable: bool = True

Whether to create an IP address observable and relate it to agent systems

field create_incident: IncidentCreateMode = IncidentCreateMode.PerSighting

How and when to create incidents

See IncidentCreateMode.

field create_incident_response: bool = True

Create an incident response case if there any incidents created

Cases are very useful to get an overview, and is the only entity that will include reference to observables created through enrichment.

field create_incident_summary: bool = True

Whether to create a summary STIX note about each enrichment, along with OpenSearch query and results information, and attach it to all incidents.

See create_sighting_summary (this is the same summary).

field create_incident_threshold: int = 1

Alert rule level threshold for creating incidents

If the alert from OpenSearch has a rule level below this value, no incident will be created. However, a sighting may still be created.

Note

Note that an alert rule level is not necessarily a good filter. A FIM/syscheck alert informing that a file has been added to a system is not a high-severity alert, but it could be the alert that results in an IoC match against a file hash.

Constraints:

  • ge = 1

  • le = 15

field create_obs_sightings: bool = True

Create sightings of observables even if there are no indicators tied to it

If False, sightings will only be created if the observable entity has one or more indicators “based on” it. The indicator pattern is not considered.

field create_sighting_summary: bool = True

Whether to create a summary STIX note about each enrichment, along with OpenSearch query and results information, and attach it to all sightings. See enrichment and notes.

field enrich: EnrichmentConfig [Optional]

Settings for what and how to enrich

field enrich_labels: set[str] = ['wazuh_ignore']

List of labels to attach to all enriched observables

The main use case for these labels is to prevent the connector from automatically running on its own entities (which could lead to “endless” recursion).

Note

When modifying this setting, be sure to include relevant labels in label_ignore_list.

field hits_abort_limit: int | None = 1000

Number of OpenSearch matches (total matches, not returned results) that should cause further processing to abort. If a large number of matches are found, aborting prevents the connector from creating a lot of noisy results.

Constraints:

  • gt = 0

field ignore_own_entities: bool = False

Whether to ignore all entities authored by this connector (author)

All entities with this author will be ignored. See FIXREF: recusion. See also label_ignore_list, which may be a better solution.

field ignore_revoked_indicators: bool = True

Only look up indicators that are not revoked

If create_obs_sightings is false or if require_indicator_for_incidents is true, indicators play a role in how events are created. This setting ignores indicators that have the revoked property set to true.

In recent OpenCTI versions, indicator lifecycle management will automatically set revoked to true according to decay rules.

field incident_rule_exclude_list: set[str] = {}

Do not create incidents for alerts with these rule IDs

This setting may be useful to limit noise from alerts caused by login attempts and web server accceses on public-facing servers. Sightings are still created. Use rule_exclude_list instead if you want to ignore these alerts altogether.

Here are some notable rules that may produce a lot of noise if your IoCs include a lot of IP addresses from spam and abuse sources:

Noisy alert rules

Rule ID

Description

5503

PAM: User login failed

5710

sshd: Attempt to login using a non-existent user

5718

sshd: Attempt to login using a denied user

5762

sshd: connection reset

31101

Web server 400 error code
field indicator_score_threshold: int | None = None

Only look up indicators whose score is above or equals this threshold

If create_obs_sightings is false or if require_indicator_for_incidents is true, indicators play a role in how events are created. This setting ignores indicators that have the revoked property set to true.

In recent OpenCTI versions, indicator lifecycle management will automatically adjust the score according to decay rules.

Constraints:

  • ge = 0

  • le = 100

field label_ignore_list: set[str] = {'hygiene', 'wazuh_ignore'}

List of labels which, if present in the entity, will make the connector to stop processing

This is usful for ignoring low-quality or noisy data, and to prevent the connector from running on its own enriched data (which could lead to “endless” recursion).

See also

Configure enrich_labels to set which labels that the connector should include on entities created through enrichment.

Validated by:

  • parse_comma_string

field max_extrefs: int = 10

Maximum number of external references to create per sighting

In addition to the limit max_extrefs_per_alert_rule, this limit dictates how many external references to alerts in Wazuh to create in total per sighting. See also max_extrefs_per_alert_rule, max_notes and max_notes_per_alert_rule.

Constraints:

  • ge = 0

field max_extrefs_per_alert_rule: int = 2

Maximum number of external references to create per alert rule per sighting

See also max_extrefs, max_notes and max_notes_per_alert_rule

Constraints:

  • ge = 0

Validated by:

  • max_ext_refs_below_total_max

field max_notes: int = 10

Maximum number of alert notes to create per sighting

In addition to the limit max_notes_per_alert_rule, this limit dictates how many alert notes to create in total per sighting. See also max_notes_per_alert_rule, max_extrefs and max_extrefs_per_alert_rule.

Constraints:

  • ge = 0

field max_notes_per_alert_rule: int = 2

Maximum number of alert notes to create per sighting

See also max_notes_per_alert_rule, max_extrefs, max_extrefs_per_alert_rule.

Constraints:

  • ge = 0

Validated by:

  • max_notes_below_total_max

field max_tlp: Literal['TLP:CLEAR', 'TLP:WHITE', 'TLP:GREEN', 'TLP:AMBER', 'TLP:AMBER+STRICT', 'TLP:RED'] [Required]

Max TLP to allow for lookups

Validated by:

  • normalise_tlp

field opencti: OpenCTIConfig [Optional]

OpenCTI-specific configuration

field opensearch: OpenSearchConfig [Optional]
field require_indicator_detection: bool = False

Only look up indicators whose detection field is true

If create_obs_sightings is false or if require_indicator_for_incidents is true, indicators play a role in how events are created. This setting ignores indicators that do not have the detection property set to true. Not all sources set this field, so it is disabled by default.

In recent OpenCTI versions, indicator lifecycle management will automatically set detection to false according to decay rules.

field require_indicator_for_incidents: bool = True

Only create incidents if the observable has indicators tied to it

Otherwise, only sightings (depending on create_obs_sightings) will be created.

See also

Require indicator explains how several settings determine when to ceate incidents.

field rule_exclude_list: set[str] = {}

Ignore all alerts with this rule ID

See also

If you want to keep sightings from alerts, but avoid getting incidents, configure incident_rule_exclude_list instead.

field search: SearchConfig [Optional]

Settings for how searching should be performed

field system_name: str = 'Wazuh SIEM'

The name of the STIX identity (type system) referenced in sightings and incidents

Constraints:

  • min_length = 1

field tlps: set[str] | None = 'TLP:AMBER+STRICT'

TLP markings to use for all created STIX entities

The marking definitions may be specified with or without a “TLP:” prefix, and several definitions may be specified, separated by a comma. See max_tlp for possible values.

Validated by:

  • convert_tlp_strings

  • parse_comma_string

  • validate_id

field vulnerability_incident_active_only: bool = True

Only create incidents when a vulnerability is still active in a system

If this setting is enabled, incidents will not be created for vulernabilities spotted in a system, if the vulnerability has since been removed or fixed (by patching the vulnerable software or removing it). If the vulnerability is active somehow again after having been fixed, an innident will be created.

Note that if a search is limited due to too many hits, incidents may be created due to lack of information.

field vulnerability_incident_cvss3_score_threshold: float | None = None

Minimum vulnerability CVSS3 score needed to create incidents

Creating incidents for every vulnerability (or several incidents, depending on create_incident) can quickly become very noisy. This setting ensures that incidents are only created for vulenerability sightings if a CVSS3 score is present in the vulnerability, and if that score is high enough. If this setting is None, incidents will never be created.

If the CVSS3 score is unavailable, but the CVSS3 severity is preent, the severity’s corresponding score (the median) is used.

Sightings will always be created, regardless of whether the CVSS3 score is present and above the threshold.

Constraints:

  • ge = 0

  • le = 10

class AlertRuleSeverity(value)

Alert rule level severity

A convenience mapping from four severity levels to a Wazuh alert rule level.

Low = 2

Low severity

Medium = 7

Medium severity

High = 11

High severity

Critical = 14

Critical severity

class IncidentCreateMode(value)

How and when incidents should be created

If incidents should be created (see require indicator), this enumerator determines how incidents are created.

The amount of incidents created for every option is roughly in the following order, from the least to the most: Never, PerQuery, PerSighting, PerAlertRule, PerAlert.

PerQuery = 'per-query'

An incident is created only once per enrichment/query. This is the least noisy option (except for Never).

PerSighting = 'per-sighting'

Create an incident for every sighting.

PerAlertRule = 'per-alert-rule'

Create one incident per distinct alert rule. If there are 4 alerts with rule ID 550 and 2 alerts with rule ID 80792, only two alerts are created.

PerAlert = 'per-alert'

Create one incident for every alert.

Warning

Using this option is highly discouraged, as it will potentially create a lot of incidents.

Note

Enrichment is curently not implemented for this option.

Never = 'never'

Never create incidents.

classmethod from_env()

OpenCTI configuration

OPENCTI settings

pydantic settings OpenCTIConfig

Connector OpenCTI settings

These settings are the most important settings used by the connector. There are other settings supported by the connector API, but they are not listed here, nor is there any official documentation for them.

Config:

  • extra: str = allow

  • env_prefix: str = OPENCTI_

  • validate_assignment: bool = True

Fields:
field ssl_verify: bool = False

Whether to verify OpenCTI’s TLS certificate

Warning

If the connector and the OpenCTI server is not running in docker-compose, where the connector can directly access the server in a closed network, do not disable verification. Use a proper certificate in such cases.

field token: str [Required]

Token used for authenticating the connector as a user in OpenCTI

This token is used for the connector to access OpenCTI’s API. See create OpenCTI user for how to create a token. Please refrain from using an admin token (like ${OPENCTI_ADMIN_TOKEN}, for reasons described in the aforementioned chapter.

field url: Url [Required]

OpenCTI URL

This is the URL to the OpenCTI server. Connectors are typically run in the same docker-compose file as the server. This lets you refer to this URL with the variable ${OPENCTI_BASE_URL}, typically defined in an .env file.

Constraints:

  • allowed_schemes = [‘http’, ‘https’]

CONNECTOR settings

class ConnectorType(value)

OpenCTI connector type

InternalEnrichment = 'internal_enrichment'

Internal enrichment, then only supported type for this connector

class SupportedEntity(value)

The entities that the connector support

See also

See supported entities.

class LogLevel(value)

Log level

Debug = 'debug'

Debug, info, warning and error messages

Info = 'info'

Info, warning and error messages

Warning = 'warning'

Warning and error messages

Error = 'error'

Error messages only

pydantic settings ConnectorConfig

Connector settings

These settings are the most important settings used by the connector. There are other settings supported by the connector API, but they are not listed here, nor is there any official documentation for them.

Config:

  • extra: str = allow

  • env_prefix: str = CONNECTOR_

  • validate_assignment: bool = True

Fields:
field auto: bool = True

Run automatically or manually

Whether to run the connector automatically whenever an entity in CONNECTOR_SCOPE is created, or just manually.

See also

See when to run for details.

field id: str [Required]

Connector ID

This string should be a UUID

field log_level: LogLevel = LogLevel.Warning

Log level

Set the log level to warning or error under normal use. Use debug when troubleshooting and gathering info for an issue.

See also

See how to access logs in troubleshooting

field name: str = 'Wazuh'

Name used to identify the connector in OpenCTI

field scope: set[SupportedEntity] = {SupportedEntity.Artifact, SupportedEntity.Directory, SupportedEntity.DomainName, SupportedEntity.EMailAddr, SupportedEntity.Hostname, SupportedEntity.IPv4Addr, SupportedEntity.IPv6Addr, SupportedEntity.Indicator, SupportedEntity.MAC, SupportedEntity.NetworkTraffic, SupportedEntity.Process, SupportedEntity.StixFile, SupportedEntity.URL, SupportedEntity.UserAccount, SupportedEntity.UserAgent, SupportedEntity.Vulnerability, SupportedEntity.WindowsRegistryKey, SupportedEntity.WindowsRegistryValueType}

Which entities to enable enrichment for

This specifies all entities that the connector should be made available for enrichment. If an entity is not lsted here, the connector will not show up as an option when clicking on the enrichment button in OpenCTI.

See also

See supported entities for supported choices.

field type: ConnectorType = ConnectorType.InternalEnrichment

The type of the connector, which must be Enrichment

OpenSearch configuration

pydantic settings OpenSearchConfig

Configuration used for the opensearch module to connect to OpenSearch

TODO: explain filters (include, exclude, filter). link to this section from settings

add more information about opensearch?

Config:

  • env_prefix: str = WAZUH_OPENSEARCH_

  • validate_assignment: bool = True

Fields:
field exclude_match: list[Match] = [Match(field='data.integration', query='opencti')]

FIXME to a “bool” “must_not” array. The default value will exclude alerts produced by the wazuh-opencti Wazuh integration.

Validated by:

  • parse_match_expression

field filter: list[Term | Exists | Range | Match | MultiMatch | Wildcard | Regexp | Bool] = []

Default filter used when searching

All searches are performed with a Bool query. The members search_after, include_match and exclude_match are used in the Bool query’s filter unless overriden by this setting. i.e. if this setting is non-empty, the values in search_after, search_include and search_exclude are ignored.

When set as an environment variable, this setting must be specified as JSON.

The implicit default filter (based on the settings mentioned) is

[
    {
        "range": {
            "@timestamp": {
                "gte": "<timestamp>",
            }
        }
    },
    {
        "bool": {
            "must_not": [
                {
                    "match": {
                        "data.integration": "opencti"
                    }
                }
            ]
        }
    }
]
field include_match: list[Match] = []

FIXME

Validated by:

  • parse_match_expression

field index: str = 'wazuh-alerts-*'

Indices to search for Wazuh alerts

field limit: int = 50

Maximum number of results to return from the OpenSearch alert query (after ordering by timestamp (or your custom order, if order_by is overridden).

Any results exceeding this limit will simply be dropped (after being ordered by order_by).

Constraints:

  • gt = 0

field order_by: list[OrderBy] = [OrderBy(field='timestamp', order=<SortOrder.Desc: 'desc'>)]

How to order alert results before returning limit number of results. The default and recommended settings is to order by timestamp, descending, to get the most recent results. Alternatively, order alert by alert rule level, descending, then by timestamp, descending, in order to not miss any important alerts.

Alternative simple string format:

  • timestamp:desc

  • rule.level:desc,timestamp:desc

Validated by:

  • parser_order_by_expression

field password: str [Required]

User password

field search_after: datetime | timedelta | None = None

Search for alerts in OpenSearch after this point in time, which may be specified either as a timestamp or a relative time (like “2 months ago”)

Validated by:

  • parse_lax_datetime

field timeout: timedelta = datetime.timedelta(seconds=20)

Time to wait before aborting the OpenSearch request

In the event OpenSearch fails to return results from a query in timely manner, this setting ensures that the connection is closed instead of waiting forever. Typical causes are network issues.

Be sure to set the timeout high enough so that your OpenSearch instances has time to finish all your queries. If you are using regular expressions on a large database, queries may take up to several seconds in some cases. Do not use this setting as a way to time out complicated queries. Configure OpenSearch itself for that.

Validated by:

  • parse_lax_datetime

field url: Url [Required]

URL, including port and path, if neccessary, but must not include username and password

Note

By default, OpenSearch runs on port 9200. This port must be specified in the URL unless the address on the specified scheme redirects or proxies the traffic.

Constraints:

  • allowed_schemes = [‘http’, ‘https’]

Validated by:

  • parse_http_url

  • validate_http_url

field username: str [Required]

A user that has necessary read-only permissions to alert indices

See create OpenSearch user for a guide to create a user.

field verify_tls: bool = True

Verify the HTTPS certificate

Disabling verification is highly discouraged. Use FIXME instead if the certificate is self-signed.

field_json(field: str) → str

Search configuration

Look at the alert search topic for details.

class FileSearchOption(value)

Options determining how to search for File/Artifact SCOs

SearchSize = 'search-size'

If size is defined in the File SCO, search for size along with filename

If only a hash is defined, size is ignored.

SearchNameAndHash = 'search-name-and-hash'

If name is defined in the File SCO, match filename in addition to hashes

If a filename (name, and also x_opencti_additional_names if SearchAdditionalFilenames is set) is defined, the filename must match as well has the hash (see FIXME for matching behaviour).

If disabled, filenames will still be searched if there are no hashes and SearchFilenameOnly is enabled.

SearchFilenameOnly = 'search-filename-only'

Search for filenames if no hashes are defined

Filenames in x_opencti_additional_names will also be searched for if SearchAdditionalFilenames is set.

SearchAdditionalFilenames = 'search-additional-filenames'

Search additional filenames along with name

OpenCTI’s custom SCO extenion x_opencti_additional_names holds a list of additional names for a File. This settings searches all of these names just as it would with name.

BasenameOnly = 'basename-only'

If name contains a path, remove this before searching

OpenCTI or STIX does not explicitly forbid the filename from including a (full or partial) path. If this setting is not set, any path part of name (and x_opencti_additional_names, if SearchAdditionalFilenames) will be part of the search.

If IncludeParentDirRef is set, that path is included in the search.

If RequireAbsPath is set, and no path is provided by parent_directory_ref (IncludeParentDirRef), the search is not performed.

Basename does not imply that the file extension is not removed.

IncludeParentDirRef = 'include-parent-dir-ref'

Include Directory path in parent_directory_ref (if any) in path when searching

A File SCO may have a parent directory reference to a Directory. If this setting is enabled, and this reference exists, this directory’s path will be part of the resulting search path. If this setting is set, and if the filename already includes a path and BasenameOnly is not set, the path in the filename is replaced with that of the parent path.

IncludeRegValues = 'include-reg-values'

Include registry values that matches hashes

Wazuh’s FIM module stores hashes of registry values and produces events when values are created, modified and deleted. This settings includes registry values along with files with matching hashes. Disable this setting to only return files.

AllowRegexp = 'allow-regexp'

Allow regexp queries

This allows regexp queries when searching. Regexp is used to search for paths that are not absolute, and also to search for any number of backslash escapes in the resulting filename path and fields’ path.

Note

Disable this setting if search.allow_expensive_queries is set to false in your OpenSearch installation, or if regexp queries fail.

CaseInsensitive = 'case-insensitive'

Perform a case-insensitive search for filenames/paths on all platforms

Note

Requires AllowRegexp if enabled

RequireAbsPath = 'require-abs-path'

Require an absolute path, either in the filename or together with its parent directory

Searching for filenames without any additional restrictions, like hashes, size or at least a partial path (in the file name or as part of the path from parent_directory_ref, may produce a lot of noisy results. This setting ignores any paths produced by parent_directory_ref::path and name (or x_opencti_additional_names if SearchAdditionalFilenames is enabled) that are not absolute.

class DirSearchOption(value)

Options determining how to search for Directory SCOs

MatchSubdirs = 'match-subdirs'

Match subdirectories where the observable is a parent

If enabled, the observable ‘/foo/bar’ will match the path ‘/foo/bar/baz’. However, it will not match ‘/foo/barbaz’.

Note

Requires AllowRegexp if enabled

SearchFilenames = 'search-filenames'

Match directories in fields that contains filenames

If not set, only directory/path fields will be searched. This setting implies IgnoreTrailingSlash and MatchSubdirs, because it is not always possible to distinguish filenames from directories in paths.

Note

Requires AllowRegexp if enabled

CaseInsensitive = 'case-insensitive'

Perform a case-insensitive search for filenames/paths on all platforms

Note

Requires AllowRegexp if enabled

RequireAbsPath = 'require-abs-path'

Require an absolute path

AllowRegexp = 'allow-regexp'

Allow regexp queries

This allows regexp queries when searching. Regexp is used to search for paths that are not absolute, and also to search for any number of backslash escapes in paths.

Note that this may limit the number of fields searched.

Note

Disable this setting if search.allow_expensive_queries is set to false in your OpenSearch installation, or if regexp queries fail.

NormaliseBackslashes = 'normalise-backslashes'

Normalise backslashes in observable path before searching

Replace all sequences of ‘\’ with ‘\\’ and ‘\\\\’ (searchng for both variants).

If AllowRegexp is enabled, this setting is ignored, and any number of backslashes are searched for.

IgnoreTrailingSlash = 'ignore-trailing-slash'

Disregard trailing slashes in observables and field values

Note

Requires AllowRegexp if enabled

class ProcessSearchOption(value)

An enumeration.

CaseInsensitive = 'case-insensitive'

Perform a case-insensitive search for filenames/paths/arguments on all platforms

class RegKeySearchOption(value)

An enumeration.

MatchSubdirs = 'match-subdirs'

TODO: rephrase: Match subdirectories where the observable is a parent

If enabled, the observable ‘HKLMfoobar’ will match the path ‘HKLMfoobarbaz’. However, it will not match ‘HHLMfoobarbaz’.

Note

Requires AllowRegexp if enabled

RequireAbsPath = 'require-abs-path'

Require an absolute path

The path must start with “HKCU”, “HKEY_CURRENT_USER”, “HKEY_LOCAL_MACHINE” etc. The exact format of the hive (i.e. “HKLM”/”HKEY_LOCAL_MACHINE”) is not important if SearchHiveAliases is enabled.

IgnoreTrailingSlash = 'ignore-trailing-slash'

Disregard trailing slashes in the registry key path

Note

Requires AllowRegexp if enabled

IgnoreSID = 'ignore-sid'

Match key regardless of SID in path

TODO

CaseInsensitive = 'case-insensitive'

Perform a case-insensitive search for key paths

SearchHiveAliases = 'search-hive-aliases'

Search abbreviated as well as full hive names

The following alternatives are searched:

TODO

AllowRegexp = 'allow-regexp'

Allow regexp queries

This allows regexp queries when searching. Regexp is used to search for paths that are not absolute, search for any number of backslash escapes in paths, ignoring SIDs and searching for alternative hive names.

Note

Disable this setting if search.allow_expensive_queries is set to false in your OpenSearch installation, or if regexp queries fail.

pydantic settings SearchConfig

FIXME

Config:

  • env_prefix: str = WAZUH_SEARCH_

  • validate_assignment: bool = True

Fields:
field dirsearch_options: set[DirSearchOption] = {DirSearchOption.AllowRegexp, DirSearchOption.CaseInsensitive, DirSearchOption.IgnoreTrailingSlash, DirSearchOption.MatchSubdirs, DirSearchOption.SearchFilenames}

Directory searching options

See DirSearchOption for details.

The set may be specified as a comma-separated string, like

  • “match-subdirs,require-abs-path, allow-regexp”

Validated by:

  • check_diropt_regexp_dep

field filesearch_options: set[FileSearchOption] = {FileSearchOption.AllowRegexp, FileSearchOption.CaseInsensitive, FileSearchOption.IncludeParentDirRef, FileSearchOption.IncludeRegValues, FileSearchOption.SearchAdditionalFilenames, FileSearchOption.SearchFilenameOnly, FileSearchOption.SearchSize}

File/Artifact searching options

See FileSearchOption for details.

The set may be specified as a comma-separated string, like

  • “search-size,allow-regexp, case-insensitive”

Validated by:

  • check_fileopt_regexp_dep

field ignore_private_addrs: bool = True

Whether to ignore IP addresses in private address spaces when searching for IP address observables

field lookup_agent_ip: bool = False

Whether to include agents’ addresses when searching for IPv4/IPv6 address observables

field lookup_agent_name: bool = False

Whether to search agents’ names (typically, but not necessarily, hostnames) when searching for domain name and hostname observables

field lookup_hostnames_in_cmd_line: bool = False

Search for domain names / hostname in command line arguments

Note

This query will use Wildcard queries, which may be expensive, or even disabled in your OpenSearch installation (search.allow_expensive_queries is set to false) (in which case the query will fail)

field lookup_mac_variants: bool = True

Look up all common MAC address formats

The following formats will be looked up if enabled:

  • 01:02:03:04:ab:cd

  • 01:02:03:04:AB:CD

  • 01020304abcd

  • 01020304ABCD

  • 0102.0304.abcd

  • 0102.0304.ABCD

If disabled, only lower-case, colon-separated MAC addresses will be looked up.

field lookup_url_ignore_trailing_slash: bool = False

Ignore trailing slash when searching for URLs

Note

This will use Wildcard queries, which may be expensive, or even disabled in your OpenSearch installation (search.allow_expensive_queries is set to false) (in which case the query will fail)

field lookup_url_without_host: bool = False

Search for URLs also without host

Some alerts only have URL path without a host. This setting allows searches only for this path. Beware that this can produce a lot of results.

This is probably not useful for looking up IoCs unless you’re looking for a malicious requests.

Note

This will use Wildcard queries, which may be expensive, or even disabled in your OpenSearch installation (search.allow_expensive_queries is set to false) (in which case the query will fail)

field procsearch_options: set[ProcessSearchOption] = {ProcessSearchOption.CaseInsensitive}

Process searching options

See ProcessSearchOption for details.

field regkeysearch_options: set[RegKeySearchOption] = {RegKeySearchOption.AllowRegexp, RegKeySearchOption.CaseInsensitive, RegKeySearchOption.IgnoreSID, RegKeySearchOption.IgnoreTrailingSlash, RegKeySearchOption.MatchSubdirs, RegKeySearchOption.SearchHiveAliases}
Validated by:

  • check_regopt_regexp_dep

Enrichment configuration

Look at the enrichment topic for details.

pydantic settings EnrichmentConfig

This configuration dictates how the connector should enrich incidents with observables and other entities

Config:

  • env_prefix: str = WAZUH_ENRICH_

  • validate_assignment: bool = True

Fields:
field enrich_urls_without_host: bool = False

Enrich URLs without scheme and host

If true, URL observables like ‘/foo’ and ‘/foo/bar?baz=qux’ will be created. If false, URLs must include scheme (like ‘http://’) and host (‘mylocalhost’, ‘example.org’) etc.

field filename_behaviour: set[FilenameBehaviour] = {FilenameBehaviour.CreateDir, FilenameBehaviour.RemovePath}

How Filename STIX cyber observables should be created

See attr:FilenameBehaviour.

Validated by:

  • parse_behaviour_string

field types: set[EntityType] = {EntityType.Account, EntityType.AttackPattern, EntityType.Directory, EntityType.Domain, EntityType.EMailAddr, EntityType.File, EntityType.IPv4Address, EntityType.IPv6Address, EntityType.MAC, EntityType.NetworkTraffic, EntityType.Process, EntityType.RegistryKey, EntityType.Software, EntityType.Tool, EntityType.URL, EntityType.UserAgent, EntityType.Vulnerability}

Which entity types to enrich

The set may be specified as a comma-separated string, like

  • “software,process”

  • “Tool, URL, user-agent”

  • “all”

The special string “all” includes all supported entity types.

Validated by:

  • parse_types_string

class EntityType(value)

Entity types to enrich

See Enrichment for details.

Account = 'user-account'

Enrich user accounts

User accounts will be created from all fields that contain usernames and/or user IDs / SIDs. The user ID may be an e-mail, for instance in alerts from Office 365 and GCP.

The following properties may be set:

  • account_login

  • user_id

AttackPattern = 'attack-pattern'

Enrich MITRE attack patterns

Create and reference MITRE TTPs from rule.mitre.id. Only the MITRE ID is used, so unless another connector like mitre is used, the attack patterns created by opencti-wazuh will be empty, containing only the MITRE ID.

The following properties are set:

  • Name

  • External ID

Directory = 'directory'

Enrich directories from paths

The fields used are fields known to contain only paths, without any filenames. Directory objects are still created as parent directory references whenever File objects are created. See File.

The following properties are set:

  • path

Domain = 'domain-name'

Enrich domain names

Since it is often hard to distinguish hostnames from domain names, no hostname SCOs (OpenCTI’s custom SCO) are created. Hostnames may be created as domain names.

The following properties are set:

  • value

EMailAddr = 'email-addr'

Enrich e-mail addresses

The following properties are set:

  • value

File = 'file'

Enrich files

The following properties may be set:

  • name (always)

  • MD5

  • SHA1

  • SHA256

  • atime

  • ctime

  • mtime

  • size

IPv4Address = 'ipv4-addr'

Enrich IPv4 addresses

The following properties are set:

  • value

IPv6Address = 'ipv6-addr'

Enrich IPv6 addresses

The following properties are set:

  • value

MAC = 'mac-addr'

Enrich MAC addresses

The format used is lower-case colon-delimited hexadecimal characters (EUI-48, as per the STIX standard).

The following properties are set:

  • value

NetworkTraffic = 'network-traffic'

Enrich network traffic

As opposed to when searching for network traffic SCOs, enrichment will only extract network traffic from fields known to contain network traffic logs. Searching is perfomed much more broadly. Therefore, there is (currently) no support for domain names and MAC addreses as source/destination.

The following properties may be set:

  • src_ref (IPv4-Addr/IPv6-Addr)

  • dst_ref (IPv4-Addr/IPv6-Addr)

  • src_port

  • dst_port

  • protocols

  • description

At least two of src_ref, dst_ref, src_port and dst_port must be present for the SCO to be created. protocols may be inferred from the event.

Note

Unfortunately, OpenCTI has decided to focus on dst_port when displaying the network traffic SCO in graphs, or “Unknown” if the dst_port is not set. In many alerts, the destination port is not known. In order to provide a more helpful way to understand the SCO, the connector writes a connetion string in the description, like “ipv4:ssh 10.20.30.40 → 10.20.30.42:?”.

Process = 'process'

Enrich processes

Due to a limitation set by OpenCTI (not the STIX standard), process SCOs cannot be created unless command_line can be populated (even if there is a lot of other useful information). The log will inform about this (log level info) when this happens.

sysmon

The following properties may be set (most are typically available):

  • pid

  • cwd

  • command_line

  • creator (User-Account with account_login and/or user_id)

  • image (File with filename (and SHA256))

  • parent_ref (Process with similar information about the parent process)

auditd

The following properties may be set (most are typically available):

  • pid

  • command_line

  • creator (User-Account with user_id (auid))

  • image (File with filename)

ppid (parent PID) is available, but cannot be referenced because it would imply using parent_ref and another Process object, and there is no command_line information for the parent.

RegistryKey = 'windows-registry-key'

Enrich Windows registry keys

The following properties may be set:

  • key (always)

  • values

Note

Due to the OpenCTI bug #2574, the values are currently not imported.

Software = 'software'

Enrich software

Currently, software SCOs are only enriched from vulnerability alerts.

The following properties may be set:

  • name (always)

  • version

Tool = 'tool'

Enrich tool SDOs

Tools are enriched by looking up names of all tools found in OpenCTI (fetched using the API when the connector starts) in fields containing command lines or names of executables. This may produce some false positives.

Note

This requires tools to exist in OpenCTI. The MITRE connector provides a number of tools, along with a number of other very useful entities.

URL = 'url'

Enrich URLs

The following properties are set:

  • value

UserAgent = 'user-agent'

Enrich user agents strings

This is a custom SCO provided by OpenCTI. Very few fields contain user agent strings. The only one so far are provided by the AWS and Office 365 integrations.

The following properties are set:

  • value

Vulnerability = 'vulnerability'

Enrich vulnerabilities

Vulnerabilities are enriched from Wazuh’s vulnerability checker, from both events created when the vulnerabilities are detected, and when they are resolved.

The following properties may be set (most are typically available):

  • name (always)

  • CVSS - Score (x_opencti_cvss_base_score)

  • CVSS3 - Severity (x_opencti_cvss_base_severity)

  • CVSS3 - Attack vector (x_opencti_cvss_attack_vector)

  • CVSS3 - Integrity impact (x_opencti_cvss_integrity_impact)

  • CVSS3 - Availability impact (x_opencti_cvss_availability_impact)

  • CVSS3 - Confidentiality impact (x_opencti_cvss_confidentiality_impact)

Although alerts contain more metadata, there is no place to put them in the vulnerability SDO, and the connector will not override the description, since it typically contains useful information imported from another source, like MITRE.