# Technology Detection

Purplemet detects technologies (frameworks, libraries, servers, languages) running on your sites and tracks their security status.

## List Technologies

```bash
purplemet-cli tech list [siteId|url] [flags]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | `100` | Page size (1–1000) |
| `--all` | `false` | Fetch every page automatically (capped by `--max`) |
| `--max` | `10000` | Hard cap on items fetched when `--all` is set |
| `--include-sites` | `false` | Include site count in output (global mode only) |
| `--json` | `false` | JSON output |

See [Pagination](configuration.md#pagination) for the full set of pagination flags shared by every `list` command.

### Two modes

| Mode | Command | Source endpoint | What you get |
|------|---------|------------------|--------------|
| Global | `tech list` | `GET /technology` | Every technology known to the subscription. The `CVEs` column is omitted here — the global endpoint doesn't compute per-instance CVE counts. Use this for inventory across all sites. |
| Per-site | `tech list <siteId\|url>` | `GET /site/<id>/technology` | Only technologies currently detected on the given site. `cveCnt` is populated per detected instance. Use this to audit a specific site's stack. |

The output columns differ slightly: the per-site mode replaces `SITES` (which is meaningless when you're already scoped to one site) with `DETECTED` (the first-detection date for that technology on that site).

**Example — global mode** (illustrative):

```bash
$ purplemet-cli tech list
NAME                  CATEGORY              VERSION     EOL         SITES
------                --------              -------     ---         -----
Nginx                 Web servers           1.25.3      -           4
React                 JavaScript frame...   18.2.0      -           7
PHP                   Server-side lang...   5.6.40      2018-12-31  2
```

> The global view intentionally omits the `CVEs` column: the `/technology` endpoint doesn't compute per-instance CVE counts, so the value would always be 0 and mislead readers. To get accurate CVE counts, scope the query to a specific site (see below).

**Example — per-site mode**:

```bash
$ purplemet-cli tech list https://your-app.com
NAME                  CATEGORY              VERSION     EOL         DETECTED    CVEs
------                --------              -------     ---         --------    ----
Nginx                 Web servers           1.25.3      -           2025-04-12  0
PHP                   Server-side lang...   5.6.40      2018-12-31  2025-04-12  12
```

## Understanding the Output

### End of Life (EOL)

Technologies past their end-of-life date no longer receive security patches. This is a significant risk — any new vulnerability discovered will remain unpatched.

The `EOL` column shows the year the version reached end of life. Use `--fail-on-eol` in your analysis to block on EOL components.

### CVE Count

The number of known CVEs (Common Vulnerabilities and Exposures) associated with the detected version. A high CVE count doesn't necessarily mean the site is exploitable — it depends on configuration and usage context — but it indicates increased risk.

### OpenSSF Scorecard

Some technologies include an [OpenSSF Scorecard](https://scorecard.dev/) score (0–10) reflecting the security practices of the upstream project (code review, CI, dependency management, etc.). A low score suggests the project may be less reliable from a security maintenance standpoint.

Use `--fail-on-ossf-score 5.0` to block on technologies with a low scorecard score.

## JSON Output

```bash
purplemet-cli tech list https://your-app.com --json
```

Each technology object contains:

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique technology ID |
| `name` | string | Product name |
| `version` | string | Detected version |
| `category` | string | Technology category as defined by the Purplemet platform |
| `cveCnt` | int | Known CVE count for this version |
| `endOfLife` | int | EOL timestamp (unix ms, 0 if not EOL) |
| `latestVersion` | string | Latest available version |
| `branchLatestVersion` | string | Latest version in the same major branch |
| `repository` | string | Source repository URL |
| `backportPossibility` | bool | Whether backporting is available |
| `ossfScorecard.score` | float | OpenSSF Scorecard score (0–10) |
| `ossfScorecard.checks` | array | Individual scorecard checks |
| `siteCnt` | int | Sites with this technology (with `--include-sites`) |
| `firstDetectedAt` | int | First detection (unix ms) |
| `lastDetectedAt` | int | Last detection (unix ms) |

## Related Gates

| Gate | Description |
|------|-------------|
| `--fail-on-eol` | Fail if end-of-life components are detected |
| `--exclude-tech "php,java"` | Fail if specified technologies are detected |
| `--fail-on-ossf-score 5.0` | Fail if any technology has an OpenSSF Scorecard score below threshold |

## Use Cases

### Monitor for outdated components

```bash
# List technologies on a single site that carry CVEs (per-instance counts)
purplemet-cli tech list https://your-app.com --json | jq '.[] | select(.cveCnt > 0)'

# Inventory of EOL components across the whole subscription
purplemet-cli tech list --all --json | jq '.[] | select(.endOfLife > 0) | {name, version, endOfLife}'
```

> **Note**: the global view (`tech list` without an argument) doesn't surface CVE counts — the `/technology` endpoint doesn't compute them per detected instance. The human-readable output omits the column entirely, and the JSON output drops `cveCnt` via `omitempty`. To get accurate CVE counts, scope the query to a specific site.

### Enforce technology policy

Block pipelines if forbidden technologies are detected:

```bash
purplemet-cli analyze https://your-app.com --json \
  --fail-on-eol \
  --exclude-tech "php,java" \
  --fail-on-ossf-score 5.0
```

### Track technology inventory

```bash
# All technologies across all sites
purplemet-cli tech list --include-sites --json --all
```