BED-9346 - Managed OpenHound Implementation

.github/workflows/test.yml

@@ -42,6 +42,14 @@ jobs:
         run: |
           uv pip install --python .venv -e ".[all]" --group dev
 
+      - name: Run AWS Secrets Manager tests
+        run: |
+          .venv/bin/pytest tests/test_aws_secrets_manager.py -v
+
+      - name: Run managed configuration and AWS profile adapter tests
+        run: |
+          .venv/bin/pytest tests/test_managed_configuration.py tests/test_aws_profile_adapter.py -v
+
       - name: Run log handling tests
         run: |
           .venv/bin/pytest tests/test_log_handlers.py -v

AGENTS.md

@@ -0,0 +1,23 @@
+# Repository guidance
+
+## Managed collector job queue API
+
+Managed collector job queue endpoints must use `/api/v2/collie-job-queue` in
+public URL paths. Do not use `collector` in this endpoint path: ad blockers may
+block URLs containing that term. This applies to all managed queue operations.
+This URL naming requirement does not change internal terminology. Keep names
+such as `CollectorJob`, collector-related Python identifiers, job keys, models,
+and database concepts unchanged unless a separate requirement calls for it.
+
+## BloodHound API contracts
+
+When adding or changing a BloodHound or BloodHound Enterprise (BHE) API endpoint,
+verify its path, HTTP method, parameters, request body, and response against the
+applicable API contract. Refer to the [BloodHound repository](https://github.com/SpecterOps/BloodHound)
+and [BloodHound Enterprise repository](https://github.com/SpecterOps/bloodhound-enterprise)
+for their contracts and implementation details. If an endpoint is being
+developed concurrently and is not yet in the published contract, check the
+relevant repository's implementation or mock for the agreed behavior and
+coordinate any contract changes with that work. Update existing OpenHound API
+specifications or endpoint documentation when present; do not invent a new
+specification if the repository has none.

example-configurations/bloodhound-enterprise/.dlt-example/config.toml

@@ -1,4 +1,14 @@
 # Example configuration: https://bloodhound.specterops.io/openhound/enterprise#full-configuration-example
+[openhound]
+managed = false
+
+# Managed deployments read BHE HMAC credentials from AWS Secrets Manager rather
+# than secrets.toml. The named secret must be a JSON object with token_id and
+# token_key fields. poll_interval controls the BHE scheduler cadence in seconds.
+# [openhound.aws_secrets_manager]
+# secret_name = "openhound/bhe-credentials"
+# poll_interval = 30
+
 [runtime]
 http_show_error_body = true
 log_cli_level = "WARNING"
@@ -10,8 +20,9 @@ request_max_attempts = 15
 request_backoff_factor = 1.3
 request_max_retry_delay = 900
 
-# Default: logs are set to human readable text
-# To switch to structured JSON instead, uncomment the line below (must be uppercase "JSON")
+# Self-managed mode defaults to human-readable text; managed mode defaults to
+# structured JSON. To override either default, uncomment the line below (DLT
+# requires the value to be uppercase "JSON").
 # log_format = "JSON"
 
 # BHE destination URL (non-sensitive; tokens go in secrets.toml)

pyproject.toml

@@ -19,6 +19,8 @@ dependencies = [
     "jinja2>=3.1.6",
     "types-requests==2.33.0.20260503",
     "pydantic-extra-types>=2.11.1",
+    "boto3>=1.43.90",
+    "filelock>=3.32.0",
 ]
 
 [project.optional-dependencies]

src/openhound/config.py

@@ -0,0 +1,76 @@
+"""OpenHound managed-mode configuration."""
+
+from dataclasses import dataclass
+
+import dlt
+
+
+@dataclass(frozen=True)
+class ModeDefaults:
+    """Configuration defaults that differ between OpenHound modes."""
+
+    log_format: str
+
+
+@dataclass(frozen=True)
+class ManagedBHEConfig:
+    """Managed-mode settings for BHE credentials and scheduler polling."""
+
+    secret_name: str
+    poll_interval: int
+
+
+_UNMANAGED_DEFAULTS = ModeDefaults(log_format="text")
+_MANAGED_DEFAULTS = ModeDefaults(log_format="json")
+DEFAULT_MANAGED_BHE_POLL_INTERVAL = 30
+MAX_MANAGED_BHE_POLL_INTERVAL = 599
+
+
+def is_managed() -> bool:
+    """Return whether OpenHound is configured to run in managed mode.
+
+    The value is resolved on every call so all platform code observes the current
+    DLT configuration. Missing configuration defaults to unmanaged mode. Invalid
+    boolean values raise DLT's configuration coercion error.
+    """
+
+    configured = dlt.config.get("openhound.managed", bool)
+    return configured if configured is not None else False
+
+
+def get_mode_defaults() -> ModeDefaults:
+    """Return the defaults profile for the configured mode."""
+
+    return _MANAGED_DEFAULTS if is_managed() else _UNMANAGED_DEFAULTS
+
+
+def get_managed_bhe_config() -> ManagedBHEConfig:
+    """Return AWS secret and scheduler settings used by managed BHE clients.
+
+    ``openhound.aws_secrets_manager.secret_name`` is deliberately required in
+    managed mode: there is no safe default credential source.  The scheduler
+    cadence defaults to 30 seconds, matching the historical fixed interval.
+    """
+
+    secret_name = dlt.config.get("openhound.aws_secrets_manager.secret_name", str)
+    if not secret_name:
+        raise ValueError(
+            "Managed mode requires "
+            "openhound.aws_secrets_manager.secret_name to be configured"
+        )
+
+    poll_interval = dlt.config.get(
+        "openhound.aws_secrets_manager.poll_interval", int
+    )
+    if poll_interval is None:
+        poll_interval = DEFAULT_MANAGED_BHE_POLL_INTERVAL
+    if not 0 < poll_interval <= MAX_MANAGED_BHE_POLL_INTERVAL:
+        raise ValueError(
+            "openhound.aws_secrets_manager.poll_interval must be between 1 and "
+            f"{MAX_MANAGED_BHE_POLL_INTERVAL} seconds"
+        )
+
+    return ManagedBHEConfig(
+        secret_name=secret_name,
+        poll_interval=poll_interval,
+    )