hound-cli 0.1.0__py3-none-any.whl

hound_cli/workflows/launch.py

@@ -0,0 +1,444 @@
+"""Launch account-local Hound engagements and retests."""
+
+import json
+import time
+import uuid
+from dataclasses import dataclass
+
+import click
+import questionary
+from botocore.exceptions import BotoCoreError, ClientError
+
+from hound_cli.aws import (
+    _aws_account_id,
+    active_domain_work,
+    aws_client,
+    get_engagement_records,
+    get_workflow_record,
+    operator_only,
+    scan_workflow_records,
+    short_task_id,
+    sqs_queue_url,
+)
+from hound_cli.contracts.workflow import (
+    ACTIVE_INFRA_STATUSES,
+    ACTIVE_WORKFLOW_STATUSES,
+    ENGAGEMENT_RELAUNCH_STATUSES,
+    RETEST_LAUNCH_STATUSES,
+    SKIP_DNS_CHECK_FIELD,
+    RuntimeConfig,
+    runtime_config_from_record,
+    runtime_launch_value,
+)
+from hound_cli.targets.configure import prepare_target_access
+from hound_cli.targets.verification import require_launch_authorization
+from hound_cli.ui import MENU_STYLE
+from hound_cli.workflows.selection import select_record, selected_domain
+
+CAPABILITY_PARAMETERS = {
+    "relay": "/hound/capabilities/relay",
+    "residential_proxy": "/hound/capabilities/residential-proxy",
+}
+LAUNCH_RECEIPT_TIMEOUT_SECONDS = 60
+LAUNCH_RECEIPT_POLL_SECONDS = 1
+SKIP_DNS_CHECK_HELP = "Skip live DNS authorization checks after confirming authorization out of band."
+
+
+@dataclass(frozen=True)
+class EligibleEip:
+    """An unassigned persistent Hound Elastic IP."""
+
+    allocation_id: str
+    public_ip: str
+    name: str | None
+
+    @property
+    def title(self) -> str:
+        suffix = f" — {self.name}" if self.name else ""
+        return f"{self.public_ip} ({self.allocation_id}){suffix}"
+
+
+@dataclass(frozen=True)
+class RuntimeSelection:
+    """One launch runtime plus its operator-facing EIP label."""
+
+    runtime: RuntimeConfig
+    eip_label: str
+
+
+def _select_with_default(message: str, choices: list[questionary.Choice], default: object) -> object:
+    """Start on the default while styling only the moving cursor as selected."""
+    default_choice = next((choice for choice in choices if choice.value == default), None)
+    if default_choice is None:
+        raise ValueError(f"Invalid default selection: {default}")
+    ordered_choices = [default_choice, *(choice for choice in choices if choice is not default_choice)]
+    return questionary.select(message, choices=ordered_choices, style=MENU_STYLE).unsafe_ask()
+
+
+def _record_status(record: dict) -> str:
+    statuses = [
+        f"{attr.removesuffix('_status')}={record[attr]['S']}" for attr in ACTIVE_WORKFLOW_STATUSES if attr in record
+    ]
+    return ", ".join(statuses) or "?"
+
+
+def _active_domain_precheck(ddb, domain: str) -> None:
+    active = active_domain_work(ddb, domain)
+    if not active:
+        return
+
+    status_summary = ", ".join(
+        (
+            f"{short_task_id(record['task_id']['S'])} "
+            f"({_record_status(record)}/{record.get('infra_status', {}).get('S', '?')})"
+        )
+        for record in sorted(active, key=lambda record: record["task_id"]["S"], reverse=True)
+    )
+    raise click.ClickException(f"Domain {domain} already has active Hound work: {status_summary}")
+
+
+def _capabilities() -> dict[str, bool]:
+    """Read both exact account capability parameters in one request."""
+    names = list(CAPABILITY_PARAMETERS.values())
+    try:
+        response = aws_client("ssm").get_parameters(Names=names, WithDecryption=False)
+    except (BotoCoreError, ClientError) as exc:
+        raise click.ClickException("Could not read account runtime capabilities.") from exc
+
+    returned = {parameter.get("Name"): parameter for parameter in response.get("Parameters", [])}
+    invalid = response.get("InvalidParameters", [])
+    if invalid or set(returned) != set(names):
+        missing = sorted(set(names) - set(returned) | set(invalid))
+        raise click.ClickException(f"Missing account runtime capability parameter(s): {', '.join(missing)}")
+
+    capabilities = {}
+    for capability, name in CAPABILITY_PARAMETERS.items():
+        parameter = returned[name]
+        if parameter.get("Type") != "String" or parameter.get("Value") not in {"enabled", "disabled"}:
+            raise click.ClickException(
+                f"Invalid account runtime capability {name}: expected a String with value enabled or disabled"
+            )
+        capabilities[capability] = parameter["Value"] == "enabled"
+    return capabilities
+
+
+def _eligible_eips() -> list[EligibleEip]:
+    """Discover unassigned persistent Hound EIPs directly from EC2."""
+    try:
+        response = aws_client("ec2").describe_addresses(Filters=[{"Name": "tag:app", "Values": ["hound"]}])
+    except (BotoCoreError, ClientError) as exc:
+        raise click.ClickException("Could not discover persistent Hound Elastic IPs.") from exc
+
+    eligible = []
+    for address in response.get("Addresses", []):
+        tags = {tag.get("Key"): tag.get("Value") for tag in address.get("Tags", []) if isinstance(tag.get("Key"), str)}
+        allocation_id = address.get("AllocationId")
+        public_ip = address.get("PublicIp")
+        if tags.get("app") != "hound" or "task_id" in tags:
+            continue
+        if isinstance(allocation_id, str) and isinstance(public_ip, str):
+            eligible.append(EligibleEip(allocation_id, public_ip, tags.get("Name")))
+    return sorted(eligible, key=lambda address: (address.name or "", address.public_ip, address.allocation_id))
+
+
+@click.command()
+@operator_only
+def ips():
+    """List persistent Hound Elastic IPs."""
+    addresses = _eligible_eips()
+    if not addresses:
+        click.echo("No persistent Hound Elastic IPs.")
+        return
+    for address in addresses:
+        click.echo(address.title)
+
+
+def _runtime_selection(
+    capabilities: dict[str, bool],
+    eips: list[EligibleEip],
+    current: RuntimeConfig | None = None,
+) -> RuntimeSelection:
+    """Prompt for one complete runtime map, preselecting current values."""
+    current_eip = current.eip_allocation_id if current else None
+    choices = [questionary.Choice("Dynamically assigned per-run IP", value="__dynamic__")]
+    choices.extend(questionary.Choice(address.title, value=address.allocation_id) for address in eips)
+    available_ids = {address.allocation_id for address in eips}
+    if current_eip is not None and current_eip not in available_ids:
+        raise click.ClickException(
+            f"Current persistent EIP {current_eip} is no longer eligible. Clean it up or choose a launchable record."
+        )
+
+    selected_eip = _select_with_default("Cloud IP", choices, current_eip or "__dynamic__")
+    if selected_eip is None:
+        raise click.Abort()
+
+    if capabilities["residential_proxy"]:
+        residential_proxy_enabled = questionary.confirm(
+            "Use the account residential proxy?",
+            default=None,
+            instruction="(y/n)",
+        ).unsafe_ask()
+        if residential_proxy_enabled is None:
+            raise click.Abort()
+    else:
+        residential_proxy_enabled = False
+
+    if capabilities["relay"]:
+        relay_enabled = questionary.confirm(
+            "Allow Hound to request operator assistance for CAPTCHAs or similar verification challenges?",
+            default=None,
+            instruction="(y/n)",
+        ).unsafe_ask()
+        if relay_enabled is None:
+            raise click.Abort()
+    else:
+        relay_enabled = False
+
+    allocation_id = None if selected_eip == "__dynamic__" else selected_eip
+    selected = next((address for address in eips if address.allocation_id == allocation_id), None)
+    return RuntimeSelection(
+        runtime=RuntimeConfig(
+            eip_allocation_id=allocation_id,
+            residential_proxy_enabled=residential_proxy_enabled,
+            relay_enabled=relay_enabled,
+        ),
+        eip_label=selected.title if selected else "Dynamically assigned per-run IP",
+    )
+
+
+def _record_is_active(record: dict) -> bool:
+    if record.get("infra_status", {}).get("S") in ACTIVE_INFRA_STATUSES:
+        return True
+    return any(
+        record.get(attribute, {}).get("S") in statuses for attribute, statuses in ACTIVE_WORKFLOW_STATUSES.items()
+    )
+
+
+def _same_eip_users(ddb, domain: str, task_id: str, allocation_id: str | None) -> list[dict]:
+    """Find other active records using a selected persistent EIP."""
+    if allocation_id is None:
+        return []
+
+    users = []
+    for record in scan_workflow_records(ddb):
+        if (
+            record.get("domain", {}).get("S") == domain and record.get("task_id", {}).get("S") == task_id
+        ) or not _record_is_active(record):
+            continue
+        try:
+            runtime = runtime_config_from_record(record)
+        except ValueError:
+            continue
+        if runtime.eip_allocation_id == allocation_id:
+            users.append(record)
+    return sorted(users, key=lambda record: record["task_id"]["S"], reverse=True)
+
+
+def _review_launch(
+    *,
+    domain: str,
+    workflow: str,
+    task_id: str,
+    selection: RuntimeSelection,
+    same_eip_users: list[dict],
+    authorization: str,
+    workflow_status: str | None = None,
+) -> None:
+    click.echo("\nLaunch review")
+    click.echo(f"  Domain:             {domain}")
+    click.echo(f"  Workflow:           {workflow}")
+    click.echo(f"  Task ID:            {task_id}")
+    if workflow == "retest":
+        click.echo(f"  Completed engagement: {task_id}")
+    if workflow_status is not None:
+        click.echo(f"  Current status:     {workflow_status}")
+    click.echo(f"  Cloud IP:           {selection.eip_label}")
+    click.echo(f"  Authorization:      {authorization}")
+    click.echo(f"  Residential proxy: {'enabled' if selection.runtime.residential_proxy_enabled else 'disabled'}")
+    click.echo(f"  Operator assistance: {'enabled' if selection.runtime.relay_enabled else 'disabled'}")
+    if same_eip_users:
+        click.echo("\n  Warning: the selected persistent EIP also appears on active work:")
+        for record in same_eip_users:
+            click.echo(
+                f"    {record['domain']['S']} — {short_task_id(record['task_id']['S'])} "
+                f"({_record_status(record)}/{record.get('infra_status', {}).get('S', '?')})"
+            )
+
+    click.confirm("\nQueue launch?", default=None, abort=True)
+
+
+def _queue_launch(
+    queue_name: str,
+    domain: str,
+    task_id: str,
+    runtime: RuntimeConfig,
+    *,
+    skip_dns_check: bool,
+) -> None:
+    message: dict[str, object] = {
+        "domain": domain,
+        "task_id": task_id,
+        "runtime": runtime_launch_value(runtime),
+    }
+    if skip_dns_check:
+        message[SKIP_DNS_CHECK_FIELD] = True
+    aws_client("sqs").send_message(
+        QueueUrl=sqs_queue_url(queue_name),
+        MessageBody=json.dumps(message),
+    )
+
+
+def _wait_for_launch_record(
+    ddb,
+    domain: str,
+    task_id: str,
+    workflow: str,
+    runtime: RuntimeConfig,
+) -> dict:
+    """Wait until the provisioner claim and runtime replacement are observable."""
+    status_attr = f"{workflow}_status"
+    deadline = time.monotonic() + LAUNCH_RECEIPT_TIMEOUT_SECONDS
+    while time.monotonic() < deadline:
+        record = get_workflow_record(ddb, domain, task_id)
+        if record is not None:
+            try:
+                observed_runtime = runtime_config_from_record(record)
+            except ValueError:
+                observed_runtime = None
+            status = record.get(status_attr, {}).get("S")
+            infra_status = record.get("infra_status", {}).get("S")
+            if observed_runtime == runtime and (status in {"queued", "running"} or infra_status != "absent"):
+                return record
+        time.sleep(LAUNCH_RECEIPT_POLL_SECONDS)
+    raise click.ClickException(
+        "Launch request was sent, but its workflow record was not observable within 60 seconds. "
+        f"Check with: hound status --domain {domain} --task-id {task_id}"
+    )
+
+
+def _show_receipt(domain: str, workflow: str, task_id: str, selection: RuntimeSelection) -> None:
+    noun = "engagements" if workflow == "engagement" else "retests"
+    click.echo("\nLaunch accepted")
+    click.echo(f"  AWS account:         {_aws_account_id()}")
+    click.echo(f"  Domain:              {domain}")
+    click.echo(f"  Workflow:            {workflow}")
+    click.echo(f"  Task ID:             {task_id}")
+    click.echo(f"  Cloud IP:            {selection.eip_label}")
+    click.echo(f"  Residential proxy:  {'enabled' if selection.runtime.residential_proxy_enabled else 'disabled'}")
+    click.echo(f"  Operator assistance: {'enabled' if selection.runtime.relay_enabled else 'disabled'}")
+    click.echo("\nFollow-up")
+    click.echo(f"  hound status --domain {domain} --task-id {task_id}")
+    click.echo(f"  hound {noun} logs --domain {domain} --task-id {task_id}")
+    click.echo(f"  hound {noun} stop --domain {domain} --task-id {task_id}")
+
+
+def _select_engagement_launch(records: list[dict]) -> dict | None:
+    """Select a failed/cancelled engagement for relaunch, or create a new one."""
+    if not records:
+        return None
+
+    records = sorted(records, key=lambda record: record["task_id"]["S"], reverse=True)
+    choices = [questionary.Choice("Create a new engagement", value="__new__")]
+    choices.extend(
+        questionary.Choice(
+            f"Relaunch {record['engagement_status']['S']} — {short_task_id(record['task_id']['S'])}",
+            value=record,
+        )
+        for record in records
+    )
+    selected = _select_with_default("Engagement", choices, "__new__")
+    if selected is None:
+        raise click.Abort()
+    return None if selected == "__new__" else selected
+
+
+def _launch(
+    *,
+    workflow: str,
+    domain_option: str | None,
+    skip_dns_check: bool,
+) -> None:
+    domain = selected_domain(domain_option)
+    ddb = aws_client("dynamodb")
+    _active_domain_precheck(ddb, domain)
+    current = None
+    current_status = None
+    if workflow == "engagement":
+        record = _select_engagement_launch(get_engagement_records(ddb, domain, status=ENGAGEMENT_RELAUNCH_STATUSES))
+        if record is None:
+            task_id = str(uuid.uuid7())
+        else:
+            task_id = record["task_id"]["S"]
+            try:
+                current = runtime_config_from_record(record)
+            except ValueError as exc:
+                raise click.ClickException(f"Engagement record has invalid runtime: {exc}") from exc
+            current_status = record["engagement_status"]["S"]
+    else:
+        records = [
+            record
+            for record in get_engagement_records(ddb, domain, status="completed")
+            if record.get("infra_status", {}).get("S") == "absent"
+            and record.get("retest_status", {}).get("S") in (None, *RETEST_LAUNCH_STATUSES)
+        ]
+        if not records:
+            raise click.ClickException(f"No retestable completed engagements for {domain}")
+        record = select_record(records, label="retest", status_attr="retest_status")
+        task_id = record["task_id"]["S"]
+        current_status = record.get("retest_status", {}).get("S", "not started")
+        try:
+            current = runtime_config_from_record(record)
+        except ValueError as exc:
+            raise click.ClickException(f"Retest record has invalid runtime: {exc}") from exc
+
+    prepare_target_access(domain)
+    authorization = require_launch_authorization(domain, skip_dns_check=skip_dns_check)
+    capabilities = _capabilities()
+    eips = _eligible_eips()
+    selection = _runtime_selection(capabilities, eips, current=current)
+    eip_users = _same_eip_users(ddb, domain, task_id, selection.runtime.eip_allocation_id)
+    _review_launch(
+        domain=domain,
+        workflow=workflow,
+        task_id=task_id,
+        selection=selection,
+        same_eip_users=eip_users,
+        authorization=authorization,
+        workflow_status=current_status,
+    )
+
+    queue_name = f"hound-{workflow}-provisioner"
+    _queue_launch(
+        queue_name,
+        domain,
+        task_id,
+        selection.runtime,
+        skip_dns_check=skip_dns_check,
+    )
+    _wait_for_launch_record(ddb, domain, task_id, workflow, selection.runtime)
+    _show_receipt(domain, workflow, task_id, selection)
+
+
+def _launch_options(command):
+    command = click.option("--domain", help="Use this exact target domain.")(command)
+    return click.option(
+        "--skip-dns-check",
+        is_flag=True,
+        help=SKIP_DNS_CHECK_HELP,
+    )(command)
+
+
+@click.command(name="launch")
+@_launch_options
+@operator_only
+def engagement_launch(domain: str | None, skip_dns_check: bool):
+    """Start a new penetration test or relaunch a previous one."""
+    _launch(workflow="engagement", domain_option=domain, skip_dns_check=skip_dns_check)
+
+
+@click.command(name="launch")
+@_launch_options
+@operator_only
+def retest_launch(domain: str | None, skip_dns_check: bool):
+    """Start or relaunch a retest for a completed penetration test."""
+    _launch(workflow="retest", domain_option=domain, skip_dns_check=skip_dns_check)

