OSCAL assessment results reference
The dashboard can export the mTLS and FIPS status of your mesh as an OSCAL Assessment Results document. For steps to fetch, secure, and validate the document, see Exporting OSCAL assessment results.
Endpoint
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.
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.
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. |
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-8requires at least one assessed connection.sc-13requires 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
443is 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.