ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
"""Transport-neutral contracts for one-time WebSocket tickets."""
from __future__ import annotations
import hashlib
import re
import secrets
from dataclasses import dataclass, field
from datetime import UTC, datetime
from enum import Enum
from ares.core.token_sessions import require_family_id
WEBSOCKET_TICKET_TTL_SECONDS = 30
WEBSOCKET_TICKET_ENTROPY_BYTES = 32
WEBSOCKET_TICKET_PATTERN = re.compile(r"^[A-Za-z0-9_-]{43}$")
_VALID_PRINCIPAL_ROLES = frozenset(
{"team_lead", "operator", "recon", "reporter"}
)
class WebSocketTicketCredentialKind(str, Enum):
BEARER = "bearer"
API_KEY = "api_key"
def _canonical_identifier(value: str, field_name: str) -> str:
if not isinstance(value, str) or not value or value != value.strip():
raise ValueError(f"{field_name} must be a non-empty canonical string")
return value
def normalize_utc_datetime(value: datetime) -> datetime:
"""Return an aware UTC datetime without accepting an ambiguous naive value."""
if not isinstance(value, datetime) or value.tzinfo is None:
raise ValueError("timestamp must be timezone-aware")
offset = value.utcoffset()
if offset is None:
raise ValueError("timestamp must have a UTC offset")
return value.astimezone(UTC)
def format_sqlite_utc(value: datetime) -> str:
"""Format a timestamp using the canonical millisecond UTC SQLite contract."""
return (
normalize_utc_datetime(value)
.isoformat(timespec="milliseconds")
.replace("+00:00", "Z")
)
def parse_sqlite_utc(value: str) -> datetime:
"""Parse only the canonical UTC representation emitted by this module."""
if not isinstance(value, str) or not value.endswith("Z"):
raise ValueError("timestamp must use canonical UTC format")
parsed = datetime.fromisoformat(value[:-1] + "+00:00")
normalized = normalize_utc_datetime(parsed)
if format_sqlite_utc(normalized) != value:
raise ValueError("timestamp must use canonical UTC format")
return normalized
def generate_websocket_ticket() -> str:
raw_ticket = secrets.token_urlsafe(WEBSOCKET_TICKET_ENTROPY_BYTES)
if WEBSOCKET_TICKET_PATTERN.fullmatch(raw_ticket) is None:
raise RuntimeError("ticket generator returned a non-canonical value")
return raw_ticket
def is_canonical_websocket_ticket(raw_ticket: object) -> bool:
return (
isinstance(raw_ticket, str)
and WEBSOCKET_TICKET_PATTERN.fullmatch(raw_ticket) is not None
)
def hash_websocket_ticket(raw_ticket: str) -> str:
if not is_canonical_websocket_ticket(raw_ticket):
raise ValueError("ticket must use canonical format")
return hashlib.sha256(raw_ticket.encode("ascii")).hexdigest()
def normalize_api_key_scopes(raw_scopes: object) -> tuple[str, ...]:
if not isinstance(raw_scopes, str):
return ()
return tuple(
scope
for scope in raw_scopes.replace(",", " ").split()
if scope
)
def is_valid_websocket_principal_role(role: object) -> bool:
return isinstance(role, str) and role in _VALID_PRINCIPAL_ROLES
@dataclass(frozen=True, slots=True, eq=False)
class BearerTicketSource:
user_id: str = field(repr=False)
subject: str = field(repr=False)
jti: str = field(repr=False)
expires_at: datetime = field(repr=False)
family_id: str = field(repr=False)
auth_epoch: int = field(repr=False)
def __post_init__(self) -> None:
object.__setattr__(
self, "user_id", _canonical_identifier(self.user_id, "user_id")
)
object.__setattr__(
self, "subject", _canonical_identifier(self.subject, "subject")
)
object.__setattr__(self, "jti", _canonical_identifier(self.jti, "jti"))
object.__setattr__(
self, "expires_at", normalize_utc_datetime(self.expires_at)
)
object.__setattr__(self, "family_id", require_family_id(self.family_id))
if isinstance(self.auth_epoch, bool) or self.auth_epoch < 1:
raise ValueError("invalid bearer authentication epoch")
@property
def credential_kind(self) -> WebSocketTicketCredentialKind:
return WebSocketTicketCredentialKind.BEARER
@dataclass(frozen=True, slots=True, eq=False)
class ApiKeyTicketSource:
user_id: str = field(repr=False)
api_key_id: str = field(repr=False)
def __post_init__(self) -> None:
object.__setattr__(
self, "user_id", _canonical_identifier(self.user_id, "user_id")
)
object.__setattr__(
self,
"api_key_id",
_canonical_identifier(self.api_key_id, "api_key_id"),
)
@property
def credential_kind(self) -> WebSocketTicketCredentialKind:
return WebSocketTicketCredentialKind.API_KEY
@property
def required_scope(self) -> str:
return "read"
@dataclass(frozen=True, slots=True, eq=False)
class ConsumedWebSocketTicket:
campaign_id: str = field(repr=False)
user_id: str = field(repr=False)
credential_kind: WebSocketTicketCredentialKind
bearer_subject: str | None = field(default=None, repr=False)
bearer_jti: str | None = field(default=None, repr=False)
bearer_expires_at: datetime | None = field(default=None, repr=False)
bearer_family_id: str | None = field(default=None, repr=False)
bearer_auth_epoch: int | None = field(default=None, repr=False)
api_key_id: str | None = field(default=None, repr=False)
required_scope: str | None = field(default=None, repr=False)
def __post_init__(self) -> None:
object.__setattr__(
self,
"campaign_id",
_canonical_identifier(self.campaign_id, "campaign_id"),
)
object.__setattr__(
self, "user_id", _canonical_identifier(self.user_id, "user_id")
)
if self.credential_kind is WebSocketTicketCredentialKind.BEARER:
if (
self.bearer_subject is None
or self.bearer_jti is None
or self.bearer_expires_at is None
or self.bearer_family_id is None
or self.bearer_auth_epoch is None
or self.api_key_id is not None
or self.required_scope is not None
):
raise ValueError("invalid bearer ticket handle")
object.__setattr__(
self,
"bearer_subject",
_canonical_identifier(self.bearer_subject, "bearer_subject"),
)
object.__setattr__(
self,
"bearer_jti",
_canonical_identifier(self.bearer_jti, "bearer_jti"),
)
object.__setattr__(
self,
"bearer_expires_at",
normalize_utc_datetime(self.bearer_expires_at),
)
object.__setattr__(
self,
"bearer_family_id",
require_family_id(self.bearer_family_id),
)
if isinstance(self.bearer_auth_epoch, bool) or self.bearer_auth_epoch < 1:
raise ValueError("invalid bearer authentication epoch")
elif self.credential_kind is WebSocketTicketCredentialKind.API_KEY:
if (
self.api_key_id is None
or self.required_scope != "read"
or self.bearer_subject is not None
or self.bearer_jti is not None
or self.bearer_expires_at is not None
or self.bearer_family_id is not None
or self.bearer_auth_epoch is not None
):
raise ValueError("invalid API-key ticket handle")
object.__setattr__(
self,
"api_key_id",
_canonical_identifier(self.api_key_id, "api_key_id"),
)
else:
raise ValueError("invalid ticket credential kind")
@dataclass(frozen=True, slots=True, eq=False)
class WebSocketTicketPrincipal:
user_id: str = field(repr=False)
username: str = field(repr=False)
role: str
credential_kind: WebSocketTicketCredentialKind
api_key_id: str | None = field(default=None, repr=False)
api_key_scopes: tuple[str, ...] = field(default=(), repr=False)
def __post_init__(self) -> None:
object.__setattr__(
self, "user_id", _canonical_identifier(self.user_id, "user_id")
)
object.__setattr__(
self, "username", _canonical_identifier(self.username, "username")
)
if not is_valid_websocket_principal_role(self.role):
raise ValueError("invalid principal role")
if self.credential_kind is WebSocketTicketCredentialKind.BEARER:
if self.api_key_id is not None or self.api_key_scopes:
raise ValueError("bearer principal cannot contain API-key state")
elif self.credential_kind is WebSocketTicketCredentialKind.API_KEY:
if self.api_key_id is None:
raise ValueError("API-key principal requires a key identifier")
object.__setattr__(
self,
"api_key_id",
_canonical_identifier(self.api_key_id, "api_key_id"),
)
object.__setattr__(
self, "api_key_scopes", tuple(self.api_key_scopes)
)
else:
raise ValueError("invalid principal credential kind")