hound-cli 0.1.0__py3-none-any.whl

hound_cli/reports/close.py

@@ -0,0 +1,115 @@
+"""Upload reviewed task artifacts to S3 and securely wipe local copies.
+
+Usage:
+    hound reports close
+"""
+
+import contextlib
+import mimetypes
+import os
+import secrets as secrets_module
+from pathlib import Path
+
+import click
+from boto3.exceptions import S3UploadFailedError
+from botocore.exceptions import BotoCoreError, ClientError
+
+from hound_cli.aws import report_reviewer_only, report_s3_client, short_task_id
+from hound_cli.contracts.domain import domain_id
+from hound_cli.contracts.workflow import artifacts_bucket_name
+from hound_cli.reports.reviews import select_open_review
+
+LOCAL_REVIEW_STATE = (".git", ".hound-local")
+
+
+def _secure_wipe_file(path: Path) -> None:
+    """Overwrite a file with random bytes before deleting.
+
+    Best-effort on SSDs — wear leveling means old data may persist in
+    flash cells. Full-disk encryption is the real protection.
+    """
+    try:
+        size = path.stat().st_size
+        if size > 0:
+            with open(path, "r+b") as f:
+                remaining = size
+                while remaining:
+                    chunk_size = min(remaining, 1024 * 1024)
+                    f.write(secrets_module.token_bytes(chunk_size))
+                    remaining -= chunk_size
+                f.flush()
+                os.fsync(f.fileno())
+        path.unlink()
+    except OSError:
+        path.unlink(missing_ok=True)
+
+
+def _secure_wipe_directory(directory: Path) -> None:
+    """Recursively overwrite and delete all files, then remove directories."""
+    if directory.is_symlink():
+        directory.unlink()
+        return
+    paths = sorted(directory.rglob("*"), key=lambda path: len(path.parts), reverse=True)
+    for path in paths:
+        if path.is_file() or path.is_symlink():
+            if path.is_symlink():
+                path.unlink()
+            else:
+                _secure_wipe_file(path)
+    for path in paths:
+        if path.is_dir():
+            with contextlib.suppress(OSError):
+                path.rmdir()
+    with contextlib.suppress(OSError):
+        directory.rmdir()
+    if directory.exists() or directory.is_symlink():
+        raise OSError(f"Secure wipe did not remove directory completely: {directory}")
+
+
+def _upload_review(review_path: Path, bucket: str, task_id: str, s3) -> None:
+    """Upload local task files without removing existing S3 objects."""
+
+    def walk_error(error: OSError) -> None:
+        raise error
+
+    try:
+        for directory, directories, filenames in review_path.walk(on_error=walk_error):
+            if directory == review_path:
+                directories[:] = [name for name in directories if name not in LOCAL_REVIEW_STATE]
+            for filename in filenames:
+                path = directory / filename
+                if path.is_symlink():
+                    continue
+                key = f"{task_id}/{path.relative_to(review_path).as_posix()}"
+                content_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+                s3.upload_file(str(path), bucket, key, ExtraArgs={"ContentType": content_type})
+    except (OSError, BotoCoreError, ClientError, S3UploadFailedError) as exc:
+        raise click.ClickException(
+            f"Could not upload the report review to S3: {exc} Local files were preserved."
+        ) from exc
+
+
+@click.command(name="close")
+@report_reviewer_only
+def close_report():
+    """Upload one reviewed task to S3 and wipe its local copy."""
+    account_id, domain, task_id, review_path = select_open_review("close")
+
+    bucket = artifacts_bucket_name(domain_id(domain), account_id)
+
+    click.echo(f"\n  Account: {account_id}")
+    click.echo(f"  Domain:  {domain}")
+    click.echo(f"  Task:    {short_task_id(task_id)}")
+    click.echo(f"  Prefix:  s3://{bucket}/{task_id}/")
+    click.confirm("\nUpload and wipe?", default=None, abort=True)
+
+    _upload_review(review_path, bucket, task_id, report_s3_client(domain, task_id))
+    click.echo("  Uploaded local task to S3")
+
+    click.echo("  Wiping local files...")
+    _secure_wipe_directory(review_path)
+    for directory in (review_path.parent, review_path.parent.parent):
+        if directory.exists() and not any(directory.iterdir()):
+            directory.rmdir()
+
+    click.echo(f"\n  Closed and wiped {domain} / {short_task_id(task_id)}")

