breachlock-blctl 0.1.0__py3-none-any.whl

blctl/__init__.py

@@ -0,0 +1,5 @@
+"""Defines the `blctl` command-line interface package.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""

blctl/api/__init__.py

@@ -0,0 +1,9 @@
+"""Defines the BreachLock AEV public v1 API client and data contracts.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from .client import *
+from .enums import *
+from .models import *

blctl/api/client/__init__.py

@@ -0,0 +1,9 @@
+"""Defines the HTTP client for the BreachLock AEV public v1 API.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from .api_client import *
+from .api_error import *
+from .api_response_error import *

blctl/api/client/api_client.py

@@ -0,0 +1,248 @@
+"""Defines the `ApiClient` HTTP client for the BreachLock public v1 API.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TypeVar
+
+import httpx
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from blctl.api.client.api_error import ApiError
+from blctl.api.client.api_response_error import ApiResponseError
+from blctl.api.models import (
+    ApiErrorBody,
+    EngagementCreated,
+    ExternalAssetItem,
+    ExternalAssetResult,
+    ExternalNetworkEngagementRequest,
+    ExternalWebEngagementRequest,
+    InternalNetworkEngagementRequest,
+    InternalWebEngagementRequest,
+)
+
+ResponseModelT = TypeVar("ResponseModelT", bound=BaseModel)
+"""Type variable for Pydantic response models validated by `ApiClient`."""
+
+_EXTERNAL_ASSET_LIST_ADAPTER: TypeAdapter[list[ExternalAssetResult]] = TypeAdapter(
+    list[ExternalAssetResult]
+)
+"""Validates the list response from `POST /api/public/v1/external-asset`."""
+
+
+class ApiClient:
+    """Represents a client for the BreachLock AEV public v1 API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float = 60.0,
+    ) -> None:
+        """Initializes a new `ApiClient`.
+
+        Args:
+            `base_url` (`str`): The portal base URL (e.g.
+                `https://tenant.app.breachlock.com`).
+            `api_key` (`str`): The Bearer API key for authentication.
+            `timeout` (`float`): The HTTP request timeout in seconds.
+        """
+        normalised_base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=normalised_base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def __enter__(self) -> ApiClient:
+        """Enters the client context manager.
+
+        Returns:
+            `ApiClient`: This client instance.
+        """
+        return self
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Exits the client context manager and closes the underlying HTTP client."""
+        self.close()
+
+    def close(self) -> None:
+        """Closes the underlying HTTP client and releases connections."""
+        self._client.close()
+
+    def create_external_assets(
+        self,
+        items: list[ExternalAssetItem],
+    ) -> list[ExternalAssetResult]:
+        """Registers manually added external assets in batch.
+
+        Args:
+            `items` (`list[ExternalAssetItem]`): Each item must contain
+                `organization_id` and `hostname`.
+        Returns:
+            `list[ExternalAssetResult]`: The per-item result list as returned by
+                the portal.
+        """
+        endpoint = "/api/public/v1/external-asset"
+        request_body = [self._serialise_request(item) for item in items]
+        response = self._client.post(endpoint, json=request_body)
+        payload = self._read_json(response)
+        try:
+            return _EXTERNAL_ASSET_LIST_ADAPTER.validate_python(payload)
+        except ValidationError as validation_error:
+            raise ApiResponseError(endpoint, validation_error) from validation_error
+
+    def create_external_network_engagement(
+        self,
+        request: ExternalNetworkEngagementRequest,
+    ) -> EngagementCreated:
+        """Creates and launches an external network engagement.
+
+        Args:
+            `request` (`ExternalNetworkEngagementRequest`): The request model
+                matching the portal-side `CreateExternalEngagementSchema`.
+        Returns:
+            `EngagementCreated`: The created engagement summary.
+        """
+        endpoint = "/api/public/v1/engagement/network/external"
+        request_body = self._serialise_request(request)
+        response = self._client.post(endpoint, json=request_body)
+        payload = self._read_json(response)
+        return self._validate_response(endpoint, payload, EngagementCreated)
+
+    def create_internal_network_engagement(
+        self,
+        request: InternalNetworkEngagementRequest,
+    ) -> EngagementCreated:
+        """Creates and launches an internal network engagement.
+
+        Args:
+            `request` (`InternalNetworkEngagementRequest`): The request model
+                matching the portal-side `CreateInternalEngagementSchema`.
+        Returns:
+            `EngagementCreated`: The created engagement summary.
+        """
+        endpoint = "/api/public/v1/engagement/network/internal"
+        request_body = self._serialise_request(request)
+        response = self._client.post(endpoint, json=request_body)
+        payload = self._read_json(response)
+        return self._validate_response(endpoint, payload, EngagementCreated)
+
+    def create_external_web_engagement(
+        self,
+        request: ExternalWebEngagementRequest,
+    ) -> EngagementCreated:
+        """Creates and launches an external web engagement.
+
+        Args:
+            `request` (`ExternalWebEngagementRequest`): The request model
+                matching the portal-side `CreateExternalWebEngagementSchema`.
+        Returns:
+            `EngagementCreated`: The created engagement summary.
+        """
+        endpoint = "/api/public/v1/engagement/web/external"
+        request_body = self._serialise_request(request)
+        response = self._client.post(endpoint, json=request_body)
+        payload = self._read_json(response)
+        return self._validate_response(endpoint, payload, EngagementCreated)
+
+    def create_internal_web_engagement(
+        self,
+        request: InternalWebEngagementRequest,
+    ) -> EngagementCreated:
+        """Creates and launches an internal web engagement.
+
+        Args:
+            `request` (`InternalWebEngagementRequest`): The request model
+                matching the portal-side `CreateInternalWebEngagementSchema`.
+        Returns:
+            `EngagementCreated`: The created engagement summary.
+        """
+        endpoint = "/api/public/v1/engagement/web/internal"
+        request_body = self._serialise_request(request)
+        response = self._client.post(endpoint, json=request_body)
+        payload = self._read_json(response)
+        return self._validate_response(endpoint, payload, EngagementCreated)
+
+    @staticmethod
+    def _serialise_request(model: BaseModel) -> dict[str, object]:
+        """Serialises a Pydantic request model to a JSON-ready dict.
+
+        Omits fields whose value is `None` so optional portal fields accept
+        absent keys rather than explicit `null` (Zod `.optional()` semantics).
+
+        Args:
+            `model` (`BaseModel`): The request model to serialise.
+        Returns:
+            `dict[str, object]`: The serialised request body.
+        """
+        return model.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+    @staticmethod
+    def _read_json(response: httpx.Response) -> object:
+        """Reads and validates the JSON body of an HTTP response.
+
+        Raises `ApiError` when the response status indicates failure.
+
+        Args:
+            `response` (`httpx.Response`): The HTTP response to read.
+        Returns:
+            `object`: The parsed JSON body on success.
+        Raises:
+            `ApiError`: When the response status is not successful.
+        """
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if response.is_error:
+            error_body: ApiErrorBody | None = None
+            if isinstance(body, dict):
+                try:
+                    error_body = ApiErrorBody.model_validate(body)
+                except ValidationError:
+                    error_body = None
+            message = (
+                (error_body.message if error_body else None)
+                or response.reason_phrase
+                or "Request failed."
+            )
+            details = error_body.errors if error_body else None
+            raise ApiError(
+                status_code=response.status_code,
+                message=message,
+                details=details,
+            )
+        return body
+
+    @staticmethod
+    def _validate_response(
+        endpoint: str,
+        payload: object,
+        model: type[ResponseModelT],
+    ) -> ResponseModelT:
+        """Validates a successful response payload against a Pydantic model.
+
+        Args:
+            `endpoint` (`str`): The API path that returned the payload.
+            `payload` (`object`): The parsed JSON body to validate.
+            `model` (`type[ResponseModelT]`): The expected response model type.
+        Returns:
+            `ResponseModelT`: The validated response model instance.
+        Raises:
+            `ApiResponseError`: When the payload does not match the model.
+        """
+        try:
+            return model.model_validate(payload)
+        except ValidationError as validation_error:
+            raise ApiResponseError(endpoint, validation_error) from validation_error