hound_cli/workflows/logs.py

@@ -0,0 +1,197 @@
+"""View workflow log streams.
+
+Shows the full log stream — thinking, subagent spawns, and tool calls.
+Use --tail to keep polling for new events.
+
+Usage:
+    hound engagements logs
+    hound engagements logs --tail
+    hound retests logs
+    hound retests logs --tail
+"""
+
+import json
+import signal
+import sys
+import time
+
+import click
+from botocore.exceptions import ClientError
+
+from hound_cli.aws import (
+    aws_client,
+    get_engagement_records,
+    get_retest_records,
+    get_workflow_record,
+    operator_only,
+)
+from hound_cli.workflows.selection import canonical_task_id, select_record, selected_domain
+
+STATUSES_WITH_LOGS = ["running", "completed", "failed", "cancelled"]
+
+POLL_INTERVAL_SECONDS = 5
+
+
+def _log_group(task_id: str, workflow: str) -> str:
+    """Derive CloudWatch log group from task ID and workflow."""
+    return f"/ecs/hound-task-{task_id[-12:]}-{workflow}"
+
+
+def _extract_message(raw: str) -> str | None:
+    """Extract the message field from a JSON log line, or return raw text."""
+    try:
+        return json.loads(raw).get("message")
+    except json.JSONDecodeError, AttributeError:
+        return raw
+
+
+def _print_events(events: list[dict]) -> int:
+    """Print log events, return count printed."""
+    count = 0
+    for event in events:
+        message = _extract_message(event["message"])
+        if message:
+            click.echo(message.strip())
+            click.echo()
+            count += 1
+    return count
+
+
+def _event_identity(event: dict) -> str:
+    """Return the stable CloudWatch identity used to suppress tail overlap."""
+    event_id = event.get("eventId")
+    if isinstance(event_id, str):
+        return event_id
+    return json.dumps(
+        {
+            "timestamp": event.get("timestamp"),
+            "ingestionTime": event.get("ingestionTime"),
+            "logStreamName": event.get("logStreamName"),
+            "message": event.get("message"),
+        },
+        sort_keys=True,
+    )
+
+
+def _print_logs(logs, log_group: str, tail: bool) -> None:
+    """Consume every FilterLogEvents page, then poll from the latest timestamp."""
+    base_kwargs = {"logGroupName": log_group}
+    kwargs = base_kwargs.copy()
+    count = 0
+    cursor_timestamp: int | None = None
+    cursor_event_ids: set[str] = set()
+
+    while True:
+        resp = logs.filter_log_events(**kwargs)
+        events = resp.get("events", [])
+        unseen_events = []
+        for event in events:
+            timestamp = event["timestamp"]
+            if cursor_timestamp is None or timestamp > cursor_timestamp:
+                cursor_timestamp = timestamp
+                cursor_event_ids.clear()
+            elif timestamp < cursor_timestamp:
+                continue
+
+            event_id = _event_identity(event)
+            if event_id in cursor_event_ids:
+                continue
+            cursor_event_ids.add(event_id)
+            unseen_events.append(event)
+
+        count += _print_events(unseen_events)
+
+        # FilterLogEvents pages may be empty even when more pages contain
+        # events. Consume nextToken until the service says pagination is done.
+        request_token = kwargs.get("nextToken")
+        next_token = resp.get("nextToken")
+        if next_token and next_token != request_token:
+            kwargs["nextToken"] = next_token
+            continue
+
+        if not tail:
+            break
+
+        time.sleep(POLL_INTERVAL_SECONDS)
+        kwargs = base_kwargs.copy()
+        if cursor_timestamp is not None:
+            # startTime is inclusive. Re-read the cursor millisecond and
+            # suppress only the event IDs already printed at that timestamp,
+            # so late events sharing the timestamp cannot be skipped.
+            kwargs["startTime"] = cursor_timestamp
+
+    if count == 0:
+        click.echo("  No matching log entries found.")
+
+
+def _show_logs(
+    get_records,
+    status_attr: str,
+    label: str,
+    workflow: str,
+    tail: bool,
+    domain_option: str | None,
+    task_id: str | None,
+) -> None:
+    """Prompt for a workflow record and print its log stream."""
+    if task_id is not None and domain_option is None:
+        raise click.UsageError("--task-id requires --domain")
+    domain = selected_domain(domain_option)
+
+    ddb = aws_client("dynamodb")
+    if task_id is not None:
+        task_id = canonical_task_id(task_id)
+        exact = get_workflow_record(ddb, domain, task_id)
+        records = [exact] if exact and exact.get(status_attr, {}).get("S") in STATUSES_WITH_LOGS else []
+    else:
+        records = get_records(ddb, domain, status=STATUSES_WITH_LOGS)
+    if not records:
+        raise click.ClickException(f"No {label}s with logs for {domain}")
+
+    record = select_record(records, label=label, status_attr=status_attr, task_id=task_id)
+    task_id = record["task_id"]["S"]
+    status = record[status_attr]["S"]
+    log_group = _log_group(task_id, workflow)
+
+    click.echo(f"\n  Status:  {status}")
+    click.echo(f"  Task ID: {task_id}")
+    if tail:
+        signal.signal(signal.SIGINT, lambda *_: sys.exit(0))
+        click.echo("  Ctrl+C to stop")
+    click.echo()
+
+    cw = aws_client("logs")
+    try:
+        _print_logs(cw, log_group, tail)
+    except ClientError as e:
+        if e.response["Error"]["Code"] == "ResourceNotFoundException":
+            raise click.ClickException("Log group not found — may have expired.") from None
+        raise
+
+
+@click.command(name="logs")
+@click.option("--tail", "-t", is_flag=True, help="Keep polling for new events.")
+@click.option("--domain", help="Use this exact target domain.")
+@click.option("--task-id", help="Use one exact task; requires --domain.")
+@operator_only
+def engagement_logs(tail: bool, domain: str | None, task_id: str | None):
+    """View the log stream for an engagement."""
+    _show_logs(
+        get_engagement_records,
+        "engagement_status",
+        "engagement",
+        "engagement",
+        tail,
+        domain,
+        task_id,
+    )
+
+
+@click.command(name="logs")
+@click.option("--tail", "-t", is_flag=True, help="Keep polling for new events.")
+@click.option("--domain", help="Use this exact target domain.")
+@click.option("--task-id", help="Use one exact task; requires --domain.")
+@operator_only
+def retest_logs(tail: bool, domain: str | None, task_id: str | None):
+    """View the log stream for a retest."""
+    _show_logs(get_retest_records, "retest_status", "retest", "retest", tail, domain, task_id)