fix(signatures): send canonical signature types and skip invalid expectations (#352)

[Mariot Tsitoara (mariot)]

Proposed changes

• SignatureManager.build_payload sends the canonical SignatureTypes values instead of the ExecutionSignature field names: start_time → start_date, end_time → end_date, source_ipv4/source_ipv6 → source_ipv4_address/source_ipv6_address, target_ipv4/target_ipv6/target_hostname → target_ipv4_address/target_ipv6_address/target_hostname_address. The cloud fields already use canonical names.
• Keys that aren't a SignatureTypes value (partial_results, Nmap's ports_discovered/services_discovered, Netexec's protocols_*, Nuclei's cves_*) and None, list or dict values are left out, with one warning per call that names them. The platform already discards non-scalar values, and collectors parse each signature as SignatureTypes + str. Extra signatures go through the same mapping, and they still override the base value for the same type.
• expectations_models_for_source builds expectations one by one and skips an invalid one with a warning (its id and the validation error), so one bad expectation no longer hides the others. I skip the whole expectation rather than dropping its unknown signatures, because match_alert requires every signature to match: dropping one would loosen the match and could create false positives.
• ExecutionSignature field names are unchanged, so injector code using them keeps working.

Before / after

Signatures received by the platform (Mimikyu), same inject, pyoaev 3.261014.1 vs this branch

Nmap SYN scan on an asset group (one hostname target, one IPv4 target), DETECTION + PREVENTION:

before  start_time, end_time, source_ipv4, source_ipv6, target_hostname | target_ipv4, ports_discovered=[22, 80], services_discovered=[{...}]
after   start_date, end_date, source_ipv4_address, source_ipv6_address, target_hostname_address | target_ipv4_address
        WARNING Signatures left out of the payload, not a known signature type or not a single value: ports_discovered, services_discovered

Injector (live run)	Before	After	Inject lifecycle
Nmap (asset group, stub nmap)	start_time, source_ipv4, target_hostname/target_ipv4, ports_discovered, services_discovered	canonical types only, lists left out	identical (SUCCESS, EXECUTED)
Netexec SMB (assets, stub netexec)	same + protocols_tested, protocols_succeeded	canonical types only	identical
Nuclei panel scan (real nuclei, VULNERABILITY + DETECTION)	same + cves_tested, cves_found_vulnerable	canonical types only	identical
Email SMTP (local SMTP server)	start_time, end_time	start_date, end_date	identical; its own source_email/target_email/url_hash indicators are unchanged

Collectors: each one ran for 50 s (COLLECTOR_PERIOD=PT20S) against Mimikyu + ofapi. A proxy added the 4 expectations the unfixed Nmap run produced (stored as the platform stores them) to the 11 valid ones Mimikyu serves.

Collector	Before	After
SentinelOne, LogRhythm, NetWitness, QRadar, Splunk ES, Cortex XDR, Cortex XSOAR, template, Microsoft Defender, Defender for O365	every cycle: Error fetching expectations: 5 validation errors for DetectionExpectation, 0 expectations processed	4 Skipping expectation <id> warnings, the 11 valid expectations are processed (Splunk ES, template and both Defenders update them)
Elastic	15 loaded (it doesn't build the pyoaev models)	unchanged

Unit tests: 196 → 212. Ten of the new tests fail on main and pass here. The other ten pin behaviour that must not change (extras merge order, per-expectation-type extras, model per expectation type, null signatures).

Testing Instructions

1. pytest, plus black --check ., isort --check-only ., flake8 --ignore=E,W .
2. Issue's minimal check, now prints canonical types:

   import os
   from types import SimpleNamespace
   from pyoaev.signatures import SignatureManager, NetworkInjectorConfig
   os.environ["CONTAINER_IP"] = "10.0.0.5"
   sig = SignatureManager(client=None).build_execution_signatures(NetworkInjectorConfig(target_ipv4="192.0.2.11"))
   target = SimpleNamespace(agent_id=None, asset_id="a", asset_group_id=None)
   payload = SignatureManager.build_payload(sig, [target], ["DETECTION"])
   print([v["signature_type"] for v in payload["targets"][0]["signature_values"][0]["values"]])
   # ['start_date', 'source_ipv4_address', 'source_ipv6_address', 'target_ipv4_address']
   # (source_ipv6_address only when the host has a global IPv6 address)

3. End to end: run an injector that uses SignatureManager (Nmap, Netexec, Nuclei, Email SMTP) with this branch against Mimikyu, and check the signature callback. Then run a collector against expectations that contain start_time/source_ipv4 signatures and check that the valid ones are still processed.

Related issues

• Closes fix(signatures): SignatureManager sends non-canonical signature types (start_time, source_ipv4, ...) that break collectors #352
• Follow-ups, not in this PR: release pyoaev and bump the pin in nmap, netexec, nuclei and email-smtp. On the platform, normalize or reject unknown signature types at ingestion, and repair the rows written since openaev#7115 (they will now be skipped by collectors instead of blocking them).

Checklist

• I consider the submitted work as finished
• I tested the code for its functionality
• I wrote test cases for the relevant uses case
• I added/update the relevant documentation (either on github or on notion)
• Where necessary I refactored code to improve the overall quality
• For bug fix -> I implemented a test that covers the bug

Further comments

Found while testing, not changed here:

• build_payload accepts targets_meta as a dict, but then reads target.agent_id, so a dict raises AttributeError. Every injector passes a list of objects, so I left it.
• Netexec: asset-group injects fail with KeyError: 'assetGroups' (execute() passes the parsed credentials to Targets.build_execution_message instead of the inject message). The error handler then calls injector_logger.error(msg, inject_id, e), which AppLogger.error doesn't accept, so the inject never gets an error callback.

[Copilot]

🟢 Approval recommended

The focused changes address the reported failures with regression coverage and no identified blocking issues.

0 open findings

What changed in this PR

Fixes #352 by sending canonical signature types and preventing invalid expectations from blocking collectors.

Changes:

• Maps signature names and filters unsupported keys and values.
• Skips invalid expectations individually with warnings.
• Adds regression coverage for payload compatibility and expectation handling.

File	Description
test/​signatures/​test_signature_manager_build_payload.py	Tests canonical types, filtering, overrides, and collector compatibility.
test/​apis/​inject_expectation/​test_inject_expectation.py	Tests model selection and isolation of invalid expectations.
pyoaev/​signatures/​signature_manager.py	Canonicalizes and filters outgoing signatures.
pyoaev/​apis/​inject_expectation/​inject_expectation.py	Logs and skips invalid expectations individually.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.