feat(metras): add Metras external-import connector for EDR telemetry (#7042) by Khidr6G · Pull Request #7039 · OpenCTI-Platform/connectors

Khidr6G · 2026-07-17T18:43:35Z

Proposed changes

Add a new EXTERNAL_IMPORT connector for the Metras EDR platform
(api.metras.sa, X-API-KEY) under external-import/metras/.
Imports three data sources into OpenCTI as STIX:
- EDR alerts → Incident, with Attack-Pattern (uses) from the alert mitre_ids
  and Url observables for external artifacts.
- File binaries → StixFile observables (banned/unsigned only by default to limit noise).
- Endpoint inventory → Identity(identity_class="system"). Internal fleet assets are
  modeled as System identities (internal IPs/hostnames kept in the description), not as
  IOC observables or Infrastructure, per maintainer guidance (PR [qualys] Add Qualys CVE enrichment connector #6164).
Incremental sync: client-side cursor on last_occurrence_time for the alerts endpoint
(no server fromTime), server-side fromTime windowing for binaries, full listing for
endpoints. Deterministic STIX IDs via pycti generate_id. Full Work-API lifecycle.
Secrets typed as pydantic.SecretStr; startup API ping; structured logging; CIS-hardened
docker-compose.yml; non-root python:3.12-alpine image with libmagic.
Unit tests for settings, API client, converter, and connector orchestration; pyproject.toml
coverage config for the codecov/patch gate. black / isort --profile black /
flake8 --ignore=E,W clean.
Validated end-to-end against OpenCTI 7.260529.0 (pycti==7.260529.0,
connectors-sdk @7.260529.0, support_version ">=7.260529.0").

Related issues

Closes feat(metras): Add Metras EDR connector suite (external-import, internal-enrichment, stream) #7042

Checklist

I consider the submitted work as finished
I have signed my commits using GPG key.
I tested the code for its functionality using different use cases
I added/update the relevant documentation (either on github or on notion)
Where necessary I refactored code to improve the overall quality

Further comments

Design notes driven by the Metras API: the EDR alerts endpoint exposes no fromTime
parameter, so incremental import uses a client-side cursor on last_occurrence_time rather
than a server-side window; only the binaries endpoint supports fromTime. Endpoints are
emitted as System identities rather than observables to keep the IOC space clean — this is the
main modeling decision and is consistent with the accompanying Metras enrichment connector.

…penCTI-Platform#7038)

Copilot

Pull request overview

Adds a new Metras EXTERNAL_IMPORT connector under external-import/metras/ to ingest Metras EDR telemetry into OpenCTI as STIX (Incidents + ATT&CK Attack-Patterns + Url/File observables + System identities), with a shared HTTP client, deterministic IDs, and a basic unit-test suite.

Changes:

Introduces the Metras feed connector implementation (settings, API client, STIX conversion, import loop with state cursors + Work API lifecycle).
Adds unit tests for utility functions, settings, API client, converter, and orchestration.
Adds packaging/runtime artifacts for containerized deployment (Dockerfile, compose, entrypoint) plus connector metadata/docs.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
external-import/metras/VERSION	Adds connector version marker.
external-import/metras/tests/test-requirements.txt	Defines test dependencies for the connector.
external-import/metras/tests/test_main.py	Tests pure utility functions (refang, validation, timestamps, severity mapping).
external-import/metras/tests/test_connector/test_settings.py	Tests Pydantic settings behavior and defaults.
external-import/metras/tests/test_connector/test_orchestration.py	Tests connector import loop behavior with mocked helper/client.
external-import/metras/tests/test_connector/test_converter.py	Tests alert/binary/endpoint → STIX conversion outputs.
external-import/metras/tests/test_connector/test_client.py	Tests API client request/response handling with mocked HTTP.
external-import/metras/tests/conftest.py	Adds src path for test imports.
external-import/metras/src/requirements.txt	Adds runtime dependencies (pycti, stix2, requests, connectors-sdk, etc.).
external-import/metras/src/metras_client/api_client.py	Implements shared Metras REST API client (retrying session + endpoints).
external-import/metras/src/metras_client/init.py	Exposes `MetrasClient` / `MetrasAPIError`.
external-import/metras/src/main.py	Adds connector entrypoint wiring settings → helper → connector.run().
external-import/metras/src/connector/utils.py	Adds dependency-free helpers (refang, validation, timestamp helpers, severity mapping).
external-import/metras/src/connector/settings.py	Adds connector + Metras config models (connectors-sdk + pydantic).
external-import/metras/src/connector/converter_to_stix.py	Converts Metras alerts/binaries/endpoints into STIX objects + relationships.
external-import/metras/src/connector/connector.py	Implements the feed import loop, cursors/state, and Work API status updates.
external-import/metras/src/connector/init.py	Exposes connector and settings entrypoints.
external-import/metras/README.md	Documents behavior, mapping, incremental sync, and configuration.
external-import/metras/pyproject.toml	Adds coverage configuration for this connector.
external-import/metras/entrypoint.sh	Adds container entrypoint script.
external-import/metras/Dockerfile	Builds a non-root Alpine-based container image for the connector.
external-import/metras/docker-compose.yml	Provides a hardened compose example for deployment.
external-import/metras/config.yml.sample	Provides sample YAML configuration.
external-import/metras/.dockerignore	Excludes unnecessary files from Docker build context.
external-import/metras/metadata/connector_manifest.json	Adds connector catalog metadata manifest.

…penCTI-Platform#7042)

…m#7042)

Copilot

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 4 comments.

Powlinett · 2026-07-27T10:08:15Z

+from pycti import (
+    AttackPattern,
+    Identity,
+    Incident,
+    StixCoreRelationship,
+)
+
+if TYPE_CHECKING:
+    from pycti import OpenCTIConnectorHelper
+
+_TLP_BY_NAME = {
+    "clear": stix2.TLP_WHITE,
+    "white": stix2.TLP_WHITE,
+    "green": stix2.TLP_GREEN,
+    "amber": stix2.TLP_AMBER,
+    "red": stix2.TLP_RED,
+}


To avoid this kind of issues, it's strongly advised to use the OCTI models from connectors_sdk instead of stix2 objects (see https://github.com/OpenCTI-Platform/connectors/blob/master/connectors-sdk/connectors_sdk/models/tlp_marking.py)

+        if len(all_objects) > 1:  # more than just the author
+            bundle = self.helper.stix2_create_bundle(all_objects)
+            self.helper.send_stix2_bundle(
+                bundle, work_id=work_id, cleanup_inconsistent_bundle=True
+            )


+        # Advance cursors only for categories that did not hard-fail.
+        new_state = dict(state)
+        if "alerts" not in "".join(errors) and new_alerts_max is not None:
+            new_state["alerts_last_occurrence"] = stix_timestamp(new_alerts_max)
+        if "binaries" not in "".join(errors) and new_binaries_max:
+            new_state["binaries_last_seen"] = new_binaries_max


+| `CONNECTOR_SCOPE` | no | `Metras` | Import scope |
+| `CONNECTOR_LOG_LEVEL` | no | `info` | Log level |
+| `CONNECTOR_DURATION_PERIOD` | yes | `PT1H` | ISO-8601 poll interval |
+| `METRAS_API_BASE_URL` | no | `https://api.metras.sa/api` | Metras API base URL |


Powlinett

Hi @Khidr6G , thanks for your contribution.

Before addressing Copilot's comments, please rebase your branch onto the latest version of master to ensure the CI performs the same checks as on master 🙏

Powlinett · 2026-07-27T10:19:29Z

Also, please rename connector folder so it has a unique name. The rule is: folder name == manifest's slug == docker image's name 👌

feat(metras): add Metras external-import connector for EDR telemetry (O…

d147bf3

…penCTI-Platform#7038)

Copilot AI review requested due to automatic review settings July 17, 2026 18:43

github-actions Bot assigned Khidr6G Jul 17, 2026

Copilot started reviewing on behalf of Khidr6G July 17, 2026 18:44 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread external-import/metras/src/connector/converter_to_stix.py

Comment thread external-import/metras/src/metras_client/api_client.py Outdated

Comment thread external-import/metras/__metadata__/connector_manifest.json

Khidr6G changed the title ~~feat(metras): add Metras external-import connector for EDR telemetry (#7038)~~ feat(metras): add Metras external-import connector for EDR telemetry (#7042) Jul 17, 2026

Khidr6G added 2 commits July 18, 2026 00:53

fix(metras): stable incident id, fail-loud client, add config schema (O…

e35fd2c

…penCTI-Platform#7042)

fix(metras): set manifest source_code required by CI (OpenCTI-Platfor…

5d489dd

…m#7042)

romain-filigran added the community Contribution from the community. label Jul 24, 2026

romain-filigran requested a review from Copilot July 27, 2026 08:56

Copilot started reviewing on behalf of romain-filigran July 27, 2026 08:57 View session

Copilot AI reviewed Jul 27, 2026

View reviewed changes

Powlinett reviewed Jul 27, 2026

View reviewed changes

Powlinett mentioned this pull request Jul 27, 2026

feat(metras): add Metras internal-enrichment connector for fleet-presence lookups (#7042) #7040

Open

5 tasks

Powlinett mentioned this pull request Jul 27, 2026

feat(metras): add Metras stream connector for blocklist sync (#7042) #7041

Open

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(metras): add Metras external-import connector for EDR telemetry (#7042)#7039

feat(metras): add Metras external-import connector for EDR telemetry (#7042)#7039
Khidr6G wants to merge 3 commits into
OpenCTI-Platform:masterfrom
Khidr6G:feature/metras-external-import

Khidr6G commented Jul 17, 2026 •

edited by romain-filigran

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Powlinett Jul 27, 2026

Uh oh!

Powlinett left a comment

Uh oh!

Powlinett commented Jul 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

Khidr6G commented Jul 17, 2026 • edited by romain-filigran Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Related issues

Checklist

Further comments

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Powlinett Jul 27, 2026

Choose a reason for hiding this comment

Uh oh!

Powlinett left a comment

Choose a reason for hiding this comment

Uh oh!

Powlinett commented Jul 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Khidr6G commented Jul 17, 2026 •

edited by romain-filigran

Loading