php-radar 0.1.0__py3-none-any.whl

php_radar/scope.py

@@ -0,0 +1,174 @@
+"""Scope file parsing, and the guardrails the network scanner passes before it sends a packet.
+
+The scope file is the authorization boundary. Each line is an IPv4 address, an IPv4 range in
+CIDR form, or a hostname, with an optional :port. IPv6 literals are refused for now. Parsing is
+offline: nothing here resolves a name or opens a socket.
+"""
+import ipaddress
+import string
+from dataclasses import dataclass
+from typing import Iterator, Union
+
+# A line with no port is probed on the two usual web ports.
+DEFAULT_PORTS = (80, 443)
+
+_LABEL_CHARS = frozenset(string.ascii_letters + string.digits + "-")
+
+_Spec = Union[ipaddress.IPv4Network, str]
+
+
+class ScopeError(Exception):
+    """The scope file cannot be read or parsed, or guard refused what it names."""
+
+
+@dataclass(frozen=True)
+class Target:
+    host: str
+    port: int
+
+
+@dataclass(frozen=True)
+class _Entry:
+    line: int
+    text: str  # the line as written, minus the comment and the padding
+    spec: _Spec  # a bare address is a /32; a name stays a string
+    ports: tuple[int, ...]
+
+    def hosts(self) -> Iterator[tuple[str, bool]]:
+        """Each host the line names, with whether the guard counts it as public."""
+        if isinstance(self.spec, str):
+            # Telling a name from public space takes a DNS lookup, and a lookup here is a side
+            # effect whose answer can change before the probe. So a name counts as public and
+            # needs the override. The one exception is localhost, which resolvers pin to loopback.
+            yield self.spec, self.spec.lower().rstrip(".") != "localhost"
+            return
+        # Judge each address on its own. A range's ends say nothing about its middle, and
+        # 0.0.0.0/1 starts and ends in private space. The host string that gets probed is
+        # built from the same address object that gets classified.
+        for addr in self.spec.hosts():
+            yield str(addr), addr.is_global
+
+
+@dataclass(frozen=True)
+class Scope:
+    source: str
+    entries: tuple[_Entry, ...]
+
+    def targets(self) -> Iterator[Target]:
+        for _, target, _ in self._walk():
+            yield target
+
+    def _walk(self) -> Iterator[tuple[_Entry, Target, bool]]:
+        # Lazy, so guard can stop at the cap instead of expanding a /8. A target listed twice
+        # (overlapping ranges, a range and one of its members) comes out once. Probing it twice
+        # would report the same box twice, because the asset inventory never merges on an ip.
+        seen: set[Target] = set()
+        for entry in self.entries:
+            for host, public in entry.hosts():
+                for port in entry.ports:
+                    target = Target(host, port)
+                    if target not in seen:
+                        seen.add(target)
+                        yield entry, target, public
+
+
+def _port(text: str) -> int:
+    # ASCII digits only, because int() also takes fullwidth and Arabic-Indic digits. A leading
+    # zero is out, which also rules out 0, and the length check keeps a huge string away from int().
+    if text.isascii() and text.isdigit() and text[0] != "0" and len(text) <= 5:
+        port = int(text)
+        if port <= 65535:
+            return port
+    raise ValueError(f"{text!r} is not a port from 1 to 65535")
+
+
+def _label_ok(label: str) -> bool:
+    return (0 < len(label) <= 63 and label[0] != "-" and label[-1] != "-"
+            and _LABEL_CHARS.issuperset(label))
+
+
+def _hostname(text: str) -> str:
+    name = text[:-1] if text.endswith(".") else text  # one trailing dot marks a rooted name
+    labels = name.split(".")
+    # The last label has to start with a letter. The OS resolver reads 2130706433, 0x7f.1 and
+    # 127.1 as addresses while ipaddress rejects them, and the last label of every such spelling
+    # starts with a digit. Without this rule they would pass as names and skip the public check.
+    if not (len(name) <= 253 and all(map(_label_ok, labels)) and labels[-1][0].isalpha()):
+        raise ValueError(f"{text!r} is not an IPv4 address, an IPv4 range, or a hostname")
+    return text
+
+
+def _spec(text: str) -> _Spec:
+    try:
+        # Strict, so 10.0.0.5/24 is an error. Widening it to 10.0.0.0/24 would probe hosts
+        # nobody listed.
+        return ipaddress.IPv4Network(text)
+    except ValueError:
+        if "/" in text:
+            raise
+    return _hostname(text)
+
+
+def _parse_entry(text: str) -> tuple[_Spec, tuple[int, ...]]:
+    if any(ch.isspace() for ch in text):
+        raise ValueError("one entry per line, with no spaces inside it")
+    if text.count(":") > 1:
+        raise ValueError("too many colons; IPv6 is not supported, so use an IPv4 address "
+                         "or a hostname")
+    spec, colon, port = text.partition(":")
+    return _spec(spec), ((_port(port),) if colon else DEFAULT_PORTS)
+
+
+def parse_scope(path: str) -> Scope:
+    """Read a scope file. An unreadable file or a single bad line raises ScopeError."""
+    try:
+        # utf-8-sig drops the byte order mark that Windows editors put at the front.
+        with open(path, encoding="utf-8-sig") as f:
+            lines = f.read().split("\n")
+    except UnicodeDecodeError as exc:
+        raise ScopeError(f"cannot read scope file {path}: it must be UTF-8 text") from exc
+    except OSError as exc:
+        raise ScopeError(f"cannot read scope file {path}: {exc.strerror or exc}") from exc
+    entries = []
+    for number, raw in enumerate(lines, 1):
+        text = raw.split("#", 1)[0].strip()
+        if not text:
+            continue
+        try:
+            spec, ports = _parse_entry(text)
+        except ValueError as exc:
+            raise ScopeError(f"{path} line {number}: {exc}") from exc
+        entries.append(_Entry(number, text, spec, ports))
+    # An empty scan would read as a clean result, so an empty file is an error.
+    if not entries:
+        raise ScopeError(f"{path} lists no targets")
+    return Scope(path, tuple(entries))
+
+
+def guard(scope: Scope, allow_public: bool, max_hosts: int) -> list[Target]:
+    """The targets a scan may probe, or a ScopeError. It fails closed and sends nothing itself.
+
+    Public space needs allow_public. So does every hostname except localhost, because a name
+    cannot be classified without DNS. max_hosts caps targets, which are host and port pairs, so
+    a host on two ports counts twice. The list comes back only when every target has passed.
+    """
+    # Only the literal True opens the gate. A flag read from the environment or a config file
+    # is a string, and the string "false" is truthy.
+    open_gate = allow_public is True
+    found: list[Target] = []
+    for entry, target, public in scope._walk():
+        if public and not open_gate:
+            where = f"{scope.source} line {entry.line}: {entry.text!r}"
+            if isinstance(entry.spec, str):
+                raise ScopeError(f"{where} is a hostname. A name cannot be checked against "
+                                 "private address space without a DNS lookup, so it needs the "
+                                 "explicit public override")
+            raise ScopeError(f"{where} reaches {target.host}, a public address, which needs "
+                             "the explicit public override")
+        found.append(target)
+        if len(found) > max_hosts:
+            raise ScopeError(f"scope expands past the cap of {max_hosts} targets (a host counts "
+                             "once per port). Narrow the ranges or raise the cap")
+    if not found:
+        raise ScopeError("scope lists no targets")
+    return found

