# Find the images that contain a package

Search the package list every scan keeps, to know which images carry a package the day an advisory names it.

Every scan keeps the image's full package list (its software bill of materials): every
operating-system and language package the scanner found, vulnerable or not. When an advisory
names a package, search for it here to see which of your images contain it, which version, and
which apps run them. That works before the vulnerability database lists the CVE, because the
search reads the stored list, not the scan's findings.

## Prerequisites

- `ecr:GetScanResults` on the whole registry (every repository).
- An image has a package list once a scan of it has completed. Images in use are scanned again
  within a day; to get a list for another image at once, [scan it again](scan-an-image.md).

## Search

**Console**
1. Open **Container registry**, then **Packages** under **Registry settings**.
2. Type the package name (`openssl`, `log4j-core`, `next`). Add a version to match only that
   version, or tick **Name contains** to match every package whose name contains the text.
3. Choose **Search**. Each row is an image and the place in it where the package was found; the
   **Running in** column names the apps whose machines run that image.

**CLI**
```sh
dcloud ecr packages search --name openssl
dcloud ecr packages search --name log4j --contains true --ecosystem jar
```

**API**
```http
GET /ecr/api/packages?name=openssl&version=3.0.11-1
```

## Fields

| Field                | Meaning                                                                                       |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `name`, `version`    | The package as the scanner read it; names are lower case                                      |
| `ecosystem`          | Where it comes from: `debian`, `alpine`, `ubuntu`, `npm`, `gomod`, `cargo`, `pip`, `jar` …    |
| `target`             | The operating system or the file the package was found in (`app/package-lock.json`)           |
| `purl`               | The package URL, when the scanner gave one                                                    |
| `runningIn`          | Apps whose machines last reported running this image                                          |
| `imagesWithPackages` | How many of your images have a package list; an image scanned before lists were kept has none |

Matching is by name and exact version only: the search does not compare version ranges. To find
every version below a fixed one, search by name and read the `version` column.

## Related

- [Scan an image](scan-an-image.md)
- `ecr.packages.search` · `dcloud ecr packages search`
