Skip to content

feat(sdk): run injectors and collectors without the platform (#383) - #384

Open
Christophe Melchior (Kakudou) wants to merge 17 commits into
feat/303-sdk-initfrom
feat/isolate-run
Open

Christophe Melchior (Kakudou) wants to merge 17 commits into
feat/303-sdk-initfrom
feat/isolate-run

Conversation

@Kakudou

Copy link
Copy Markdown
Member

Proposed changes

  • seam/port_io models that mirror the platform DTOs key for key. The sent bodies are validated before they are written.
  • Common dev options (--dev, --out, help). The configuration is relaxed under --dev, and flags the SDK doesn't own are left alone.
  • A dev sink that writes one redacted JSON list. NeedsPlatformError for the calls that need a live platform.
  • ContractValidator, matched to the platform health-check by fixtures taken from HealthCheckUtilsTest. A single-trace route.
  • Signatures sent under their signature types, with LEGACY_SIGNATURE_TYPES for reading the old names.
  • The tape capability (--record / --replay): readable JSON, secrets masked, fail-closed sockets, lint_tape.
  • docs/how_to_dev_mode.md.

Testing Instructions

End to end: chain the nmap injector into the Elastic collector, with no platform and no RabbitMQ. Needs the injectors (OpenAEV-Platform/injectors#530) and collectors (OpenAEV-Platform/collectors#681) PRs.

Setup: check out the three repos side by side on feat/isolate-run, then make one venv per side:

python -m venv .venv-inj && .venv-inj/bin/pip install -e client-python -e client-python/libs/xtm-oaev-sdk \
  -e injectors/libs/injectors-sdk -e injectors/injector_common -e injectors/nmap
python3.14 -m venv .venv-col && .venv-col/bin/pip install -e client-python -e client-python/libs/xtm-oaev-sdk \
  -e collectors/libs/collectors-sdk -e collectors/elastic
export INJECTOR_ID=nmap-dev COLLECTOR_ID=elastic-dev COLLECTOR_NAME="Elastic Security"
export ELASTIC_BASE_URL=https://your-es:9200 ELASTIC_API_KEY=...       # an Elasticsearch with Elastic Security alerts
export OPENAEV_URL=http://unused OPENAEV_TOKEN=unused   # the Elastic config still asks for them; dev mode never calls them

Write the inject message, then fill in what stderr lists. That's an asset whose seen_ip is a host you are allowed to scan, not loopback, because injector_common drops loopback targets.

(cd injectors/nmap && ../../.venv-inj/bin/python -m nmap.openaev_nmap --dev --new-inject "tcp connect") > inject.json

Chain through a file, then through a pipe:

(cd injectors/nmap && ../../.venv-inj/bin/python -m nmap.openaev_nmap --dev --inject ../../inject.json \
   --emit expectations --out ../../nmap.json) > pending.json
(cd collectors/elastic && ../../.venv-col/bin/python -m src --dev --expectations ../../pending.json --once --out ../../elastic.json)

(cd injectors/nmap && ../../.venv-inj/bin/python -m nmap.openaev_nmap --dev --inject ../../inject.json --emit expectations --out ../../nmap.json) \
  | (cd collectors/elastic && ../../.venv-col/bin/python -m src --dev --expectations - --once --out ../../elastic.json)

Expected results:

  • Both commands exit 0.
  • pending.json holds one DETECTION and one PREVENTION expectation, carrying start_date, end_date, source_ipv4_address and target_ipv4_address.
  • elastic.json holds the bulk update for those same ids, plus the traces of the matching alerts. The file run and the pipe run give the same results.

Record once, then replay offline: add --record nmap.tape.json and --record elastic.tape.json to the pipe. Then run it again with --replay instead, with Elasticsearch unreachable and nmap off the PATH. The replay should exit 0 · 0 and write the same calls, apart from start_date and end_date. lint_tape("elastic.tape.json", secrets=["<your api key>"]) should return [].

Related issues

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

  • The seam versions are bumped and the goldens regenerated where contracts changed.

@Kakudou Christophe Melchior (Kakudou) added filigran team Item from the Filigran team. do not merge Do not merge until this label is removed. tech foundation Linked to tech foundation. labels Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

do not merge Do not merge until this label is removed. filigran team Item from the Filigran team. tech foundation Linked to tech foundation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(sdk): Run injectors and collectors without the platform (dev mode, chain, record/replay)

1 participant