From c7ca3e573495fa6c2483cc099d5f3028e5350ab0 Mon Sep 17 00:00:00 2001 From: Christophe Melchior Date: Mon, 9 Nov 2026 23:33:03 +0100 Subject: [PATCH 01/17] :white_check_mark: test(sdk): CHK.1 mirror the platform payloads key for key, RED Tests --- libs/xtm-oaev-sdk/test/port_io/__init__.py | 0 .../port_io/fixtures/execution_callback.json | 11 + .../port_io/fixtures/execution_reception.json | 3 + .../fixtures/expectation_bulk_update.json | 17 + .../port_io/fixtures/expectation_update.json | 8 + .../test/port_io/fixtures/inject_message.json | 62 ++ .../fixtures/pending_expectations.json | 79 +++ .../test/port_io/fixtures/traces_bulk.json | 12 + .../port_io/test_platform_payload_samples.py | 166 +++++ .../test/port_io/test_platform_payloads.py | 586 ++++++++++++++++++ 10 files changed, 944 insertions(+) create mode 100644 libs/xtm-oaev-sdk/test/port_io/__init__.py create mode 100644 libs/xtm-oaev-sdk/test/port_io/fixtures/execution_callback.json create mode 100644 libs/xtm-oaev-sdk/test/port_io/fixtures/execution_reception.json create mode 100644 libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_bulk_update.json create mode 100644 libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_update.json create mode 100644 libs/xtm-oaev-sdk/test/port_io/fixtures/inject_message.json create mode 100644 libs/xtm-oaev-sdk/test/port_io/fixtures/pending_expectations.json create mode 100644 libs/xtm-oaev-sdk/test/port_io/fixtures/traces_bulk.json create mode 100644 libs/xtm-oaev-sdk/test/port_io/test_platform_payload_samples.py create mode 100644 libs/xtm-oaev-sdk/test/port_io/test_platform_payloads.py diff --git a/libs/xtm-oaev-sdk/test/port_io/__init__.py b/libs/xtm-oaev-sdk/test/port_io/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/libs/xtm-oaev-sdk/test/port_io/fixtures/execution_callback.json b/libs/xtm-oaev-sdk/test/port_io/fixtures/execution_callback.json new file mode 100644 index 00000000..6e12abfd --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/fixtures/execution_callback.json @@ -0,0 +1,11 @@ +{ + "execution_message": "Scan completed", + "execution_output_structured": "{\"scan_results\": [{\"host\": \"10.0.0.5\", \"port\": 22}]}", + "execution_output_raw": "PORT STATE SERVICE\n22/tcp open ssh", + "execution_status": "SUCCESS", + "execution_duration": 3, + "execution_action": "complete", + "execution_context_identifiers": [ + "0d3f7d1a-web-01" + ] +} diff --git a/libs/xtm-oaev-sdk/test/port_io/fixtures/execution_reception.json b/libs/xtm-oaev-sdk/test/port_io/fixtures/execution_reception.json new file mode 100644 index 00000000..dfdd1ad0 --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/fixtures/execution_reception.json @@ -0,0 +1,3 @@ +{ + "tracking_total_count": 1 +} diff --git a/libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_bulk_update.json b/libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_bulk_update.json new file mode 100644 index 00000000..beee93af --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_bulk_update.json @@ -0,0 +1,17 @@ +{ + "inputs": { + "4e5d-expectation": { + "collector_id": "c0ffee-collector", + "result": "Detected", + "is_success": true, + "metadata": { + "alertId": "a-42" + } + }, + "7f1a-expectation": { + "collector_id": "c0ffee-collector", + "result": "Not Prevented", + "is_success": false + } + } +} diff --git a/libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_update.json b/libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_update.json new file mode 100644 index 00000000..9c401be4 --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/fixtures/expectation_update.json @@ -0,0 +1,8 @@ +{ + "collector_id": "c0ffee-collector", + "result": "Detected", + "is_success": true, + "metadata": { + "alertId": "a-42" + } +} diff --git a/libs/xtm-oaev-sdk/test/port_io/fixtures/inject_message.json b/libs/xtm-oaev-sdk/test/port_io/fixtures/inject_message.json new file mode 100644 index 00000000..68f4da29 --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/fixtures/inject_message.json @@ -0,0 +1,62 @@ +{ + "injection": { + "inject_id": "8a4f1f0e-2c4b-4f43-9d5e-0b6f5b6f1a01", + "inject_title": "Scan the DMZ", + "inject_description": "Port scan of the DMZ web servers", + "inject_content": { + "target_selector": "assets", + "expectations": [ + { + "expectation_type": "DETECTION", + "expectation_name": "Detection", + "expectation_score": 100.0, + "expectation_expectation_group": false, + "expectation_expiration_time": 21600 + } + ] + }, + "inject_injector_contract": { + "injector_contract_id": "5c8b6c3e-tcp-connect", + "injector_contract_content": "{\"contract_id\": \"5c8b6c3e-tcp-connect\"}", + "convertedContent": { + "contract_id": "5c8b6c3e-tcp-connect" + }, + "injector_contract_labels": { + "en": "TCP connect scan" + } + }, + "inject_documents": [], + "inject_status": null + }, + "assets": [ + { + "asset_id": "0d3f7d1a-web-01", + "asset_hostname": "web-01", + "asset_ips": [ + "10.0.0.5" + ], + "asset_seen_ip": "10.0.0.5", + "asset_agents": [ + { + "agent_id": "c1b2-agent", + "agent_privilege": "admin", + "agent_deployment_mode": "service", + "agent_executed_by_user": "SYSTEM", + "agent_active": true, + "agent_last_seen": "2026-11-05T19:59:00Z", + "agent_version": "2.1.0" + } + ] + } + ], + "assetGroups": [ + { + "asset_group_id": "f00d-dmz", + "asset_group_name": "DMZ" + } + ], + "attachments": { + "credential_references": [], + "authorisation_code": null + } +} diff --git a/libs/xtm-oaev-sdk/test/port_io/fixtures/pending_expectations.json b/libs/xtm-oaev-sdk/test/port_io/fixtures/pending_expectations.json new file mode 100644 index 00000000..5bd74322 --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/fixtures/pending_expectations.json @@ -0,0 +1,79 @@ +[ + { + "inject_expectation_id": "4e5d-expectation", + "inject_expectation_type": "DETECTION", + "inject_expectation_name": "Detection", + "inject_expectation_description": null, + "inject_expectation_score": null, + "inject_expectation_expected_score": 100.0, + "inject_expiration_time": 21600, + "inject_expectation_group": false, + "inject_expectation_order": null, + "inject_expectation_status": "PENDING", + "inject_expectation_created_at": "2026-11-05T20:00:00Z", + "inject_expectation_updated_at": "2026-11-05T20:00:00Z", + "inject_expectation_signatures": [ + { + "type": "parent_process_name", + "value": "oaev-implant-8a4f" + }, + { + "type": "start_date", + "value": "2026-11-05T20:00:00Z" + } + ], + "inject_expectation_results": [ + { + "inject_expectation_id": "9b9b-result", + "sourceId": "c0ffee-collector", + "sourceType": "collector", + "sourceName": "Splunk ES", + "sourceAssetId": null, + "sourcePlatform": "SIEM", + "date": "2026-11-05T20:01:00Z", + "score": 0.0, + "result": "Not Detected", + "metadata": {}, + "inject_expectation_result_created_at": "2026-11-05T20:01:00Z", + "inject_expectation_result_updated_at": "2026-11-05T20:01:00Z" + } + ], + "inject_expectation_traces": [], + "inject_expectation_exercise": null, + "inject_expectation_inject": "8a4f1f0e-2c4b-4f43-9d5e-0b6f5b6f1a01", + "inject_expectation_user": null, + "inject_expectation_team": null, + "inject_expectation_agent": "c1b2-agent", + "inject_expectation_asset": "0d3f7d1a-web-01", + "inject_expectation_asset_group": null, + "inject_expectation_article": null, + "inject_expectation_challenge": null, + "target_id": "c1b2-agent", + "inject_expectation_expected_security_platforms": [ + "SIEM" + ], + "inject_expectation_collector_missing_at_init": false + }, + { + "inject_expectation_id": "7f1a-expectation", + "inject_expectation_type": "PREVENTION", + "inject_expectation_name": "Prevention", + "inject_expectation_expected_score": 100.0, + "inject_expiration_time": 21600, + "inject_expectation_group": false, + "inject_expectation_status": "PENDING", + "inject_expectation_created_at": "2026-11-05T20:00:00Z", + "inject_expectation_updated_at": "2026-11-05T20:00:00Z", + "inject_expectation_signatures": [ + { + "type": "target_ipv4_address", + "value": "10.0.0.5" + } + ], + "inject_expectation_results": [], + "inject_expectation_traces": [], + "inject_expectation_inject": "8a4f1f0e-2c4b-4f43-9d5e-0b6f5b6f1a01", + "inject_expectation_asset": "0d3f7d1a-web-01", + "target_id": "0d3f7d1a-web-01" + } +] diff --git a/libs/xtm-oaev-sdk/test/port_io/fixtures/traces_bulk.json b/libs/xtm-oaev-sdk/test/port_io/fixtures/traces_bulk.json new file mode 100644 index 00000000..73dab6b7 --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/fixtures/traces_bulk.json @@ -0,0 +1,12 @@ +{ + "expectation_traces": [ + { + "inject_expectation_trace_expectation": "4e5d-expectation", + "inject_expectation_trace_source_id": "c0ffee-collector", + "inject_expectation_trace_alert_name": "Suspicious port scan", + "inject_expectation_trace_alert_link": "https://siem.example/alerts/a-42", + "inject_expectation_trace_date": "2026-11-05T20:01:00Z", + "inject_expectation_trace_match_type": "marker" + } + ] +} diff --git a/libs/xtm-oaev-sdk/test/port_io/test_platform_payload_samples.py b/libs/xtm-oaev-sdk/test/port_io/test_platform_payload_samples.py new file mode 100644 index 00000000..70c788e3 --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/test_platform_payload_samples.py @@ -0,0 +1,166 @@ +"""Tests for the sample platform payloads and the sources the payload models mirror. + +Feature: Platform payload samples + Each payload model is written by hand from the platform DTO it mirrors, and ships with + one sample payload written from that DTO. A sample read with its model and written + back is unchanged, the platform's dates are read whether it wrote them as ISO text or + as epoch numbers, and every model names the DTO it mirrors. +""" + +import json +from pathlib import Path +from typing import Any + +import pytest +import xtm_oaev_sdk as sdk +from pydantic import TypeAdapter + +FIXTURES = Path(__file__).parent / "fixtures" + +#: Each payload model and the platform source it mirrors (openaev-platform repository). +PLATFORM_SOURCES = { + "ExecutableInject": "openaev-api/src/main/java/io/openaev/execution/ExecutableInjectDTO.java", + "ExecutableInjection": "openaev-model/src/main/java/io/openaev/database/model/Injection.java", + "ExecutableInjectorContract": "openaev-model/src/main/java/io/openaev/database/model/InjectorContract.java", + "EndpointTargetOutput": "openaev-api/src/main/java/io/openaev/rest/asset/endpoint/output/EndpointTargetOutput.java", + "AgentOutput": "openaev-api/src/main/java/io/openaev/rest/asset/endpoint/form/AgentOutput.java", + "AssetGroupSimple": "openaev-api/src/main/java/io/openaev/rest/asset_group/form/AssetGroupSimple.java", + "InjectReceptionInput": "openaev-api/src/main/java/io/openaev/rest/inject/form/InjectReceptionInput.java", + "InjectExecutionInput": "openaev-api/src/main/java/io/openaev/rest/inject/form/InjectExecutionInput.java", + "InjectExpectationOutput": "openaev-api/src/main/java/io/openaev/api/expectations/dto/InjectExpectationOutput.java", + "InjectExpectationSignature": "openaev-model/src/main/java/io/openaev/database/model/InjectExpectationSignature.java", + "InjectExpectationResult": "openaev-model/src/main/java/io/openaev/database/model/InjectExpectationResult.java", + "InjectExpectationUpdateFromCollectorInput": "openaev-api/src/main/java/io/openaev/rest/inject/form/InjectExpectationUpdateFromCollectorInput.java", + "InjectExpectationBulkUpdateInput": "openaev-api/src/main/java/io/openaev/rest/inject/form/InjectExpectationBulkUpdateInput.java", + "InjectExpectationTraceInput": "openaev-api/src/main/java/io/openaev/rest/inject_expectation_trace/form/InjectExpectationTraceInput.java", + "InjectExpectationTraceBulkInsertInput": "openaev-api/src/main/java/io/openaev/rest/inject_expectation_trace/form/InjectExpectationTraceBulkInsertInput.java", +} + + +def _given_payload_model(name: str) -> Any: + """Given the SDK models the "" platform payload""" + model = getattr(sdk, name, None) + assert model is not None, f"Expected xtm_oaev_sdk.{name} to exist on public surface" + return model + + +def _given_sample(fixture: str) -> Any: + """Given the sample payload "" written from its platform DTO""" + return json.loads((FIXTURES / fixture).read_text(encoding="utf-8")) + + +def _given_pending_expectation_dated(created_at: Any) -> dict[str, Any]: + """Given a pending expectation the platform dated """ + expectation = dict(_given_sample("pending_expectations.json")[0]) + expectation["inject_expectation_created_at"] = created_at + expectation["inject_expectation_updated_at"] = created_at + return expectation + + +def _given_trace_dated(date: Any) -> dict[str, Any]: + """Given an expectation trace dated """ + trace = dict(_given_sample("traces_bulk.json")["expectation_traces"][0]) + trace["inject_expectation_trace_date"] = date + return trace + + +def _when_reading_and_writing_back(model: Any, payload: Any, many: bool) -> Any: + """When the payload is read with that model and written back as JSON""" + adapter = TypeAdapter(list[model] if many else model) + value = adapter.validate_python(payload) + return adapter.dump_python(value, mode="json", exclude_unset=True) + + +def _when_reading_the_docstring(model: Any) -> str: + """When the model's documentation is read""" + return model.__doc__ or "" + + +def _then_written_payload_is(written: Any, payload: Any) -> None: + """Then the written payload is exactly the payload read""" + assert written == payload + + +def _then_docstring_names(docstring: str, source: str) -> None: + """Then the documentation names the platform source "" """ + flat = " ".join(docstring.split()) + assert source in flat, f"Expected the docstring to name {source}, got: {flat}" + + +@pytest.mark.parametrize( + "fixture, model_name, many", + [ + ("inject_message.json", "ExecutableInject", False), + ("execution_reception.json", "InjectReceptionInput", False), + ("execution_callback.json", "InjectExecutionInput", False), + ("pending_expectations.json", "InjectExpectationOutput", True), + ("expectation_update.json", "InjectExpectationUpdateFromCollectorInput", False), + ("expectation_bulk_update.json", "InjectExpectationBulkUpdateInput", False), + ("traces_bulk.json", "InjectExpectationTraceBulkInsertInput", False), + ], +) +def test_sample_payload_round_trips_unchanged( + fixture: str, model_name: str, many: bool +) -> None: + """It reads each sample payload with its model and writes it back unchanged. + + Scenario Outline: A sample payload round-trips unchanged + Given the sample payload "" written from its platform DTO + And the SDK models the "" platform payload + When the payload is read with that model and written back as JSON + Then the written payload is exactly the payload read + """ + payload = _given_sample(fixture) + model = _given_payload_model(model_name) + written = _when_reading_and_writing_back(model, payload, many) + _then_written_payload_is(written, payload) + + +@pytest.mark.parametrize("created_at", ["2026-11-05T20:00:00Z", 1762372800.0]) +def test_pending_expectation_keeps_the_dates_as_the_platform_wrote_them( + created_at: Any, +) -> None: + """It reads a pending expectation dated as ISO text or as an epoch number. + + Scenario Outline: The platform's dates are read as written + Given a pending expectation the platform dated + And the SDK models the "InjectExpectationOutput" platform payload + When the payload is read with that model and written back as JSON + Then the written payload is exactly the payload read + """ + payload = _given_pending_expectation_dated(created_at) + model = _given_payload_model("InjectExpectationOutput") + written = _when_reading_and_writing_back(model, payload, False) + _then_written_payload_is(written, payload) + + +@pytest.mark.parametrize("date", ["2026-11-05T20:01:00Z", 1762372860]) +def test_expectation_trace_takes_an_iso_or_epoch_date(date: Any) -> None: + """It accepts a trace dated as ISO text or as an epoch number. + + Scenario Outline: A trace date is written as given + Given an expectation trace dated + And the SDK models the "InjectExpectationTraceInput" platform payload + When the payload is read with that model and written back as JSON + Then the written payload is exactly the payload read + """ + payload = _given_trace_dated(date) + model = _given_payload_model("InjectExpectationTraceInput") + written = _when_reading_and_writing_back(model, payload, False) + _then_written_payload_is(written, payload) + + +@pytest.mark.parametrize("model_name, source", sorted(PLATFORM_SOURCES.items())) +def test_payload_model_names_the_platform_dto_it_mirrors( + model_name: str, source: str +) -> None: + """It documents each payload model with the platform DTO it mirrors. + + Scenario Outline: A payload model names its platform DTO + Given the SDK models the "" platform payload + When the model's documentation is read + Then the documentation names the platform source "" + """ + model = _given_payload_model(model_name) + docstring = _when_reading_the_docstring(model) + _then_docstring_names(docstring, source) diff --git a/libs/xtm-oaev-sdk/test/port_io/test_platform_payloads.py b/libs/xtm-oaev-sdk/test/port_io/test_platform_payloads.py new file mode 100644 index 00000000..5708a463 --- /dev/null +++ b/libs/xtm-oaev-sdk/test/port_io/test_platform_payloads.py @@ -0,0 +1,586 @@ +"""Tests for the platform payloads exchanged with injectors and collectors. + +Feature: Platform payloads + Injectors and collectors exchange JSON payloads with the OpenAEV platform: the inject + message an injector consumes, the execution calls it sends back, the pending + expectations a collector reads, and the updates and traces it answers with. + The SDK models each payload exactly as the platform publishes or accepts it, so a + connector running without the platform reads and writes the same JSON. +""" + +from typing import Any, NamedTuple + +import pytest +import xtm_oaev_sdk as sdk +from pydantic import ValidationError + + +class Reading(NamedTuple): + value: Any + error: ValidationError | None + + +def _given_payload_model(name: str) -> Any: + """Given the SDK models the "" platform payload""" + model = getattr(sdk, name, None) + assert model is not None, f"Expected xtm_oaev_sdk.{name} to exist on public surface" + return model + + +def _given_platform_inject_message() -> dict[str, Any]: + """Given an inject message as the platform publishes it to an injector queue""" + return { + "injection": { + "inject_id": "8a4f1f0e-2c4b-4f43-9d5e-0b6f5b6f1a01", + "inject_title": "Scan the DMZ", + "inject_content": { + "target_selector": "assets", + "expectations": [ + { + "expectation_type": "DETECTION", + "expectation_name": "Detection", + "expectation_score": 100.0, + "expectation_expectation_group": False, + "expectation_expiration_time": 21600, + } + ], + }, + "inject_injector_contract": { + "injector_contract_id": "5c8b6c3e-tcp-connect", + "injector_contract_content": '{"contract_id": "5c8b6c3e-tcp-connect"}', + "convertedContent": {"contract_id": "5c8b6c3e-tcp-connect"}, + "injector_contract_labels": {"en": "TCP connect scan"}, + }, + "inject_documents": [], + "inject_status": None, + }, + "assets": [ + { + "asset_id": "0d3f7d1a-web-01", + "asset_hostname": "web-01", + "asset_ips": ["10.0.0.5"], + "asset_seen_ip": "10.0.0.5", + "asset_agents": [{"agent_id": "c1b2-agent", "agent_active": True}], + } + ], + "assetGroups": [{"asset_group_id": "f00d-dmz", "asset_group_name": "DMZ"}], + "attachments": None, + } + + +def _given_execution_callback(**overrides: Any) -> dict[str, Any]: + """Given an execution callback as an injector sends it""" + payload: dict[str, Any] = { + "execution_message": "Scan completed", + "execution_output_structured": '{"scan_results": [{"host": "10.0.0.5"}]}', + "execution_output_raw": "PORT STATE SERVICE\n22/tcp open ssh", + "execution_status": "SUCCESS", + "execution_duration": 3, + "execution_action": "complete", + "execution_context_identifiers": ["0d3f7d1a-web-01"], + } + payload.update(overrides) + return payload + + +def _given_pending_expectation(**overrides: Any) -> dict[str, Any]: + """Given a pending expectation as the platform serves it to a collector""" + payload: dict[str, Any] = { + "inject_expectation_id": "4e5d-expectation", + "inject_expectation_type": "DETECTION", + "inject_expectation_name": "Detection", + "inject_expectation_description": None, + "inject_expectation_score": None, + "inject_expectation_expected_score": 100.0, + "inject_expiration_time": 21600, + "inject_expectation_group": False, + "inject_expectation_order": None, + "inject_expectation_status": "PENDING", + "inject_expectation_created_at": "2026-11-05T20:00:00Z", + "inject_expectation_updated_at": "2026-11-05T20:00:00Z", + "inject_expectation_signatures": [ + {"type": "parent_process_name", "value": "oaev-implant-8a4f"} + ], + "inject_expectation_results": [ + { + "inject_expectation_id": "9b9b-result", + "sourceId": "c0ffee-collector", + "sourceType": "collector", + "sourceName": "Splunk ES", + "sourceAssetId": None, + "sourcePlatform": "SIEM", + "date": "2026-11-05T20:01:00Z", + "score": 0.0, + "result": "Not Detected", + "metadata": {}, + "inject_expectation_result_created_at": "2026-11-05T20:01:00Z", + "inject_expectation_result_updated_at": "2026-11-05T20:01:00Z", + } + ], + "inject_expectation_traces": [], + "inject_expectation_exercise": None, + "inject_expectation_inject": "8a4f1f0e-2c4b-4f43-9d5e-0b6f5b6f1a01", + "inject_expectation_user": None, + "inject_expectation_team": None, + "inject_expectation_agent": "c1b2-agent", + "inject_expectation_asset": "0d3f7d1a-web-01", + "inject_expectation_asset_group": None, + "inject_expectation_article": None, + "inject_expectation_challenge": None, + "target_id": "c1b2-agent", + "inject_expectation_expected_security_platforms": ["SIEM"], + "inject_expectation_collector_missing_at_init": False, + } + payload.update(overrides) + return payload + + +def _given_collector_update(**overrides: Any) -> dict[str, Any]: + """Given an expectation update as a collector sends it""" + payload: dict[str, Any] = { + "collector_id": "c0ffee-collector", + "result": "Detected", + "is_success": True, + "metadata": {"alertId": "a-42"}, + } + payload.update(overrides) + return payload + + +def _given_expectation_trace(**overrides: Any) -> dict[str, Any]: + """Given an expectation trace as a collector sends it""" + payload: dict[str, Any] = { + "inject_expectation_trace_expectation": "4e5d-expectation", + "inject_expectation_trace_source_id": "c0ffee-collector", + "inject_expectation_trace_alert_name": "Suspicious port scan", + "inject_expectation_trace_alert_link": "https://siem.example/alerts/a-42", + "inject_expectation_trace_date": "2026-11-05T20:01:00Z", + "inject_expectation_trace_match_type": "marker", + } + payload.update(overrides) + return payload + + +def _given_without(payload: dict[str, Any], field: str) -> dict[str, Any]: + """Given that payload without its "" field""" + return {key: value for key, value in payload.items() if key != field} + + +def _when_reading(model: Any, payload: Any) -> Reading: + """When the payload is read with that model""" + try: + return Reading(model.model_validate(payload), None) + except ValidationError as error: + return Reading(None, error) + + +def _when_writing(reading: Reading) -> dict[str, Any]: + """When the payload read is written back as JSON""" + return reading.value.model_dump(mode="json", exclude_unset=True) + + +def _when_writing_with_defaults(reading: Reading) -> dict[str, Any]: + """When the payload read is written back as JSON""" + return reading.value.model_dump(mode="json") + + +def _then_payload_is_read(reading: Reading) -> None: + """Then the payload is read""" + assert reading.error is None, f"Expected the payload to be read: {reading.error}" + + +def _then_payload_is_refused(reading: Reading, field: str) -> None: + """Then the payload is refused because of its "" field""" + assert reading.error is not None, "Expected the payload to be refused" + failing = {str(part) for error in reading.error.errors() for part in error["loc"]} + assert field in failing, f"Expected {field} to fail, got {failing}" + + +def _then_written_payload_is(written: dict[str, Any], payload: dict[str, Any]) -> None: + """Then the written payload is exactly the payload read""" + assert written == payload + + +def _then_written_field_is(written: dict[str, Any], field: str, value: Any) -> None: + """Then the written "" is """ + assert written[field] == value + + +def _then_expectation_has_no_signature(reading: Reading) -> None: + """Then the expectation has no signature""" + assert reading.value.inject_expectation_signatures == [] + + +def _then_contract_version_is(version: str, expected: str) -> None: + """Then the contract version is "" """ + assert version == expected + + +def test_inject_message_is_kept_as_the_platform_publishes_it() -> None: + """It reads an inject message and writes it back unchanged, unmodelled keys included. + + Scenario: An inject message is kept as the platform publishes it + Given the SDK models the "ExecutableInject" platform payload + And an inject message as the platform publishes it to an injector queue + When the payload is read with that model + And the payload read is written back as JSON + Then the payload is read + And the written payload is exactly the payload read + """ + model = _given_payload_model("ExecutableInject") + payload = _given_platform_inject_message() + reading = _when_reading(model, payload) + written = _when_writing(reading) + _then_payload_is_read(reading) + _then_written_payload_is(written, payload) + + +def test_inject_message_without_its_injection_is_refused() -> None: + """It refuses an inject message that carries no injection. + + Scenario: An inject message without its injection is refused + Given the SDK models the "ExecutableInject" platform payload + And an inject message as the platform publishes it to an injector queue + And that payload without its "injection" field + When the payload is read with that model + Then the payload is refused because of its "injection" field + """ + model = _given_payload_model("ExecutableInject") + payload = _given_without(_given_platform_inject_message(), "injection") + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, "injection") + + +def test_execution_reception_counts_no_tracking_by_default() -> None: + """It sends a tracking count of 0 when an injector gives none, as the platform reads it. + + Scenario: An execution reception counts no tracking by default + Given the SDK models the "InjectReceptionInput" platform payload + When the payload is read with that model + And the payload read is written back as JSON + Then the written "tracking_total_count" is 0 + """ + model = _given_payload_model("InjectReceptionInput") + reading = _when_reading(model, {}) + written = _when_writing_with_defaults(reading) + _then_written_field_is(written, "tracking_total_count", 0) + + +def test_execution_callback_is_kept_as_the_platform_takes_it() -> None: + """It keeps every field of an execution callback, structured output as text. + + Scenario: An execution callback is kept as the platform takes it + Given the SDK models the "InjectExecutionInput" platform payload + And an execution callback as an injector sends it + When the payload is read with that model + And the payload read is written back as JSON + Then the payload is read + And the written payload is exactly the payload read + """ + model = _given_payload_model("InjectExecutionInput") + payload = _given_execution_callback() + reading = _when_reading(model, payload) + written = _when_writing(reading) + _then_payload_is_read(reading) + _then_written_payload_is(written, payload) + + +@pytest.mark.parametrize( + "status", ["SUCCESS", "success", "EXECUTED", "ERROR", "ASSET_CLEARANCE_RESTRICTED"] +) +def test_execution_callback_accepts_the_statuses_the_platform_takes( + status: str, +) -> None: + """It accepts every status name the platform knows, and SUCCESS in any case. + + Scenario Outline: An execution callback accepts the statuses the platform takes + Given the SDK models the "InjectExecutionInput" platform payload + And an execution callback as an injector sends it, with status "" + When the payload is read with that model + Then the payload is read + + Examples: + | status | + | SUCCESS | + | success | + | EXECUTED | + | ERROR | + | ASSET_CLEARANCE_RESTRICTED | + """ + model = _given_payload_model("InjectExecutionInput") + payload = _given_execution_callback(execution_status=status) + reading = _when_reading(model, payload) + _then_payload_is_read(reading) + + +@pytest.mark.parametrize("status", ["DONE", "executed"]) +def test_execution_callback_refuses_a_status_the_platform_does_not_know( + status: str, +) -> None: + """It refuses a status the platform would reject. + + Scenario Outline: An execution callback refuses a status the platform does not know + Given the SDK models the "InjectExecutionInput" platform payload + And an execution callback as an injector sends it, with status "" + When the payload is read with that model + Then the payload is refused because of its "execution_status" field + + Examples: + | status | + | DONE | + | executed | + """ + model = _given_payload_model("InjectExecutionInput") + payload = _given_execution_callback(execution_status=status) + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, "execution_status") + + +@pytest.mark.parametrize("field", ["execution_action", "execution_message"]) +def test_execution_callback_requires_what_the_platform_needs(field: str) -> None: + """It refuses an execution callback without an action or a message. + + Scenario Outline: An execution callback requires what the platform needs + Given the SDK models the "InjectExecutionInput" platform payload + And an execution callback as an injector sends it + And that payload without its "" field + When the payload is read with that model + Then the payload is refused because of its "" field + + Examples: + | field | + | execution_action | + | execution_message | + """ + model = _given_payload_model("InjectExecutionInput") + payload = _given_without(_given_execution_callback(), field) + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, field) + + +def test_pending_expectation_is_kept_as_the_platform_serves_it() -> None: + """It reads a pending expectation and writes it back unchanged, results included. + + Scenario: A pending expectation is kept as the platform serves it + Given the SDK models the "InjectExpectationOutput" platform payload + And a pending expectation as the platform serves it to a collector + When the payload is read with that model + And the payload read is written back as JSON + Then the payload is read + And the written payload is exactly the payload read + """ + model = _given_payload_model("InjectExpectationOutput") + payload = _given_pending_expectation() + reading = _when_reading(model, payload) + written = _when_writing(reading) + _then_payload_is_read(reading) + _then_written_payload_is(written, payload) + + +def test_pending_expectation_of_an_unknown_type_is_refused() -> None: + """It refuses an expectation type the platform does not have. + + Scenario: A pending expectation of an unknown type is refused + Given the SDK models the "InjectExpectationOutput" platform payload + And a pending expectation as the platform serves it, with type "TELEMETRY" + When the payload is read with that model + Then the payload is refused because of its "inject_expectation_type" field + """ + model = _given_payload_model("InjectExpectationOutput") + payload = _given_pending_expectation(inject_expectation_type="TELEMETRY") + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, "inject_expectation_type") + + +def test_collector_update_is_kept_as_the_platform_takes_it() -> None: + """It keeps every field of an expectation update. + + Scenario: A collector update is kept as the platform takes it + Given the SDK models the "InjectExpectationUpdateFromCollectorInput" platform payload + And an expectation update as a collector sends it + When the payload is read with that model + And the payload read is written back as JSON + Then the payload is read + And the written payload is exactly the payload read + """ + model = _given_payload_model("InjectExpectationUpdateFromCollectorInput") + payload = _given_collector_update() + reading = _when_reading(model, payload) + written = _when_writing(reading) + _then_payload_is_read(reading) + _then_written_payload_is(written, payload) + + +@pytest.mark.parametrize("field", ["collector_id", "is_success"]) +def test_collector_update_requires_what_the_platform_needs(field: str) -> None: + """It refuses an expectation update without its collector or its outcome. + + Scenario Outline: A collector update requires what the platform needs + Given the SDK models the "InjectExpectationUpdateFromCollectorInput" platform payload + And an expectation update as a collector sends it + And that payload without its "" field + When the payload is read with that model + Then the payload is refused because of its "" field + + Examples: + | field | + | collector_id | + | is_success | + """ + model = _given_payload_model("InjectExpectationUpdateFromCollectorInput") + payload = _given_without(_given_collector_update(), field) + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, field) + + +def test_bulk_update_maps_expectation_ids_to_their_update() -> None: + """It keeps a bulk update as expectation ids mapped to their update. + + Scenario: A bulk update maps expectation ids to their update + Given the SDK models the "InjectExpectationBulkUpdateInput" platform payload + And an expectation update as a collector sends it + When the payload is read with that model, under "inputs" for "4e5d-expectation" + And the payload read is written back as JSON + Then the payload is read + And the written payload is exactly the payload read + """ + model = _given_payload_model("InjectExpectationBulkUpdateInput") + payload = {"inputs": {"4e5d-expectation": _given_collector_update()}} + reading = _when_reading(model, payload) + written = _when_writing(reading) + _then_payload_is_read(reading) + _then_written_payload_is(written, payload) + + +def test_expectation_trace_is_kept_as_the_platform_takes_it() -> None: + """It keeps every field of an expectation trace. + + Scenario: An expectation trace is kept as the platform takes it + Given the SDK models the "InjectExpectationTraceInput" platform payload + And an expectation trace as a collector sends it + When the payload is read with that model + And the payload read is written back as JSON + Then the payload is read + And the written payload is exactly the payload read + """ + model = _given_payload_model("InjectExpectationTraceInput") + payload = _given_expectation_trace() + reading = _when_reading(model, payload) + written = _when_writing(reading) + _then_payload_is_read(reading) + _then_written_payload_is(written, payload) + + +@pytest.mark.parametrize( + "field", + [ + "inject_expectation_trace_expectation", + "inject_expectation_trace_source_id", + "inject_expectation_trace_alert_name", + "inject_expectation_trace_alert_link", + "inject_expectation_trace_date", + ], +) +def test_expectation_trace_requires_what_the_platform_needs(field: str) -> None: + """It refuses an expectation trace missing one of its mandatory fields. + + Scenario Outline: An expectation trace requires what the platform needs + Given the SDK models the "InjectExpectationTraceInput" platform payload + And an expectation trace as a collector sends it + And that payload without its "" field + When the payload is read with that model + Then the payload is refused because of its "" field + + Examples: + | field | + | inject_expectation_trace_expectation | + | inject_expectation_trace_source_id | + | inject_expectation_trace_alert_name | + | inject_expectation_trace_alert_link | + | inject_expectation_trace_date | + """ + model = _given_payload_model("InjectExpectationTraceInput") + payload = _given_without(_given_expectation_trace(), field) + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, field) + + +def test_trace_bulk_insert_lists_the_traces() -> None: + """It keeps a bulk trace insert as the list of its traces. + + Scenario: A trace bulk insert lists the traces + Given the SDK models the "InjectExpectationTraceBulkInsertInput" platform payload + And an expectation trace as a collector sends it + When the payload is read with that model, under "expectation_traces" + And the payload read is written back as JSON + Then the payload is read + And the written payload is exactly the payload read + """ + model = _given_payload_model("InjectExpectationTraceBulkInsertInput") + payload = {"expectation_traces": [_given_expectation_trace()]} + reading = _when_reading(model, payload) + written = _when_writing(reading) + _then_payload_is_read(reading) + _then_written_payload_is(written, payload) + + +# ---- Constraints identified ---- + + +def test_execution_callback_refuses_a_field_the_platform_does_not_take() -> None: + """It refuses a field the platform does not take, so nothing invented is sent. + + Scenario: An execution callback refuses a field the platform does not take + Given the SDK models the "InjectExecutionInput" platform payload + And an execution callback as an injector sends it, with "execution_kind" set + When the payload is read with that model + Then the payload is refused because of its "execution_kind" field + """ + model = _given_payload_model("InjectExecutionInput") + payload = _given_execution_callback(execution_kind="complete") + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, "execution_kind") + + +def test_execution_callback_refuses_more_than_1000_context_identifiers() -> None: + """It refuses more than 1000 context identifiers, as the platform does. + + Scenario: An execution callback refuses more than 1000 context identifiers + Given the SDK models the "InjectExecutionInput" platform payload + And an execution callback as an injector sends it, with 1001 context identifiers + When the payload is read with that model + Then the payload is refused because of its "execution_context_identifiers" field + """ + model = _given_payload_model("InjectExecutionInput") + identifiers = [f"target-{index}" for index in range(1001)] + payload = _given_execution_callback(execution_context_identifiers=identifiers) + reading = _when_reading(model, payload) + _then_payload_is_refused(reading, "execution_context_identifiers") + + +def test_pending_expectation_reads_null_signatures_as_none() -> None: + """It reads null signatures as an empty list, as earlier platforms send them. + + Scenario: A pending expectation reads null signatures as none + Given the SDK models the "InjectExpectationOutput" platform payload + And a pending expectation as the platform serves it, with null signatures + When the payload is read with that model + Then the payload is read + And the expectation has no signature + """ + model = _given_payload_model("InjectExpectationOutput") + payload = _given_pending_expectation(inject_expectation_signatures=None) + reading = _when_reading(model, payload) + _then_payload_is_read(reading) + _then_expectation_has_no_signature(reading) + + +def test_payload_contract_version_announces_the_platform_payloads() -> None: + """It announces the platform payloads with a minor contract version. + + Scenario: The payload contract version announces the platform payloads + Given the SDK models the "PORT_IO_CONTRACT_VERSION" platform payload + Then the contract version is "1.1.0" + """ + version = _given_payload_model("PORT_IO_CONTRACT_VERSION") + _then_contract_version_is(version, "1.1.0") From f0553894574e0481bd016172fd65dc60d1defe5a Mon Sep 17 00:00:00 2001 From: Christophe Melchior Date: Mon, 9 Nov 2026 23:35:08 +0100 Subject: [PATCH 02/17] :white_check_mark: test(sdk): CHK.1 mirror the platform payloads key for key, GREEN Tests --- libs/xtm-oaev-sdk/CHANGELOG.md | 22 ++ .../test/seam/fixtures/seam_golden.json | 66 +++- .../xtm_oaev_sdk/public/__init__.py | 30 ++ .../xtm_oaev_sdk/seam/port_io/__init__.py | 32 ++ .../xtm_oaev_sdk/seam/port_io/models.py | 3 +- .../xtm_oaev_sdk/seam/port_io/platform.py | 367 ++++++++++++++++++ 6 files changed, 516 insertions(+), 4 deletions(-) create mode 100644 libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/platform.py diff --git a/libs/xtm-oaev-sdk/CHANGELOG.md b/libs/xtm-oaev-sdk/CHANGELOG.md index abf7aa5d..f791c669 100644 --- a/libs/xtm-oaev-sdk/CHANGELOG.md +++ b/libs/xtm-oaev-sdk/CHANGELOG.md @@ -4,6 +4,28 @@ Every notable change to xtm-oaev-sdk lands here. Every seam change too, with the version of its seam ([seam-changes-are-versioned-contract-changes](docs/tdr/seam-changes-are-versioned-contract-changes.tdr.md)). +## [Unreleased] + +### Added + +- `port_io`: the platform's own payloads, key for key, so injectors and collectors + running without the platform read and write the same JSON. Injector side: + `ExecutableInject` (the queue message, with `ExecutableInjection`, + `ExecutableInjectorContract`, `EndpointTargetOutput`, `AgentOutput`, + `AssetGroupSimple`), `InjectReceptionInput` and `InjectExecutionInput`. Collector + side: `InjectExpectationOutput` (with `InjectExpectationSignature`, + `InjectExpectationResult`), `InjectExpectationUpdateFromCollectorInput`, + `InjectExpectationBulkUpdateInput`, `InjectExpectationTraceInput` and + `InjectExpectationTraceBulkInsertInput`. Each model is written by hand from the + platform DTO it mirrors, names that DTO in its docstring, and ships with a sample + payload. Dates are kept as the platform wrote them, ISO text or epoch numbers. + `PORT_IO_CONTRACT_VERSION` `1.1.0`. + +### Changed + +- `port_io`: `ExecutionStatus` gains `ASSET_CLEARANCE_RESTRICTED`, a status the + platform accepts. `PORT_IO_CONTRACT_VERSION` `1.1.0`. + ## [0.1.0] - Unreleased First version. The shared, client-free code of `pyoaev` 3.261014.1 moves out and into diff --git a/libs/xtm-oaev-sdk/test/seam/fixtures/seam_golden.json b/libs/xtm-oaev-sdk/test/seam/fixtures/seam_golden.json index 8ff3ea3e..2b798fd1 100644 --- a/libs/xtm-oaev-sdk/test/seam/fixtures/seam_golden.json +++ b/libs/xtm-oaev-sdk/test/seam/fixtures/seam_golden.json @@ -337,11 +337,11 @@ }, "xtm_oaev_sdk.seam.port_io.models.ExecutionDetails": { "kind": "pydantic model", - "sha256": "4d9546d2033c3d68bc31a688481bc580fb876fa1f984495bd8d1ac4bb8c6ce15" + "sha256": "25624ca9f13cf3c6f63e696387392b9c7dd075de5c536f0d2e8a7a09035850a8" }, "xtm_oaev_sdk.seam.port_io.models.ExecutionStatus": { "kind": "class", - "sha256": "1ac92fe06592d1ef55703df64941baf70b75c646d138e4f7698abe02bba50af0" + "sha256": "995f92f6347f41e6283f67db054c43bc5af96840d22654c970a508a21ced7cba" }, "xtm_oaev_sdk.seam.port_io.models.ExpectationSignatureGroup": { "kind": "pydantic model", @@ -353,7 +353,7 @@ }, "xtm_oaev_sdk.seam.port_io.models.PORT_IO_CONTRACT_VERSION": { "kind": "assignment", - "sha256": "4b3aa3a5b079ff1222ce2bb723750e882555bc2c857097f589066dcae2398d0a" + "sha256": "bc502ccda84bd144f61cedbf436da83a9dec614d11e6793c73254ba0ddb16b45" }, "xtm_oaev_sdk.seam.port_io.models.SignatureCallbackPayload": { "kind": "pydantic model", @@ -383,6 +383,66 @@ "kind": "pydantic model", "sha256": "59c1618a317ff3f4390d3c0531e815168dce910204987062c9e044c6466b908d" }, + "xtm_oaev_sdk.seam.port_io.platform.AgentOutput": { + "kind": "pydantic model", + "sha256": "e5a03a29edde2e3fcf79720ca9a1d36b1286c186cc397c9c2421a74293a48542" + }, + "xtm_oaev_sdk.seam.port_io.platform.AssetGroupSimple": { + "kind": "pydantic model", + "sha256": "7bba28225fb8e3ef21c4ede2653104378710099425a52b176d1bad1733fe1d10" + }, + "xtm_oaev_sdk.seam.port_io.platform.EndpointTargetOutput": { + "kind": "pydantic model", + "sha256": "2732c6bf5381c60c04463d14c7af1c900bdd619875eb680955ebe5cf40195194" + }, + "xtm_oaev_sdk.seam.port_io.platform.ExecutableInject": { + "kind": "pydantic model", + "sha256": "66bbc429eceebc4a900841d2ae5073d6efd82dd936b6239f47df702abd9ea6b6" + }, + "xtm_oaev_sdk.seam.port_io.platform.ExecutableInjection": { + "kind": "pydantic model", + "sha256": "eb5ff654af2703fad27e76d02b92f7ab771f6d148536b75faec98959b6f24f27" + }, + "xtm_oaev_sdk.seam.port_io.platform.ExecutableInjectorContract": { + "kind": "pydantic model", + "sha256": "3c9f3f953e5d24117115c0cfb451c0e3ad07f382482de238b45f5e6a0010b795" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExecutionInput": { + "kind": "pydantic model", + "sha256": "edb50a4d3b023fc93316be07b4dc74bcf15e90b05e3e61d4f79e4d1d4ddaf45c" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExpectationBulkUpdateInput": { + "kind": "pydantic model", + "sha256": "fc2f108d8f5ca66f5bc891884096930289309827b0dead17e913e10364e8bf30" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExpectationOutput": { + "kind": "pydantic model", + "sha256": "80f48cd4fb3975078e4b3b07e31e9957d4671b0c07c9b34cc77e7373facde503" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExpectationResult": { + "kind": "pydantic model", + "sha256": "4d751cc56164aa36e8dab73e6dbcced7a3642ab326d5cf08ea60e0b1ed558ad1" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExpectationSignature": { + "kind": "pydantic model", + "sha256": "35a0407e78a7386e90024f87d947aba14968f43203d07121c701a6fd0aad6215" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExpectationTraceBulkInsertInput": { + "kind": "pydantic model", + "sha256": "8f815936b5d93bdfb21d0d170a250a5a8fbce9c6c2a9965ebd0bff9b6b38b757" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExpectationTraceInput": { + "kind": "pydantic model", + "sha256": "9c85d1469b81a5a68cca849f8d32280f9e89c0ed3e34eb05d3e61765b818b190" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectExpectationUpdateFromCollectorInput": { + "kind": "pydantic model", + "sha256": "a62e51dc9da19bc9659a7ba52901187ca3b3d0f18e26d0a730e1ed47370fe505" + }, + "xtm_oaev_sdk.seam.port_io.platform.InjectReceptionInput": { + "kind": "pydantic model", + "sha256": "92a669071470c38f9dd1a16b1e9f27b1cb3e21eb77a08700a7c18d18519f58be" + }, "xtm_oaev_sdk.seam.signatures.models.ExtraSignatureData": { "kind": "pydantic model", "sha256": "b69dd6b7476302eff126622e5d662fc297ca964c0484e6f948589cd1450ae4c5" diff --git a/libs/xtm-oaev-sdk/xtm_oaev_sdk/public/__init__.py b/libs/xtm-oaev-sdk/xtm_oaev_sdk/public/__init__.py index 416842aa..4e70c111 100644 --- a/libs/xtm-oaev-sdk/xtm_oaev_sdk/public/__init__.py +++ b/libs/xtm-oaev-sdk/xtm_oaev_sdk/public/__init__.py @@ -127,10 +127,25 @@ # --- Port I/O contract (versioned wire schema) --- from xtm_oaev_sdk.seam.port_io import ( PORT_IO_CONTRACT_VERSION, + AgentOutput, + AssetGroupSimple, + EndpointTargetOutput, + ExecutableInject, + ExecutableInjection, + ExecutableInjectorContract, ExecutionDetails, ExecutionStatus, ExpectationSignatureGroup, InjectExecutionActions, + InjectExecutionInput, + InjectExpectationBulkUpdateInput, + InjectExpectationOutput, + InjectExpectationResult, + InjectExpectationSignature, + InjectExpectationTraceBulkInsertInput, + InjectExpectationTraceInput, + InjectExpectationUpdateFromCollectorInput, + InjectReceptionInput, SignatureCallbackPayload, SignatureExpectationType, SignatureOutputStructure, @@ -266,5 +281,20 @@ "build_network_configs", # Seam / compatibility "PORT_IO_CONTRACT_VERSION", + "AgentOutput", + "AssetGroupSimple", + "EndpointTargetOutput", + "ExecutableInject", + "ExecutableInjection", + "ExecutableInjectorContract", + "InjectExecutionInput", + "InjectExpectationBulkUpdateInput", + "InjectExpectationOutput", + "InjectExpectationResult", + "InjectExpectationSignature", + "InjectExpectationTraceBulkInsertInput", + "InjectExpectationTraceInput", + "InjectExpectationUpdateFromCollectorInput", + "InjectReceptionInput", "make_deprecated_getattr", ] diff --git a/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/__init__.py b/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/__init__.py index 7bbfdb9b..d8a22c8a 100644 --- a/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/__init__.py +++ b/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/__init__.py @@ -33,6 +33,23 @@ SignatureValue, TargetSignatures, ) +from xtm_oaev_sdk.seam.port_io.platform import ( + AgentOutput, + AssetGroupSimple, + EndpointTargetOutput, + ExecutableInject, + ExecutableInjection, + ExecutableInjectorContract, + InjectExecutionInput, + InjectExpectationBulkUpdateInput, + InjectExpectationOutput, + InjectExpectationResult, + InjectExpectationSignature, + InjectExpectationTraceBulkInsertInput, + InjectExpectationTraceInput, + InjectExpectationUpdateFromCollectorInput, + InjectReceptionInput, +) __all__ = [ "PORT_IO_CONTRACT_VERSION", @@ -47,4 +64,19 @@ "SignatureValue", "SignatureExpectationType", "TargetSignatures", + "AgentOutput", + "AssetGroupSimple", + "EndpointTargetOutput", + "ExecutableInject", + "ExecutableInjection", + "ExecutableInjectorContract", + "InjectExecutionInput", + "InjectExpectationBulkUpdateInput", + "InjectExpectationOutput", + "InjectExpectationResult", + "InjectExpectationSignature", + "InjectExpectationTraceBulkInsertInput", + "InjectExpectationTraceInput", + "InjectExpectationUpdateFromCollectorInput", + "InjectReceptionInput", ] diff --git a/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/models.py b/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/models.py index 2bf0b685..5f9fa0a9 100644 --- a/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/models.py +++ b/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/models.py @@ -47,7 +47,7 @@ from xtm_oaev_sdk.seam.signatures.seam import ToolOutput #: Version of the port I/O wire schema. Bump on any breaking contract change. -PORT_IO_CONTRACT_VERSION = "1.0.0" +PORT_IO_CONTRACT_VERSION = "1.1.0" # --- Wire vocabulary ----------------------------------------------------------- # The three enums that appear in the JSON contract below. They live here, in @@ -83,6 +83,7 @@ class ExecutionStatus(str, Enum): TIMEOUT = "TIMEOUT" INTERRUPTED = "INTERRUPTED" ASSET_AGENTLESS = "ASSET_AGENTLESS" + ASSET_CLEARANCE_RESTRICTED = "ASSET_CLEARANCE_RESTRICTED" AGENT_INACTIVE = "AGENT_INACTIVE" AGENT_OVERLOADED = "AGENT_OVERLOADED" INFO = "INFO" diff --git a/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/platform.py b/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/platform.py new file mode 100644 index 00000000..03d0f72e --- /dev/null +++ b/libs/xtm-oaev-sdk/xtm_oaev_sdk/seam/port_io/platform.py @@ -0,0 +1,367 @@ +"""The platform's own payloads, exchanged with injectors and collectors. + +Each model mirrors one payload of the OpenAEV platform, key for key, so an injector or a +collector running without the platform reads and writes exactly the JSON the platform +would. Each model is written by hand from the platform DTO it mirrors, and its docstring +names that DTO's source file in the platform repository: + +- ``ExecutableInject``: the inject message the platform publishes to an injector + queue (``ExecutableInjectDTO``), with its ``injection``, ``assets`` and + ``assetGroups``; +- ``InjectReceptionInput`` and ``InjectExecutionInput``: what an injector posts to + ``/api/injects/execution/reception/{id}`` and ``/api/injects/execution/callback/{id}``; +- ``InjectExpectationOutput``: one pending expectation, as the platform serves it to a + collector (``/api/injects/expectations/...``); +- ``InjectExpectationUpdateFromCollectorInput`` and ``InjectExpectationBulkUpdateInput``: + a collector's answer (``PUT /api/injects/expectations/{id}`` and ``.../bulk``); +- ``InjectExpectationTraceInput`` and ``InjectExpectationTraceBulkInsertInput``: the + traces a collector attaches (``POST /api/inject-expectations-traces/bulk``). + +What the platform sends keeps the keys this module does not model (``extra="allow"``), +so nothing is lost when a payload is read and written back. What a connector sends +refuses any key the platform does not take (``extra="forbid"``). Dates stay as the +platform wrote them, ISO text or epoch numbers: they are not parsed. +""" + +from typing import Literal + +from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator +from xtm_oaev_sdk.seam.port_io.models import ExecutionStatus, InjectExecutionActions + +__all__ = [ + "AgentOutput", + "AssetGroupSimple", + "EndpointTargetOutput", + "ExecutableInject", + "ExecutableInjection", + "ExecutableInjectorContract", + "InjectExecutionInput", + "InjectExpectationBulkUpdateInput", + "InjectExpectationOutput", + "InjectExpectationResult", + "InjectExpectationSignature", + "InjectExpectationTraceBulkInsertInput", + "InjectExpectationTraceInput", + "InjectExpectationUpdateFromCollectorInput", + "InjectReceptionInput", +] + +_FROM_PLATFORM = ConfigDict(extra="allow") +_TO_PLATFORM = ConfigDict(extra="forbid") + + +def _not_blank(value: str) -> str: + if not value.strip(): + raise ValueError("must not be blank") + return value + + +# --- Inject message (platform -> injector) --------------------------------------- + + +class AgentOutput(BaseModel): + """An agent of an asset target. + + Mirrors ``openaev-api/src/main/java/io/openaev/rest/asset/endpoint/form/AgentOutput.java``. + """ + + model_config = _FROM_PLATFORM + + agent_id: str + agent_privilege: str | None = None + agent_deployment_mode: str | None = None + agent_executed_by_user: str | None = None + agent_executor: JsonValue = None + agent_active: bool | None = None + agent_last_seen: JsonValue = None + agent_version: str | None = None + + +class EndpointTargetOutput(BaseModel): + """An asset target of an inject. + + Mirrors + ``openaev-api/src/main/java/io/openaev/rest/asset/endpoint/output/EndpointTargetOutput.java``. + """ + + model_config = _FROM_PLATFORM + + asset_id: str + asset_hostname: str | None = None + asset_ips: list[str] = Field(default_factory=list) + asset_seen_ip: str | None = None + asset_agents: list[AgentOutput] = Field(default_factory=list) + + +class AssetGroupSimple(BaseModel): + """An asset group target of an inject. + + Mirrors ``openaev-api/src/main/java/io/openaev/rest/asset_group/form/AssetGroupSimple.java``. + """ + + model_config = _FROM_PLATFORM + + asset_group_id: str + asset_group_name: str | None = None + + +class ExecutableInjectorContract(BaseModel): + """The injector contract of an inject (``inject_injector_contract``). The contract + id is ``injector_contract_id``, and ``convertedContent`` (the parsed + ``injector_contract_content``) holds it again as ``contract_id``. + + Mirrors ``openaev-model/src/main/java/io/openaev/database/model/InjectorContract.java``. + """ + + model_config = _FROM_PLATFORM + + injector_contract_id: str + injector_contract_content: str | None = None + convertedContent: dict[str, JsonValue] | None = None + + +class ExecutableInjection(BaseModel): + """The inject itself (``injection``), as the platform serializes it. + + Mirrors ``openaev-model/src/main/java/io/openaev/database/model/Injection.java``. + """ + + model_config = _FROM_PLATFORM + + inject_id: str + inject_title: str | None = None + inject_content: dict[str, JsonValue] | None = None + inject_injector_contract: ExecutableInjectorContract | None = None + inject_documents: list[JsonValue] = Field(default_factory=list) + + +class ExecutableInject(BaseModel): + """The inject message published to an injector queue. + + Mirrors ``openaev-api/src/main/java/io/openaev/execution/ExecutableInjectDTO.java``. + """ + + model_config = _FROM_PLATFORM + + injection: ExecutableInjection + assets: list[EndpointTargetOutput] = Field(default_factory=list) + assetGroups: list[AssetGroupSimple] = Field(default_factory=list) + attachments: dict[str, JsonValue] | None = None + + +# --- Execution calls (injector -> platform) ---------------------------------------- + + +class InjectReceptionInput(BaseModel): + """Body of ``POST /api/injects/execution/reception/{inject_id}``. + + Mirrors ``openaev-api/src/main/java/io/openaev/rest/inject/form/InjectReceptionInput.java``. + """ + + model_config = _TO_PLATFORM + + tracking_total_count: int = 0 + + +class InjectExecutionInput(BaseModel): + """Body of ``POST /api/injects/execution/callback/{inject_id}``. + + ``execution_status`` is a platform status name, or ``SUCCESS`` in any case (the + platform reads it as ``EXECUTED``). ``execution_output_structured`` is JSON text. + + Mirrors ``openaev-api/src/main/java/io/openaev/rest/inject/form/InjectExecutionInput.java``. + """ + + model_config = _TO_PLATFORM + + execution_message: str + execution_output_structured: str | None = None + execution_output_raw: str | None = None + execution_status: str + execution_duration: int = 0 + execution_action: InjectExecutionActions + execution_context_identifiers: list[str] | None = Field( + default=None, max_length=1000 + ) + + @field_validator("execution_message", mode="after") + @classmethod + def is_not_blank(cls, value: str) -> str: + return _not_blank(value) + + @field_validator("execution_status", mode="after") + @classmethod + def is_platform_status(cls, value: str) -> str: + if value.upper() != "SUCCESS": + ExecutionStatus(value) + return value + + +# --- Pending expectations (platform -> collector) -------------------------------- + + +class InjectExpectationSignature(BaseModel): + """One signature of a pending expectation. + + Mirrors + ``openaev-model/src/main/java/io/openaev/database/model/InjectExpectationSignature.java``. + """ + + model_config = _FROM_PLATFORM + + type: str + value: str + + +class InjectExpectationResult(BaseModel): + """One result of a pending expectation (``InjectExpectationResult``). Its own id + is ``inject_expectation_id``, and its source keys are camelCase. + + Mirrors + ``openaev-model/src/main/java/io/openaev/database/model/InjectExpectationResult.java``. + """ + + model_config = _FROM_PLATFORM + + inject_expectation_id: str | None = None + sourceId: str | None = None + sourceType: str | None = None + sourceName: str | None = None + sourceAssetId: str | None = None + sourcePlatform: str | None = None + date: JsonValue = None + score: float | None = None + result: str | None = None + metadata: dict[str, str] | None = None + inject_expectation_result_created_at: JsonValue = None + inject_expectation_result_updated_at: JsonValue = None + + +class InjectExpectationOutput(BaseModel): + """One pending expectation, as the platform serves it to a collector. + ``inject_expiration_time`` is in seconds. + + Mirrors + ``openaev-api/src/main/java/io/openaev/api/expectations/dto/InjectExpectationOutput.java``. + """ + + model_config = _FROM_PLATFORM + + inject_expectation_id: str + inject_expectation_type: Literal[ + "ARTICLE", + "CHALLENGE", + "MANUAL", + "PREVENTION", + "DETECTION", + "LOGGING", + "VULNERABILITY", + ] + inject_expectation_name: str | None = None + inject_expectation_description: str | None = None + inject_expectation_score: float | None = None + inject_expectation_expected_score: float | None = None + inject_expiration_time: int | None = None + inject_expectation_group: bool | None = None + inject_expectation_order: int | None = None + inject_expectation_status: ( + Literal["FAILED", "PENDING", "PARTIAL", "UNKNOWN", "SUCCESS"] | None + ) = None + inject_expectation_created_at: JsonValue = None + inject_expectation_updated_at: JsonValue = None + inject_expectation_signatures: list[InjectExpectationSignature] = Field( + default_factory=list + ) + inject_expectation_results: list[InjectExpectationResult] = Field( + default_factory=list + ) + inject_expectation_traces: list[JsonValue] = Field(default_factory=list) + inject_expectation_exercise: str | None = None + inject_expectation_inject: str | None = None + inject_expectation_user: str | None = None + inject_expectation_team: str | None = None + inject_expectation_agent: str | None = None + inject_expectation_asset: str | None = None + inject_expectation_asset_group: str | None = None + inject_expectation_article: str | None = None + inject_expectation_challenge: str | None = None + target_id: str | None = None + inject_expectation_expected_security_platforms: list[str] | None = None + inject_expectation_collector_missing_at_init: bool | None = None + + @field_validator("inject_expectation_signatures", mode="before") + @classmethod + def null_is_none(cls, value: JsonValue) -> JsonValue: + # Earlier platforms serialize an expectation without signatures as null. + return [] if value is None else value + + +# --- Collector answers (collector -> platform) ------------------------------------- + + +class InjectExpectationUpdateFromCollectorInput(BaseModel): + """Body of ``PUT /api/injects/expectations/{expectation_id}``. The platform + ignores ``result``: it derives the label from ``is_success``. + + Mirrors ``openaev-api/src/main/java/io/openaev/rest/inject/form/InjectExpectationUpdateFromCollectorInput.java``. + """ + + model_config = _TO_PLATFORM + + collector_id: str + result: str | None = None + is_success: bool + metadata: dict[str, str] | None = None + + +class InjectExpectationBulkUpdateInput(BaseModel): + """Body of ``PUT /api/injects/expectations/bulk``: updates by expectation id. + + Mirrors + ``openaev-api/src/main/java/io/openaev/rest/inject/form/InjectExpectationBulkUpdateInput.java``. + """ + + model_config = _TO_PLATFORM + + inputs: dict[str, InjectExpectationUpdateFromCollectorInput] + + +class InjectExpectationTraceInput(BaseModel): + """One trace of ``POST /api/inject-expectations-traces/bulk``. + ``inject_expectation_trace_source_id`` is the collector id, and + ``inject_expectation_trace_match_type`` is ``marker``, ``source_ip`` or + ``target_ip`` when given. + + Mirrors ``openaev-api/src/main/java/io/openaev/rest/inject_expectation_trace/form/InjectExpectationTraceInput.java``. + """ + + model_config = _TO_PLATFORM + + inject_expectation_trace_expectation: str + inject_expectation_trace_source_id: str + inject_expectation_trace_alert_name: str + inject_expectation_trace_alert_link: str + inject_expectation_trace_date: str | int | float + inject_expectation_trace_match_type: str | None = None + + @field_validator( + "inject_expectation_trace_expectation", + "inject_expectation_trace_source_id", + "inject_expectation_trace_alert_name", + "inject_expectation_trace_alert_link", + mode="after", + ) + @classmethod + def is_not_blank(cls, value: str) -> str: + return _not_blank(value) + + +class InjectExpectationTraceBulkInsertInput(BaseModel): + """Body of ``POST /api/inject-expectations-traces/bulk``. + + Mirrors ``openaev-api/src/main/java/io/openaev/rest/inject_expectation_trace/form/InjectExpectationTraceBulkInsertInput.java``. + """ + + model_config = _TO_PLATFORM + + expectation_traces: list[InjectExpectationTraceInput] From 38a9a66f8b01fef4db29baa008cbf3011be1fe87 Mon Sep 17 00:00:00 2001 From: Christophe Melchior Date: Mon, 9 Nov 2026 23:38:59 +0100 Subject: [PATCH 03/17] :white_check_mark: test(sdk): CHK.2 read the common dev options without acting on foreign flags, RED Tests --- .../configuration/test_dev_configuration.py | 146 ++++++ .../test/daemons/test_dev_help.py | 222 +++++++++ .../test/daemons/test_dev_options.py | 436 ++++++++++++++++++ 3 files changed, 804 insertions(+) create mode 100644 libs/xtm-oaev-sdk/test/configuration/test_dev_configuration.py create mode 100644 libs/xtm-oaev-sdk/test/daemons/test_dev_help.py create mode 100644 libs/xtm-oaev-sdk/test/daemons/test_dev_options.py diff --git a/libs/xtm-oaev-sdk/test/configuration/test_dev_configuration.py b/libs/xtm-oaev-sdk/test/configuration/test_dev_configuration.py new file mode 100644 index 00000000..22413b7a --- /dev/null +++ b/libs/xtm-oaev-sdk/test/configuration/test_dev_configuration.py @@ -0,0 +1,146 @@ +"""Tests for loading a daemon configuration in dev mode. + +Feature: Configuration in dev mode + A daemon started with --dev never reaches the platform, so its configuration must + load without the platform URL and token. Whatever the configuration gives still wins; + without --dev, the platform URL and token stay required. +""" + +import sys +from pathlib import Path +from typing import Any, NamedTuple + +import pytest +import xtm_oaev_sdk as sdk +from pydantic import Field, ValidationError +from pydantic_settings import SettingsConfigDict + +PROGRAM = "openaev-shodan" +PLATFORM_ENV = ("OPENAEV_URL", "OPENAEV_TOKEN", "OPENAEV_TENANT_ID") + + +class Loading(NamedTuple): + settings: Any + error: ValidationError | None + + +class _ShodanSettings(sdk.SettingsLoader): + model_config = SettingsConfigDict(env_nested_delimiter="_", env_nested_max_split=1) + + openaev: sdk.ConfigLoaderOAEV = Field(default_factory=sdk.ConfigLoaderOAEV) + shodan_api_key: str = "dev-key" + + +def _given_no_platform_configuration( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """Given no configuration file nor environment variable names the platform""" + work = tmp_path / "injector" + work.mkdir() + monkeypatch.chdir(work) + for name in PLATFORM_ENV: + monkeypatch.delenv(name, raising=False) + + +def _given_platform_url_in_environment(monkeypatch: pytest.MonkeyPatch) -> None: + """Given the environment names the platform "https://openaev.example" """ + monkeypatch.setenv("OPENAEV_URL", "https://openaev.example") + monkeypatch.setenv("OPENAEV_TOKEN", "real-token") + + +def _given_process_command_line(monkeypatch: pytest.MonkeyPatch, *args: str) -> None: + """Given the process command line contains "" """ + monkeypatch.setattr(sys, "argv", [PROGRAM, *args]) + + +def _when_loading_settings() -> Loading: + """When the daemon loads its settings""" + try: + return Loading(_ShodanSettings(), None) + except ValidationError as error: + return Loading(None, error) + + +def _then_settings_load(loading: Loading) -> None: + """Then the settings load""" + assert loading.error is None, f"Expected the settings to load: {loading.error}" + + +def _then_settings_are_refused_for(loading: Loading, *fields: str) -> None: + """Then the settings are refused for missing """ + assert loading.error is not None, "Expected the settings to be refused" + failing = {str(error["loc"][-1]) for error in loading.error.errors()} + assert set(fields) <= failing, f"Expected {fields} to fail, got {failing}" + + +def _then_platform_is(loading: Loading, url: str, token: str) -> None: + """Then the platform is with the token """ + assert (str(loading.settings.openaev.url), loading.settings.openaev.token) == ( + url, + token, + ) + + +def _then_platform_is_a_placeholder_never_reached(loading: Loading) -> None: + """Then the platform URL is a placeholder that can never be reached""" + host = loading.settings.openaev.url.host + assert host.endswith(".invalid"), f"Expected an .invalid host, got {host}" + assert loading.settings.openaev.token + + +def test_configuration_loads_without_platform_keys_under_dev( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """It loads the settings without the platform URL and token under --dev. + + Scenario: The configuration loads without platform keys under --dev + Given no configuration file nor environment variable names the platform + And the process command line contains "--dev" + When the daemon loads its settings + Then the settings load + And the platform URL is a placeholder that can never be reached + """ + _given_no_platform_configuration(monkeypatch, tmp_path) + _given_process_command_line(monkeypatch, "--dev") + loading = _when_loading_settings() + _then_settings_load(loading) + _then_platform_is_a_placeholder_never_reached(loading) + + +def test_configured_platform_keys_still_win_under_dev( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """It keeps the platform URL and token the configuration gives, dev or not. + + Scenario: Configured platform keys still win under --dev + Given no configuration file nor environment variable names the platform + And the environment names the platform "https://openaev.example" + And the process command line contains "--dev" + When the daemon loads its settings + Then the platform is "https://openaev.example/" with the token "real-token" + """ + _given_no_platform_configuration(monkeypatch, tmp_path) + _given_platform_url_in_environment(monkeypatch) + _given_process_command_line(monkeypatch, "--dev") + loading = _when_loading_settings() + _then_platform_is(loading, "https://openaev.example/", "real-token") + + +# ---- Constraints identified ---- + + +def test_platform_keys_stay_required_without_dev( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path +) -> None: + """It still requires the platform URL and token without --dev. + + Scenario: Platform keys stay required without --dev + Given no configuration file nor environment variable names the platform + And the process command line contains "--once" + When the daemon loads its settings + Then the settings are refused for missing "url" and "token" + """ + _given_no_platform_configuration(monkeypatch, tmp_path) + _given_process_command_line(monkeypatch, "--once") + loading = _when_loading_settings() + _then_settings_are_refused_for(loading, "url", "token") diff --git a/libs/xtm-oaev-sdk/test/daemons/test_dev_help.py b/libs/xtm-oaev-sdk/test/daemons/test_dev_help.py new file mode 100644 index 00000000..7eb8ea5a --- /dev/null +++ b/libs/xtm-oaev-sdk/test/daemons/test_dev_help.py @@ -0,0 +1,222 @@ +"""Tests for the help of the dev options and the parser the role SDKs extend. + +Feature: Help on the dev options + "--dev --help" (or "--dev -h") asks for the dev options and what each one is for. + Without --dev, -h stays the daemon's own. The SDK only knows the options common to + every daemon: an injector or a collector SDK adds its own options to the dev parser, + and its help then lists the common options next to the role's. +""" + +import argparse +from typing import Any, Callable + +import pytest +import xtm_oaev_sdk as sdk + +COMMON_OPTIONS = ("--dev", "-h", "--out", "--record", "--replay") +ROLE_OPTIONS = ( + "--inject", + "--emit", + "--dump-contracts", + "--list-contracts", + "--new-inject", + "--expectations", + "--once", +) + + +def _given_dev_options_reader() -> Callable[..., Any]: + """Given the SDK exposes the daemon dev options""" + return sdk.dev_options + + +def _given_dev_help() -> Callable[[], str]: + """Given the SDK exposes the help of the dev options""" + helper = getattr(sdk, "dev_help", None) + assert helper is not None, "Expected xtm_oaev_sdk.dev_help on public surface" + return helper + + +def _given_dev_argument_parser() -> Callable[..., argparse.ArgumentParser]: + """Given the SDK exposes the dev parser a role extends""" + builder = getattr(sdk, "dev_argument_parser", None) + assert ( + builder is not None + ), "Expected xtm_oaev_sdk.dev_argument_parser on public surface" + return builder + + +def _given_command_line(*args: str) -> list[str]: + """Given a daemon command line with "" """ + return list(args) + + +def _given_role_parser( + builder: Callable[..., argparse.ArgumentParser], +) -> argparse.ArgumentParser: + """Given a role adds an "injector options" group with --inject to the dev parser""" + parser = builder(description="Injector dev mode.", epilog="Injector exit codes.") + group = parser.add_argument_group("injector options") + group.add_argument("--inject", metavar="PATH", help="the inject message to run") + return parser + + +def _when_reading_dev_options(reader: Callable[..., Any], argv: list[str]) -> Any: + """When the dev options are read""" + return reader(argv) + + +def _when_reading_the_help(helper: Callable[[], str]) -> str: + """When the help of the dev options is read""" + return helper() + + +def _when_parsing(parser: argparse.ArgumentParser, argv: list[str]) -> Any: + """When the role parses the command line""" + args, _ = parser.parse_known_args(argv) + return args + + +def _then_help_is_asked(options: Any, asked: bool) -> None: + """Then the dev help is """ + assert options.help is asked + + +def _then_help_groups(text: str, heading: str, *options: str) -> None: + """Then the help section "" lists exactly """ + section = text.split(f"{heading}:", 1)[1].split("\n\n", 1)[0] + listed = tuple( + token.rstrip(",") + for line in section.splitlines() + for token in line.split() + if token.startswith("-") and line.lstrip().startswith(token) + ) + assert listed == options, f"Expected {options} under {heading}, got {listed}" + + +def _then_help_names_no_role_option(text: str) -> None: + """Then the help names no injector nor collector option""" + named = [option for option in ROLE_OPTIONS if option in text] + assert named == [], f"Expected no role option in the common help, got {named}" + + +def _then_help_says(text: str, *phrases: str) -> None: + """Then the help says "" """ + for phrase in phrases: + assert phrase in text, f"Expected {phrase!r} in {text!r}" + + +def _then_role_option_is(args: Any, value: Any) -> None: + """Then the role's --inject is """ + assert args.inject == value + + +@pytest.mark.parametrize("flag", ["--help", "-h"]) +def test_dev_help_is_asked_with_dev(flag: str) -> None: + """It asks for the dev help when --dev comes with -h or --help. + + Scenario Outline: The dev help is asked with --dev + Given the SDK exposes the daemon dev options + And a daemon command line with "--dev " + When the dev options are read + Then the dev help is True + + Examples: + | flag | + | --help | + | -h | + """ + reader = _given_dev_options_reader() + argv = _given_command_line("--dev", flag) + options = _when_reading_dev_options(reader, argv) + _then_help_is_asked(options, True) + + +def test_dev_help_lists_only_the_common_options() -> None: + """It lists the options common to every daemon, and no role option. + + Scenario: The dev help lists only the common options + Given the SDK exposes the help of the dev options + When the help of the dev options is read + Then the help section "common options" lists exactly --dev, -h, --out, --record and --replay + And the help names no injector nor collector option + """ + helper = _given_dev_help() + text = _when_reading_the_help(helper) + _then_help_groups(text, "common options", *COMMON_OPTIONS) + _then_help_names_no_role_option(text) + + +def test_a_role_extends_the_dev_parser_with_its_own_options() -> None: + """It lets a role add its options and lists them next to the common ones. + + Scenario: A role extends the dev parser with its own options + Given the SDK exposes the dev parser a role extends + And a role adds an "injector options" group with --inject to the dev parser + When the help of the dev options is read + Then the help section "common options" lists exactly --dev, -h, --out, --record and --replay + And the help section "injector options" lists exactly --inject + And the help says "Injector dev mode." and "Injector exit codes." + """ + builder = _given_dev_argument_parser() + parser = _given_role_parser(builder) + text = _when_reading_the_help(parser.format_help) + _then_help_groups(text, "common options", *COMMON_OPTIONS) + _then_help_groups(text, "injector options", "--inject") + _then_help_says(text, "Injector dev mode.", "Injector exit codes.") + + +@pytest.mark.parametrize( + ("argv", "value"), + [ + (["--dev", "--inject", "inject.json"], "inject.json"), + (["--dev", "--inj", "inject.json"], None), + (["--dev", "--nmap-ports", "22"], None), + ], + ids=["full name", "abbreviation", "daemon's own flag"], +) +def test_a_role_parser_reads_its_options_only_under_their_full_name( + argv: list[str], value: Any +) -> None: + """It reads a role option only under its full name and leaves foreign flags alone. + + Scenario Outline: A role parser reads its options only under their full name + Given the SDK exposes the dev parser a role extends + And a role adds an "injector options" group with --inject to the dev parser + When the role parses the command line "" + Then the role's --inject is + + Examples: + | argv | value | + | --dev --inject inject.json | inject.json | + | --dev --inj inject.json | None | + | --dev --nmap-ports 22 | None | + """ + builder = _given_dev_argument_parser() + parser = _given_role_parser(builder) + args = _when_parsing(parser, argv) + _then_role_option_is(args, value) + + +# ---- Constraints identified ---- + + +@pytest.mark.parametrize("flag", ["--help", "-h"]) +def test_help_without_dev_stays_the_daemon_s_own(flag: str) -> None: + """It leaves -h and --help to the daemon when --dev is absent. + + Scenario Outline: Help without --dev stays the daemon's own + Given the SDK exposes the daemon dev options + And a daemon command line with "" + When the dev options are read + Then the dev help is False + + Examples: + | flag | + | --help | + | -h | + """ + reader = _given_dev_options_reader() + argv = _given_command_line(flag) + options = _when_reading_dev_options(reader, argv) + _then_help_is_asked(options, False) diff --git a/libs/xtm-oaev-sdk/test/daemons/test_dev_options.py b/libs/xtm-oaev-sdk/test/daemons/test_dev_options.py new file mode 100644 index 00000000..7322947d --- /dev/null +++ b/libs/xtm-oaev-sdk/test/daemons/test_dev_options.py @@ -0,0 +1,436 @@ +"""Tests for the dev command-line options common to collector and injector daemons. + +Feature: Daemon dev options + Collector and injector daemons can run without the platform ("dev mode"). + Every daemon reads its dev options from its command line, dev or not, + so the dev options must never act on anything that is not theirs. +""" + +import io +import sys +from contextlib import redirect_stdout +from typing import Any, Callable, NamedTuple +from unittest.mock import MagicMock + +import pytest +import xtm_oaev_sdk as sdk + +PROGRAM = "openaev-collector" +SCHEMA = '{"title": "collector configuration"}' + + +class Reading(NamedTuple): + options: Any + exit_code: Any + output: str + + +class Start(NamedTuple): + exit_code: Any + output: str + + +def _given_dev_options_reader() -> Callable[..., Any]: + """Given the SDK exposes the daemon dev options""" + reader = getattr(sdk, "dev_options", None) + assert ( + reader is not None + ), "Expected xtm_oaev_sdk.dev_options to exist on public surface" + return reader + + +def _given_command_line(*args: str) -> list[str]: + """Given a daemon command line with "" """ + return list(args) + + +def _given_command_line_with_every_common_dev_flag() -> list[str]: + """Given a daemon command line with: + | flag | value | + | --dev | | + | --out | run.json | + | --record | shodan.tape.json | + """ + return _given_command_line( + "--dev", "--out", "run.json", "--record", "shodan.tape.json" + ) + + +def _given_process_command_line(monkeypatch: pytest.MonkeyPatch, *args: str) -> None: + """Given the process command line contains "" """ + monkeypatch.setattr(sys, "argv", [PROGRAM, *args]) + + +def _given_configuration() -> sdk.Configuration: + """Given a daemon configuration""" + return sdk.Configuration( + config_hints={ + "log_level": {"data": "info"}, + "name": {"data": "whoami collector"}, + "collector_id": {"data": "whoami-collector"}, + } + ) + + +def _given_configuration_schema( + monkeypatch: pytest.MonkeyPatch, configuration: sdk.Configuration +) -> None: + """Given the daemon configuration has a schema""" + monkeypatch.setattr(configuration, "schema", lambda: SCHEMA) + + +def _given_daemon_with_callback( + configuration: sdk.Configuration, +) -> tuple[sdk.BaseDaemon, MagicMock, MagicMock]: + """Given a daemon with a callback""" + setup, main_loop = MagicMock(), MagicMock() + + class WhoamiCollector(sdk.BaseDaemon): + def _setup(self): + setup() + + def _start_loop(self): + main_loop() + + daemon = WhoamiCollector( + configuration=configuration, + callback=MagicMock(), + logger=MagicMock(), + api_client=MagicMock(), + ) + return daemon, setup, main_loop + + +def _when_reading_dev_options( + reader: Callable[..., Any], argv: list[str] | None +) -> Reading: + """When the dev options are read""" + output = io.StringIO() + try: + with redirect_stdout(output): + options = reader(argv) if argv is not None else reader() + except SystemExit as exit_: + return Reading(None, exit_.code, output.getvalue()) + return Reading(options, None, output.getvalue()) + + +def _when_turning_dev_mode_off(options: Any) -> Exception | None: + """When someone tries to turn dev mode off on those options""" + try: + options.enabled = False + except Exception as err: # pylint: disable=broad-except + return err + return None + + +def _when_starting_daemon(daemon: sdk.BaseDaemon) -> Start: + """When the daemon is started""" + output = io.StringIO() + try: + with redirect_stdout(output): + daemon.start() + except SystemExit as exit_: + return Start(exit_.code, output.getvalue()) + return Start(None, output.getvalue()) + + +def _then_reading_did_not_exit(reading: Reading) -> None: + """Then reading the dev options does not exit""" + assert ( + reading.exit_code is None + ), f"Expected reading the dev options not to exit, exited with {reading.exit_code}" + + +def _then_nothing_was_printed(reading: Reading) -> None: + """Then nothing is printed""" + assert reading.output == "", f"Expected no output, got {reading.output!r}" + + +def _then_dev_mode_is_enabled(options: Any) -> None: + """Then dev mode is enabled""" + assert options.enabled is True + + +def _then_dev_mode_is_disabled(options: Any) -> None: + """Then dev mode is disabled""" + assert options.enabled is False + + +def _then_output_destination_is(options: Any, destination: str | None) -> None: + """Then the output destination is "" """ + assert options.out == destination + + +def _then_tapes_are(options: Any, record: str | None, replay: str | None) -> None: + """Then the tape to record is "" and the tape to replay is "" """ + assert (options.record, options.replay) == (record, replay) + + +def _then_options_hold_only_the_common_fields(options: Any) -> None: + """Then the options hold only the fields common to every daemon""" + assert set(vars(options)) == {"enabled", "out", "record", "replay", "help"} + + +def _then_change_was_refused(error: Exception | None) -> None: + """Then the change is refused""" + assert isinstance( + error, (AttributeError, TypeError, ValueError) + ), f"Expected the change to be refused, got {error!r}" + + +def _then_option_is_unset(options: Any, option: str) -> None: + """Then the