Enable the classification banner

What you’ll accomplish

After completing this guide, web applications exposed through the Istio service mesh will display security classification banners at the top (and optionally the bottom) of each page. You can assign different classification levels to different hosts or URL path prefixes on the same host. Each banner color automatically corresponds to the standard classification markings.

Prerequisites

Before configuring classification banners, confirm that you meet these prerequisites:

• UDS CLI installed
• UDS Registry account created and authenticated locally with a read token
• Access to a Kubernetes cluster with UDS Core deployed

Before you begin

An Istio EnvoyFilter adds the classification banner to HTML responses at the gateway. By default, it inserts banner elements into the page body and places application content in a scrollable row between them.

Note

Validate the banner in a staging environment before adopting it. For custom-built applications, implementing the banner natively within the application is often a more reliable approach.

The classificationBanners array configures one or more banners. UDS Core continues to support the previous classificationBanner object for backward compatibility, but new configurations should use classificationBanners.

Steps

1. Configure the banners, hosts, and paths

   Add each banner to the classificationBanners array and assign its hosts with enabledHosts. To limit a banner to part of a host, add one or more URL prefixes with pathPrefixes. When pathPrefixes is empty or omitted, the banner matches every path on its enabled hosts.

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       keylessVerification:
         certificateIdentityRegexp: ^https://github\.com/defenseunicorns/uds-core/\.github/workflows/publish\.yaml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$
         certificateOIDCIssuer: https://token.actions.githubusercontent.com
       overrides:
         istio-controlplane:
           uds-global-istio-config:
             values:
               - path: classificationBanners
                 value:
                   - text: "UNCLASSIFIED"
                     addFooter: true
                     enabledHosts:
                       - keycloak.{{ .Values.adminDomain }}
                       - mission-app.{{ .Values.domain }}
                   - text: "SECRET//NOFORN"
                     addFooter: false
                     enabledHosts:
                       - mission-app.{{ .Values.domain }}
                     pathPrefixes:
                       - /classified
                       - /need-to-know

   Supported classification levels:

   Value	Banner color
   UNCLASSIFIED	Green
   CUI	Purple
   CONFIDENTIAL	Blue
   SECRET	Red
   TOP SECRET	Orange
   TOP SECRET//SCI	Yellow
   UNKNOWN	Black (default)
   SAMPLE BANNER	Black (demo placeholder)

   Tip

   The text field also supports additional markings appended with // (for example, SECRET//NOFORN). The banner color is determined by the base classification level.

   Tip

   Host values support Helm templating. Use {{ .Values.adminDomain }} for hosts on the admin gateway and {{ .Values.domain }} for tenant-facing applications.

   Note

   When multiple entries match the same host, UDS Core selects the longest matching path prefix. A host-only entry acts as the fallback when no path prefix matches. Path matching excludes the query string.

   Note

   If you set cssOnly: true, UDS Core renders the classification markings with an inline <style> element. A Content Security Policy (CSP) that blocks inline styles can prevent the markings from appearing.

2. Create and deploy your bundle

   uds create <path-to-bundle-dir>
   uds deploy uds-bundle-<name>-<arch>-<version>.tar.zst

Verification

Open hosts and paths from each configured banner in a browser. Each page should show the assigned classification text and color at the top. Verify that a path-specific banner overrides the host-only fallback on the same host. If addFooter is enabled for that banner, the same banner appears at the bottom.

For the default mode, confirm that the content scrolls between the banners. For cssOnly mode, confirm that content and controls remain usable between the fixed markings. Check the browser console for hydration errors.

Troubleshooting

Problem: Banner not appearing on a host

Symptom: A configured host loads normally but no classification banner is displayed.

Solution: Verify the hostname is included in an enabledHosts array under classificationBanners. The host must match exactly, including any subdomain prefixes. If the banner uses pathPrefixes, verify that the URL path begins with one of those values. If the banner appears briefly and then disappears after hydration, set cssOnly: true for that entry. If it never appears, check the deployed EnvoyFilter:

uds zarf tools kubectl get envoyfilter classification-banner -n istio-system -o yaml

Problem: Banner breaks page layout or doesn’t render correctly

Symptom: The banner HTML is injected but the page layout is disrupted, invisible or overlaps content.

Solution: If the default banner’s body elements or scrollable content row disrupt the page, set cssOnly: true for that entry. This mode leaves the body tree intact, but its fixed markings can still overlap navigation or controls. Check the page after hydration. If the application cannot accommodate either mode, implement the banner within the application.

Related documentation

Use these resources to learn more about classification markings and Istio networking:

• Astro UXDS Classification Markings - standard color and formatting reference
• Istio EnvoyFilter - how Istio modifies HTTP responses at the gateway
• Networking concepts - how UDS Core manages the Istio service mesh and gateways