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

ParameterDescriptionDefault
windowHow far back to look, in minutes.1440 (24 hours)
queryA 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

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

Document contents

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

SectionContents
metadataThe Linkerd version, cluster domain, look-back window, and a system-id that is unique to your Linkerd installation.
inventory-itemsOne item per meshed workload, with its namespace, kind, name, proxy version, and FIPS version.
observationsOne per connection (source, destination, and destination port), with its mTLS status and the bytes sent with and without mTLS.
findingsUp to two per workload: one for sc-8 and one for sc-13. See Control mapping.
risksOne 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

ObjectiveControlSatisfied when
sc-8_objsc-8Every assessed connection the workload took part in used mTLS.
sc-13_objsc-13The 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.

FieldDescription
eventAlways oscal.access.
l5d-client-idThe 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, queryThe requested path and query string.
remote-addr, user-agentThe caller’s address and user agent.
status, bytesThe response status and size.
duration-msHow 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.