hound-cli 0.1.0__py3-none-any.whl

hound_cli/__init__.py

@@ -0,0 +1 @@
+"""Hound CLI."""

hound_cli/__main__.py

@@ -0,0 +1,60 @@
+"""Hound cli entrypoint."""
+
+import click
+
+from hound_cli.agents import agents
+from hound_cli.inbox.command import inbox
+from hound_cli.reports.close import close_report
+from hound_cli.reports.open import open_report
+from hound_cli.reports.render import render_report
+from hound_cli.targets.verification import authorization
+from hound_cli.workflows.launch import engagement_launch, ips, retest_launch
+from hound_cli.workflows.logs import engagement_logs, retest_logs
+from hound_cli.workflows.status import account_status, engagement_status, retest_status
+from hound_cli.workflows.stop import engagement_stop, retest_stop
+
+CONTEXT = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(context_settings=CONTEXT)
+def main():
+    """Hound CLI."""
+
+
+@main.group()
+def engagements():
+    """Launch and manage penetration tests."""
+
+
+@main.group()
+def retests():
+    """Launch and manage retests."""
+
+
+@main.group()
+def reports():
+    """Manage task-scoped customer report reviews."""
+
+
+engagements.add_command(engagement_launch)
+engagements.add_command(engagement_status)
+engagements.add_command(engagement_logs)
+engagements.add_command(engagement_stop)
+
+retests.add_command(retest_launch)
+retests.add_command(retest_status)
+retests.add_command(retest_logs)
+retests.add_command(retest_stop)
+
+reports.add_command(open_report)
+reports.add_command(render_report)
+reports.add_command(close_report)
+
+main.add_command(agents)
+main.add_command(authorization)
+main.add_command(account_status)
+main.add_command(inbox)
+main.add_command(ips)
+
+if __name__ == "__main__":
+    main()

hound_cli/agents.py

@@ -0,0 +1,19 @@
+"""List the account-local Hound agent roster."""
+
+import click
+
+from hound_cli.aws import aws_client, operator_only
+from hound_cli.roster import load_roster
+
+
+@click.command("agents")
+@operator_only
+def agents() -> None:
+    """List Hound agents and their configured contact details."""
+    roster = load_roster(aws_client("secretsmanager"))
+
+    click.echo("Agents:")
+    for agent_id, agent in sorted(roster.items()):
+        click.echo(f"\n  {agent_id}")
+        click.echo(f"    Email: {agent['email']}")
+        click.echo(f"    Phone: {agent.get('phone_number') or '—'}")

hound_cli/aws.py

