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

The two Hunt.io C2 feed APIs use mutually exclusive authentication: V2
expects a `token` header, V3 expects `Authorization: Bearer` with an
`ak_`-prefixed key. Each returns HTTP 401 when sent the other's header.

Add `hunt_io.api_version` (HUNT_IO_API_VERSION) to select between them,
defaulting to v2 so existing deployments are unaffected. The response
payload is identical between versions, so parsing and STIX conversion are
unchanged.

- Select the auth header by version in HTTPSessionManager.create_session,
  passing the version at both construction and post-timeout refresh
- Reject a non-`ak_` key at startup when v3 is selected; V3 returns the
  same opaque 401 for a malformed key as for a missing one
- Normalize blank and mixed-case values, so an undefined compose
  passthrough (`${HUNT_IO_API_VERSION}` -> "") falls back to the default
- Document both versions and regenerate __metadata__

Author: m4r35

external-import/hunt-io/README.md

@@ -62,10 +62,28 @@ Below are the parameters you'll need to set for the connector:
 
 | Parameter    | config.yml   | Docker environment variable | Default | Mandatory | Description                                                                                                               |
 |--------------|--------------|-----------------------------|---------|-----------|---------------------------------------------------------------------------------------------------------------------------|
+| API version  | api_version  | `HUNT_IO_API_VERSION`       | v2      | No        | Which Hunt.io C2 feed API to target. Valid values: `v2`, `v3`. Must be changed together with `api_base_url` — see below.  |
 | API base URL | api_base_url | `HUNT_IO_API_BASE_URL`      |         | Yes       |                                                                                                                           |
 | API key      | api_key      | `HUNT_IO_API_KEY`           |         | Yes       |                                                                                                                           |
 | TLP level    | tlp_level    | `HUNT_IO_TLP_LEVEL`         | amber   | No        | The Traffic Light Protocol level for data being ingested. Valid values: `white`, `green`, `amber`, `amber+strict`, `red`. |
 
+#### Choosing an API version
+
+The two Hunt.io APIs use mutually exclusive authentication, so `api_version` and `api_base_url` must
+always be set together:
+
+| `api_version` | `api_base_url`                     | Authentication                    | Key format     |
+|---------------|------------------------------------|-----------------------------------|----------------|
+| `v2` (default)| `https://api.hunt.io/v1/feeds/c2`  | `token` header                    | any            |
+| `v3`          | `https://a.hunt.io/feeds/c2`       | `Authorization: Bearer`           | `ak_`-prefixed |
+
+> **Changing only the base URL will not work.** Pointing `HUNT_IO_API_BASE_URL` at the V3 endpoint
+> while leaving `HUNT_IO_API_VERSION` at `v2` keeps sending the `token` header, and V3 answers with
+> an HTTP 401 that is indistinguishable from a missing key. The same applies in reverse.
+
+Existing deployments are unaffected: `api_version` defaults to `v2`, which is the behaviour prior to
+this setting being introduced.
+
 ## Deployment
 
 ### Docker Deployment
@@ -88,6 +106,7 @@ Configure the connector in `docker-compose.yml`:
       - CONNECTOR_NAME=Hunt.io
       - CONNECTOR_SCOPE=hunt-io
       - CONNECTOR_LOG_LEVEL=info
+      - HUNT_IO_API_VERSION=v2
       - HUNT_IO_API_BASE_URL=ChangeMe
       - HUNT_IO_API_KEY=ChangeMe
     restart: always

external-import/hunt-io/__metadata__/CONNECTOR_CONFIG_DOC.md

@@ -15,10 +15,13 @@ Below is an exhaustive enumeration of all configurable parameters available, eac
 | CONNECTOR_TYPE | `const` |  | `EXTERNAL_IMPORT` |  | `"EXTERNAL_IMPORT"` |  |
 | CONNECTOR_DURATION_PERIOD | `string` |  | Format: [`duration`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) |  | `"P1D"` | Time interval between consecutive data imports from Hunt.io. Controls how frequently the connector runs |
 | HUNT_IO_API_BASE_URL | `string` |  | Format: [`uri`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) |  | `"https://api.hunt.io/v1/feeds/c2"` | Hunt.io API endpoint URL for the C2 threat intelligence feeds |
