Exporting OSCAL assessment results
The dashboard can export the mTLS and FIPS status of your mesh as an OSCAL Assessment Results document. You can fetch the document on a schedule and import it into a governance, risk, and compliance (GRC) platform as evidence for FedRAMP 20x.
For details on the endpoint’s parameters and the document’s contents, see the OSCAL assessment results reference.
Prerequisites
- The Linkerd dashboard installed on your cluster
kubectlaccess to the cluster
How access works
The endpoint is meant to be read by other workloads, such as a GRC exporter that runs on a schedule, so it doesn’t use dashboard login. Instead, Linkerd policy controls who can read it:
- The caller must be a meshed workload. The dashboard’s Linkerd proxy checks the caller’s service account identity over mTLS.
- The caller’s service account must be listed in the dashboard’s
oscal.authorizedServiceAccountsvalue.
Access is denied by default. Until you list a service account, no workload can read the document. Turning off login doesn’t change this.
The dashboard’s Helm chart creates the policy resources for you, along with a
linkerd-dashboard Service on port 8080 for in-cluster clients.
AuthorizationPolicy that targets
the dashboard’s Server or namespace, or a ServerAuthorization that selects
it. Linkerd adds these to every route on the server, which would also open the
OSCAL endpoint to the workloads they authorize.Fetch the document with a port-forward
With the dashboard port-forwarded
to localhost:8080, run:
curl -s 'http://localhost:8080/api/oscal/assessment-results?window=60' > oscal.json
A port-forward reaches the dashboard directly, without passing through its
Linkerd proxy, so Linkerd policy doesn’t apply and no token is needed. Anyone
who can create pods/portforward in the dashboard’s namespace can read the
document, so only grant that permission to people who should be able to read it.
Fetch the document from inside the cluster
The following steps allow the oscal-exporter service account in the grc
namespace to read the document. Replace it with the service account that fetches
the document.
Authorize the service account:
helm upgrade -n monitoring linkerd-dashboard \ oci://ghcr.io/buoyantio/charts/linkerd-dashboard --reuse-values \ --set 'oscal.authorizedServiceAccounts[0].name=oscal-exporter' \ --set 'oscal.authorizedServiceAccounts[0].namespace=grc'If
namespaceis not set, it defaults to the dashboard’s namespace. To authorize more service accounts, add more entries. Changes take effect without restarting the dashboard.The dashboard only accepts requests addressed to
localhostby default. Either allow the Service’s hostname:helm upgrade -n monitoring linkerd-dashboard \ oci://ghcr.io/buoyantio/charts/linkerd-dashboard --reuse-values \ --set enforcedHostRegexp='^(linkerd-dashboard\.monitoring\.svc\.cluster\.local|localhost)(:\d+)?$'Or send
Host: localhostwith each request.Without one of these, requests fail with a
400error.Run the client as a meshed workload with the authorized service account. It needs no token. For example, a CronJob that fetches the document every hour:
apiVersion: batch/v1 kind: CronJob metadata: name: oscal-exporter namespace: grc spec: schedule: "0 * * * *" jobTemplate: spec: template: metadata: annotations: linkerd.io/inject: enabled # Let the Job complete when the main container exits. config.alpha.linkerd.io/proxy-enable-native-sidecar: "true" spec: serviceAccountName: oscal-exporter restartPolicy: OnFailure containers: - name: export image: curlimages/curl:8.10.1 args: - -sf - -H - "Host: localhost" - http://linkerd-dashboard.monitoring.svc.cluster.local:8080/api/oscal/assessment-results?window=60
Requests from any other workload, or from a workload that isn’t meshed, are
denied by Linkerd with a 403 error.
To remove access for every service account, set an empty list:
helm upgrade -n monitoring linkerd-dashboard \
oci://ghcr.io/buoyantio/charts/linkerd-dashboard --reuse-values \
--set-json 'oscal.authorizedServiceAccounts=[]'
Don’t remove the value with --set oscal.authorizedServiceAccounts=null. With
--reuse-values, Helm falls back to the previous release’s list, so access
isn’t removed.
Check the policy
To see the policy that the dashboard’s proxy is enforcing, run:
POD=$(kubectl -n monitoring get po \
-l app.kubernetes.io/component=linkerd-dashboard -o name | head -1)
linkerd diagnostics policy -n monitoring "$POD" 8080
The linkerd-dashboard-oscal route should list only the authorized service
accounts, or no authorizations if none are listed, and no authorizations should
apply to the whole server.
Audit access to the document
The dashboard logs every request to the endpoint that it receives with the event
name oscal.access. To get these logs in JSON format, set logFormat:
helm upgrade -n monitoring linkerd-dashboard \
oci://ghcr.io/buoyantio/charts/linkerd-dashboard --reuse-values \
--set logFormat=json
To view the access logs, run:
kubectl -n monitoring logs deployment/linkerd-dashboard | grep oscal.access
Requests that don’t pass through the dashboard’s Linkerd proxy, such as requests
through a port-forward, have no l5d-client-id and are logged at warn level
with the message OSCAL assessment results accessed without a mesh identity. To
find out who opened a port-forward, use your Kubernetes API server’s audit log.
Requests that Linkerd denies never reach the dashboard, so they don’t appear in its access log. The dashboard’s proxy logs them instead:
kubectl -n monitoring logs deployment/linkerd-dashboard -c linkerd-proxy \
| grep 'Request denied'
For a list of the logged fields, see Access log fields.
Validate the document
To validate a saved document against the OSCAL schema and constraints, use
NIST’s oscal-cli:
docker run --rm -v "$PWD:/work" ghcr.io/metaschema-framework/oscal-cli:latest \
validate /work/oscal.json
Don’t use the FedRAMP JSON Schema validator for this document. It validates FedRAMP’s own submission formats, such as the Security Decision Record, not OSCAL.
Use the document for FedRAMP 20x
FedRAMP 20x does not accept OSCAL documents as submissions. Instead, reference
this document as evidence for KSI-SVC-SIN in your
Security Decision Record.
For example:
{
"keySecurityIndicators": [
{
"ksiId": "KSI-SVC-SIN",
"ksiEvidence": [
{
"evidenceType": "Report",
"evidenceDescription": "OSCAL 1.2.3 Assessment Results for mesh transport encryption.",
"evidenceLocation": "https://linkerd-dashboard.example.com/api/oscal/assessment-results?window=1440",
"lastUpdated": "2026-08-25"
}
]
}
]
}
The endpoint only reports on the current window and doesn’t keep history. If
your FedRAMP class requires historical metrics, fetch the document on a schedule
and store each response.