preflight-cli 0.1.0__py3-none-any.whl

preflight/keys.py

@@ -0,0 +1,98 @@
+"""Single keypresses, for the pickers that want arrow keys.
+
+Only used when there's a real terminal on the other end. Anything else — a
+pipe, a CI job, the test runner — gets `supported() is False` and the caller
+falls back to asking a question and reading a line, so every flow stays
+scriptable.
+"""
+
+from __future__ import annotations
+
+import sys
+
+UP = "up"
+DOWN = "down"
+ENTER = "enter"
+SPACE = "space"
+ESCAPE = "escape"
+
+#: What a CSI sequence's final byte means to us.
+_CSI: dict[str, str] = {"A": UP, "B": DOWN}
+
+
+def supported() -> bool:
+    """Whether we can read keypresses one at a time."""
+    if not (sys.stdin.isatty() and sys.stdin.readable()):
+        return False
+    try:
+        if sys.platform == "win32":
+            import msvcrt  # noqa: F401
+        else:
+            import termios  # noqa: F401
+            import tty  # noqa: F401
+    except ImportError:  # pragma: no cover - platform without either
+        return False
+    return True
+
+
+def read_key() -> str:
+    """Block for one keypress and name it.
+
+    Returns `UP`, `DOWN`, `ENTER`, `SPACE`, `ESCAPE`, or the character itself
+    lowercased. Raises `KeyboardInterrupt` on Ctrl-C and `EOFError` on Ctrl-D,
+    so callers can treat them the way they treat an abandoned prompt.
+    """
+    char = _read_char_windows() if sys.platform == "win32" else _read_char_posix()
+    if char == "\x03":
+        raise KeyboardInterrupt
+    if char == "\x04":
+        raise EOFError
+    if char in ("\r", "\n"):
+        return ENTER
+    if char == " ":
+        return SPACE
+    if char == "\x1b":
+        return ESCAPE
+    return char.lower()
+
+
+def _read_char_posix() -> str:
+    """One keypress from a POSIX terminal, with escape sequences collapsed.
+
+    Reads the file descriptor rather than `sys.stdin`: the text wrapper would
+    pull a whole `ESC [ A` into its own buffer while answering `read(1)` with
+    just the ESC, and then `select` — which only sees the descriptor — would
+    report nothing left and we'd call it a bare Escape.
+    """
+    import os
+    import select
+    import termios
+    import tty
+
+    descriptor = sys.stdin.fileno()
+    saved = termios.tcgetattr(descriptor)
+    try:
+        tty.setraw(descriptor)
+        first = os.read(descriptor, 1)
+        if first != b"\x1b":
+            return first.decode("utf-8", "replace")
+        # An arrow key arrives as ESC [ A. A bare Escape arrives alone, so
+        # don't block waiting for the rest of a sequence that isn't coming.
+        rest = b""
+        while len(rest) < 2 and select.select([descriptor], [], [], 0.05)[0]:
+            rest += os.read(descriptor, 8)
+        if rest[:1] != b"[":
+            return "\x1b"
+        return _CSI.get(rest[1:2].decode("utf-8", "replace"), "\x1b")
+    finally:
+        termios.tcsetattr(descriptor, termios.TCSADRAIN, saved)
+
+
+def _read_char_windows() -> str:  # pragma: no cover - exercised on Windows only
+    """One keypress from a Windows console."""
+    import msvcrt
+
+    char = msvcrt.getwch()
+    if char in ("\x00", "\xe0"):
+        return {"H": UP, "P": DOWN}.get(msvcrt.getwch(), "\x1b")
+    return char

preflight/modules/__init__.py