+| HUNT_IO_API_VERSION | `string` |  | `v2` `v3` |  | `"v2"` | Which Hunt.io C2 feed API to target. 'v2' authenticates with a 'token' header against https://api.hunt.io/v1/feeds/c2. 'v3' authenticates with 'Authorization: Bearer' against https://a.hunt.io/feeds/c2 and requires an 'ak_'-prefixed key. The two APIs are mutually exclusive: set api_base_url to match the version, as changing one without the other returns HTTP 401 |
 | HUNT_IO_TLP_LEVEL | `string` |  | `white` `clear` `green` `amber` `amber+strict` `red` |  | `"amber"` | Traffic Light Protocol (TLP) marking level to apply to imported data, controlling information sharing restrictions |
 | CONNECTOR_HUNT_UI_API_BASE_URL | `string` |  | Format: [`uri`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | ⛔️ | `"https://api.hunt.io/v1/feeds/c2"` | Use HUNT_IO_API_BASE_URL instead. |
+| CONNECTOR_HUNT_UI_API_VERSION | `string` |  | `v2` `v3` | ⛔️ | `"v2"` | Use HUNT_IO_API_VERSION instead. |
 | CONNECTOR_HUNT_UI_API_KEY | `string` |  | Format: [`password`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | ⛔️ |  | Use HUNT_IO_API_KEY instead. |
 | CONNECTOR_HUNT_UI_TLP_LEVEL | `string` |  | `white` `clear` `green` `amber` `amber+strict` `red` | ⛔️ | `"amber"` | Use HUNT_IO_TLP_LEVEL instead. |
 | CONNECTOR_HUNT_IO_API_BASE_URL | `string` |  | Format: [`uri`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | ⛔️ | `"https://api.hunt.io/v1/feeds/c2"` | Use HUNT_IO_API_BASE_URL instead. |
+| CONNECTOR_HUNT_IO_API_VERSION | `string` |  | `v2` `v3` | ⛔️ | `"v2"` | Use HUNT_IO_API_VERSION instead. |
 | CONNECTOR_HUNT_IO_API_KEY | `string` |  | Format: [`password`](https://json-schema.org/understanding-json-schema/reference/string#built-in-formats) | ⛔️ |  | Use HUNT_IO_API_KEY instead. |
 | CONNECTOR_HUNT_IO_TLP_LEVEL | `string` |  | `white` `clear` `green` `amber` `amber+strict` `red` | ⛔️ | `"amber"` | Use HUNT_IO_TLP_LEVEL instead. |

external-import/hunt-io/__metadata__/connector_config_schema.json

@@ -63,6 +63,16 @@
       "type": "string",
       "deprecated": true
     },
+    "CONNECTOR_HUNT_UI_API_VERSION": {
+      "default": "v2",
+      "description": "Use HUNT_IO_API_VERSION instead.",
+      "enum": [
+        "v2",
+        "v3"
+      ],
+      "type": "string",
+      "deprecated": true
+    },
     "CONNECTOR_HUNT_UI_API_KEY": {
       "description": "Use HUNT_IO_API_KEY instead.",
       "format": "password",
@@ -93,6 +103,16 @@
       "type": "string",
       "deprecated": true
     },
+    "CONNECTOR_HUNT_IO_API_VERSION": {
+      "default": "v2",
+      "description": "Use HUNT_IO_API_VERSION instead.",
+      "enum": [
+        "v2",
+        "v3"
+      ],
+      "type": "string",
+      "deprecated": true
+    },
     "CONNECTOR_HUNT_IO_API_KEY": {
       "description": "Use HUNT_IO_API_KEY instead.",
       "format": "password",
@@ -122,6 +142,15 @@
       "minLength": 1,
       "type": "string"
     },
+    "HUNT_IO_API_VERSION": {
+      "default": "v2",
+      "description": "Which Hunt.io C2 feed API to target. 'v2' authenticates with a 'token' header against https://api.hunt.io/v1/feeds/c2. 'v3' authenticates with 'Authorization: Bearer' against https://a.hunt.io/feeds/c2 and requires an 'ak_'-prefixed key. The two APIs are mutually exclusive: set api_base_url to match the version, as changing one without the other returns HTTP 401",
+      "enum": [
+        "v2",
+        "v3"
+      ],
+      "type": "string"
+    },
     "HUNT_IO_API_KEY": {
       "description": "Authentication key for accessing the Hunt.io API. Obtain this from your Hunt.io account settings",
       "format": "password",

external-import/hunt-io/config.yml.sample

@@ -19,5 +19,9 @@ connector:
   #send_to_directory_retention: 7
 
 hunt_io:
+  # 'v2' pairs with https://api.hunt.io/v1/feeds/c2 and a plain API key.
+  # 'v3' pairs with https://a.hunt.io/feeds/c2 and an 'ak_'-prefixed key.
+  # api_version and api_base_url must be changed together, or the API returns 401.
+  api_version: 'v2'
   api_base_url: 'https://api.hunt.io/v1/feeds/c2'
   api_key: 'ChangeMe'

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

@@ -11,6 +11,7 @@ services:
       - CONNECTOR_DURATION_PERIOD=PT24H
 
       # Connector's custom execution parameters
+      - HUNT_IO_API_VERSION=${HUNT_IO_API_VERSION:-v2}
       - HUNT_IO_API_BASE_URL=${CONNECTOR_HUNT_UI_API_BASE_URL}
       - HUNT_IO_API_KEY=${CONNECTOR_HUNT_UI_API_KEY}
     restart: always

external-import/hunt-io/src/external_import_connector/client_api.py

@@ -31,10 +31,18 @@ class HTTPSessionManager:
     def __init__(self, helper: OpenCTIConnectorHelper):
         self.helper = helper
 
-    def create_session(self, api_key: str) -> requests.Session:
-        """Create a new HTTP session with resilience features."""
+    def create_session(self, api_key: str, api_version: str) -> requests.Session:
+        """Create a new HTTP session with resilience features.
+
+        The two Hunt.io APIs use mutually exclusive auth schemes: V2 expects a `token`
+        header and rejects bearer auth, V3 expects `Authorization: Bearer` and rejects
+        the `token` header. Both return HTTP 401 on a mismatch.
+        """
         session = requests.Session()
-        session.headers.update({"token": api_key})
+        if api_version == "v3":
+            session.headers.update({"Authorization": f"Bearer {api_key}"})
+        else:
+            session.headers.update({"token": api_key})
 
         # Configure retry strategy
         retry_strategy = Retry(
@@ -195,7 +203,8 @@ def __init__(self, helper: OpenCTIConnectorHelper, config: "ConnectorSettings"):
 
         # Create HTTP session with resilience features
         self.session = self.session_manager.create_session(
-            self.config.hunt_io.api_key.get_secret_value()
+            self.config.hunt_io.api_key.get_secret_value(),
+            self.config.hunt_io.api_version,
         )
 
     @property
@@ -322,7 +331,8 @@ def _refresh_session_on_timeout(self) -> None:
 
             # Create new session with same configuration
             self.session = self.session_manager.create_session(
-                self.config.hunt_io.api_key.get_secret_value()
+                self.config.hunt_io.api_key.get_secret_value(),
+                self.config.hunt_io.api_version,
             )
 
             self.helper.connector_logger.info(

external-import/hunt-io/src/external_import_connector/settings.py

@@ -1,5 +1,5 @@
 from datetime import timedelta
-from typing import Literal
+from typing import Annotated, Any, Literal
 
 from connectors_sdk import (
     BaseConfigModel,
@@ -8,14 +8,53 @@
     DeprecatedField,
     ListFromString,
 )
-from pydantic import Field, HttpUrl, SecretStr, SkipValidation
+from pydantic import (
+    BeforeValidator,
+    Field,
+    HttpUrl,
+    SecretStr,
+    SkipValidation,
+    model_validator,
+)
+
+DEFAULT_API_VERSION = "v2"
+
+
+def _normalize_api_version(value: Any) -> Any:
+    """Normalize an api_version coming from an environment variable.
+
+    A compose passthrough such as `HUNT_IO_API_VERSION=${HUNT_IO_API_VERSION}` sets the
+    variable to an empty string when it is not defined, which would otherwise fail
+    validation instead of falling back to the default. Case is normalized too, since
+    environment variables are commonly written in upper case.
+    """
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        return normalized or DEFAULT_API_VERSION
+    return value
+
+
+ApiVersion = Annotated[
+    Literal["v2", "v3"],
+    BeforeValidator(_normalize_api_version),
+]
 
 
 class HuntIoConfig(BaseConfigModel):
     api_base_url: HttpUrl = Field(
         description="Hunt.io API endpoint URL for the C2 threat intelligence feeds",
         default=HttpUrl("https://api.hunt.io/v1/feeds/c2"),
     )
+    api_version: ApiVersion = Field(
+        description=(
+            "Which Hunt.io C2 feed API to target. 'v2' authenticates with a 'token' "
+            "header against https://api.hunt.io/v1/feeds/c2. 'v3' authenticates with "
+            "'Authorization: Bearer' against https://a.hunt.io/feeds/c2 and requires an "
+            "'ak_'-prefixed key. The two APIs are mutually exclusive: set api_base_url "
+            "to match the version, as changing one without the other returns HTTP 401"
+        ),
+        default=DEFAULT_API_VERSION,
+    )
     api_key: SecretStr = Field(
         description=(
             "Authentication key for accessing the Hunt.io API. "
@@ -32,6 +71,25 @@ class HuntIoConfig(BaseConfigModel):
         )
     )
 
+    @model_validator(mode="after")
+    def _validate_api_key_matches_version(self) -> "HuntIoConfig":
+        """Fail fast when a V3 key is malformed.
+
+        The V3 API rejects any key without an `ak_` prefix using the same opaque 401 it
+        returns for a missing key, which makes a typo indistinguishable from an
+        entitlement problem at runtime. V2 has no documented prefix rule, so this check
+        is deliberately scoped to V3 only.
+        """
+        if self.api_version == "v3" and not self.api_key.get_secret_value().startswith(
+            "ak_"
+        ):
+            raise ValueError(
+                "api_version 'v3' requires an 'ak_'-prefixed API key; the V3 API "
+                "rejects other keys with an HTTP 401 indistinguishable from a "
+                "missing key"
+            )
+        return self
+
 
 class ExternalImportConfig(BaseExternalImportConnectorConfig):
     name: str = Field(

external-import/hunt-io/tests/conftest.py

@@ -31,6 +31,48 @@ def correct_config():
         yield
 
 
+@pytest.fixture
+def v3_config():
+    with patch(
+        "os.environ",
+        {
+            "OPENCTI_URL": "http://url",
+            "OPENCTI_TOKEN": "token",
+            "CONNECTOR_ID": "connector_id",
+            "CONNECTOR_NAME": "connector_name",
+            "CONNECTOR_TYPE": "EXTERNAL_IMPORT",
+            "CONNECTOR_LOG_LEVEL": "error",
+            "CONNECTOR_SCOPE": "scope",
+            "CONNECTOR_DURATION_PERIOD": "PT5M",
+            "HUNT_IO_API_VERSION": "v3",
+            "HUNT_IO_API_BASE_URL": "https://a.hunt.io/feeds/c2",
+            "HUNT_IO_API_KEY": "ak_api_key_value",
+        },
+    ):
+        yield
+
+
+@pytest.fixture
+def deprecated_v3_config():
+    with patch(
+        "os.environ",
+        {
+            "OPENCTI_URL": "http://url",
+            "OPENCTI_TOKEN": "token",
+            "CONNECTOR_ID": "connector_id",
+            "CONNECTOR_NAME": "connector_name",
+            "CONNECTOR_TYPE": "EXTERNAL_IMPORT",
+            "CONNECTOR_LOG_LEVEL": "error",
+            "CONNECTOR_SCOPE": "scope",
+            "CONNECTOR_DURATION_PERIOD": "PT5M",
+            "CONNECTOR_HUNT_IO_API_VERSION": "v3",
+            "CONNECTOR_HUNT_IO_API_BASE_URL": "https://a.hunt.io/feeds/c2",
+            "CONNECTOR_HUNT_IO_API_KEY": "ak_api_key_value",
+        },
+    ):
+        yield
+
+
 @pytest.fixture
 def deprecated_config():
     with patch(

external-import/hunt-io/tests/tests_connector/test_client_api.py

@@ -0,0 +1,61 @@
+from unittest.mock import MagicMock
+
+import pytest
+from external_import_connector.client_api import ConnectorClient, HTTPSessionManager
+from external_import_connector.settings import ConnectorSettings
+
+V2_KEY = "api_key_value"
+V3_KEY = "ak_api_key_value"
+
+
+@pytest.mark.parametrize(
+    "api_version, api_key, expected_header, expected_value, absent_header",
+    [
+        pytest.param("v2", V2_KEY, "token", V2_KEY, "Authorization", id="v2_token"),
+        pytest.param(
+            "v3",
+            V3_KEY,
+            "Authorization",
+            f"Bearer {V3_KEY}",
+            "token",
+            id="v3_bearer",
+        ),
+    ],
+)
+def test_create_session_sets_auth_header_matching_api_version(
+    api_version, api_key, expected_header, expected_value, absent_header
+):
+    """
+    The two Hunt.io APIs use mutually exclusive auth schemes and each answers 401 when
+    sent the other one's header, so the session must carry exactly one of them.
+    """
+    session_manager = HTTPSessionManager(MagicMock())
+
+    session = session_manager.create_session(api_key, api_version)
+
+    assert session.headers[expected_header] == expected_value
+    assert absent_header not in session.headers
+
+
+def test_api_version_is_accepted_through_deprecated_namespace(deprecated_v3_config):
+    """
+    `api_version` is a new field, so its deprecated spellings exist only because the SDK
+    namespace shim forwards every key. Guard that, since the naming decision relies on it.
+    """
+    client = ConnectorClient(helper=MagicMock(), config=ConnectorSettings())
+
+    assert client.session.headers["Authorization"] == f"Bearer {V3_KEY}"
+
+
+def test_refresh_session_on_timeout_keeps_v3_bearer_header(v3_config):
+    """
+    `_refresh_session_on_timeout` rebuilds the session independently of `__init__`, so a
+    missed argument there would silently drop authentication after a connection timeout.
+    """
+    client = ConnectorClient(helper=MagicMock(), config=ConnectorSettings())
+    assert client.session.headers["Authorization"] == f"Bearer {V3_KEY}"
+
+    client._refresh_session_on_timeout()
+
+    assert client.session.headers["Authorization"] == f"Bearer {V3_KEY}"
+    assert "token" not in client.session.headers