# OSCAL assessment results reference

The dashboard can export the mTLS and FIPS status of your mesh as an
[OSCAL](https://pages.nist.gov/OSCAL/) Assessment Results document. For steps to
fetch, secure, and validate the document, see
[Exporting OSCAL assessment results](/linkerd-dashboard/guides/exporting-oscal-assessment-results/).

## Endpoint

```text
GET /api/oscal/assessment-results?window=<minutes>&query=<filter>
```

### Parameters

| Parameter | Description                                                     | Default           |
| --------- | --------------------------------------------------------------- | ----------------- |
| `window`  | How far back to look, in minutes.                               | `1440` (24 hours) |
| `query`   | A filter expression. Accepts the same filters as the dashboard. | (none)            |

### Authentication

Access is controlled by
[Linkerd authorization policy](https://linkerd.io/docs/reference/authorization-policy/).
The caller must be a meshed workload whose service account is listed in the
dashboard's `oscal.authorizedServiceAccounts` value. Access is denied by
default.

See
[Exporting OSCAL assessment results](/linkerd-dashboard/guides/exporting-oscal-assessment-results/#how-access-works).

### Responses

| Status | Description                                                                                 |
| ------ | ------------------------------------------------------------------------------------------- |
| `200`  | The assessment results document, as `application/json`.                                     |
| `400`  | Invalid `window` or `query`, or a request to a host the dashboard doesn't allow.            |
| `403`  | Denied by Linkerd policy: the caller isn't meshed, or its service account isn't authorized. |
| `500`  | The dashboard couldn't query Prometheus.                                                    |

## Document contents

The document reports on the connections the mesh observed during the `window`.

| Section           | Contents                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `metadata`        | The Linkerd version, cluster domain, look-back window, and a `system-id` that is unique to your Linkerd installation.          |
| `inventory-items` | One item per meshed workload, with its namespace, kind, name, proxy version, and FIPS version.                                 |
| `observations`    | One per connection (source, destination, and destination port), with its mTLS status and the bytes sent with and without mTLS. |
| `findings`        | Up to two per workload: one for `sc-8` and one for `sc-13`. See [Control mapping](/linkerd-dashboard/reference/oscal/#control-mapping).                           |
| `risks`           | One per failure type found anywhere in the mesh: `plaintext-traffic` or `non-fips-cryptography`. Omitted when there are none.  |

An observation's `mtls` value is `true`, `false`, or `mixed`. A connection that
used mTLS also includes its TLS version, cipher suites, and crypto library, and
its FIPS module details when both ends use FIPS.

Endpoints that aren't meshed, such as clients outside the mesh, don't get an
inventory item. They appear in observations as `unmeshed`.

A workload that stops using mTLS stays in the document with a failing finding.

## Control mapping

| Objective   | Control | Satisfied when                                                                           |
| ----------- | ------- | ---------------------------------------------------------------------------------------- |
| `sc-8_obj`  | `sc-8`  | Every assessed connection the workload took part in used mTLS.                           |
| `sc-13_obj` | `sc-13` | The workload's proxy uses FIPS cryptography, and so does every meshed peer it talked to. |

A finding appears only when there is evidence for it, so some workloads have
fewer than two findings:

- `sc-8` requires at least one assessed connection.
- `sc-13` requires at least one mTLS connection, because that is how the
  dashboard learns the proxy's FIPS version.

Every finding includes the FedRAMP 20x Key Security Indicator `KSI-SVC-SIN` as a
`ksi` property.

### Traffic excluded from sc-8

Some traffic can't be meshed or can't be assessed, so it doesn't count toward
the `sc-8` result:

- Traffic from unmeshed clients to a workload's probe ports (readiness,
  liveness, and startup) or to the proxy admin port, `4191`. This is traffic
  such as kubelet health checks and metrics scrapes.
- Traffic from a meshed workload to an unmeshed destination on port `443`. This
  is assumed to be TLS, such as calls to an external API.

Keep in mind:

- An unmeshed client's application traffic on a probe port is also excluded.
- Plaintext traffic to an unmeshed destination on any port other than `443` is
  reported, even if the application encrypts it.

When exclusions apply, the `sc-8` finding has a status reason of
`pass-with-exclusions` instead of `pass`, remarks that explain what was
excluded, and an `excluded-connections` count. Each observation includes an
`excluded-from-sc-8` property, so you can recompute the result yourself.

## Identifiers

Every UUID in the document is generated from stable inputs, so the same
observation, finding, or risk keeps its UUID across fetches. Use the UUIDs to
track changes over time.

The document's own UUID is also stable. To tell one fetch from the next, use
`metadata.last-modified`.

## Access log fields

The dashboard logs every request to the endpoint that it receives with the event
name `oscal.access`. Requests denied by Linkerd policy never reach the
dashboard, and are logged by its proxy as `Request denied` instead.

| Field                       | Description                                                                                                                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `event`                     | Always `oscal.access`.                                                                                                                                                                           |
| `l5d-client-id`             | The caller's mesh identity, as verified by the dashboard's proxy. Empty if the request didn't pass through the proxy, such as through a port-forward; these requests are logged at `warn` level. |
| `path`, `query`             | The requested path and query string.                                                                                                                                                             |
| `remote-addr`, `user-agent` | The caller's address and user agent.                                                                                                                                                             |
| `status`, `bytes`           | The response status and size.                                                                                                                                                                    |
| `duration-ms`               | How long the request took.                                                                                                                                                                       |

## Limitations

- The document only covers traffic that passes through a Linkerd proxy during
  the `window`.
- The endpoint doesn't keep history. Each response covers only the current
  `window`.
- The document doesn't include roles, parties, or components.