blctl/api/client/api_error.py

@@ -0,0 +1,43 @@
+"""Defines the `ApiError` exception for public API error responses.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+import json
+
+
+class ApiError(Exception):
+    """Represents an error returned by the BreachLock AEV public API."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        details: object | None = None,
+    ) -> None:
+        """Initializes a new `ApiError`.
+
+        Args:
+            `status_code` (`int`): The HTTP status code returned by the portal.
+            `message` (`str`): The human-readable error message.
+            `details` (`object | None`): Optional structured error details from
+                the response body (e.g. Zod validation errors).
+        """
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message
+        self.details = details
+
+    def __str__(self) -> str:
+        """Returns a human-readable representation of this error.
+
+        Returns:
+            `str`: The error message, HTTP status, and optional details.
+        """
+        if self.details:
+            return (
+                f"{self.message} (HTTP {self.status_code}): "
+                f"{json.dumps(self.details, default=str)}"
+            )
+        return f"{self.message} (HTTP {self.status_code})"

blctl/api/client/api_response_error.py

@@ -0,0 +1,38 @@
+"""Defines the `ApiResponseError` exception for unexpected 2xx response shapes.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from pydantic import ValidationError
+
+
+class ApiResponseError(Exception):
+    """Represents a 2xx response body that does not match the expected schema.
+
+    This indicates either API contract drift on the server or a bug in the
+    client's models; it should not happen during normal operation.
+    """
+
+    def __init__(self, endpoint: str, validation_error: ValidationError) -> None:
+        """Initializes a new `ApiResponseError`.
+
+        Args:
+            `endpoint` (`str`): The API path that returned the unexpected body.
+            `validation_error` (`ValidationError`): The Pydantic validation
+                failure describing the schema mismatch.
+        """
+        super().__init__(str(validation_error))
+        self.endpoint = endpoint
+        self.validation_error = validation_error
+
+    def __str__(self) -> str:
+        """Returns a human-readable representation of this error.
+
+        Returns:
+            `str`: The endpoint and validation failure details.
+        """
+        return (
+            f"Unexpected response shape from {self.endpoint}: "
+            f"{self.validation_error}"
+        )

blctl/api/enums/__init__.py

@@ -0,0 +1,9 @@
+"""Defines string enumerations mirroring Prisma enums for the public v1 API.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from .scan_intensity import *
+from .score_severity import *
+from .vulnerability_confidence import *