@@ -0,0 +1,340 @@
+"""Account-local AWS access for the Hound CLI."""
+
+import json
+import re
+from functools import cache, wraps
+
+import boto3
+import click
+from botocore.exceptions import BotoCoreError, ClientError
+
+from hound_cli.contracts.domain import domain_id, normalize_domain
+from hound_cli.contracts.workflow import ACTIVE_WORKFLOW_STATUSES, artifacts_bucket_name
+
+PENTESTS_TABLE = "hound-pentests"
+OPERATOR_ROLE = "hound-operator"
+REPORT_REVIEWER_ROLE = "hound-report-reviewer"
+REPORT_SESSION_ROLE = "hound-report-session"
+_OPERATOR_ARN = re.compile(rf"^arn:aws:sts::(?P<account_id>[0-9]{{12}}):assumed-role/{OPERATOR_ROLE}/[^/]+$")
+_REPORT_REVIEWER_ARN = re.compile(
+    rf"^arn:aws:sts::(?P<account_id>[0-9]{{12}}):assumed-role/{REPORT_REVIEWER_ROLE}/[^/]+$"
+)
+
+
+def short_task_id(task_id: str) -> str:
+    """Return the operator-facing task suffix used in AWS resource names."""
+    return task_id[-12:]
+
+
+@cache
+def _aws_region() -> str:
+    """Resolve AWS region from the current session."""
+    return boto3.session.Session().region_name or "us-east-1"
+
+
+@cache
+def _aws_identity() -> tuple[str, str]:
+    """Resolve the account and ARN for the current AWS session."""
+    try:
+        identity = boto3.client("sts", region_name=_aws_region()).get_caller_identity()
+        return identity["Account"], identity["Arn"]
+    except (BotoCoreError, ClientError, KeyError) as exc:
+        raise click.ClickException("Could not verify the active AWS identity.") from exc
+
+
+def _validate_operator_identity(account_id: str, arn: str) -> str:
+    """Return the account ID when the caller is the account-local operator."""
+    match = _OPERATOR_ARN.fullmatch(arn)
+    if match is None or match.group("account_id") != account_id:
+        raise click.ClickException(
+            f"Active AWS identity must be an assumed {OPERATOR_ROLE} role; got {arn}. "
+            "Select the managed account's operator profile."
+        )
+    return account_id
+
+
+def _validate_report_reviewer_identity(account_id: str, arn: str) -> str:
+    """Return the account ID when the caller is the account-local report reviewer."""
+    match = _REPORT_REVIEWER_ARN.fullmatch(arn)
+    if match is None or match.group("account_id") != account_id:
+        raise click.ClickException(
+            f"Active AWS identity must be an assumed {REPORT_REVIEWER_ROLE} role; got {arn}. "
+            "Select the managed account's report-reviewer profile."
+        )
+    return account_id
+
+
+def require_operator_identity() -> str:
+    """Fail closed unless the active session uses the account-local operator role."""
+    return _validate_operator_identity(*_aws_identity())
+
+
+def require_report_reviewer_identity() -> str:
+    """Fail closed unless the active session uses the account-local report-reviewer role."""
+    return _validate_report_reviewer_identity(*_aws_identity())
+
+
+def operator_only(func):
+    """Require the normal public workflow-operator identity before running a command."""
+
+    @wraps(func)
+    def wrapped(*args, **kwargs):
+        account_id = require_operator_identity()
+        click.echo(f"AWS account: {account_id}")
+        return func(*args, **kwargs)
+
+    return wrapped
+
+
+def report_reviewer_only(func):
+    """Require the report-review identity before running a report command."""
+
+    @wraps(func)
+    def wrapped(*args, **kwargs):
+        account_id = require_report_reviewer_identity()
+        click.echo(f"AWS account: {account_id}")
+        return func(*args, **kwargs)
+
+    return wrapped
+
+
+@cache
+def _aws_account_id() -> str:
+    """Resolve AWS account ID from the current session."""
+    return _aws_identity()[0]
+
+
+def prompt_target(label: str = "Domain") -> str:
+    """Return the normalized exact submitted target used as the workflow key."""
+    raw = click.prompt(label).strip()
+    try:
+        return normalize_domain(raw)
+    except ValueError as exc:
+        raise click.ClickException(f"Invalid target: {raw}") from exc
+
+
+def get_secret(client, secret_id: str) -> dict | None:
+    """Read a JSON secret. Returns None if it doesn't exist."""
+    try:
+        resp = client.get_secret_value(SecretId=secret_id)
+        return json.loads(resp["SecretString"])
+    except ClientError as e:
+        if e.response["Error"]["Code"] == "ResourceNotFoundException":
+            return None
+        raise
+
+
+def aws_client(service: str):
+    """Create a boto3 client with the resolved region."""
+    return boto3.client(service, region_name=_aws_region())
+
+
+def put_secret(client, secret_id: str, value: dict) -> None:
+    """Create or update a JSON secret."""
+    secret_string = json.dumps(value, indent=2)
+    try:
+        client.put_secret_value(SecretId=secret_id, SecretString=secret_string)
+    except ClientError as e:
+        if e.response["Error"]["Code"] == "ResourceNotFoundException":
+            client.create_secret(Name=secret_id, SecretString=secret_string)
+        else:
+            raise
+
+
+def sqs_queue_url(queue_name: str) -> str:
+    """Return an account-local Hound queue URL."""
+    return f"https://sqs.{_aws_region()}.amazonaws.com/{_aws_account_id()}/{queue_name}"
+
+
+def _domain_records(
+    ddb,
+    table_name: str,
+    domain: str,
+    status_attr: str | None = None,
+    status: str | list[str] | None = None,
+    infra_status: str | list[str] | None = None,
+) -> list[dict]:
+    """Fetch domain records, optionally filtered by lifecycle or infra status."""
+    kwargs = {
+        "TableName": table_name,
+        "KeyConditionExpression": "#d = :d",
+        "ExpressionAttributeNames": {"#d": "domain"},
+        "ExpressionAttributeValues": {":d": {"S": domain}},
+    }
+
+    filters = []
+
+    if isinstance(status, (list, tuple, set, frozenset)):
+        if status_attr is None:
+            raise ValueError("status_attr is required when status filter is set")
+        placeholders = {f":s{i}": {"S": s} for i, s in enumerate(status)}
+        filters.append(f"{status_attr} IN ({', '.join(placeholders)})")
+        kwargs["ExpressionAttributeValues"].update(placeholders)
+    elif status:
+        if status_attr is None:
+            raise ValueError("status_attr is required when status filter is set")
+        filters.append(f"{status_attr} = :s")
+        kwargs["ExpressionAttributeValues"][":s"] = {"S": status}
+
+    if isinstance(infra_status, (list, tuple, set, frozenset)):
+        placeholders = {f":is{i}": {"S": s} for i, s in enumerate(infra_status)}
+        filters.append(f"infra_status IN ({', '.join(placeholders)})")
+        kwargs["ExpressionAttributeValues"].update(placeholders)
+    elif infra_status:
+        filters.append("infra_status = :is")
+        kwargs["ExpressionAttributeValues"][":is"] = {"S": infra_status}
+
+    if filters:
+        kwargs["FilterExpression"] = " AND ".join(filters)
+
+    records = []
+    while True:
+        page = ddb.query(**kwargs)
+        records.extend(page.get("Items", []))
+        last_key = page.get("LastEvaluatedKey")
+        if not last_key:
+            return records
+        kwargs["ExclusiveStartKey"] = last_key
+
+
+def get_workflow_record(ddb, domain: str, task_id: str) -> dict | None:
+    """Read one exact account-local workflow record."""
+    response = ddb.get_item(
+        TableName=PENTESTS_TABLE,
+        Key={"domain": {"S": domain}, "task_id": {"S": task_id}},
+    )
+    return response.get("Item")
+
+
+def scan_workflow_records(ddb) -> list[dict]:
+    """Read every account-local workflow record for the operator work queue."""
+    records = []
+    kwargs = {"TableName": PENTESTS_TABLE, "ConsistentRead": False}
+    while True:
+        page = ddb.scan(**kwargs)
+        records.extend(page.get("Items", []))
+        last_key = page.get("LastEvaluatedKey")
+        if not last_key:
+            return records
+        kwargs["ExclusiveStartKey"] = last_key
+
+
+def get_engagement_records(
+    ddb,
+    domain: str,
+    status: str | list[str] | None = None,
+    infra_status: str | list[str] | None = None,
+) -> list[dict]:
+    """Fetch engagement records for a domain, optionally filtered by status fields."""
+    return _domain_records(
+        ddb,
+        PENTESTS_TABLE,
+        domain,
+        status_attr="engagement_status",
+        status=status,
+        infra_status=infra_status,
+    )
+
+
+def get_retest_records(
+    ddb,
+    domain: str,
+    status: str | list[str] | None = None,
+    infra_status: str | list[str] | None = None,
+) -> list[dict]:
+    """Fetch engagement records that have current retest state."""
+    records = _domain_records(
+        ddb,
+        PENTESTS_TABLE,
+        domain,
+        status_attr="retest_status",
+        status=status,
+        infra_status=infra_status,
+    )
+    return [record for record in records if "retest_status" in record]
+
+
+def active_domain_work(ddb, domain: str) -> list[dict]:
+    """Return same-domain engagement records that block launch."""
+    records = get_engagement_records(ddb, domain)
+    active = []
+    for record in records:
+        infra_status = record.get("infra_status", {}).get("S")
+        if infra_status != "absent":
+            active.append(record)
+            continue
+        if any(
+            record.get(attr, {}).get("S") in active_statuses
+            for attr, active_statuses in ACTIVE_WORKFLOW_STATUSES.items()
+        ):
+            active.append(record)
+    return active
+
+
+@cache
+def _report_session(domain: str, task_id: str) -> boto3.Session:
+    """Return the task-scoped AWS session used for one report review."""
+    account_id = require_report_reviewer_identity()
+    role_arn = f"arn:aws:iam::{account_id}:role/{REPORT_SESSION_ROLE}"
+    bucket_arn = f"arn:aws:s3:::{artifacts_bucket_name(domain_id(domain), account_id)}"
+    renderer_arn = f"arn:aws:lambda:{_aws_region()}:{account_id}:function:hound-report-renderer"
+
+    session_policy = json.dumps(
+        {
+            "Version": "2012-10-17",
+            "Statement": [
+                {
+                    "Effect": "Allow",
+                    "Action": "s3:ListBucket",
+                    "Resource": bucket_arn,
+                    "Condition": {
+                        "StringLike": {
+                            "s3:prefix": [
+                                f"{task_id}/",
+                                f"{task_id}/*",
+                            ]
+                        }
+                    },
+                },
+                {
+                    "Effect": "Allow",
+                    "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
+                    "Resource": f"{bucket_arn}/{task_id}/*",
+                },
+                {
+                    "Effect": "Allow",
+                    "Action": "lambda:InvokeFunction",
+                    "Resource": renderer_arn,
+                },
+            ],
+        }
+    )
+
+    creds = aws_client("sts").assume_role(
+        RoleArn=role_arn,
+        RoleSessionName=f"report-review-{domain_id(domain)}",
+        Policy=session_policy,
+        Tags=[
+            {"Key": "domain_id", "Value": domain_id(domain)},
+            {"Key": "task_id", "Value": task_id},
+            {"Key": "target_domain", "Value": domain},
+        ],
+        DurationSeconds=900,
+    )["Credentials"]
+
+    return boto3.Session(
+        region_name=_aws_region(),
+        aws_access_key_id=creds["AccessKeyId"],
+        aws_secret_access_key=creds["SecretAccessKey"],
+        aws_session_token=creds["SessionToken"],
+    )
+
+
+def report_client(service: str, domain: str, task_id: str, *, config=None):
+    """Create an AWS client inside the report review's security boundary."""
+    return _report_session(domain, task_id).client(service, region_name=_aws_region(), config=config)
+
+
+def report_s3_client(domain: str, task_id: str):
+    """Create the task-scoped S3 client for a customer report review."""
+    return report_client("s3", domain, task_id)

