mitre / saf-site-frontend

MITRE SAF© Site

MITRE Security Automation Framework Website

Overview

The MITRE Security Automation Framework© (SAF) brings together open-source, accessible applications, techniques, libraries, and tools developed by MITRE and the security community to streamline security automation for systems and DevOps pipelines.

This repository contains the frontend source code for the upcoming new https://saf.mitre.org website.

Getting Started

Frontend Development

1. Fork repository and clone it locally
2. Install project dependencies: yarn install
3. Install playwright dependencies with npx playwright install
4. Copy .env-sample into .env and replace CHANGEME values as appropriate
5. For developing use: yarn dev
6. For production use: yarn build and yarn preview

Backend Development

• Backend is handled in the saf-site backend repository

Technology Stack

• Nuxt 3
• Vue 3
• Tailwind CSS v3
• Lucide
• Vite
• Headless UI - unstyled, fully accessible UI components, designed to integrate beautifully with Tailwind CSS
• prettier-plugin-tailwindcss - Automatic Class Sorting with Prettier

First-party plugins needed for Tailwind UI:

• tailwindcss/forms
• tailwindcss/typography
• tailwindcss/line-clamp
• tailwindcss/aspect-ratio

Contributing, Issues and Support

Contributing

Please feel free to look through our issues, make a fork and submit PRs and improvements. We love hearing from our end-users and the community and will be happy to engage with you on suggestions, updates, fixes or new capabilities.

Issues and Support

Please feel free to contact us by opening an issue on the issue board, or, at [email protected] should you have any suggestions, questions or issues.

saf-site-frontend's Issues

Make Single Component for Blog Post and Individual FAQ Page

As the individual blog post page and individual FAQ page use very similar styling, make a single component for both and make use of v-slots where needed. This will promote DRY code.

Possible Issue with use of <Dialog> in Docs Page

There was an error that was affecting routing in the docs page. There was a hydration mismatch in the DocumentationMobileNavigation.vue file. It was caused by the component, to fix this I wrapped it in the component. This fixed the issue for now, but It may become an issue on static deployments.

Here is the related issue, tailwindlabs/headlessui#1496

Header Content

Currently the header content was filled appropriately with the content that had made the most sense to add.

However as more features and pages are created and fleshed out the header needs to be routed and reorganized as needed.

The header is a component so this changes would occur once and span site wide.

If new interactive pieces are needed the best first point of reference would be the Tailwind UI page.

Blog Search / Site Search

Implement search system for blog including filtering between authors, date, company, etc. Return to this issue once site search has been added to define use case or absorb functionality into site search.

Error Handling for invaid slugs

This issue is tracking fatal errors occuring when trying to catch errors in useAsyncData calls. This must be solved to handle errors when invalid slug is in url, leading to failed requests. Current strategy is to return to this issue after upgrading nuxt major versions to 3.x stable version.

This issue is being tracked by mutiple recent Nuxt discussions/issues.

nuxt/nuxt#15432

nuxt/nuxt#14695

nuxt/framework#7290

Possible Accessibility Issue When Using DL HTML Tag

    https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl#accessibility_concerns

Are DL's the best way to do it? Is there a different semantic construct we can use instead to show the previous/next buttons?

Originally posted by @Amndeep7 in #9 (comment)

Interactive SAF CLI Tutorial

I came across a cool way of going through docs on this k8s page.

It would be great (if possible) to incorporate an interactive shell on the SAF site when explaining SAF CLI commands perhaps?

One other use case could also be showing users how easy it is to run InSpec profiles that are publicly accessible - but that would require a target (maybe a few containers) so might not be worth the maintenance.

Documentation System Enhancements

• As documentation grows, think about displaying list of all the documentation at the documentation index page. This will also ensure that the documentation system follows the DRY principle. The current implementation has an index page which fetches the first page, repeating most of the code from the dynamic page ([section].vue).
• (Thought) Have a documentation grouping Strapi collection type separate from the current documentation collection type in Strapi. It will group like docs (i.e., documentation) together.
  • For example, the index page for /docs will be a grid of documentation grouping (e.g., Heimdall, Vulcan, etc.) where the user can choose which one to browse to. This will solve the non DRY code in the first bullet point and organize documentation section.
  • Expand the documentation GraphQL call so that a limit is defined similar to the limit added to the blog post GraphQL query. By default it will only grab 10 documentation if it isn't defined.

Update Blog Cards Sizing Bug

Fix blog cards from infinitely text wrapping causing the blog card to become larger than other ones.

Best fix for this is just to keep the size static and have text cutoff at a certain character count for the post.description attribute in the data.

