ZTMF Scoring

The ZTMF Scoring Application allows ADOs to view their Zero Trust Maturity score online. An upcoming release will allow new ADOs to answer the questionnaire from scratch, and existing ADOs to update their answers, all within a web-based interface. The interface and the API are protected by AWS Verified Access which requires authentication via IDM (Okta).

This monorepo contains the following major components:

• .src/components/ contains reusable components shared within views
• .src/views/ contains all pages and dialogs that are used throughout the application
• .github/workflows/ contains workflows for Github Actions to test, build, and deploy to AWS

Architecture

This project contains the application's UI built with React, Vite, TypeScript, and SWC. It requires Node.js v20, nvm (or n), and Yarn v4.

System Requirements

• Node 20
• Yarn
• GitLeaks

CI/CD Workflows

The project uses GitHub Actions for continuous integration and deployment. The workflows are organized into modular components that are orchestrated differently for development and production environments.

Workflow Components

1. Analysis (analysis.yml)

   • Performs code quality and security checks
   • Lints Go code using staticcheck
   • Lints Terraform code using tflint
   • Runs Snyk security scans for Go code, source code, and infrastructure as code

2. ui (ui.yml)

   • DEBUG - node, npm, yarn versions
   • Get the cache dependencies. Install new dependencies if the last build is different than the latest build
   • Install dependencies
   • Perform linting
   • Get AWS creds
   • Sync build to to AWS S3

Orchestration

The workflows are orchestrated differently based on the environment:

PR checks (orchestration-dev.yml)

• Triggered on pull requests to the main branch
• Runs analysis on all non-draft PRs, then the UI workflow's lint, tests, and build without deploying
• Deploys nothing: PR previews run in per-PR environments (orchestration-pr.yml)

dev and prod (orchestration-prod.yml)

• Triggered when a pull request to main is merged (closed with merge)
• Runs analysis, then the UI workflow for dev, then the same for prod
• prod runs only if the dev deploy succeeded
• Only executes if the PR was actually merged

Getting Started

1. Clone the repository and cd into the root directory:

git clone git@github.com:CMS-Enterprise/ztmf-ui.git`

cd ztmf-ui

2. Setup Node.js and Yarn

# using nvm
nvm install --latest-npm
nvm use

# using n
n install auto
n use auto

# enable corepack
corepack enable yarn

3. Install dependencies:

yarn

3. Install pre-commit hooks:

yarn prepare

Building

To build the application, run the following from the root directory:

yarn build

PR environment image

Dockerfile builds the frontend for per-PR environments (ztmf-misc#343): an nginx container that serves the path-agnostic bundle under a prefix, proxies its api/ calls to the API container, and writes config.js at start with a test-mode bearer token. The bundle is built with VITE_IDP_ENABLED=false, so this image is never what dev or prod serve, and a PR that changes the IdP login path or the showIdpSelector branch is not exercised by its PR environment.

Variable	Default	Purpose
AUTH_HS256_SECRET	required	Signs the token in config.js; must match the API's AUTH_HS256_SECRET
PR_PATH_PREFIX	empty	/pr/<repo>/<n> in a PR environment; empty serves at /
API_UPSTREAM	http://127.0.0.1:8080	Where ${PR_PATH_PREFIX}/api/ is proxied
TEST_USER_EMAIL	Grand.Moff@DeathStar.Empire	Seeded user the token is minted for

Local check against the ztmf compose-test.yml API on 8090:

docker build -t ztmf-ui:pr-env .
docker run --rm -p 8443:443 -e AUTH_HS256_SECRET=zeroTrust -e PR_PATH_PREFIX=/pr/ui/999 \
  -e API_UPSTREAM=http://host.docker.internal:8090 ztmf-ui:pr-env
curl -k https://localhost:8443/pr/ui/999/config.js

Testing

To run all tests, run the following from the root directory:

yarn test

To lint all files, run the following from the root directory:

yarn lint

Developing

First, run the post-install script to create the local development environment file from the example environment file.

sh ./scripts/post-install.sh

To start the local development server, run the following from the root directory:

yarn dev

Development Commands (Makefile)

For convenience, common development tasks are available via Makefile:

# Quick development commands
make dev          # Start development server
make pre-commit   # Format code and run linting (recommended before commits)
make check        # Run all checks (format, lint, build)

# Individual tasks
make lint         # Run linting checks
make format       # Format code with Prettier
make build        # Build for production
make build-dev    # Build for development
make test         # Run tests

# Setup
make setup        # Install dependencies
make help         # Show all available commands

Backend

ZTMF (backend) has its own repository.