hound_cli/contracts/__init__.py

@@ -0,0 +1 @@
+"""Minimal service-boundary values needed by the public CLI."""

hound_cli/contracts/domain.py

@@ -0,0 +1,129 @@
+"""Target identity and DNS verification values used by the public CLI."""
+
+import hashlib
+import ipaddress
+import urllib.parse
+
+import dns.exception
+import dns.resolver
+import idna
+from publicsuffixlist import PublicSuffixList
+
+_TXT_PREFIX = "hound-verification="
+_icann_psl = PublicSuffixList(only_icann=True)
+_resolver = dns.resolver.Resolver()
+_resolver.timeout = 1.5
+_resolver.lifetime = 2.0
+
+
+class VerificationUnavailable(RuntimeError):
+    """DNS could not determine the target's verification state."""
+
+
+def _extract_hostname(raw: str) -> str:
+    if not raw:
+        raise ValueError("Empty target")
+
+    value = raw.strip()
+    parsed = urllib.parse.urlparse(value if "://" in value or value.startswith("//") else f"//{value}")
+    try:
+        _ = parsed.port
+    except ValueError as exc:
+        raise ValueError("Invalid target") from exc
+
+    hostname = (parsed.hostname or "").strip().rstrip(".")
+    if not hostname:
+        raise ValueError("Invalid target")
+    return hostname
+
+
+def normalize_domain(raw: str) -> str:
+    """Return the canonical DNS name or IPv4 workflow key for a target."""
+    hostname = _extract_hostname(raw)
+    try:
+        address = ipaddress.ip_address(hostname)
+    except ValueError:
+        address = None
+    if address is not None:
+        if address.version != 4:
+            raise ValueError("IPv6 targets are not supported")
+        return str(address)
+
+    try:
+        domain = idna.encode(hostname, uts46=True, std3_rules=True).decode("ascii").lower()
+    except idna.IDNAError as exc:
+        raise ValueError("Invalid domain") from exc
+    if "." not in domain or not _icann_psl.privatesuffix(domain):
+        raise ValueError("Invalid domain")
+    return domain
+
+
+def is_ip_target(target: str) -> bool:
+    """Return whether a canonical target is an IPv4 address."""
+    try:
+        return ipaddress.ip_address(target).version == 4
+    except ValueError:
+        return False
+
+
+def domain_id(domain: str) -> str:
+    """Return the stable artifact-routing identifier for a target."""
+    return hashlib.sha256(normalize_domain(domain).encode()).hexdigest()[:20]
+
+
+def derive_root_domain(domain: str) -> str:
+    """Return the DNS fallback location for a canonical domain target."""
+    root_domain = _icann_psl.privatesuffix(domain)
+    if not root_domain:
+        raise ValueError(f"Invalid domain: {domain}")
+    return root_domain
+
+
+def verification_hash(account_id: str, domain: str) -> str:
+    """Return the account-scoped verification hash for a target domain."""
+    if len(account_id) != 12 or not account_id.isdigit():
+        raise ValueError("account_id must be a 12-digit AWS account ID")
+    canonical_domain = normalize_domain(domain)
+    return hashlib.sha256(f"{account_id}:{canonical_domain}".encode()).hexdigest()
+
+
+def verification_txt_value(expected_hash: str) -> str:
+    """Return the exact TXT value Hound expects in DNS."""
+    return f"{_TXT_PREFIX}{expected_hash}"
+
+
+def verification_record_names(domain: str) -> list[str]:
+    """Return the DNS names where Hound accepts the verification record."""
+    domain = normalize_domain(domain)
+    if is_ip_target(domain):
+        return []
+    root_domain = derive_root_domain(domain)
+    return [domain] if root_domain == domain else [domain, root_domain]
+
+
+def _txt_value(rdata) -> str:
+    strings = getattr(rdata, "strings", None)
+    if strings is not None:
+        return "".join(part.decode() for part in strings)
+    return rdata.to_text().strip().strip('"').strip()
+
+
+def verification_txt_present(domain: str, expected_hash: str) -> bool:
+    """Return whether the expected account-scoped TXT value is present."""
+    expected = verification_txt_value(expected_hash)
+    lookup_error: VerificationUnavailable | None = None
+
+    for location in verification_record_names(domain):
+        try:
+            answers = _resolver.resolve(location, "TXT")
+        except dns.resolver.NXDOMAIN, dns.resolver.NoAnswer:
+            continue
+        except (dns.exception.Timeout, dns.resolver.NoNameservers) as exc:
+            lookup_error = VerificationUnavailable(str(exc))
+            continue
+        if any(_txt_value(rdata) == expected for rdata in answers):
+            return True
+
+    if lookup_error:
+        raise lookup_error
+    return False