@@ -0,0 +1,95 @@
+"""The module registry.
+
+`REGISTRY` is the list `preflight scan` shows and the single source of truth
+for which IAM actions end up in a generated role.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from preflight.modules.base import (
+    BASE_ACTIONS,
+    Module,
+    ModuleError,
+    ModuleNotAvailableError,
+    ModuleStatus,
+    UnknownModuleError,
+)
+from preflight.modules.cost import COST
+from preflight.modules.planned import (
+    BUS_FACTOR,
+    DELIVERY,
+    OBSERVABILITY,
+    RELIABILITY,
+    SECURITY,
+)
+
+# Display order for the picker: available modules first, then the rest in the
+# order we expect to ship them.
+REGISTRY: tuple[Module, ...] = (
+    COST,
+    SECURITY,
+    RELIABILITY,
+    DELIVERY,
+    OBSERVABILITY,
+    BUS_FACTOR,
+)
+
+__all__ = [
+    "BASE_ACTIONS",
+    "REGISTRY",
+    "Module",
+    "ModuleError",
+    "ModuleNotAvailableError",
+    "ModuleStatus",
+    "UnknownModuleError",
+    "available_modules",
+    "by_key",
+    "resolve",
+]
+
+
+def available_modules() -> tuple[Module, ...]:
+    """Modules that can run today."""
+    return tuple(module for module in REGISTRY if module.is_available)
+
+
+def by_key(key: str) -> Module | None:
+    """Look a module up by key, case- and whitespace-insensitively."""
+    wanted = key.strip().lower()
+    for module in REGISTRY:
+        if module.key == wanted:
+            return module
+    return None
+
+
+def resolve(keys: Iterable[str]) -> tuple[Module, ...]:
+    """Turn module keys into modules, in registry order.
+
+    `all` expands to every available module. Raises `UnknownModuleError` for
+    keys that don't exist and `ModuleNotAvailableError` for ones that haven't
+    shipped, so the caller can tell the user which of the two happened.
+    """
+    wanted: list[str] = []
+    for key in keys:
+        cleaned = key.strip().lower()
+        if not cleaned:
+            continue
+        if cleaned == "all":
+            wanted.extend(module.key for module in available_modules())
+        else:
+            wanted.append(cleaned)
+
+    unknown = tuple(dict.fromkeys(key for key in wanted if by_key(key) is None))
+    if unknown:
+        raise UnknownModuleError(unknown)
+
+    not_ready = tuple(
+        dict.fromkeys(key for key in wanted if not by_key(key).is_available)  # type: ignore[union-attr]
+    )
+    if not_ready:
+        raise ModuleNotAvailableError(not_ready)
+
+    selected = set(wanted)
+    return tuple(module for module in REGISTRY if module.key in selected)

preflight/modules/base.py

@@ -0,0 +1,69 @@
+"""The shape of a Preflight module.
+
+A module is a group of related checks plus the IAM actions those checks need.
+Nothing here touches AWS: a module declares its permissions so Preflight can
+build the smallest possible read-only role before any scan happens.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+# Actions every scan needs, whatever modules are selected. Preflight calls
+# GetCallerIdentity first so it can show you which account it's about to read
+# and warn you if the identity has more access than it needs.
+BASE_ACTIONS: tuple[str, ...] = ("sts:GetCallerIdentity",)
+
+
+class ModuleStatus(Enum):
+    """Whether a module can run yet."""
+
+    AVAILABLE = "available"
+    COMING_SOON = "coming-soon"
+
+    @property
+    def label(self) -> str:
+        return "available" if self is ModuleStatus.AVAILABLE else "coming soon"
+
+
+@dataclass(frozen=True)
+class Module:
+    """A named group of checks and the read-only IAM actions they need.
+
+    Modules are declared, not discovered: adding one means adding a `Module`
+    to the registry with every action its checks call. The actions are the
+    contract — `preflight scan` builds the IAM role from them, so a check that
+    calls something it didn't declare will fail against a Preflight role
+    rather than quietly reading more than the user agreed to.
+    """
+
+    key: str
+    name: str
+    summary: str
+    iam_actions: tuple[str, ...]
+    status: ModuleStatus = ModuleStatus.COMING_SOON
+
+    @property
+    def is_available(self) -> bool:
+        return self.status is ModuleStatus.AVAILABLE
+
+
+class ModuleError(Exception):
+    """Base class for problems with a module selection."""
+
+
+class UnknownModuleError(ModuleError):
+    """A requested module key isn't in the registry."""
+
+    def __init__(self, keys: tuple[str, ...]) -> None:
+        self.keys = keys
+        super().__init__(f"unknown module(s): {', '.join(keys)}")
+
+
+class ModuleNotAvailableError(ModuleError):
+    """A requested module exists but hasn't shipped yet."""
+
+    def __init__(self, keys: tuple[str, ...]) -> None:
+        self.keys = keys
+        super().__init__(f"module(s) not available yet: {', '.join(keys)}")