blctl/api/enums/scan_intensity.py

@@ -0,0 +1,33 @@
+"""Defines the `ScanIntensity` enumeration for engagement scan depth.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from enum import StrEnum
+
+
+class ScanIntensity(StrEnum):
+    """An enumeration of scan intensity levels accepted by the public API."""
+
+    STEALTH = "STEALTH"
+    """Represents the stealthiest scan intensity."""
+
+    QUIET = "QUIET"
+    """Represents a quiet scan intensity."""
+
+    POLITE = "POLITE"
+    """Represents a polite scan intensity."""
+
+    NORMAL = "NORMAL"
+    """Represents the default scan intensity."""
+
+    AGGRESSIVE = "AGGRESSIVE"
+    """Represents an aggressive scan intensity."""
+
+    EXTREME = "EXTREME"
+    """Represents the most aggressive scan intensity."""
+
+
+SCAN_INTENSITY_CHOICES: list[str] = [member.value for member in ScanIntensity]
+"""Valid `--scan-intensity` values for Click option choices."""

blctl/api/enums/score_severity.py

@@ -0,0 +1,30 @@
+"""Defines the `ScoreSeverity` enumeration for engagement severity thresholds.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from enum import StrEnum
+
+
+class ScoreSeverity(StrEnum):
+    """An enumeration of severity thresholds accepted by the public API."""
+
+    NONE = "NONE"
+    """Represents no minimum severity threshold."""
+
+    LOW = "LOW"
+    """Represents a low severity threshold."""
+
+    MEDIUM = "MEDIUM"
+    """Represents a medium severity threshold."""
+
+    HIGH = "HIGH"
+    """Represents a high severity threshold."""
+
+    CRITICAL = "CRITICAL"
+    """Represents a critical severity threshold."""
+
+
+SCORE_SEVERITY_CHOICES: list[str] = [member.value for member in ScoreSeverity]
+"""Valid `--severity-threshold` values for Click option choices."""

