Exporting OSCAL assessment results

New in v1.0.0

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

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.authorizedServiceAccounts value.

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.

Don’t create your own 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.

  1. 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 namespace is not set, it defaults to the dashboard’s namespace. To authorize more service accounts, add more entries. Changes take effect without restarting the dashboard.

  2. The dashboard only accepts requests addressed to localhost by 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: localhost with each request.

    Without one of these, requests fail with a 400 error.

  3. 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.