From f252b747f56bcc5a743242d87fb062c2011ebae1 Mon Sep 17 00:00:00 2001
From: Michael Waring <mwaring@mitre.org>
Date: Wed, 12 Oct 2022 17:52:38 -0400
Subject: [PATCH] Added basic documentation

---
 docs/ansible.md   | 25 +++++++++++++++++++
 docs/inspec.md    |  8 ++++++
 docs/src.md       |  6 +++++
 docs/toolsUsed.md | 25 +++++++++++++++++++
 docs/workflows.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 127 insertions(+)
 create mode 100644 docs/ansible.md
 create mode 100644 docs/inspec.md
 create mode 100644 docs/src.md
 create mode 100644 docs/toolsUsed.md
 create mode 100644 docs/workflows.md

diff --git a/docs/ansible.md b/docs/ansible.md
new file mode 100644
index 0000000..eecf1c6
--- /dev/null
+++ b/docs/ansible.md
@@ -0,0 +1,25 @@
+# ansible
+
+## pull_images_and_start_containers.yml
+Script used in generatehardenedimages.yml [generatehardenedimages.yml](/.github/workflows/generatehardenedimages.yml).
+Creates and starts the ironbank nginx container
+
+## nginx_hardening.yml
+Script used in generatehardenedimages.yml [generatehardenedimages.yml](/.github/workflows/generatehardenedimages.yml).
+Hardens the nginx container. Specific hardening configurations can be found at [ansible.md](/ansible/nginx_hardening.yml) lines 88-376
+
+## hosts.yml
+Variables used in nginx_hardening.yml.
+Provides connection type and host name
+
+## docker_commit.yml
+Script used in generatehardenedimages.yml [generatehardenedimages.yml](/.github/workflows/generatehardenedimages.yml).
+Adds the hardened container to the ironbank inventory
+
+## etc-nginx.conf.js
+Config file used in nginx_hardening.yml [nginx_hardening.yml](/ansible/nginx_hardening.yml). 
+Creates the nginx config file on the machine
+
+## hardening.conf.js
+Config file used in nginx_hardening.yml [nginx_hardening.yml](/ansible/nginx_hardening.yml). 
+Creates the hardeneing config file on the machine
diff --git a/docs/inspec.md b/docs/inspec.md
new file mode 100644
index 0000000..fbee080
--- /dev/null
+++ b/docs/inspec.md
@@ -0,0 +1,8 @@
+# inspec
+
+## nginx_inputs.yml
+This 'inputs' file feeds into our nginx inspec scan.
+The purpose on an inputs file is to provide custom configurations to the scan being run.
+This inputs file simply specifies the nginx version allowed,
+disallowes the use of PKI (Public Key Infrastructure),
+and defines the system admin and system admin group to be 'root'.
diff --git a/docs/src.md b/docs/src.md
new file mode 100644
index 0000000..5260af8
--- /dev/null
+++ b/docs/src.md
@@ -0,0 +1,6 @@
+# src
+
+This folder contains a simple 'hello world' style web app to use for demo purposes to run scans off of.
+
+Text is programmatically swapped into the html file from the js file on DOM load, 
+and a message is printed to the developer console when prompted.
diff --git a/docs/toolsUsed.md b/docs/toolsUsed.md
new file mode 100644
index 0000000..1622347
--- /dev/null
+++ b/docs/toolsUsed.md
@@ -0,0 +1,25 @@
+# Tools used
+
+## sonarqube
+Scans code to detect bugs/issues
+
+## inspec
+Scans containers/images to detect level of compliance
+
+## trivy
+scans docker image for vulnerabilities
+
+## heimdall
+Display results from scans in a dashboard
+
+## ansible
+container for nginx
+
+## nginx
+server to run scans off of
+
+## ironbank
+repository of validated hardened containers
+
+## GHCR
+GitHub Container Registry
diff --git a/docs/workflows.md b/docs/workflows.md
new file mode 100644
index 0000000..774cf62
--- /dev/null
+++ b/docs/workflows.md
@@ -0,0 +1,63 @@
+# github workflows
+
+
+## fullpipeline.yml
+This wrapper script calls the other scripts in the repo, namely 
+code analyst [codeanalysis.yml](/.github/workflows/codeanalysis.yml),
+generate hardened images [generatehardenedimages.yml](/.github/workflows/generatehardenedimages.yml),
+and container analysis [containeranalysis.yml](/.github/workflows/containeranalysis.yml)
+
+## [codeanalysis.yml](/.github/workflows/codeanalysis.yml)
+Analize code in this git repo and import it into Heinmall
+### Steps
+repo code -> sonarqube -> heimdall
+
+#### Check out
+checks out the git repo
+#### Sonarqube scan
+Scans the code for vulnerabilities
+#### Convert sonarqube scan to hdf
+converts the scan results to HDF file format
+#### Upload sonarqube hdf to heimdall
+Uploads the sonarqube results to heimdall
+
+
+## [generatehardenedimages.yml](/.github/workflows/generatehardenedimages.yml)
+Generate hardened images and push them to ironbank
+### Steps
+repo on ansible -> ironbank nginx container -> hardened container -> images from hardened container -> image pushed to ironbank
+
+#### Check out
+checks out the git repo
+#### Set up python
+Install python
+#### Install ansible dependencies
+Install ansible
+#### Run playbook to pull images and start containers
+Run the [pull_images_and_start_containers.yml](/ansible/pull_images_and_start_containers.yml) script, which creates and starts the ironbank nginx container
+#### Run playbook to harden nginx
+Run the [nginx_hardening.yml](/ansible/nginx_hardening.yml) script, which hardens the nginx container. Specific configurations can be found at [ansible.md](/ansible/nginx_hardening.yml) lines 88-376
+#### Run playbook to generate new images from hardened containers
+Run the [docker_commit.yml](/ansible/docker_commit.yml) script, which adds the hardened container to the ironbank inventory
+#### Create images
+Builds images from the hardened ironbank containers
+#### Push to ironbank base to GHCR
+Pushes images to ironbank using GHCS(Github Container Registry)
+
+
+## [containeranalysis.yml](/.github/workflows/containeranalysis.yml)
+Scan results of generatehardenedimages agains inspec and trivy, and upload results to heimdall
+### Steps
+RHEL8 OS  -> inspec -> heimdall
+NGINX app -> inspec -> heimdall
+Image     -> Trivy  -> heimdall
+
+#### Run RHEL8 profile
+Installs inspec, runs scan on RHEL8 OS from generatehardenedimages.yml, and uploads results to heimdall
+
+#### Run NGINX profile
+Installs inspec, runs scan on hardened app from generatehardenedimages.yml with config from
+[nginx_inputs.yml](/inspec/nginx_inputs.yml), and uploads results to heimdall
+
+#### Run Trivy scan
+Runs Trivy scan on hardened image from generatehardenedimages.yml, and uploads results to heimdall