blctl/api/enums/vulnerability_confidence.py

@@ -0,0 +1,32 @@
+"""Defines the `VulnerabilityConfidence` enumeration for confidence thresholds.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from enum import StrEnum
+
+
+class VulnerabilityConfidence(StrEnum):
+    """An enumeration of vulnerability confidence thresholds accepted by the public API."""
+
+    VERY_LOW = "VERY_LOW"
+    """Represents a very low confidence threshold."""
+
+    LOW = "LOW"
+    """Represents a low confidence threshold."""
+
+    MEDIUM = "MEDIUM"
+    """Represents a medium confidence threshold."""
+
+    HIGH = "HIGH"
+    """Represents a high confidence threshold."""
+
+    VERY_HIGH = "VERY_HIGH"
+    """Represents a very high confidence threshold."""
+
+
+VULNERABILITY_CONFIDENCE_CHOICES: list[str] = [
+    member.value for member in VulnerabilityConfidence
+]
+"""Valid `--confidence-threshold` values for Click option choices."""

blctl/api/models/__init__.py

@@ -0,0 +1,26 @@
+"""Defines Pydantic models for BreachLock AEV public v1 API payloads.
+
+Python attributes are snake_case; the wire format is camelCase via
+`pydantic.alias_generators.to_camel`. Request models forbid unknown fields;
+response models ignore unknown fields for forward compatibility.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from .api_error_body import *
+from .engagement_created import *
+from .engagement_request_base import *
+from .external_asset_item import *
+from .external_asset_result import *
+from .external_network_engagement_request import *
+from .external_web_engagement_request import *
+from .internal_network_engagement_request import *
+from .internal_web_engagement_request import *
+from .network_engagement_request_base import *
+from .notify_url import *
+from .request_model import *
+from .response_model import *
+from .web_engagement_credentials import *
+from .web_engagement_request_base import *
+from .webhook_header import *

blctl/api/models/api_error_body.py

@@ -0,0 +1,17 @@
+"""Defines the `ApiErrorBody` model for non-2xx public API responses.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from blctl.api.models.response_model import ResponseModel
+
+
+class ApiErrorBody(ResponseModel):
+    """Represents a parsed non-2xx response body from the BreachLock public API."""
+
+    message: str | None = None
+    """The human-readable error message, when present."""
+
+    errors: object | None = None
+    """The Zod `flatten()` validation errors object, when the failure was a 400."""

blctl/api/models/engagement_created.py

@@ -0,0 +1,27 @@
+"""Defines the `EngagementCreated` model for engagement creation responses.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from blctl.api.models.response_model import ResponseModel
+
+
+class EngagementCreated(ResponseModel):
+    """Represents the response body returned when an engagement is created.
+
+    All engagement creation endpoints (network external/internal, web
+    external/internal) share this minimal shape.
+    """
+
+    id: str
+    """The engagement ID (CUID)."""
+
+    name: str
+    """The engagement name."""
+
+    deployment_id: str
+    """The deployment ID (CUID) running the engagement."""
+
+    deployment_command_id: str
+    """The deployment command ID (CUID) for the enqueued engage command."""

blctl/api/models/engagement_request_base.py