php_radar/sources/cloud/__init__.py

@@ -0,0 +1,64 @@
+"""Cloud inventory sources, one per provider, behind one interface.
+
+A cloud source lists what an account runs and returns CLOUD Evidence for the resources that run or
+hold PHP. get_cloud_source(name) builds one. The provider's SDK is an optional install, imported
+only when its source is asked for, so the rest of php-radar runs without it.
+"""
+from typing import Any, Callable, Optional, Protocol, runtime_checkable
+
+from php_radar.model import Evidence
+from php_radar.sources.cloud.aws import AwsSource
+
+
+@runtime_checkable
+class CloudSource(Protocol):
+    """What a provider adapter offers. The runtime check lets a caller test for it."""
+
+    def inventory(self) -> list[Evidence]:
+        ...
+
+
+# The default of _boto3. A sentinel, because None has to mean a boto3 that is not installed.
+_IMPORT = object()
+
+
+def _import_boto3() -> Optional[Any]:
+    try:
+        import boto3
+    except ImportError:
+        return None
+    return boto3
+
+
+def _aws(sdk: Any) -> CloudSource:
+    module = _import_boto3() if sdk is _IMPORT else sdk
+    if module is None:
+        raise RuntimeError("the aws source needs boto3, and it is not installed. "
+                           "Install the extra with: pip install php-radar[aws]")
+    try:
+        # No argument, so credentials come from boto3's default chain and from nowhere else.
+        session = module.Session()
+    except Exception as exc:  # a profile that is not there, or a config file boto3 cannot read
+        # The message stays out. It can quote the profile name or a path.
+        raise RuntimeError(f"boto3 could not start a session ({type(exc).__name__})") from None
+    return AwsSource(session)
+
+
+_PROVIDERS: dict[str, Callable[[Any], CloudSource]] = {"aws": _aws}
+
+
+def get_cloud_source(name: str, _boto3: Any = _IMPORT) -> CloudSource:
+    """The source for the provider called name.
+
+    The only provider is aws. ValueError means name is no provider. RuntimeError means the source
+    cannot start: boto3 is not installed, and the message gives the pip command that installs it,
+    or boto3 could not make a session.
+
+    _boto3 is for tests and stands in for the boto3 module. Anything with a Session() that returns
+    a session will do. None means boto3 is not installed. By default boto3 is imported here, on
+    the call, and nowhere else.
+    """
+    if name not in _PROVIDERS:
+        choices = ", ".join(_PROVIDERS)
+        raise ValueError(f"unknown cloud provider {name!r}, the choices are: {choices}")
+    return _PROVIDERS[name](_boto3)

