misje / opencti-wazuh-connector

OpenCTI–Wazuh connector looking for indicators in Wazuh and creating sightings

OpenCTI–Wazuh-connector

opencti-wazuh-connector is an OpenCTI connector that lets you look up entities from your cyber threat database in your Wazuh SIEM. It's implemented as an enrichment connector, which triggers automatically (or manually if you want) whenever a new entity is added to the OpenCTI database.

This connector has several use cases. Perhaps the most obvious one is to automatically scan your whole SIEM database whenever there is a new indicator imported in OpenCTI. However, it can also act as a comfortable search interface, automatically creating sightings for you for every hit.

See the extensive documentation for information about installation, configuration and usage.

Caution

opencti-wazuh-connector is in an early alpha stage. Although the connector does not make any changes to Wazuh, it may produce a lot of data in OpenCTI. Do not use the connector yet in production.

Overview

The connector performs its work in the following defined stages:

Inspect

This stage looks at the incoming entity, determines whether it should be looked up according to the thresholds in the settings (TLP allowed, is an indicator required, is it a private IP address, does it have a label in the ignore list). If the entity should be looked up in Wazuh, the connector proceeds.

Search

The search stage constructs an OpenSearch query that will look for the entity's metadata in a number of fields. How the query is formed, varies depending on the entity type and search settings. For instance, if the entity is a StixFile, the resulting query may look for one or more of the observable's hashes. If just a name is provided, a search for the filename (including its path, if provided), is performed. If the File has a size defined, the size may be included as a search parameter. Any filename aliases may be included too.

For a User-Account, the search may either for the account_login, user_id or both. For a Process object, the command_line can be looked up in known command line fields, with wildcard support and ignoring argument order.

Whether you want specific and targeted searches, or searches that look for partial matches, is entirely up to you through the plethora of options. Most observables, as well as some entities, like Vulnerability, are supported.

Events

The next stage is deciding what to do with the results. The first step is to create sightings, which indicates that an observable was "sighted" in a system (a Wazuh agent, AWS, GitHub, Office 365 or the SIEM itself). A sighting contains information about when the observation was first made, the time of the last observation, and the number of observations in this time frame.

Enrich