hound_cli/contracts/workflow.py

@@ -0,0 +1,76 @@
+"""Workflow values the public CLI must send or interpret."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+SKIP_DNS_CHECK_FIELD = "skip_dns_check"
+
+ENGAGEMENT_RELAUNCH_STATUSES = ("cancelled", "failed")
+RETEST_LAUNCH_STATUSES = ("completed", "failed", "cancelled")
+ACTIVE_INFRA_STATUSES = frozenset(
+    {
+        "provisioning",
+        "provisioned",
+        "destroying",
+        "provisioning_failed",
+        "destroy_failed",
+    }
+)
+
+ACTIVE_WORKFLOW_STATUSES = {
+    "engagement_status": frozenset({"queued", "running"}),
+    "retest_status": frozenset({"queued", "running"}),
+}
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    """One workflow run's complete effective runtime selection."""
+
+    eip_allocation_id: str | None
+    residential_proxy_enabled: bool
+    relay_enabled: bool
+
+
+def runtime_config_from_record(record: Mapping[str, object]) -> RuntimeConfig:
+    """Read the runtime fields displayed or reused by the public CLI."""
+    attribute = record.get("runtime")
+    if not isinstance(attribute, Mapping) or not isinstance(attribute.get("M"), Mapping):
+        raise ValueError("Workflow record runtime must be a DynamoDB map")
+
+    runtime = attribute["M"]
+    booleans: dict[str, bool] = {}
+    for field in ("relay_enabled", "residential_proxy_enabled"):
+        value = runtime.get(field)
+        if not isinstance(value, Mapping) or not isinstance(value.get("BOOL"), bool):
+            raise ValueError(f"Workflow record runtime.{field} must be a DynamoDB boolean")
+        booleans[field] = value["BOOL"]
+
+    eip_allocation_id = None
+    if "eip_allocation_id" in runtime:
+        value = runtime["eip_allocation_id"]
+        if not isinstance(value, Mapping) or not isinstance(value.get("S"), str):
+            raise ValueError("Workflow record runtime.eip_allocation_id must be a DynamoDB string")
+        eip_allocation_id = value["S"]
+
+    return RuntimeConfig(
+        eip_allocation_id=eip_allocation_id,
+        residential_proxy_enabled=booleans["residential_proxy_enabled"],
+        relay_enabled=booleans["relay_enabled"],
+    )
+
+
+def runtime_launch_value(runtime: RuntimeConfig) -> dict[str, object]:
+    """Encode a runtime selection for the public launch message."""
+    value: dict[str, object] = {
+        "residential_proxy_enabled": runtime.residential_proxy_enabled,
+        "relay_enabled": runtime.relay_enabled,
+    }
+    if runtime.eip_allocation_id is not None:
+        value["eip_allocation_id"] = runtime.eip_allocation_id
+    return value
+
+
+def artifacts_bucket_name(domain_id: str, account_id: str) -> str:
+    """Return the account-local artifact bucket for a target-domain identity."""
+    return f"hound-artifacts-{domain_id}-{account_id}"

hound_cli/inbox/__init__.py

@@ -0,0 +1 @@
+"""Agent inbox commands."""