@@ -0,0 +1,71 @@
+"""Defines the `EngagementRequestBase` model shared by all engagement requests.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from pydantic import Field
+
+from blctl.api.enums import ScanIntensity, ScoreSeverity, VulnerabilityConfidence
+from blctl.api.models.notify_url import NotifyUrl
+from blctl.api.models.request_model import RequestModel
+
+
+class EngagementRequestBase(RequestModel):
+    """Represents fields shared by every engagement creation request.
+
+    Not intended to be instantiated directly; subclasses layer on type-specific
+    fields (network recon toggles, web credentials, etc.) and direction-specific
+    fields (`organization_id` for external, `deployment_id` for internal).
+    """
+
+    name: str
+    """The human-readable engagement name."""
+
+    asset_ids: list[str]
+    """The asset IDs (CUIDs) to include in the engagement."""
+
+    severity_threshold: ScoreSeverity = ScoreSeverity.NONE
+    """The minimum severity threshold for results."""
+
+    confidence_threshold: VulnerabilityConfidence = VulnerabilityConfidence.VERY_LOW
+    """The minimum confidence threshold for vulnerabilities."""
+
+    attempt_credential_recovery: bool = False
+    """Whether to attempt credential recovery during the engagement."""
+
+    provide_tailored_remediation_advice: bool = False
+    """Whether to provide tailored remediation advice in findings."""
+
+    capture_screenshots: bool = False
+    """Whether to capture screenshots during the engagement."""
+
+    attempt_exploitation: bool = False
+    """Whether to attempt exploitation of discovered vulnerabilities."""
+
+    learn_findings: bool = False
+    """Whether to feed findings back into the BreachLock learning pipeline."""
+
+    learn_exploits: bool = False
+    """Whether to feed exploits back into the BreachLock learning pipeline."""
+
+    excluded_protocols: list[str] = Field(default_factory=list)
+    """Protocol IDs or codes to exclude from the engagement."""
+
+    excluded_findings: list[str] = Field(default_factory=list)
+    """Finding IDs or codes to exclude from the engagement."""
+
+    excluded_cves: list[str] = Field(default_factory=list)
+    """CVE IDs to exclude from the engagement."""
+
+    included_cves: list[str] = Field(default_factory=list)
+    """CVE IDs to explicitly include in the engagement."""
+
+    notify_urls: list[NotifyUrl] = Field(default_factory=list)
+    """Webhook targets for engagement status updates."""
+
+    scan_intensity: ScanIntensity = ScanIntensity.NORMAL
+    """The scan intensity (affects host timeout and depth)."""
+
+    threat_actor_assessment_ids: list[str] = Field(default_factory=list)
+    """Threat actor assessment IDs (CUIDs) to associate with the engagement."""

blctl/api/models/external_asset_item.py

@@ -0,0 +1,17 @@
+"""Defines the `ExternalAssetItem` model for the external-asset batch endpoint.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from blctl.api.models.request_model import RequestModel
+
+
+class ExternalAssetItem(RequestModel):
+    """Represents one entry in the `POST /api/public/v1/external-asset` batch."""
+
+    organization_id: str
+    """The organization ID (CUID) under which to register the asset."""
+
+    hostname: str
+    """The hostname or IP address to register as a manually added external asset."""

blctl/api/models/external_asset_result.py

@@ -0,0 +1,34 @@
+"""Defines the `ExternalAssetResult` model for external-asset registration responses.
+
+Author: Saul Johnson <saul.j@breachlock.com>
+Since: 15/06/2026
+"""
+
+from typing import Literal
+
+from blctl.api.models.response_model import ResponseModel
+
+
+class ExternalAssetResult(ResponseModel):
+    """Represents one entry in the `POST /api/public/v1/external-asset` response."""
+
+    asset_id: str
+    """The asset ID (CUID) assigned to the registered target."""
+
+    external_asset_id: str
+    """The external asset ID (CUID) for the registration."""
+
+    domain_report_id: str
+    """The domain report ID (CUID) created or updated for this asset."""
+
+    domain_investigation_id: str
+    """The domain investigation ID (CUID) scoped to the organization."""
+
+    hostname: str
+    """The hostname that was registered."""
+
+    ip_address: str
+    """The resolved IP address for the hostname."""
+
+    status: Literal["created", "updated"]
+    """Whether the asset was newly created or updated in place."""