Training Page refactor

• make the page the standard page width
• move the component for course signups inside the main page body instead of floating off to the side (at minimum need buttons for each course and the date for the next course offering)
• Add functionality for graying out the button for a given course and replacing the text with "Coming Soon!" when the course link is empty

Header/Footer Enhancements

• Possible additions of other color schemes like "high contrast" or "colorblind-variantX-compatible" could be added to the theme switcher.

Add Getting Started Page

• Similar to #49 . Borrow from existing SAF site Getting Started.

Update header of FAQ Page

Update top content of FAQ page to include proper contact information.

MAJOR FEATURE: Add doc board

user story

What is done

1. dfklj
2. 1,.akjdf
3. flkadjfl
4. a;dlfk
5. ;lakdf;k

Site Search Bar (Mobile/Desktop)

The site search bar (command palette) should be able to search content over all the pages in the site.

Fill out documentation pages

• Take existing SAF resources that are scattered around GitHub wikis and move them into documentation links -- ex. how to make a mapper
• Remove the existing courses links and add a single top-level header for the courses that links to https://mitre.github.io/saf-training/

Site Roadmap

This is the progress of what has been done and what is next in line for implementation

NOTE: This is progress for the frontend and backend!

• Created Strapi CMS (Content Management System) project to create database and generated endpoints
• Designed backend architecture to replicate the use cases for the current site and cater to new features using Strapi content types
• Created Nuxt 3 (Vue 3/Vite) project for the Frontend
• Enable backend and frontend to utilized GraphQL for query based API calls
• Designed header
• Set frame of reference for spacing on the site
• Created static 404 exception page
• Create a markdown renderer in a Strapi controller in order to get HTML which can be styled on the frontend with Tailwind Typography plugin. See this related issue
• Style blog content using Tailwind Typography
• Add search bar for blog posts. See related issue
• Update tags in blog posts. See this related issue
• Finish populating the database with the data from json files of the old site. Verify that the current schema is appropriate for our use cases to save time updating entries later down the road.
• Create documentation page
• Create landing page (Aaron, Eugene, and Emily have good ideas for what we want conceptionally)
• Add Netlify support to better comunciate project updates to the team via demos. See this related issue

Add Search Bar for Blog

Add a search bar, similar to the header, for the blog articles in order to search through our blog post content.

This will make it easier to navigate through our content down the line when we have a large amount of posts to scroll through.

According to how our URLs are structured it makes sense to structure searching on titles, date, and tags.

Improve Code Readability and Structure

• Review where code repeats and create common components
• Add comments to code where needed for future developers
• Add instructions and notes to GitHub wiki for future developers
• Add slots to components where needed to improve re-usability
• Structure and refactor assets folder

Documentation System Element Anchor Bug

    If you click on one of the anchors it drops you below the element that was anchored.  Ideally if you click on something that's anchored, that's what's at the top of the screen.  Very brief search says it might be due to the sticky header screwing up positioning: https://stackoverflow.com/questions/71754275/anchor-links-do-not-redirect-to-correct-position-on-the-webpage

Originally posted by @Amndeep7 in #9 (comment)

Possible Solution: https://markus.oberlehner.net/blog/simple-solution-for-anchor-links-behind-sticky-headers/

Blog Enhancements

• Display documents such as PowerPoint, PDF, word document, etc.
  • Good resource: https://www.vuescript.com/pdf-document-embed/
• Implement tag system with option to filter by tag.

Add Linter To Dev Environment