php_radar/sources/cloud/aws.py

@@ -0,0 +1,435 @@
+"""Reads an AWS account, read-only, and reports where PHP runs.
+
+AwsSource(session).inventory() looks at the Elastic Beanstalk environments, the Lambda functions,
+and the ECR images of a region and returns one CLOUD Evidence for each that runs or holds PHP. It
+makes four calls and every one is a read: DescribeEnvironments, ListFunctions, DescribeRepositories,
+and ListImages. A policy that allows those four is all the access it uses.
+
+The session is the way in. Its default credential chain supplies credentials when a call goes
+out, so this module takes no key as an argument and never asks the session for one. From each
+answer it copies the few fields it names, because a Lambda function record carries the values of
+its environment variables. A failed call is recorded by the class of its error and the service's
+error code. The message stays out. It can name the caller's ARN or repeat part of the request.
+
+No service reports a PHP build, so PHP is found by name, and each find carries what the name gave.
+A Beanstalk platform called "PHP 8.3 running on 64bit Amazon Linux 2023/4.3.0" gives the branch,
+8.3. The 4.3.0 is the platform's own version and is never read as PHP's. A Lambda layer called
+php-83 marks a PHP runtime and gives no version. An ECR tag gives a version when it names one. In
+a repository called php, the official image's tags do (8.3.12-fpm). Anywhere else the tag has to
+say php (php8.3, php-8.3.12).
+
+Only a full 8.3.12 hands the grader a build to compare. A branch, or the mark of PHP alone, grades
+INDETERMINATE. The PHP2Shell fix landed in a patch release of each branch, so a branch cannot say
+whether it is in, and a packaged PHP can carry the fix under an older number. For the same reason
+a full number counts unless what follows it reads as a distro revision or a pre-release, by the
+grader's own test. 8.3.12-1ubuntu2.28 could be a Ubuntu build, and a tag like it gives the branch
+alone.
+
+Every tag of an ECR repository carries the repository's ARN, so the tags of one repository fold
+into one asset whose verdict is the worst of them, and each tag keeps its own evidence line. A
+Beanstalk find carries the environment's DNS name in hostname (its CNAME, or the load balancer's
+name when there is none), so a host read or a network probe of that name merges with it. A single
+instance has an address and no load balancer. The address goes in ip, which merges nothing.
+
+Nothing is skipped quietly. A failed call, a listing that runs past its page limit, and an entry
+that cannot be read each leave a row. The row has the reason in note and kind skipped, as the repo
+scan marks its own, and with no PHP in it the row grades INDETERMINATE at LOW. A failure inside a
+repository that already showed PHP leaves a row that says PHP is there, so a repository read only
+in part is never cleared by the part that was read. Three repositories in a row that cannot be
+listed end the ECR read. A credential that expired midway would otherwise cost a slow failure for
+every repository left.
+
+Limits. A run reads one region, the session's own unless regions says otherwise. PHP that does not
+say so by name goes unseen: a Docker or ECS Beanstalk platform, a Lambda container image, a zip
+with PHP inside it, an image whose tags never say php. An ECR tag is a label somebody typed. The
+image behind it may never run, and a tag that can be pushed again may point at another build
+tomorrow. boto3's own timeouts and retries apply.
+"""
+import string
+from collections import Counter
+from typing import Any, Callable, Iterable, Iterator, NamedTuple, Optional, Union
+
+from php_radar.model import Evidence, Sapi, Source
+from php_radar.versions import PhpVersion, parse_branch
+# The grader decides what a distro revision and a pre-release are. The network source tells a name
+# from an address, and the repo scan reads a SAPI out of an image tag. Using theirs keeps a cloud
+# read in step with the other sources.
+from php_radar.knowledge import _is_prerelease, _is_revision
+from php_radar.sources.network import _identity
+from php_radar.sources.repo import _sapi
+
+# Pages read from one listing. A listing past this is cut and says so, which also ends a service
+# that keeps handing back a token.
+_MAX_PAGES = 200
+
+# The page size asked of ECR, its largest. Beanstalk and Lambda choose their own.
+_PAGE = 1000
+
+# Repositories in a row whose images cannot be listed before the ECR read stops.
+_MAX_MISSES = 3
+
+# The longest value of each kind taken from an answer. A DNS name is 253 characters at most, a tag
+# 128, and an ARN 2048. An AWS error code is far shorter than 64.
+_MAX_DNS = 253
+_MAX_TAG = 128
+_MAX_ARN = 2048
+_MAX_CODE = 64
+_MAX_TEXT = 256
+
+_NAME = frozenset(string.ascii_letters + string.digits + "-._")  # DNS names, layers, tags, codes
+_PATH = _NAME | frozenset("/")  # repository names and the URIs docker pulls from
+
+# PHP 5 is the oldest major worth reading and 9 the newest accepted, so an app version such as
+# 2.1.0 in a repository called php is not taken for PHP.
+_MAJORS = range(5, 10)
+
+_BRANCH = "{} names only the PHP branch, so the build is not read"
+
+# What an entry of each list lacks when it cannot be read. The row that counts the entries says so,
+# because a dropped environment is a puzzle otherwise. A non-ASCII application name is one cause.
+_UNREAD = {"environments": "no usable ARN", "functions": "no usable ARN",
+           "repositories": "no usable ARN or name", "images": "no usable tag"}
+
+# A person meets these two first, and the class name alone says too little.
+_KNOWN = {"NoCredentialsError": "no AWS credentials were found",
+          "NoRegionError": "no AWS region is configured"}
+
+
+class _Stop(Exception):
+    """A read that cannot go on. The message is the reason to record."""
+
+
+class _Repo(NamedTuple):
+    arn: str
+    name: str
+    uri: str  # what docker pulls from, or the name when the answer gave no usable URI
+    official: bool  # php is the last part of the name, as in a mirror of the official image
+
+
+def _fits(value: object, chars: frozenset, limit: int) -> bool:
+    return isinstance(value, str) and 0 < len(value) <= limit and chars.issuperset(value)
+
+
+def _arn(value: object, spaces: bool = False) -> Optional[str]:
+    # Printable ASCII, because the ARN becomes the identity of an asset and goes into a report
+    # line. A space is allowed only where AWS allows one. A Beanstalk environment ARN holds the
+    # application name, as in environment/My First Elastic Beanstalk Application/Test.
+    ok = (isinstance(value, str) and value.startswith("arn:") and len(value) <= _MAX_ARN
+          and value.isascii() and value.isprintable() and (spaces or " " not in value))
+    return value if ok else None
+
+
+def _dns(value: object) -> Optional[str]:
+    return value if _fits(value, _NAME, _MAX_DNS) and value[0] not in ".-" else None
+
+
+def _printable(value: str) -> bool:
+    return 0 < len(value) <= _MAX_TEXT and value.isascii() and value.isprintable()
+
+
+def _why(exc: Exception) -> str:
+    """What to record about a failed call: the error's class and, for a service error, its code.
+
+    The message is left out. It can name the caller's ARN or account, or repeat part of the request.
+    """
+    name = type(exc).__name__
+    if name in _KNOWN:
+        return f"{_KNOWN[name]} ({name})"
+    response = getattr(exc, "response", None)
+    error = response.get("Error") if isinstance(response, dict) else None
+    code = error.get("Code") if isinstance(error, dict) else None
+    return f"{name} ({code})" if _fits(code, _NAME, _MAX_CODE) and code != name else name
+
+
+def _listing(call: Callable[..., Any], items: str, into: str, out_of: str,
+             **fixed: Any) -> Iterator[object]:
+    """Each item on every page that call returns.
+
+    The continuation comes back in the answer field out_of and goes into the next call as the
+    parameter into. A call that fails, or an answer that is not the shape the service documents,
+    ends the listing with _Stop, once the items already read have been handed over.
+    """
+    params = dict(fixed)
+    for _ in range(_MAX_PAGES):
+        try:
+            page = call(**params)
+        except Exception as exc:  # botocore is optional here, so its error classes cannot be named
+            raise _Stop(_why(exc)) from None
+        if not isinstance(page, dict):
+            raise _Stop("the answer is not understood")
+        found = page.get(items)
+        if found is None:
+            found = []  # a service may leave out a list that is empty
+        if not isinstance(found, list):
+            raise _Stop("the answer is not understood")
+        yield from found
+        after = page.get(out_of)
+        if not after:
+            return
+        if not isinstance(after, str):
+            raise _Stop("the answer is not understood")
+        params[into] = after
+    raise _Stop(f"the list runs past {_MAX_PAGES} pages")
+
+
+def _where(service: str, region: Optional[str]) -> str:
+    return f"aws {service} {region}" if region else f"aws {service}"
+
+
+def _gap(service: str, region: Optional[str], why: str) -> Evidence:
+    # The repo scan marks a row about something it passed over with kind skipped. The same mark
+    # lets a caller count the gaps of every source one way.
+    return Evidence(Source.CLOUD, _where(service, region), None, Sapi.UNKNOWN,
+                    {"service": service, "kind": "skipped"}, "not inventoried: " + why)
+
+
+def _unread(service: str, region: Optional[str], count: int, what: str) -> Evidence:
+    entries = "entry" if count == 1 else "entries"
+    return _gap(service, region,
+                f"{count} {entries} in the list of {what} could not be read ({_UNREAD[what]})")
+
+
+def _number(word: str) -> Optional[str]:
+    """X.Y.Z or X.Y when the word is exactly that and could be PHP, else None."""
+    release = PhpVersion.parse(word)
+    if release is not None:
+        parts = None if release.suffix else (release.major, release.minor, release.micro)
+    else:
+        parts = parse_branch(word)
+    return ".".join(map(str, parts)) if parts and parts[0] in _MAJORS else None
+
+
+# --- Elastic Beanstalk ---
+
+def _php_platform(env: dict) -> Optional[tuple[str, str]]:
+    """(platform name, PHP number) when the environment runs a platform that names PHP."""
+    arn, stack = env.get("PlatformArn"), env.get("SolutionStackName")
+    names = []
+    if isinstance(arn, str):
+        # The name follows the first slash: ...::platform/PHP 8.3 running on 64bit Amazon Linux.
+        names.append(arn.partition("/")[2])
+    if isinstance(stack, str):
+        names.append(stack)
+    for name in names:
+        words = name.split()
+        for word, after in zip(words, words[1:]):
+            number = _number(after) if word.lower() == "php" else None
+            if number:
+                return name, number
+    return None
+
+
+def _environment(arn: str, env: dict) -> Optional[Evidence]:
+    found = _php_platform(env)
+    if found is None:
+        return None
+    name, number = found
+    signals = {"resource": arn, "service": "elasticbeanstalk", "php_present": "true"}
+    named = "the platform"
+    if _printable(name):
+        signals["platform"] = name
+        # The platform version ends the name and fixes which PHP release the environment runs,
+        # so the note gives a reader the whole name.
+        named = "platform " + name
+    host = _dns(env.get("CNAME")) or _dns(env.get("EndpointURL"))
+    if host:
+        signals.update(_identity(host))
+    note = "" if number.count(".") == 2 else _BRANCH.format(named)
+    return Evidence(Source.CLOUD, arn, number, Sapi.UNKNOWN, signals, note)
+
+
+def _beanstalk(client: Any, odd: Counter) -> Iterator[Evidence]:
+    for env in _listing(client.describe_environments, "Environments", "NextToken", "NextToken"):
+        arn = _arn(env.get("EnvironmentArn"), spaces=True) if isinstance(env, dict) else None
+        if arn is None:
+            odd["environments"] += 1
+        elif env.get("Status") != "Terminated":
+            ev = _environment(arn, env)
+            if ev is not None:
+                yield ev
+
+
+# --- Lambda ---
+
+def _layer_name(arn: object) -> Optional[str]:
+    # arn:aws:lambda:us-east-1:534081306603:layer:php-83:20, with or without the version.
+    parts = arn.split(":") if isinstance(arn, str) else []
+    ok = len(parts) >= 7 and parts[2] == "lambda" and parts[5] == "layer"
+    return parts[6] if ok and _fits(parts[6], _NAME, _MAX_TEXT) else None
+
+
+def _says_php(name: str) -> bool:
+    # A word of the name is php, or php and a number: php-83, php83, my-php-runtime. Not phpunit.
+    words = name.lower().replace("_", "-").split("-")
+    return any(w == "php" or (w.startswith("php") and w[3:].isdigit()) for w in words)
+
+
+def _php_function(fn: dict) -> str:
+    """Why the function runs PHP, in words for a note, or "" when nothing says it does."""
+    runtime = fn.get("Runtime")
+    # AWS offers no PHP runtime today. A custom one, with PHP in a layer, is how PHP gets here.
+    if _fits(runtime, _NAME, _MAX_TEXT) and runtime.lower().startswith("php"):
+        return f"runtime {runtime} names PHP, and the build is not read"
+    layers = fn.get("Layers")
+    for layer in layers if isinstance(layers, list) else []:
+        name = _layer_name(layer.get("Arn") if isinstance(layer, dict) else None)
+        if name is not None and _says_php(name):
+            return f"layer {name} marks a PHP runtime, and the build is not read"
+    return ""
+
+
+def _lambda(client: Any, odd: Counter) -> Iterator[Evidence]:
+    for fn in _listing(client.list_functions, "Functions", "Marker", "NextMarker"):
+        arn = _arn(fn.get("FunctionArn")) if isinstance(fn, dict) else None
+        if arn is None:
+            odd["functions"] += 1
+            continue
+        why = _php_function(fn)
+        if why:
+            signals = {"resource": arn, "service": "lambda", "php_present": "true"}
+            yield Evidence(Source.CLOUD, arn, None, Sapi.UNKNOWN, signals, why)
+
+
+# --- ECR ---
+
+def _number_word(words: list[str], official: bool) -> Optional[tuple[int, str]]:
+    """(index, text) of the word that should hold the PHP number in a tag, or None.
+
+    Two shapes name PHP. The word php can be followed by the number (php-8.3.12), or a word can
+    start with php and a digit and hold the number itself (php8.3.12). In a repository called php,
+    a tag names PHP by starting with the number, as the official image's tags do.
+    """
+    for at, word in enumerate(words):
+        if word == "php" and at + 1 < len(words):
+            return at + 1, words[at + 1]
+        if word.startswith("php") and word[3:4].isdigit():
+            return at, word[3:]
+    return (0, words[0]) if official else None
+
+
+def _tag_version(tag: str, official: bool) -> Optional[str]:
+    """The PHP version an image tag names, X.Y.Z or X.Y, or None when it names none.
+
+    A full number stands unless what follows it reads as a distro revision or a pre-release, by
+    the grader's own test. Then the tag gives the branch alone. The number could be the upstream
+    one of a build with fixes of its own.
+    """
+    words = tag.lower().replace("_", "-").split("-")
+    found = _number_word(words, official)
+    number = _number(found[1]) if found else None
+    if found and number is not None and number.count(".") == 2:
+        # The number parsed on its own, so it parses with a suffix after it too.
+        release = PhpVersion.parse("-".join([found[1]] + words[found[0] + 1:]))
+        if _is_revision(release) or _is_prerelease(release):
+            number = number.rpartition(".")[0]
+    return number
+
+
+def _repository(item: object) -> Optional[_Repo]:
+    if not isinstance(item, dict):
+        return None
+    arn, name = _arn(item.get("repositoryArn")), item.get("repositoryName")
+    if arn is None or not _fits(name, _PATH, _MAX_TEXT):
+        return None
+    uri = item.get("repositoryUri")
+    return _Repo(arn, name, uri if _fits(uri, _PATH, _MAX_ARN) else name,
+                 name.rpartition("/")[2] == "php")
+
+
+def _image(repo: _Repo, tag: str) -> Optional[Evidence]:
+    number = _tag_version(tag, repo.official)
+    if number is None:
+        return None
+    signals = {"resource": repo.arn, "service": "ecr", "php_present": "true"}
+    full = number.count(".") == 2
+    note = "version read from the image tag" if full else _BRANCH.format("the tag")
+    return Evidence(Source.CLOUD, f"{repo.uri}:{tag}", number, _sapi(tag.lower()), signals, note)
+
+
+def _repo_gap(repo: _Repo, why: str, saw_php: bool) -> Evidence:
+    signals = {"resource": repo.arn, "service": "ecr", "kind": "skipped"}
+    if saw_php:
+        # The part not read may hold an older build, so the part that was read cannot clear it.
+        signals["php_present"] = "true"
+    return Evidence(Source.CLOUD, repo.uri, None, Sapi.UNKNOWN, signals,
+                    "not fully inventoried: " + why)
+
+
+def _ecr(client: Any, odd: Counter) -> Iterator[Evidence]:
+    misses = 0
+    for item in _listing(client.describe_repositories, "repositories", "nextToken", "nextToken",
+                         maxResults=_PAGE):
+        repo = _repository(item)
+        if repo is None:
+            odd["repositories"] += 1
+            continue
+        saw_php = False
+        try:
+            for image in _listing(client.list_images, "imageIds", "nextToken", "nextToken",
+                                  repositoryName=repo.name, filter={"tagStatus": "TAGGED"},
+                                  maxResults=_PAGE):
+                tag = image.get("imageTag") if isinstance(image, dict) else None
+                if not _fits(tag, _NAME, _MAX_TAG):
+                    odd["images"] += 1
+                    continue
+                ev = _image(repo, tag)
+                if ev is not None:
+                    saw_php = True
+                    yield ev
+        except _Stop as stop:
+            misses += 1
+            yield _repo_gap(repo, str(stop), saw_php)
+            if misses == _MAX_MISSES:
+                raise _Stop(f"{_MAX_MISSES} repositories in a row could not be read") from None
+        else:
+            misses = 0
+
+
+_READERS = (("elasticbeanstalk", _beanstalk), ("lambda", _lambda), ("ecr", _ecr))
+
+
+class AwsSource:
+    """The PHP in an AWS account, read through a boto3 session.
+
+    session is a boto3 Session, or anything with its region_name and client(). regions is the
+    region to read as a name, or several as a list, a tuple, or any iterator of names. It is the
+    session's own by default and when it is empty. The regions read are kept in regions, so a
+    caller can say what was covered. inventory() reads afresh each time it is called.
+    """
+
+    def __init__(self, session: Any,
+                 regions: Union[str, Iterable[Optional[str]], None] = None) -> None:
+        self._session = session
+        if isinstance(regions, str):
+            # One name is one region. Read as a sequence it would be one region for each letter.
+            # An empty name is no region, so it leaves the session's own.
+            regions = [regions] if regions else None
+        self.regions = tuple(regions or ()) or (session.region_name,)
+
+    def inventory(self) -> list[Evidence]:
+        """One Evidence for each Beanstalk environment, Lambda function, and ECR image tag that
+        names PHP. Whatever could not be read leaves a row in the same list."""
+        found: list[Evidence] = []
+        for region in self.regions:
+            for service, read in _READERS:
+                found += self._read(service, region, read)
+        return found
+
+    def _client(self, service: str, region: Optional[str]) -> Any:
+        try:
+            return self._session.client(service, region_name=region)
+        except Exception as exc:  # a missing profile or region, and anything else boto3 raises
+            raise _Stop(_why(exc)) from None
+
+    def _read(self, service: str, region: Optional[str],
+              read: Callable[[Any, Counter], Iterator[Evidence]]) -> list[Evidence]:
+        found: list[Evidence] = []
+        odd: Counter = Counter()  # entries that could not be read, by the list they came from
+        try:
+            for ev in read(self._client(service, region), odd):
+                found.append(ev)
+        except _Stop as stop:
+            found.append(_gap(service, region, str(stop)))
+        # After the stop as well, so a count is never lost to a failure that comes later.
+        found.extend(_unread(service, region, count, what) for what, count in odd.items())
+        return found