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

The classification banner is injected into HTTP responses by an Istio EnvoyFilter on the gateway. A CSS-only viewport frame places the application in a scrollable row between dedicated banner rows, including applications with fixed navigation or roots sized to the full viewport.

Because both modes modify the HTML response body, 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
       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.

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.

Confirm that the application is constrained between the banners and that its content scrolls within the middle row. Confirm that fixed navigation, dialogs, and other overlays do not cover either banner.

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. 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 or the banner is invisible.

Solution: The banner uses a CSS-only frame with dedicated banner rows and a scrollable content row. If an application still breaks because it depends on a specific body structure, implement the classification banner natively within the application instead of relying on EnvoyFilter injection.

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