# Exporting OSCAL assessment results

_[New in v1.0.0](/release-notes/linkerd-dashboard/v1.0.0/)_

The dashboard can export the mTLS and FIPS status of your mesh as an
[OSCAL](https://pages.nist.gov/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](/linkerd-dashboard/reference/oscal/).

## Prerequisites

- The [Linkerd dashboard](/linkerd-dashboard/getting-started/) installed on your cluster
- `kubectl` access 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](/linkerd-dashboard/guides/logging-in/). 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.

> [!WARNING]
> 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](/linkerd-dashboard/getting-started/#accessing-the-dashboard)
to `localhost:8080`, run:

```bash
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:

   ```bash
   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.

1. The dashboard only accepts requests addressed to `localhost` by default.
   Either allow the Service's hostname:

   ```bash
   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.

1. 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:

   ```yaml
   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:

```bash
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:

```bash
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`:

```bash
helm upgrade -n monitoring linkerd-dashboard \
  oci://ghcr.io/buoyantio/charts/linkerd-dashboard --reuse-values \
  --set logFormat=json
```

To view the access logs, run:

```bash
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:

```bash
kubectl -n monitoring logs deployment/linkerd-dashboard -c linkerd-proxy \
  | grep 'Request denied'
```

For a list of the logged fields, see
[Access log fields](/linkerd-dashboard/reference/oscal/#access-log-fields).

## Validate the document

To validate a saved document against the OSCAL schema and constraints, use
NIST's `oscal-cli`:

```bash
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](https://www.fedramp.gov/schemas/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](https://www.fedramp.gov/2026/providers/20x/rules/security-decision-record/).
For example:

```json
{
  "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.