hound_cli/reports/files.py

@@ -0,0 +1,69 @@
+"""Layout and filesystem rules for local report reviews."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+PENTEST_REPORT = "pentest"
+RETEST_REPORT = "retest"
+CUSTOMER_REPORT_SOURCE_PATHS = {
+    PENTEST_REPORT: {
+        "executive_summary.md": Path("engagement/artifacts/debriefer/output/executive_summary.md"),
+        "technical_report.md": Path("engagement/artifacts/debriefer/output/technical_report.md"),
+        "hardening_report.md": Path("engagement/artifacts/debriefer/output/hardening_report.md"),
+        "coverage_summary.md": Path("engagement/artifacts/debriefer/output/coverage_summary.md"),
+    },
+    RETEST_REPORT: {
+        "retest_report.md": Path("retest/artifacts/retester/retest_report.md"),
+    },
+}
+CUSTOMER_REPORT_TYPES = tuple(CUSTOMER_REPORT_SOURCE_PATHS)
+CUSTOMER_DELIVERABLE_DIR = Path("deliverables")
+CUSTOMER_PDF_FILENAME_SUFFIXES = {
+    PENTEST_REPORT: "_Pentest_Report.pdf",
+    RETEST_REPORT: "_Pentest_Retest_Report.pdf",
+}
+
+
+class ReportFileError(ValueError):
+    """A local report path or filename is unsafe or unusable."""
+
+
+def assert_confined_path(root: Path, path: Path, label: str) -> None:
+    """Reject paths that escape root or traverse any symlink component."""
+    try:
+        relative = path.relative_to(root)
+    except ValueError as exc:
+        raise ReportFileError(f"{label} is outside its required directory: {path}") from exc
+
+    current = root
+    if current.is_symlink():
+        raise ReportFileError(f"{label} must not traverse symlinks: {current}")
+    for component in relative.parts:
+        current /= component
+        if current.is_symlink():
+            raise ReportFileError(f"{label} must not traverse symlinks: {current}")
+
+    root_resolved = root.resolve(strict=False)
+    if not path.resolve(strict=False).is_relative_to(root_resolved):
+        raise ReportFileError(f"{label} escapes its required directory: {path}")
+
+
+def read_customer_report_sources(review_path: Path, report_type: str) -> dict[str, bytes]:
+    """Read the known source files that exist for one report package."""
+    sources: dict[str, bytes] = {}
+    for name, relative in CUSTOMER_REPORT_SOURCE_PATHS[report_type].items():
+        path = review_path / relative
+        assert_confined_path(review_path, path, "Customer report source")
+        if path.is_file():
+            sources[name] = path.read_bytes()
+    return sources
+
+
+def customer_pdf_relative_path(report_type: str, customer_name: str) -> Path:
+    """Return the safe customer-facing PDF path for one review."""
+    filename_name = re.sub(r"[\W_]+", "_", customer_name.strip()).strip("_")
+    if not filename_name:
+        raise ReportFileError("Customer name must contain a letter or number for the PDF filename.")
+    return CUSTOMER_DELIVERABLE_DIR / f"{filename_name}{CUSTOMER_PDF_FILENAME_SUFFIXES[report_type]}"

hound_cli/reports/open.py

@@ -0,0 +1,113 @@
+"""Pull task-scoped customer-facing artifacts for local review.
+
+Downloads the full artifact tree and logs from S3 into
+reports/{account_id}/{domain}/{task_id}/, preserving S3 keys relative to the
+task prefix.
+
+Usage:
+    hound reports open
+"""
+
+from pathlib import Path
+
+import click
+import questionary
+
+from hound_cli.aws import (
+    _aws_account_id,
+    aws_client,
+    get_engagement_records,
+    get_workflow_record,
+    report_reviewer_only,
+    report_s3_client,
+    short_task_id,
+)
+from hound_cli.contracts.domain import domain_id
+from hound_cli.contracts.workflow import artifacts_bucket_name
+from hound_cli.reports.files import ReportFileError, assert_confined_path
+from hound_cli.reports.reviews import customer_report_review_dir
+from hound_cli.ui import MENU_STYLE
+from hound_cli.workflows.selection import canonical_task_id, selected_domain
+
+
+def _download_s3_prefix(s3, bucket: str, prefix: str, local_dir: Path) -> int:
+    """Download all objects under an S3 prefix as-is.
+
+    Returns the count of files downloaded.
+    """
+    paginator = s3.get_paginator("list_objects_v2")
+    count = 0
+    for page in paginator.paginate(Bucket=bucket, Prefix=prefix):
+        for obj in page.get("Contents", []):
+            key = obj["Key"]
+            relative = key[len(prefix) :]
+            if not relative:
+                continue
+            if Path(relative).parts[0] in {".git", ".hound-local"}:
+                raise click.ClickException("Downloaded report artifacts must not contain local review state.")
+            local_path = local_dir / relative
+            try:
+                assert_confined_path(local_dir, local_path, "Downloaded report artifact")
+            except ReportFileError as exc:
+                raise click.ClickException(str(exc)) from exc
+            local_path.parent.mkdir(parents=True, exist_ok=True)
+            s3.download_file(bucket, key, str(local_path))
+            count += 1
+    return count
+
+
+@click.command(name="open")
+@click.option("--domain", help="Use this exact target domain.")
+@click.option("--task-id", help="Use one exact task; requires --domain.")
+@report_reviewer_only
+def open_report(domain: str | None, task_id: str | None):
+    """Pull task artifacts for local review."""
+    if task_id is not None and domain is None:
+        raise click.UsageError("--task-id requires --domain")
+    domain = selected_domain(domain)
+    account_id = _aws_account_id()
+    bucket = artifacts_bucket_name(domain_id(domain), account_id)
+
+    ddb = aws_client("dynamodb")
+    if task_id is not None:
+        task_id = canonical_task_id(task_id)
+        record = get_workflow_record(ddb, domain, task_id)
+        task_ids = [task_id] if record else []
+    else:
+        task_ids = sorted(
+            (record["task_id"]["S"] for record in get_engagement_records(ddb, domain)),
+            reverse=True,
+        )
+    if not task_ids:
+        raise click.ClickException(f"No task records found for {domain}")
+    if len(task_ids) == 1:
+        task_id = task_ids[0]
+    else:
+        choices = [short_task_id(candidate) for candidate in task_ids]
+        selected = questionary.select("Task ID", choices=choices, style=MENU_STYLE).unsafe_ask()
+        if selected is None:
+            raise click.Abort()
+        task_id = task_ids[choices.index(selected)]
+
+    prefix = f"{task_id}/"
+    try:
+        review_path = customer_report_review_dir(account_id, domain, task_id)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if review_path.exists():
+        if not review_path.is_dir() or review_path.is_symlink():
+            raise click.ClickException(f"Review path is not a local directory: {review_path}")
+        click.echo(f"\n  Review already open at {review_path}")
+        return
+
+    click.echo(f"\n  Pulling s3://{bucket}/{prefix}")
+    click.echo(f"  To: {review_path}")
+    click.confirm("\nProceed?", default=True, abort=True)
+
+    s3 = report_s3_client(domain, task_id=task_id)
+    review_path.mkdir(parents=True, exist_ok=True)
+    file_count = _download_s3_prefix(s3, bucket, prefix, review_path)
+    click.echo(f"  Downloaded {file_count} files")
+
+    click.echo(f"\nReview open at {review_path}")

hound_cli/reports/render.py

@@ -0,0 +1,116 @@
+"""Render reviewed customer reports through the restricted AWS renderer."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+import click
+import questionary
+
+from hound_cli.aws import report_reviewer_only, short_task_id
+from hound_cli.reports.files import (
+    CUSTOMER_REPORT_SOURCE_PATHS,
+    CUSTOMER_REPORT_TYPES,
+    PENTEST_REPORT,
+    RETEST_REPORT,
+    ReportFileError,
+    assert_confined_path,
+    customer_pdf_relative_path,
+    read_customer_report_sources,
+)
+from hound_cli.reports.reviews import select_open_review
+from hound_cli.reports.service import ReportServiceError, render_customer_report
+from hound_cli.ui import MENU_STYLE
+
+REPORT_TYPE_LABELS = {
+    PENTEST_REPORT: "Penetration test report",
+    RETEST_REPORT: "Penetration test retest report",
+}
+
+
+def _available_report_types(review_path: Path) -> list[str]:
+    """Return report packages represented in the local review."""
+    available: list[str] = []
+    for report_type in CUSTOMER_REPORT_TYPES:
+        found_source = False
+        for relative in CUSTOMER_REPORT_SOURCE_PATHS[report_type].values():
+            path = review_path / relative
+            assert_confined_path(review_path, path, "Customer report source")
+            found_source = found_source or path.is_file()
+        if found_source:
+            available.append(report_type)
+    return available
+
+
+def _select_report_type(review_path: Path) -> str:
+    """Select a report type only when the review contains more than one."""
+    available = _available_report_types(review_path)
+    if not available:
+        raise ReportFileError("No penetration test or retest report sources were found in this review.")
+    if len(available) == 1:
+        return available[0]
+
+    choices = [
+        questionary.Choice(title=REPORT_TYPE_LABELS[report_type], value=report_type) for report_type in available
+    ]
+    selected = questionary.select("Report to render", choices=choices, style=MENU_STYLE).unsafe_ask()
+    if selected is None:
+        raise click.Abort()
+    return selected
+
+
+def _publish_pdf(review_path: Path, report_type: str, customer_name: str, pdf_bytes: bytes) -> Path:
+    output = review_path / customer_pdf_relative_path(report_type, customer_name)
+    assert_confined_path(review_path, output, "Customer PDF")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=output.parent,
+            prefix=f".{output.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary:
+            temporary.write(pdf_bytes)
+            temporary.flush()
+            os.fsync(temporary.fileno())
+            temporary_path = Path(temporary.name)
+        os.replace(temporary_path, output)
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+    return output
+
+
+@click.command(name="render")
+@click.option("--customer-name", help="Customer or application name shown on the cover.")
+@report_reviewer_only
+def render_report(customer_name: str | None) -> None:
+    """Render one reviewed customer report package as a PDF."""
+    account_id, domain, task_id, review_path = select_open_review("render")
+
+    try:
+        report_type = _select_report_type(review_path)
+        if customer_name is None:
+            default_name = domain.split(".", 1)[0].replace("-", " ").title()
+            customer_name = click.prompt("Customer name", default=default_name)
+
+        sources = read_customer_report_sources(review_path, report_type)
+        pdf_bytes = render_customer_report(
+            domain,
+            task_id,
+            report_type,
+            customer_name,
+            sources,
+        )
+        output = _publish_pdf(review_path, report_type, customer_name, pdf_bytes)
+    except (ReportFileError, ReportServiceError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    click.echo(f"\n  Account: {account_id}")
+    click.echo(f"  Domain:  {domain}")
+    click.echo(f"  Task:    {short_task_id(task_id)}")
+    click.echo(f"\nRendered customer PDF:\n  {output}")

hound_cli/reports/reviews.py

@@ -0,0 +1,120 @@
+"""Shared discovery and selection for local customer report reviews."""
+
+import os
+import uuid
+from pathlib import Path
+
+import click
+import questionary
+
+from hound_cli.aws import _aws_account_id, short_task_id
+from hound_cli.contracts.domain import normalize_domain
+from hound_cli.reports.files import ReportFileError, assert_confined_path
+from hound_cli.ui import MENU_STYLE
+
+OpenReview = tuple[str, str, str, Path]
+
+
+def customer_reports_dir() -> Path:
+    """Return the explicit override or the normal per-user report root."""
+    configured = os.environ.get("HOUND_REPORTS_DIR")
+    if configured:
+        root = Path(configured)
+        if not root.is_absolute():
+            raise click.ClickException("HOUND_REPORTS_DIR must be an absolute path")
+        return root
+    return Path.home() / "Hound" / "reports"
+
+
+def customer_report_review_dir(account_id: str, domain: str, task_id: str) -> Path:
+    """Return the only permitted local directory for one customer review."""
+    if len(account_id) != 12 or not account_id.isdigit():
+        raise ValueError(f"Invalid AWS account ID: {account_id}")
+    if normalize_domain(domain) != domain:
+        raise ValueError(f"Customer report domain is not normalized: {domain}")
+    try:
+        parsed_task_id = uuid.UUID(task_id)
+    except ValueError as exc:
+        raise ValueError(f"Customer report task ID is not a UUID: {task_id}") from exc
+    if str(parsed_task_id) != task_id:
+        raise ValueError(f"Customer report task ID is not canonical: {task_id}")
+
+    root = customer_reports_dir()
+    review_path = root / account_id / domain / task_id
+    assert_confined_path(root, review_path, "Customer report storage path")
+    return review_path
+
+
+def find_open_reviews(account_id: str | None = None) -> list[OpenReview]:
+    """Return valid local reviews, optionally for one account, newest first."""
+    base = customer_reports_dir()
+    if not base.exists():
+        return []
+    try:
+        assert_confined_path(base, base, "Customer reports directory")
+    except ReportFileError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    results: list[OpenReview] = []
+    for account_dir in sorted(base.iterdir()):
+        if account_id is not None and account_dir.name != account_id:
+            continue
+        if len(account_dir.name) == 12 and account_dir.name.isdigit():
+            try:
+                assert_confined_path(base, account_dir, "Customer report account directory")
+            except ReportFileError as exc:
+                raise click.ClickException(str(exc)) from exc
+        if not account_dir.is_dir() or len(account_dir.name) != 12 or not account_dir.name.isdigit():
+            continue
+        for domain_dir in sorted(account_dir.iterdir()):
+            if not domain_dir.name.startswith("."):
+                try:
+                    assert_confined_path(base, domain_dir, "Customer report domain directory")
+                except ReportFileError as exc:
+                    raise click.ClickException(str(exc)) from exc
+            if not domain_dir.is_dir() or domain_dir.name.startswith("."):
+                continue
+            for task_dir in sorted(domain_dir.iterdir()):
+                if not task_dir.name.startswith("."):
+                    try:
+                        assert_confined_path(base, task_dir, "Customer report task directory")
+                    except ReportFileError as exc:
+                        raise click.ClickException(str(exc)) from exc
+                if not task_dir.is_dir() or task_dir.name.startswith("."):
+                    continue
+                try:
+                    expected = customer_report_review_dir(
+                        account_dir.name,
+                        domain_dir.name,
+                        task_dir.name,
+                    )
+                except ValueError as exc:
+                    raise click.ClickException(str(exc)) from exc
+                if task_dir != expected:
+                    raise click.ClickException(f"Customer report task is outside its required directory: {task_dir}")
+                results.append(
+                    (
+                        account_dir.name,
+                        domain_dir.name,
+                        task_dir.name,
+                        task_dir,
+                    )
+                )
+    results.sort(key=lambda review: review[2], reverse=True)
+    return results
+
+
+def select_open_review(action: str) -> OpenReview:
+    """Select one local review for an operator action."""
+    account_id = _aws_account_id()
+    reviews = find_open_reviews(account_id)
+    if not reviews:
+        raise click.ClickException(
+            f"No open reviews for active AWS account {account_id}. Run 'hound reports open' first."
+        )
+    if len(reviews) == 1:
+        return reviews[0]
+
+    choices = [f"{domain} / {short_task_id(task_id)}" for _, domain, task_id, _ in reviews]
+    selected = questionary.select(f"Review to {action}", choices=choices, style=MENU_STYLE).unsafe_ask()
+    return reviews[choices.index(selected)]

hound_cli/reports/service.py

@@ -0,0 +1,81 @@
+"""Direct client for the account-local customer report renderer."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+
+from botocore.config import Config
+from botocore.exceptions import BotoCoreError, ClientError
+
+from hound_cli.aws import report_client
+
+
+class ReportServiceError(RuntimeError):
+    """The renderer could not complete the requested operation."""
+
+
+REPORT_RENDERER_FUNCTION_NAME = "hound-report-renderer"
+RENDERER_CLIENT_CONFIG = Config(read_timeout=150)
+
+
+def _invoke_renderer(
+    domain: str,
+    task_id: str,
+    request: dict[str, object],
+) -> dict[str, object]:
+    payload = json.dumps(request, separators=(",", ":"), ensure_ascii=True).encode("utf-8")
+    try:
+        response = report_client("lambda", domain, task_id, config=RENDERER_CLIENT_CONFIG).invoke(
+            FunctionName=REPORT_RENDERER_FUNCTION_NAME,
+            InvocationType="RequestResponse",
+            Payload=payload,
+        )
+        response_payload = response["Payload"].read()
+    except (BotoCoreError, ClientError, KeyError, OSError) as exc:
+        message = "Could not reach the customer report renderer. Local report data was preserved."
+        raise ReportServiceError(message) from exc
+
+    if response.get("FunctionError"):
+        raise ReportServiceError("The customer report renderer failed. Local report data was preserved.")
+    try:
+        result = json.loads(response_payload)
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ReportServiceError("The customer report renderer returned an invalid response.") from exc
+    if not isinstance(result, dict):
+        raise ReportServiceError("The customer report renderer returned an invalid response.")
+    if result.get("ok") is not True:
+        error = result.get("error")
+        message = error.get("message") if isinstance(error, dict) else None
+        if not isinstance(message, str) or not message.strip():
+            message = "The customer report renderer rejected the report."
+        raise ReportServiceError(message)
+    return result
+
+
+def _encode_sources(sources: dict[str, bytes]) -> dict[str, str]:
+    return {name: base64.b64encode(content).decode("ascii") for name, content in sources.items()}
+
+
+def render_customer_report(
+    domain: str,
+    task_id: str,
+    report_type: str,
+    company_name: str,
+    sources: dict[str, bytes],
+) -> bytes:
+    result = _invoke_renderer(
+        domain,
+        task_id,
+        {
+            "operation": "render",
+            "report_type": report_type,
+            "company_name": company_name,
+            "sources": _encode_sources(sources),
+        },
+    )
+    try:
+        return base64.b64decode(result["pdf_base64"])
+    except (KeyError, TypeError, binascii.Error) as exc:
+        raise ReportServiceError("The customer report renderer returned an invalid response.") from exc

hound_cli/roster.py

@@ -0,0 +1,64 @@
+"""Validate and load the account-local Hound agent roster."""
+
+from __future__ import annotations
+
+import re
+
+import click
+
+from hound_cli.aws import get_secret
+
+ROSTER_SECRET_ID = "hound/agents"
+_AGENT_ID = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_E164_PHONE_NUMBER = re.compile(r"^\+[1-9]\d{7,14}$")
+
+
+def validate_agent_id(value: str) -> str:
+    """Return a lowercase DNS-safe stable agent ID."""
+    if not isinstance(value, str) or not _AGENT_ID.fullmatch(value):
+        raise click.ClickException(f"Invalid agent ID in hound/agents: {value!r}.")
+    return value
+
+
+def validate_phone_number(value: str) -> str:
+    """Return an exact E.164 agent phone number."""
+    normalized = value.strip()
+    if not _E164_PHONE_NUMBER.fullmatch(normalized):
+        raise click.ClickException("The selected agent must have a valid E.164 phone_number in hound/agents.")
+    return normalized
+
+
+def validate_roster(roster: dict) -> dict:
+    """Return a validated coordinate-only Hound agent roster."""
+    if not isinstance(roster, dict) or not roster:
+        raise click.ClickException("Agent roster must be a non-empty JSON object.")
+
+    for agent_id, agent in roster.items():
+        validate_agent_id(agent_id)
+        if not isinstance(agent, dict):
+            raise click.ClickException("Agent roster entries must map agent IDs to JSON objects.")
+
+        email = agent.get("email")
+        if not isinstance(email, str) or not email.strip():
+            raise click.ClickException(f"Agent roster entry '{agent_id}' must contain a non-empty email.")
+
+        phone_number = agent.get("phone_number")
+        if phone_number is not None:
+            try:
+                validate_phone_number(phone_number)
+            except (AttributeError, click.ClickException) as exc:
+                raise click.ClickException(
+                    f"Agent roster entry '{agent_id}' phone_number must use E.164 format, for example +12125550123."
+                ) from exc
+
+    return roster
+
+
+def load_roster(client) -> dict:
+    """Load the validated agent roster from Secrets Manager."""
+    roster = get_secret(client, ROSTER_SECRET_ID)
+    if roster is None:
+        raise click.ClickException(
+            f"Agent roster not found at '{ROSTER_SECRET_ID}'. Create it in Secrets Manager first."
+        )
+    return validate_roster(roster)

hound_cli/targets/__init__.py

@@ -0,0 +1 @@
+"""Target configuration commands."""