Add linting to dev environment to make code cleaner (https://vueschool.io/articles/vuejs-tutorials/eslint-and-prettier-with-vite-and-vue-js-3/)

Add Visualize Page

• Describe Heimdall (with a few screenshots, borrow from Heimdall's github page)
• Describe HDF converters (what they're for, namely allowing you to use other visualizers for data if desired)
• describe emasser

Implement Control Assessment table

• Port over the auto-updating control assessment table from v1 of SAF site.

Update Nuxt version to stable 3.0.0

Ensure that Nuxt is in a stable version before V1 release of site.

• Resolve Tailwind config issues

Should fix #84 and #80

This also includes updating Strapi and related plugins (e.g., CKeditor 5) to newest version.

Add Dependabot

Look into adding dependabot to resolve dependency security issues.

Validate/Harden Page Issues

Known bugs and possible enhancements:

Bugs:

• There currently is a bug where when scrolling through the table component and routing over to the modal component, Nuxt saves the scroll behavior so that when opening the modal you render already at the bottom of the page. Luckly Nuxt seems to have fixed this issue in the 3.0.0 stable version. (Current plan to check back on this issue after upgrading our Nuxt version) Related issue: nuxt/nuxt#14544

Enhancements

• Add the upcoming 'Guidance scraper database' functionality to auto update certain values.

Documentation Navigation Search Feature

Implement functionality for search bar in documentation navigation to search the entire documentation system. Search bar should be OS aware and change shortcuts accordingly.

Add an admin login button for Strapi

We need site admins to be able to find the link for managing content in Strapi. We should put the link (https://saf-site-backend.herokuapp.com/admin/) on the frontend site.

Add a button with "admin login" to the More modal.

Overall Site Enhancements

• Move slugify function out of individual pages. Can bring in an external library for slugify or make a utility function that can be called in each page.

FAQ page updates

• Rename "Help Center" in the More modal as "FAQs" with an appropriate description
• Change the life preserver icon to a question mark (or similar)

Error Handeling Slug

(Check after Nuxt 3 stable version update) Possible solutions are to redirect to index page or bring to 404 page. Currently, an invalid slug shows

Linter Issues

Go back and apply linting updates to the codebase before the v1 release.

• In a previous PR linting was apply to all files and when built and ran without previous caching there would be a vite error. This would cause data not to load and transition menus not to pop out.

• The best way forward is the apply linting bits at a time checking the dev deploy without caching to ensure config files aren't breaking or some other error is occurring.

• Main issue with linter is it flags all Nuxt content as errors/warnings. For now we have converted no-undef errors to warnings as they only are called on global Nuxt functions. There are Nuxt plugins however there was trouble getting them to work properly.

• Addiontionally a warning is called using v-html as it rasies XSS security concerns. To render in the html in those use cases we must use v-html, therefore a way to address these concerns is to use a library to sanitize our html input. See https://stackoverflow.com/questions/46782359/vue-js-v-html-alternative
  Additionally I found this plugin that can handle XSS sanitation concerns for HTML and SVGS (https://github.com/cure53/DOMPurify)

Add Netlify Support

Deploy this repo to Netlify simlar to previous repo.

NOTE: Our previous netlify config file can be found in the previous repo.

Documentation on how to do this in Nuxt 3

Training Enhancements

Enhancements for later iterations of the Training Page

• Create a carousel for the course embedded videos]
• There is avaliable space for some kind of menu or content on the left bar. This could be filled with related blog posts
• We could in-house our form system (possibly using netlify forms) however this would need to get cleared from info-sec

Inconsistent FAQ Routing

When navigating between FAQs in the netlify deployment the routing doesn't always go to the proper page.

User Story: Site Command Palette

Summary

As a user, I want to have a site wide search bar so that I can search based on any keyword(s) and get related results, limiting the time I need to search across the site.

Acceptance Criteria

1. User can search across the site using search functionality nested in the header or with OS specific shortcut
2. Results from the search will be split up by the sections in which they are found
3. Search will also pick up on tags related to collection types

Resources:

• Mockups: https://tailwindui.com/components/application-ui/navigation/command-palettes

Blog Post Tags

Indentifying tags for blog posts is something that members of the team think are valuable to included to sort articles as we have various subjects that can be written as a blog post.

Quick examples would be tags to differatiate documentation from sponser or specific project related information.

The tag field already exists as a text field within the database as of now. My approach would be to create an enumerated list to limit the user's input to tags which the team can agree upon. I was thinking as well depending on how many tags are needed to color code them.

Image Loading Failure

Look into moving images locally or some other solution as certain VPN solutions can't resolve the Cloudinary images.

Possible Solutions:

• Move the "upload provider" from Cloudinary to local (https://docs.strapi.io/developer-docs/latest/plugins/upload.html#configuration)

Style Markdown Content

We need to be able to style our blog post content.

As of now Strapi passes raw markdown through the API in postData.content within the single blog post page (currently [title].vue). This is incompatible as we are using the Tailwind CSS Typography plugin to use the prose feature to style the content.

Here is a good example of how this works from the Tailwind people themselves (https://www.youtube.com/watch?v=J0Wy359NJPM)

The problem occurs as this plugin only can style basic HTML. The solution to this is that we can use a markdown renderer to convert the raw markdown to HTML and then the Tailwind Typography plugin should be able to easily style our content.

The way that most made sense to me to achieve this is to use Strapi controllers to render the markdown before it even gets to the frontend. This example was the one that I was looking into using Marked, a tool to render the markdown within a Strapi controller.

Documentation System Fixes

• Add max-width to content of documentation system to work with ultra-wide, similar to blogs background
• (If can be done quickly include in V1, if not include in V2)Feature Requests:
  (Amdneep) "Imo would be good to have a button that would take you to the top of the page. Ex. https://deploy-preview-9--mitre-saf-v2.netlify.app/docs/review-the-fundamentals#2-inspec-content-review has some text before the first header that you wouldn't be able to get back to and reread if you only used used the navigation button things."
• Feature Requests:
  (Gavin) "Some sort of loading screen should prob be added to doc pages. In general it would probably be beneficial to have some sort of standardized loading screen for all page loads. However for now a generic v-if/v-else that would just state loading instead of "object Object"".
• Determine if documentation search should be kept for V1 (Currently not functional)
  

Add foundation Normalize page

• Use existing SAF normalize page as a template where possible.
• Link it under "Normalize" in the Toolkit modal.

Linter Issues

• Main issue with linter is it flags all Nuxt content as errors/warnings. For now we have converted no-undef errors to warnings as they only are called on global Nuxt functions. There are Nuxt plugins however there was trouble getting them to work properly.

• Addiontionally a warning is called using v-html as it rasies XSS security concerns. To render in the html in those use cases we must use v-html, therefore a way to address these concerns is to use a library to sanitize our html input. See https://stackoverflow.com/questions/46782359/vue-js-v-html-alternative

Enhance Frontend Testing Framework

• Look into integrating something like Vitest or Jest for Unit Tests (Vitest seems recommended if Jest isn't already set up)
• Determine if component testing is needed

Possible resources:

• Different recommended libraries for Unit Testing, Component Testing, and E2E Testing of Vue (https://vuejs.org/guide/scaling-up/testing.html#e2e-testing)
• https://nuxt.com/docs/getting-started/testing
• https://playwright.tech/blog/using-jest-with-playwright
• https://github.com/playwright-community/jest-playwright

Fill out Blog posts

• add a MITRE SAF Team author profile for general SAF articles
• add in some articles:
  • background on why we need security automation/DevSecOps -- check GitBook
  • put up some diagrams of InSpec implementations in cloud
  • add post that shows SAF-at-a-glance, using an image of the old SAF homepage component

Header and Footer Enhancements (Mobile/Desktop)

Header:

• Make search bar visible in mobile view
• Make header sticky across all pages
• Ensure navigation buttons work and redirect you to proper pages (Disabled navigation buttons that aren't implemented)
• Make the color scheme button a dropdown of some kind so as to choose between light/dark/system (and maybe in the future other color schemes like "high contrast" or "colorblind-variantX-compatible"?)
• Take out erroneous divs
• Delete commented code
• Add copyright after MITRE SAF in top left of header "MITRE SAF ©"

Footer:

• Copyright year should be updated with variable

Add Plan page

• Similar to #49 .
• Discuss and link to Vulcan.
• Give brief context on security baselines and why they are important and how they relate to automated content.
• @wdower might have language for this on Gitbook for SAF.

Cleanup for v1

• in the "Toolkit" modal:
  • remove "Our tools"
  • ensure Normalize, Plan, Visualize links go somewhere once we have those pages built (#49 #50 #51)
  • Remove "Watch Demo" and "Contact Us"
• in the "More" modal:
  • fix "Help Center" to "FAQ" as per #47
  • Remove "Events"
  • Remove "Recent Posts" and everything else on down
• Revamp mobile nav view
  • Remove "Our Tools"
  • Add necessary nav links
• Move inline svg to asset (Check for more than github and saf)
  • Take out png or jpeg versions of logos where needed
• Change nav link color when on active page
• Fix view details table for validate and harden (Discussed in comment by Will in #42 )
• Make slugify a utility function or import library to clean code (Addressed in #29 )
• Add copyright logo to MITRE SAF (i.e. "MITRE SAF" should be "MITRE SAF©" and "MITRE Security Automation Framework" should be "MITRE Security Automation Framework©")
• Start migration from Vue 2 script to Vue 3 script

Look Into Refactoring Component Directory Structure

See the feasibility of changing the structure of the components directory to something like below:

├── components
│   └── screens
│            └── documentation
│                ├── Component1.vue
│                ├── Component2.vue
│                ├── Component3.vue
│   └── common
│       ├── Header.vue
│       ├── Footer.vue
│       ├── Button.vue

NOTE: One reason to possibly avoid this is that the naming convention of the component will need to change as noted here (https://forum.vuejs.org/t/nuxt-components-work-but-subfolder-components-does-not/109031). For example,

would become and something like would need to become .

Add the homepage

• Use premade Vue Tailwind components wherever possible (currently working with Salient template).
• Should roughly cover what was on the original SAF homepage.