preflight/modules/cost.py

@@ -0,0 +1,36 @@
+"""Cost Check: what you're paying for that you aren't using."""
+
+from __future__ import annotations
+
+from preflight.modules.base import Module, ModuleStatus
+
+COST = Module(
+    key="cost",
+    name="Cost Check",
+    summary="Unattached volumes and IPs, idle NAT gateways and load balancers, "
+    "stopped instances, old snapshots, oversized instances.",
+    status=ModuleStatus.AVAILABLE,
+    iam_actions=(
+        # What exists, and how big it is.
+        "ec2:DescribeRegions",
+        "ec2:DescribeInstances",
+        "ec2:DescribeVolumes",
+        "ec2:DescribeAddresses",
+        "ec2:DescribeSnapshots",
+        "ec2:DescribeNatGateways",
+        "ec2:DescribeImages",
+        "elasticloadbalancing:DescribeLoadBalancers",
+        "elasticloadbalancing:DescribeTargetGroups",
+        "elasticloadbalancing:DescribeTargetHealth",
+        "autoscaling:DescribeAutoScalingGroups",
+        "rds:DescribeDBInstances",
+        "rds:DescribeDBSnapshots",
+        # Whether it's actually being used.
+        "cloudwatch:GetMetricStatistics",
+        # What it costs, and what the alternatives cost.
+        "ce:GetCostAndUsage",
+        "pricing:GetProducts",
+        # Who owns it.
+        "tag:GetResources",
+    ),
+)

preflight/modules/planned.py

@@ -0,0 +1,106 @@
+"""Modules that are declared but haven't shipped yet.
+
+Their actions are real: between them and `cost.py` they account for every
+action in `iam/policy.json`, which is the role you get with every module
+selected. They live here rather than in their own files until their checks
+are written — graduating one means moving it to `modules/<key>.py` and
+flipping its status to `AVAILABLE`.
+"""
+
+from __future__ import annotations
+
+from preflight.modules.base import Module
+
+SECURITY = Module(
+    key="security",
+    name="Security & IAM",
+    summary="MFA, stale access keys, root account usage, public buckets, "
+    "open security groups, CloudTrail, encryption defaults.",
+    iam_actions=(
+        "iam:GetAccountSummary",
+        "iam:GetAccountPasswordPolicy",
+        "iam:ListUsers",
+        "iam:ListAccessKeys",
+        "iam:GetAccessKeyLastUsed",
+        "iam:ListMFADevices",
+        "iam:ListRoles",
+        "iam:ListPolicies",
+        "ec2:DescribeSecurityGroups",
+        "s3:ListAllMyBuckets",
+        "s3:GetBucketLocation",
+        "s3:GetBucketPolicyStatus",
+        "s3:GetBucketPublicAccessBlock",
+        "s3:GetEncryptionConfiguration",
+        "cloudtrail:DescribeTrails",
+        "cloudtrail:GetTrailStatus",
+    ),
+)
+
+RELIABILITY = Module(
+    key="reliability",
+    name="Reliability",
+    summary="Single-AZ databases, missing backups, no autoscaling, missing health checks.",
+    iam_actions=(
+        "ec2:DescribeInstances",
+        "rds:DescribeDBInstances",
+        "rds:DescribeDBSnapshots",
+        "autoscaling:DescribeAutoScalingGroups",
+        "elasticloadbalancing:DescribeLoadBalancers",
+        "elasticloadbalancing:DescribeTargetGroups",
+        "elasticloadbalancing:DescribeTargetHealth",
+        "ecs:ListClusters",
+        "ecs:ListServices",
+        "ecs:DescribeClusters",
+        "ecs:DescribeServices",
+    ),
+)
+
+DELIVERY = Module(
+    key="delivery",
+    name="Delivery & IaC",
+    summary="How much is managed as code, CloudFormation drift, deploy strategy, "
+    "`latest` image tags, stale AMIs, SSH-only access.",
+    iam_actions=(
+        "cloudformation:ListStacks",
+        "cloudformation:DescribeStacks",
+        "cloudformation:DescribeStackDriftDetectionStatus",
+        "cloudformation:DescribeStackResourceDrifts",
+        "ecr:DescribeRepositories",
+        "ecr:DescribeImages",
+        "ec2:DescribeImages",
+        "ec2:DescribeLaunchTemplates",
+        "ec2:DescribeSecurityGroups",
+        "codedeploy:ListApplications",
+        "codedeploy:GetDeploymentConfig",
+    ),
+)
+
+OBSERVABILITY = Module(
+    key="observability",
+    name="Observability",
+    summary="Alarm coverage, log retention, where alerts actually go.",
+    iam_actions=(
+        "cloudwatch:DescribeAlarms",
+        "logs:DescribeLogGroups",
+        "sns:ListTopics",
+        "sns:ListSubscriptions",
+    ),
+)
+
+BUS_FACTOR = Module(
+    key="bus-factor",
+    name="Bus factor",
+    summary="Whether changes come from one or two people, how many admins you have, "
+    "resources with no clear owner.",
+    iam_actions=(
+        # Read-only event query. Listed as an exception to the Get/List/Describe
+        # rule in core/iam.py — it reads the CloudTrail event history and
+        # mutates nothing.
+        "cloudtrail:LookupEvents",
+        "iam:ListUsers",
+        "iam:ListRoles",
+        "iam:ListPolicies",
+        "s3:GetBucketTagging",
+        "tag:GetResources",
+    ),
+)

