feat(hunt-io): add support for hunt v3 api while keeping v2 (#7678)

[Marko Marjanović (m4r35)]

Proposed changes

• Add a hunt_io.api_version setting (HUNT_IO_API_VERSION, values v2 / v3, default v2) that
  selects the authentication scheme for the Hunt.io C2 feed. V2 (https://api.hunt.io/v1/feeds/c2)
  authenticates with a token header; V3 (https://a.hunt.io/feeds/c2) requires
  Authorization: Bearer with an ak_-prefixed key. The two are mutually exclusive — each returns
  HTTP 401 when sent the other's header — so HTTPSessionManager.create_session now sets the header
  matching the selected version, at both construction and post-timeout session refresh.
• Reject a non-ak_ key at startup when v3 is selected. V3 returns an identical, opaque 401 for a
  missing key, a malformed key, and a wrong-scheme key, so this converts a confusing runtime failure
  into a clear configuration error. Deliberately scoped to V3 only, as V2 documents no prefix rule.
• Normalise blank and mixed-case values for the new setting. A declared-but-undefined Compose
  passthrough (- HUNT_IO_API_VERSION=${HUNT_IO_API_VERSION}) resolves to an empty string, which
  would otherwise fail validation instead of falling back to the default.
• Document both versions in the README (config table plus a version-selection section warning that
  api_version and api_base_url must change together), update config.yml.sample, and regenerate
  __metadata__.
• Extend the existing test suites: parametrised settings cases for an unknown version, a v3 key
  missing the ak_ prefix, and blank/whitespace/uppercase normalisation; plus new create_session
  coverage asserting the correct header per version, that the deprecated namespace still forwards the
  new setting, and that a post-timeout session refresh retains bearer auth.

Backward compatibility: api_version defaults to v2, which reproduces existing behaviour
exactly. Nothing becomes mandatory — the generated schema's required list is unchanged — and no
existing variable is renamed or removed. The response payload is byte-identical between versions
(gzipped NDJSON, same record fields), so parsing, STIX conversion, and the entity pipeline are
untouched.

Testing: both paths verified end-to-end against the live APIs on OpenCTI 7.260910.0 —
authentication, feed fetch, conversion, and ingestion of observables, indicators, malware,
infrastructure and relationships, with no errors from the connector, workers, or platform. Switching
between versions was exercised in both directions. Unit tests pass, and black, isort and flake8
are clean for the changed files.

Related issues

• Closes feat(hunt-io): add support for hunt v3 c2 feed api #7678

Checklist

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

Further comments

a.hunt.io and api.hunt.io are separate services rather than two paths on one host, which is why a
single credential cannot address both and why the selector is an explicit setting rather than
something inferred from the base URL. Deriving the version from the URL was considered and rejected:
it couples behaviour to a hostname pattern and breaks for staging or custom hostnames.

The new setting is documented as HUNT_IO_API_VERSION, matching the current prefix convention. The
deprecated CONNECTOR_HUNT_UI_* and CONNECTOR_HUNT_IO_* namespaces still resolve it through the
existing SDK shim, and all three spellings appear in the regenerated config schema.

[filigran-cla-bot]

Contributor License Agreement

✅ CLA signed 💚

Thank you Marko Marjanović (@m4r35) for signing the Contributor License Agreement! Your pull request can now be reviewed and merged.

We appreciate your contribution to Filigran's open source projects! ❤️

_{This is an automated message from the Filigran CLA Bot.}

[Copilot]

Pull request overview

Adds configurable Hunt.io v3 API support while preserving v2 compatibility through version-specific authentication, validation, documentation, and tests.

Changes:

• Adds normalized API version settings and v3 key validation.
• Implements token/Bearer authentication and session refresh handling.
• Updates tests, deployment configuration, documentation, and generated metadata.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Summary
external-import/hunt-io/tests/tests_connector/test_settings.py	Adds configuration validation and normalization tests.
external-import/hunt-io/tests/tests_connector/test_client_api.py	Tests version-specific authentication and session refresh.
external-import/hunt-io/tests/conftest.py	Adds v3 test configuration fixtures.
external-import/hunt-io/src/external_import_connector/settings.py	Adds API version configuration and v3 validation.
external-import/hunt-io/src/external_import_connector/client_api.py	Selects authentication headers by API version.
external-import/hunt-io/README.md	Documents API version selection.
external-import/hunt-io/docker-compose.yml	Adds API version deployment configuration. Moderate finding (1 vote): deprecated API-version aliases are not passed through.
external-import/hunt-io/config.yml.sample	Adds sample API version configuration.
external-import/hunt-io/__metadata__/connector_config_schema.json	Regenerates the configuration schema. Moderate finding (3 votes): the stable schema $id loses the hunt-io connector slug.
external-import/hunt-io/__metadata__/CONNECTOR_CONFIG_DOC.md	Updates generated configuration documentation.

Suppressed comments (1)

external-import/hunt-io/docker-compose.yml:14

• The Compose sample expands only HUNT_IO_API_VERSION, so a deployment using either deprecated CONNECTOR_HUNT_UI_API_VERSION or CONNECTOR_HUNT_IO_API_VERSION cannot reach the SDK namespace shim: Compose substitutes v2 and silently sends the V2 token scheme even when the deprecated setting is v3. Please include the deprecated variables in the fallback chain (or pass them through) so the advertised backward-compatible aliases work with this deployment path.

      - HUNT_IO_API_VERSION=${HUNT_IO_API_VERSION:-v2}

---

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