In order to provide useful context for the events created later, the enrichment stage tries to extract all possible information from alerts as STIX cyber observables. For instance, if an alert includes information about a process, a Process SCO (STIX cyber observable) is created. The process may also include a parent process as an individual, referenced, Process SCO, and references to the commands ran as File SCOs. Additionally, any network traffic is represented as Network-Traffic. And so on, including pretty much all SCOs, as well as Attack-Pattern (Wazuh's MITRE data).

Enrichment is performed if an incident is created.

Incidents and cases

Depending on your settings, the sighting may be the cause of an incident. An incident typically indicates something serious, like if a "sighted" observable is part of an indicator. Incidents would typically create a notification of some sort for you to act on.

You may choose how incidents are created. Either never, per sighting, per distinct alert rule ID, per alert or per query.

An incident response case is optionally created for an incident. Cases help visualise incidents by providing a graph of all entities involved, starting from the entitiy the connector was run on, sightings, incidents and enriched entities.

Screenshots

opencti-wazuh-connector's Issues

Add debug output whenever an entity is created

The worker log output is not enough when debugging import errors. The connector should log metadata from all objects it creates.

Create unit (mocking) unit tests for complicated search module members

Some of the member functions in the search module are getting increasingly complex after introducing highly customiseable configurations. In addition to reaching 100 % function test coverage, be sure to test most, if not all, config permutations of these individual functions in the search module.

• query_file()
• query_process()

Create a simple proof-of-concept

Look up various kinds of indicators, like files/artifacts (SHA256), domain names / hostnames / IP addresses, URLs etc. in OpenSearch and create sightings for any results.

If this proof-of-concept seems to have any use, continue development and consider offering it as a connector to OpenCTI-Platform/connectors.

I'm very open to suggestions, in particular what to do with the results (objects and relationships to create, what fields to populate with what etc.).

Find a way to distinguish manual enrichments from automatic enrichments

In order to avoid a seemingly endless recursion of enrichment, this connector will by default refuse to enrich entities created by itself. The setting *label_ignore_list" is used for this, and the default behaviour is to produce the label "wazuh_ignore" for every enriched entity.

This shouldn't be necessary. Instead, the connector should be able to differentiate between an automatic enrichment call and a manual enrichment call. This is currently not possible. Either raise this as an issue with OpenCTI or find a better workaround.

Enrichment can always be performed by removing the label "wazuh_ignore" on the entity in question.

Resolve possible missing reference error when enriching vulnerabilities

Support Indicator with STIX patterns

By using a translator like STIX-shifter, or a similar project that already implements the grammar, like stix2patterns, STIX patterns could be translated into an OpenSearch DSL query. This requires a translator and a model, since Wazuh doesn't really have a common schema for alerts.

Adding direct indicator support would be incredibly useful. The current implementation depends on relationships between indicators and observables ("based-on"). These are fortunately often provided, but they only make sense when the indicator pattern is trivial. Additionaly, some sources also only provide a STIX pattern, without any references to observables.

Use GitHub actions for running tests

• Run doctests (require success)
• Run unit tests (require success)
• Generate report
• Generate HTML
• Render HTML

Ensure that connector always enriches indicators

Currently, OpenCTI is a bit inconsistent when running this connector through automated enrichment on indicators. Sometimes the "based on" relationships are present, sometimes not. Although the indicator and the relationships are created at the same time, it appears that the enrichment is run before the relationships are created. This is expected and impossible to prevent if they relationships were manually added at a later time, but it's frustrating when they're all created at the same time, part of a internal OpenCTI automation. Can this be something OpenCTI can solve? If not, how could the connector deal with this?

This can probably be resolved with a playbook, but do not force users to rely on enterprise features for core functionality.

Rewrite process search method

Following the rewrite of query_file(), rewrite the query_process() method in a similar fashion.

Generate sphinx docs and publish

Run actions to

• Generate HTML docs
• Publish docs to github-pages

Add spelling workflow and get rid of typos

Rewrite directory search method

Following the rewrite of query_file(), rewrite the query_directory() method in a similar fashion.

Create end-user documentation

Put emphasis on

• Configuration options
• General overview
• Search details
• Enrichment details

Complete "full demo" example with Wazuh sample events

The full demo docker-compose example lacks logic to populate Wazuh with demo events. Create a docker image that runs once, calling

1. docker run --rm -w "/home/node/app" -v "$(pwd):/home/node/app" node:lts-alpine node cli.js --all-modules --format bulk-api --index wazuh-alerts-4.x-sample > output.ndjson
2. curl -k -u 'admin:SecretPassword' https://localhost:9200/_bulk -H "Content-Type: application/x-ndjson" --data-binary "@output.ndjson"
3. Add missing "@timestamp" column:

curl -k -u 'admin:SecretPassword' -X POST https://localhost:9200/wazuh-alerts-*/_update_by_query -H "Content-Type: application/json" -d "$(cat <<EOF
{
"script": {
  "source": "String timestamp = ctx._source['timestamp']; if (timestamp != null) { DateTimeFormatter inputFormatter = DateTimeFormatter.ofPattern(\"yyyy-MM-dd'T'HH:mm:ss.SSSZ\"); ZonedDateTime parsedTime = ZonedDateTime.parse(timestamp, inputFormatter); String formattedTime = DateTimeFormatter.ISO_INSTANT.format(parsedTime); ctx._source['@timestamp'] = formattedTime; }",
  "lang": "painless"
}
}
EOF
)"

Use patched misje/wazuh-dashboard-plugins as a referene, since the Wazuh maintainers have not provided any feedback on my pull request to fix invalid IP addresses and invalid SHA-256 hashes in the example data. The entrypoint needs to patientely wait for OpenSearch to become available.

Add support for reading configuration from file

Not everyone is using a docker deployment, and for those, having to rely on environment variables is not a good solution. Add support yaml configuration files (pydantic settings supports this out of the box).