preflight/templates/role.cfn.yaml.j2

@@ -0,0 +1,87 @@
+# Generated by Preflight {{ version }} -- read it, then deploy it. Regenerate
+# rather than editing by hand:
+#
+#   {{ regenerate_command }}
+#
+# Modules covered:
+{% for module in modules %}
+#   - {{ module.name }} ({{ module.key }}), {{ module.count }} actions
+{% endfor %}
+{% if selected_services %}
+# Narrowed at generation time to these services:
+#   {{ selected_services | join(", ") }}
+{% endif %}
+# Always included:
+{% for action in base_actions %}
+#   - {{ action }}, so Preflight can show you which account it is reading
+{% endfor %}
+#
+# {{ actions | length }} read-only actions in total -- no write actions and no
+# wildcards. Every action below is one a check you selected actually calls.
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >
+  Dedicated read-only IAM role for Jet1 Preflight ({{ module_names }}). Creates a
+  role that can be assumed (optionally cross-account) with only the actions the
+  selected Preflight modules declare -- no write or wildcard actions. Safe to
+  deploy once and reuse for every Preflight scan.
+
+Parameters:
+  TrustedPrincipalArn:
+    Type: String
+    Description: >
+      ARN of the IAM user/role that will assume this role to run Preflight.
+      Use your own account's user/role ARN for same-account use, or an
+      external account's ARN only if you intend cross-account access.
+  ExternalId:
+    Type: String
+    Default: ""
+    Description: >
+      Optional external ID to require on AssumeRole, recommended for
+      cross-account trust relationships.
+    NoEcho: true
+
+Conditions:
+  HasExternalId: !Not [!Equals [!Ref ExternalId, ""]]
+
+Resources:
+  PreflightReadOnlyPolicy:
+    Type: AWS::IAM::ManagedPolicy
+    Properties:
+      ManagedPolicyName: {{ policy_name }}
+      Description: Read-only permissions used by Jet1 Preflight. Get*/List*/Describe* only.
+      PolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Sid: PreflightReadOnly
+            Effect: Allow
+            Action:
+{% for action in actions %}
+              - {{ action }}
+{% endfor %}
+            Resource: "*"
+
+  PreflightReadOnlyRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: {{ role_name }}
+      Description: Role assumed by Jet1 Preflight to run a read-only AWS audit.
+      MaxSessionDuration: 3600
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              AWS: !Ref TrustedPrincipalArn
+            Action: sts:AssumeRole
+            Condition: !If
+              - HasExternalId
+              - StringEquals:
+                  sts:ExternalId: !Ref ExternalId
+              - !Ref AWS::NoValue
+      ManagedPolicyArns:
+        - !Ref PreflightReadOnlyPolicy
+
+Outputs:
+  RoleArn:
+    Description: ARN to pass to `preflight scan --role-arn`
+    Value: !GetAtt PreflightReadOnlyRole.Arn