rails_template_18f 0.1.0

data/templates/doc/adr/0003-security-scans.md.tt

@@ -0,0 +1,44 @@
+# 3. Security Scans
+
+Date: <%= Date.today.iso8601 %>
+
+## Status
+
+Accepted
+
+## Context
+
+In order to maintain a secure system, it is important that we are kept notified of any potential
+vulnerabilities as early as possible, so we can mitigate them.
+
+## Decision
+
+We will add four new scans to our CI/CD Pipeline.
+
+### Brakeman
+
+Brakeman is a static code scanner designed to find security issues in Ruby on Rails code. It can flag
+potential SQL injection, Command Injection, open redirects, and other common vulnerabilities.
+
+### Bundle Audit
+
+bundle-audit checks our Ruby dependencies against a database of known CVE numbers.
+
+### Yarn Audit
+
+yarn audit checks our Javascript dependencies against a database of known CVE numbers.
+
+### OWASP ZAP
+
+[OWASP ZAP](https://www.zaproxy.org/) is a dynamic security scanner that can simulate actual attacks on a running server.
+
+An additional `RAILS_ENV` has been created called `ci`. It inherits from `production` to ensure
+that the system being tested is as close as possible to `production` while allowing for overrides such
+as bypassing authentication in a secure way.
+
+## Consequences
+
+We now have real-time information on any security vulnerabilities we may have introduced, as well as continuous
+monitoring and alerting of discovered vulnerabilities in our software dependencies.
+
+Our system security posture is overall improved by these additions.

data/templates/doc/adr/0004-rails-csp-compliant-script-tag-helpers.md.tt

@@ -0,0 +1,53 @@
+# 4. Rails CSP compliant script tag helpers
+
+Date: <%= Date.today.iso8601 %>
+
+## Status
+
+Accepted
+
+## Context
+
+The [Content-Security-Policy](https://content-security-policy.com/) header generated by the
+[secure_headers](https://github.com/github/secure_headers) gem does not work with Rails UJS AJAX forms.
+
+The Rails UJS AJAX forms might be used if this project does not use a full-on SPA library.
+
+## Decision
+
+Using Rails built-in CSP controls while keeping SecureHeaders in place for other headers results
+in a secure system that works seamlessly.
+
+## Consequences
+
+In order to define an inline `<script>` tag, use the `nonce: true` option.
+
+```
+<%%= javascript_tag nonce: true do %>
+  alert("my js runs here");
+<%% end %>
+```
+
+### Nonce pitfall
+
+[source](https://content-security-policy.com/nonce/#:~:text=Avoid%20this%20common%20nonce%20mistake)
+
+If you are outputting variables inside a nonce protected script tag, you could cancel out the XSS protection that CSP is giving you.
+
+For example assume you have a URL such as `/example/?id=123` and you are outputting that id value from the URL in your script block:
+
+```
+<%%= javascript_tag nonce: true do %>
+  var id = <%%= params[:id] %>
+<%% end %>
+```
+
+Now an attacker could request the URL: `/example/?id=doSomethingBad()`, and your application would send back:
+
+```
+<script nonce="rAnd0m">
+	var id = doSomethingBad()
+</script>
+```
+
+As you can see we just threw away all of the cross site scripting protections of CSP by improperly using the nonce.

data/templates/doc/compliance/README.md

@@ -0,0 +1,37 @@
+# Compliance artifacts
+
+## What is this?
+
+In order to maintain and revise compliance materials with minimal fuss, we store all artifacts as text source (eg Markdown, PlantUML, OSCAL), then generate rendered materials for consumption by downstream entities in the assessment and authorization process.
+
+This directory initially just contains system architecture diagrams corresponding to sections 1-12 of a typical System Security Plan (SSP) document.
+
+The source for other things (OSCAL for control descriptions, evidence generation scripts, etc) will appear here over time.
+
+## Development
+
+These plugins may be helpful for editing diagrams.
+
+- vscode: [PlantUML extension](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml)
+  - Use "PlantUML: Export Current File Diagrams" to render the diagram in the current file (eg while iterating)
+  - Use "PlantUML: Export Workspace Diagrams" to render all diagrams (eg before pushing a branch)
+
+### VSCode PlantUML Settings
+
+| Setting name | Value |
+| ------------ | ----- |
+| Diagrams Root | `doc/compliance` |
+| Export Format | `svg` |
+| Export Out Dir | `doc/compliance/rendered` |
+| Export Sub Folder | unchecked |
+| File Extensions | append `.md` |
+| Render | `PlantUMLServer` |
+| Server | `http://localhost:8080` |
+
+### PlantUML Server
+
+The plugin default settings use the public server, https://www.plantuml.com/plantuml, which may **leak sensitive information**. Instead, run a local plantuml server:
+
+```bash
+docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
+```

data/templates/doc/compliance/apps/application.boundary.md.tt

@@ -0,0 +1,80 @@
+# Application boundary view
+
+![application boundary view](../rendered/apps/application.boundary.svg)
+
+```plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+' uncomment the following line and comment the first to use locally
+' !include C4_Container.puml
+LAYOUT_WITH_LEGEND()
+title application boundary view
+
+Person_Ext(public, "Public", "A member of the public")
+
+Boundary(device, "Computing Device", "Windows, OS X, Linux, iOS, Android"){
+    System_Ext(browser, "Web Browser", "any modern version")
+}
+Rel(public, browser, "uses", "")
+
+note as EncryptionNote
+All connections depicted are encrypted with TLS 1.2 unless otherwise noted.
+end note
+Boundary(aws, "AWS GovCloud") {
+    Boundary(cloudgov, "cloud.gov") {
+        System_Ext(cg_api, "cloud.gov API")
+        System_Ext(aws_alb, "cloud.gov load-balancer", "AWS ALB")
+        System_Ext(cloudgov_router, "<&layers> cloud.gov routers", "Cloud Foundry traffic service")
+        Boundary(atob, "ATO boundary") {
+            System_Boundary(inventory, "Application") {
+                Container(app, "<&layers> <%= app_name.titleize %>", "Ruby <%= @ruby_version %>, Rails <%= Rails.version %>", "TKTK Application Description")
+                ContainerDb(app_db, "Application DB", "AWS RDS (PostgreSQL)", "Primary data storage")
+                <% if !skip_active_storage? %>
+                ContainerDb(app_s3, "File Storage", "AWS S3", "User-uploaded file storage")
+                <% end %>
+            }
+        }
+    }
+}
+
+
+Boundary(gsa_saas, "GSA-authorized SaaS") {
+    <% if @dap %>
+    System_Ext(dap, "DAP", "Analytics collection")
+    <% end %>
+    <% if @newrelic %>
+    System_Ext(newrelic, "New Relic", "Monitoring SaaS")
+    <% end %>
+}
+<% if @dap %>
+Rel(browser, dap, "reports usage", "https (443)")
+<% end %>
+<% if @newrelic %>
+Rel(app, newrelic, "reports telemetry (ruby agent)", "tcp (443)")
+Rel(browser, newrelic, "reports ux metrics (javascript agent)", "https (443)")
+<% end %>
+
+Rel(browser, aws_alb, "request info, submit requests", "https GET/POST (443)")
+Rel(aws_alb, cloudgov_router, "proxies requests", "https GET/POST (443)")
+Rel(cloudgov_router, app, "proxies requests", "https GET/POST (443)")
+Rel(app, app_db, "reads/writes primary data", "psql (5432)")
+<% if !skip_active_storage? %>
+Rel(app, app_s3, "reads/writes file data", "https (443)")
+<% end %>
+
+Person(developer, "Developer", "Application developers")
+Boundary(cicd, "CI/CD Pipeline") {
+}
+
+<% if @dap %>
+Rel(developer, dap, "View traffic statistics", "https GET (443)")
+<% end %>
+<% if @newrelic %>
+Rel(developer, newrelic, "Manage performance", "https (443)")
+<% end %>
+@enduml
+```
+
+### Notes
+
+* See the help docs for [C4 variant of PlantUML](https://github.com/RicardoNiepel/C4-PlantUML) for syntax help.

data/templates/doc/compliance/apps/data.logical.md

@@ -0,0 +1,21 @@
+# Logical Data Model
+
+![logical data model view](../rendered/apps/data.logical.svg)
+
+```plantuml
+@startuml
+scale 0.65
+
+' avoid problems with angled crows feet
+skinparam linetype ortho
+
+class TKTK_Example {
+  * id : integer <<generated>>
+}
+@enduml
+```
+
+### Notes
+
+* See the help docs for [Entity Relationship Diagram](https://plantuml.com/ie-diagram) and [Class Diagram](https://plantuml.com/class-diagram) for syntax help.
+* We're using the `*` visibility modifier to denote fields that cannot be `null`.

data/templates/editorconfig

@@ -0,0 +1,5 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+[zap.conf]
+indent_size = 4
+indent_style = tab

data/templates/env

@@ -0,0 +1,10 @@
+###################################################################################################
+# Important: NEVER ADD SECRETS OR CREDENTIALS TO THIS FILE
+# Any consistent secrets required in development should be added to config/credentials.yml.enc
+# Overrides that you do not want to check into git should be added to .env.local and/or .env.test.local
+#
+# This file is not loaded in production-like environments
+###################################################################################################
+
+# SHOW_DEMO_BANNER controls whether to show the TEST SITE banner in Rails.env.development
+SHOW_DEMO_BANNER=false

data/templates/githooks/pre-commit.tt

@@ -0,0 +1,35 @@
+#! /usr/bin/env bash
+#
+# This hook runs on `git commit` and will prevent you from committing without
+# approval from the linter and tests.
+#
+# To run, this file must be symlinked to:
+# .git/hooks/pre-commit
+#
+# To bypass this hook, run:
+# $ git commit --no-verify
+# $ git commit -n
+
+echo "Running linter..."
+bundle exec rake standard
+linter_status=$?
+
+if [ $linter_status -ne 0 ]; then
+    echo "Fix above before committing. Run 'git commit -n' to bypass linter."
+    exit 1
+fi
+
+<% if @terraform %>
+echo "Running Terraform formatter"
+# imitates https://github.com/HHS/Head-Start-TTADP/blob/3b72ff05d94fab4cda877c63d8cd6970f0eeffc7/.githooks/pre-commit
+
+files=$(git diff --cached --name-only terraform)
+for f in $files
+do
+  # Format any *.tf files that were cached/staged
+  if [ -e "$f" ] && [[ $f == *.tf ]]; then
+    terraform fmt "$f"
+    git add "$f"
+  fi
+done
+<% end %>

data/templates/lib/tasks/cf.rake

@@ -0,0 +1,9 @@
+namespace :cf do
+  desc "Only run on the first application instance"
+  task :on_first_instance do
+    instance_index = Integer(ENV["CF_INSTANCE_INDEX"])
+    exit(0) unless instance_index == 0
+  rescue
+    exit(0)
+  end
+end

data/templates/lib/tasks/scanning.rake

@@ -0,0 +1,63 @@
+desc "Run brakeman with potential non-0 return code"
+task :brakeman do
+  # -z flag makes it return non-0 if there are any warnings
+  # -q quiets output
+  unless system("brakeman -z -q") # system is true if return is 0, false otherwise
+    abort("Brakeman detected one or more code problems, please run it manually and inspect the output.")
+  end
+end
+
+namespace :bundler do
+  require "bundler/audit/cli"
+
+  desc "Updates the ruby-advisory-db and runs audit"
+  task :audit do
+    %w[update check].each do |command|
+      Bundler::Audit::CLI.start [command]
+    end
+  end
+rescue LoadError
+  # no-op, probably in a production environment
+end
+
+namespace :yarn do
+  desc "Run yarn audit"
+  task :audit do
+    require "open3"
+    stdout, stderr, status = Open3.capture3("yarn audit --json")
+    unless status.success?
+      puts stderr
+      parsed = JSON.parse("[#{stdout.lines.join(",")}]")
+      puts JSON.pretty_generate(parsed)
+      if /503 Service Unavailable/.match?(stderr)
+        puts "Ignoring unavailable server"
+      elsif all_issues_ignored?(parsed)
+        puts "Ignoring known and accepted yarn audit results"
+      else
+        puts "Failed with exit code #{status.exitstatus}"
+        exit status.exitstatus
+      end
+    end
+  end
+end
+
+def all_issues_ignored?(issues)
+  present_advisories_with_frequencies = Hash.new { |hash, key| hash[key] = 0 }
+
+  # Only look at audit advisories, and not audit summaries
+  issues.select { |issue_json| issue_json["type"] == "auditAdvisory" }.each do |issue_json|
+    present_advisories_with_frequencies[issue_json["data"]["advisory"]["id"]] += 1
+  end
+
+  # Advisory ID to be ignored with number of times it appears in project dependencies
+  # And, a comment as to why we're ignoring
+  ignored_advisories_with_frequencies = {
+    # 1005154 => 2, # high - inefficient regex in dev server and at build time
+  }
+
+  pp "Present advisories: #{present_advisories_with_frequencies}"
+  pp "Ignored advisories: #{ignored_advisories_with_frequencies}"
+  present_advisories_with_frequencies == ignored_advisories_with_frequencies
+end
+
+task default: ["standard", "brakeman", "bundler:audit", "yarn:audit"]

data/templates/manifest.yml.tt

@@ -0,0 +1,19 @@
+---
+applications:
+- name: <%= app_name %>-((env))
+  buildpacks:
+    - nodejs_buildpack
+    - ruby_buildpack
+  env:
+    RAILS_MASTER_KEY: ((rails_master_key))
+    RAILS_ENV: ((env))
+    RAILS_LOG_TO_STDOUT: true
+    RAILS_SERVE_STATIC_FILES: true<% if @newrelic %>
+    NEW_RELIC_LOG: stdout<% end %>
+  processes:
+  - type: web
+    instances: ((web_instances))
+    memory: ((web_memory))
+    command: bundle exec rake cf:on_first_instance db:migrate && bundle exec rails s -b 0.0.0.0 -p $PORT -e $RAILS_ENV
+  services:
+  - <%= app_name %>-rds-((env))

data/templates/pa11yci

@@ -0,0 +1,9 @@
+{
+  "defaults": {
+    "standard": "WCAG2AA",
+    "runners": ["axe"]
+  },
+  "urls": [
+    "http://localhost:3000"
+  ]
+}

data/templates/terraform/README.md.tt

@@ -0,0 +1,148 @@
+# Terraform
+
+This directory holds the terraform modules for maintaining your complete persistent infrastructure.
+
+Prerequisite: install the `jq` JSON processor: `brew install jq`
+
+## Initial setup
+
+1. Manually run the bootstrap module following instructions under `Terraform State Credentials`
+1. Setup CI/CD Pipeline to run Terraform
+  1. Copy bootstrap credentials to your CI/CD secrets using the instructions in the base README
+  1. Create a cloud.gov SpaceDeployer by following the instructions under `SpaceDeployers`
+  1. Copy SpaceDeployer credentials to your CI/CD secrets using the instructions in the base README
+1. Manually Running Terraform
+  1. Follow instructions under `Set up a new environment` to create your infrastructure
+
+## Terraform State Credentials
+
+The bootstrap module is used to create an s3 bucket for later terraform runs to store their state in.
+
+### Bootstrapping the state storage s3 buckets for the first time
+
+1. Run `terraform init`
+1. Run `./run.sh plan` to verify that the changes are what you expect
+1. Run `./run.sh apply` to set up the bucket and retrieve credentials
+1. Follow instructions under `Use bootstrap credentials`
+1. Ensure that `import.sh` includes a line and correct IDs for any resources created
+1. Run `./teardown_creds.sh` to remove the space deployer account used to create the s3 bucket
+
+### To make changes to the bootstrap module
+
+*This should not be necessary in most cases*
+
+1. Run `terraform init`
+1. If you don't have terraform state locally:
+    1. run `./import.sh`
+    1. optionally run `./run.sh apply` to include the existing outputs in the state file
+1. Make your changes
+1. Continue from step 2 of the boostrapping instructions
+
+### Retrieving existing bucket credentials
+
+1. Run `./run.sh show`
+1. Follow instructions under `Use bootstrap credentials`
+
+#### Use bootstrap credentials
+
+1. Add the following to `~/.aws/credentials`
+    ```
+    [<%= app_name %>-terraform-backend]
+    aws_access_key_id = <access_key_id from bucket_credentials>
+    aws_secret_access_key = <secret_access_key from bucket_credentials>
+    ```
+
+1. Copy `bucket` from `bucket_credentials` output to the backend block of `staging/providers.tf` and `production/providers.tf`
+
+## SpaceDeployers
+
+A [SpaceDeployer](https://cloud.gov/docs/services/cloud-gov-service-account/) account is required to run terraform or
+deploy the application from the CI/CD pipeline. Create a new account by running:
+
+`./create_space_deployer.sh <SPACE_NAME> <ACCOUNT_NAME>`
+
+## Set up a new environment manually
+
+The below steps rely on you first configuring access to the Terraform state in s3 as described in [Terraform State Credentials](#terraform-state-credentials).
+
+1. `cd` to the environment you are working in
+
+1. Set up a SpaceDeployer
+    ```bash
+    # create a space deployer service instance that can log in with just a username and password
+    # the value of < SPACE_NAME > should be `staging` or `prod` depending on where you are working
+    # the value for < ACCOUNT_NAME > can be anything, although we recommend
+    # something that communicates the purpose of the deployer
+    # for example: circleci-deployer for the credentials CircleCI uses to
+    # deploy the application or <your_name>-terraform for credentials to run terraform manually
+    ../create_space_deployer.sh <SPACE_NAME> <ACCOUNT_NAME> > secrets.auto.tfvars
+    ```
+
+    The script will output the `username` (as `cf_user`) and `password` (as `cf_password`) for your `<ACCOUNT_NAME>`. Read more in the [cloud.gov service account documentation](https://cloud.gov/docs/services/cloud-gov-service-account/).
+
+    The easiest way to use this script is to redirect the output directly to the `secrets.auto.tfvars` file it needs to be used in
+
+1. Run terraform from your new environment directory with
+    ```bash
+    terraform init
+    terraform plan
+    ```
+
+1. Apply changes with `terraform apply`.
+
+1. Remove the space deployer service instance if it doesn't need to be used again, such as when manually running terraform once.
+    ```bash
+    # <SPACE_NAME> and <ACCOUNT_NAME> have the same values as used above.
+    ../destroy_space_deployer.sh <SPACE_NAME> <ACCOUNT_NAME>
+    ```
+
+## Structure
+
+Each environment has its own module, which relies on a shared module for everything except the providers code and environment specific variables and settings.
+
+```
+- bootstrap/
+  |- main.tf
+  |- providers.tf
+  |- variables.tf
+  |- run.sh
+  |- teardown_creds.sh
+  |- import.sh
+- <env>/
+  |- main.tf
+  |- providers.tf
+  |- secrets.auto.tfvars
+  |- variables.tf
+- shared/
+  |- s3/
+     |- main.tf
+     |- providers.tf
+     |- variables.tf
+  |- database/
+     |- main.tf
+     |- providers.tf
+     |- variables.tf
+  |- domain/
+     |- main.tf
+     |- providers.tf
+     |- variables.tf
+```
+
+In the shared modules:
+- `providers.tf` contains set up instructions for Terraform about Cloud Foundry and AWS
+- `main.tf` sets up the data and resources the application relies on
+- `variables.tf` lists the required variables and applicable default values
+
+In the environment-specific modules:
+- `providers.tf` lists the required providers
+- `main.tf` calls the shared Terraform code, but this is also a place where you can add any other services, resources, etc, which you would like to set up for that environment
+- `variables.tf` lists the variables that will be needed, either to pass through to the child module or for use in this module
+- `secrets.auto.tfvars` is a file which contains the information about the service-key and other secrets that should not be shared
+
+In the bootstrap module:
+- `providers.tf` lists the required providers
+- `main.tf` sets up s3 bucket to be shared across all environments. It lives in `prod` to communicate that it should not be deleted
+- `variables.tf` lists the variables that will be needed. Most values are hard-coded in this module
+- `run.sh` Helper script to set up a space deployer and run terraform. The terraform action (`show`/`plan`/`apply`/`destroy`) is passed as an argument
+- `teardown_creds.sh` Helper script to remove the space deployer setup as part of `run.sh`
+- `import.sh` Helper script to create a new local state file in case terraform changes are needed

data/templates/terraform/bootstrap/import.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+read -p "Are you sure you want to import terraform state (y/n)? " verify
+
+if [[ $verify == "y" ]]; then
+  echo "Importing bootstrap state"
+  ./run.sh import module.s3.cloudfoundry_service_instance.bucket TKTK
+  ./run.sh import cloudfoundry_service_key.bucket_creds TKTK
+  ./run.sh plan
+else
+  echo "Not importing bootstrap state"
+fi

data/templates/terraform/bootstrap/main.tf.tt

@@ -0,0 +1,25 @@
+locals {
+  cf_api_url      = "https://api.fr.cloud.gov"
+  s3_service_name = "<%= app_name %>-terraform-state"
+}
+
+module "s3" {
+  source = "../shared/s3"
+
+  cf_api_url      = local.cf_api_url
+  cf_user         = var.cf_user
+  cf_password     = var.cf_password
+  cf_org_name     = "<%= @cloud_gov_organization %>"
+  cf_space_name   = "<%= @cloud_gov_production_space %>"
+  s3_service_name = local.s3_service_name<% if @cloud_gov_organization == "sandbox-gsa" %>
+  s3_plan_name    = "basic-sandbox"<% end %>
+}
+
+resource "cloudfoundry_service_key" "bucket_creds" {
+  name             = "${local.s3_service_name}-access"
+  service_instance = module.s3.bucket_id
+}
+
+output "bucket_credentials" {
+  value = cloudfoundry_service_key.bucket_creds.credentials
+}

data/templates/terraform/bootstrap/providers.tf

@@ -0,0 +1,16 @@
+terraform {
+  required_version = "~> 1.0"
+  required_providers {
+    cloudfoundry = {
+      source  = "cloudfoundry-community/cloudfoundry"
+      version = "0.15.0"
+    }
+  }
+}
+
+provider "cloudfoundry" {
+  api_url      = local.cf_api_url
+  user         = var.cf_user
+  password     = var.cf_password
+  app_logs_max = 30
+}

data/templates/terraform/bootstrap/run.sh.tt

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+if [[ ! -f "secrets.auto.tfvars" ]]; then
+  ../create_space_deployer.sh <%= @cloud_gov_production_space %> config-bootstrap-deployer > secrets.auto.tfvars
+fi
+
+if [[ $# -gt 0 ]]; then
+  echo "Running terraform $@"
+  terraform $@
+else
+  echo "Not running terraform"
+fi

data/templates/terraform/bootstrap/teardown_creds.sh.tt

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+../destroy_space_deployer.sh <%= @cloud_gov_production_space %> config-bootstrap-deployer
+
+rm secrets.auto.tfvars

data/templates/terraform/bootstrap/variables.tf

@@ -0,0 +1,2 @@
+variable "cf_password" {}
+variable "cf_user" {}

data/templates/terraform/create_space_deployer.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+set -e
+set -o pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "$0 <<SPACE_NAME>> <<ACCOUNT_NAME>>"
+  exit 1;
+fi
+
+space=$1
+service=$2
+
+cf target -s $space 1>&2
+
+# create space deployer service
+cf create-service cloud-gov-service-account space-deployer $service 1>&2
+
+# create service key
+cf create-service-key $service space-deployer-key 1>&2
+
+# output service key to stdout in secrets.auto.tfvars format
+creds=`cf service-key $service space-deployer-key | tail -n 4`
+username=`echo $creds | jq '.username'`
+password=`echo $creds | jq '.password'`
+
+cat << EOF
+# generated with $0 $space $service
+# revoke with $(dirname $0)/destroy_space_deployer.sh $space $service
+
+cf_user = $username
+cf_password = $password
+EOF