Initial cut of diagrams

doc/compliance/apps/application.boundary.md

@@ -0,0 +1,58 @@
+# 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, "request info, submit request", "")
+
+
+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(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> Application", "Ruby 3.0.3, Rails 7.0", "Presents a UX for requesting an at-home test kit")
+                ContainerDb(app_db, "Application DB", "AWS RDS (PostgreSQL)", "Stores data about requests")
+                ContainerDb(app_s3, "Export bucket", "AWS S3", "Stores encrypted export for retrieval by USPS")
+            }
+        }
+    }
+}
+
+
+Boundary(gsa_saas, "GSA-authorized SaaS") {
+    System_Ext(dap, "DAP", "Analytics collection")
+    System_Ext(newrelic, "New Relic", "Monitoring SaaS")
+}
+browser -> dap : **reports usage** \n//[https (443)]//
+Rel(app, newrelic, "reports telemetry", "tcp (443)")
+Rel(browser, aws_alb, "request info, submit request for test kit", "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 dataset metadata", "psql (5432)")
+Rel(app, app_s3, "reads/writes dataset resources", "https (443)")
+
+Boundary(unknown_boundary, "Unclear boundary") {
+    System_Ext(address_api, "Address validation API", "USPS? Google Maps? SmartyStreets? Local?")
+}
+Rel(browser, address_api, "auto-complete address entries", "https GET/POST (443)")
+
+
+@enduml
+```

doc/compliance/apps/application.logical.md

@@ -0,0 +1,16 @@
+# application logical view
+
+![application logical view](../rendered/apps/application.logical.svg)
+
+```plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+LAYOUT_WITH_LEGEND()
+title application logical view
+Person_Ext(public, "Public users", "A member of the public")
+Boundary(atob, "ATO boundary") {
+    System(application, "application", "record test kit requests")
+}
+Rel(public, application, "requests test kit for address")
+@enduml
+```

doc/compliance/apps/deployment.md

@@ -0,0 +1,106 @@
+# Deployment
+
+Configuration management and deployment for every application follows the pattern described unless otherwise specified.
+
+Figure 10-1 Deployment Diagram
+![cloud.gov typical deployment interactions](../rendered/apps/deployment.svg)
+
+```plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Deployment.puml
+
+LAYOUT_WITH_LEGEND()
+title cloud.gov typical deployment interactions
+
+note as EncryptionNote
+All connections depicted are encrypted with TLS 1.2 unless otherwise noted.
+end note
+
+Deployment_Node(aws, "AWS GovCloud", "Amazon Web Services Region") {
+    Deployment_Node(aws_alb, "Public-facing TLS termination", "AWS ALB") {
+        Deployment_Node(cloudgov, "cloud.gov", "Cloud Foundry PaaS") {
+            Deployment_Node(cloudgov_router, "cloud.gov router", "Cloud Foundry service") {
+                Boundary(cloudgov_endpoints, "cloud.gov endpoints") {
+                    System_Ext(cloudgov_logdrain, "logs.fr.cloud.gov", "ELK")
+                    System_Ext(cloudgov_controller, "cloud.gov controller", "Cloud Foundry orchestration")
+                    System_Ext(cloudgov_dashboard, "cloud.gov dashboard", "Cloud Foundry web UI")
+                    System_Ext(cloudgov_sshproxy, "cloud.gov SSH proxy", "Cloud Foundry application inspection")
+                    System_Ext(cloudgov_uaa, "cloud.gov authentication", "Cloud Foundry service")
+                }
+                Boundary(atob, "ATO boundary") {
+                    Deployment_Node(organization, "organization") {
+                        Deployment_Node(space, "space") {
+                            System(app, "application", "component")
+                            ContainerDb(cloudgov_services, "cloud.gov data services", "AWS RDS, S3, etc", "Stores persistent data for apps")
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+' Application output (not critical here, so commented out)
+' Rel(app, cloudgov_services, "reads/writes data", "data protocols")
+' Rel(app, cloudgov_logdrain, "logs to", "stdout/stderr")
+
+' cloud.gov internals
+Rel(cloudgov_dashboard, cloudgov_controller, "manipulates", "https (443)")
+Lay_D(cloudgov_dashboard, cloudgov_controller) 
+Rel(cloudgov_dashboard, cloudgov_uaa, "authenticates", "https (443)")
+Rel(cloudgov_controller, cloudgov_uaa, "authenticates", "https (443)")
+Rel(cloudgov_logdrain, cloudgov_uaa, "authenticates", "https (443)")
+Rel(cloudgov_sshproxy, cloudgov_uaa, "authenticates", "https (443)")
+Rel(cloudgov_sshproxy, app, "creates shell")
+Rel(cloudgov_controller, space, "provisions/inspects/operates apps")
+Rel(cloudgov_controller, cloudgov_services, "provisions/inspects services")
+
+Person(team, "team member")
+Deployment_Node(computer, "Computing Device", "MS Windows, OS X, or Linux"){
+    System(browser, "Web Browser", "any modern version")
+    System(git_cli, "git CLI", "local version control command")
+    System(cf_cli, "cf CLI", "local Cloud Foundry command")
+}
+Rel(team, browser, "uses")
+Rel(team, cf_cli, "uses")
+Rel(team, git_cli, "uses")
+
+Boundary(gsa_saas, "GSA-authorized SaaS") { 
+    Deployment_Node(gsuite, "GSA G Suite", "Collaboration SaaS") {
+        System(ggroup, "[email protected]", "Google Group")
+    }
+    Boundary(deploymentservices, "Deployment services") {
+        System_Ext(snyk, "Snyk", "Dependency analysis SaaS")
+        Deployment_Node(github, "GitHub", "VCS SaaS"){
+            System(github_repo, "GSA/[component name]", "Code repository")
+        }
+    }
+    System_Ext(dap, "DAP", "Web analytics SaaS")
+    System_Ext(newrelic, "New Relic", "Monitoring SaaS")
+    System_Ext(secureauth, "GSA SecureAuth", "SAML Identity Provider")
+}
+Rel_(cloudgov_uaa, secureauth, "proxies authentication requests", "SAML/https (443)", "..>")
+
+
+'Team interactions
+Rel_Back(team, newrelic, "reports problems", "email")
+Rel(browser, dap, "reviews reports", "https (443)")
+Rel(browser, cloudgov_logdrain, "reviews logs", "https (443)")
+'Lay_D(app, cloudgov_logdrain)
+Rel(browser, github_repo, "makes pull-request, approves PRs", "https (443)")
+Rel(git_cli, github_repo, "commits code", "ssh (22)")
+Rel(cf_cli, cloudgov_controller, "interacts with cloud.gov API", "https (443)")
+Rel(cf_cli, cloudgov_sshproxy, "establishes session", "ssh (22)")
+Rel(browser, cloudgov_dashboard, "interacts with cloud.gov dashboard", "https (443)")
+Rel(team, ggroup, "provides assistance", "email")
+Rel(team, secureauth, "authenticates", "https (443)")
+
+' Deployment automation
+Rel_Up(snyk, github_repo, "watches for changes, reports vulnerable dependencies", "GitHub API")
+Rel(github_repo, cloudgov_controller, "pushes code, invokes tasks", "https (443)")
+
+' Non-functional, just helps with layout'
+'Lay_R(cloudgov_endpoints, atob)  
+
+@enduml
+```

doc/compliance/generic/deployment-change.md

@@ -0,0 +1,140 @@
+# Deploying a change to production code
+
+The following interactions make a change happen in the production environment. A narrative explanation follows the diagram.
+
+![CI/CD process](../rendered/generic/deployment-change.svg)
+
+```plantuml
+@startuml
+box "Team" #LightBlue
+    entity "reviewer" as reviewer
+    entity "author" as author
+end box
+
+'autonumber
+
+== Preparing the change ==
+author ->> github: push branch
+author ->> github: start pull-request
+    participant snyk
+    github ->> githubactions: branch available
+    github ->> snyk: branch available
+
+== Checking the change ==
+    activate snyk    
+
+par Snyk and GitHub Actions check the branch
+    snyk -> snyk: inspect dependencies
+    loop vulnerabilities are found
+        github <<-- snyk: report problems
+        author <<-- github: report failure
+        author ->> github: push changes to branch
+        github ->> snyk: changes available
+        snyk -> snyk: inspect dependencies
+    end
+    github <<-- snyk: report success
+    deactivate snyk
+    
+    activate githubactions
+    githubactions -> githubactions: run tests
+    loop tests are failing
+        github <<-- githubactions: report problems
+        author <<-- github: report failure
+        author ->> github: push changes to branch
+        github ->> githubactions: changes available
+        githubactions -> githubactions: run tests
+    end
+    github <<-- githubactions: report success
+    deactivate githubactions
+end
+
+author <<-- github: report successes
+
+== Reviewing the change ==
+author ->> github: request review
+create reviewer
+reviewer <<-- github: notify of pull-request
+reviewer ->> github: inspect  branch
+loop change needed/bug identified
+    reviewer ->> github: note findings
+    author <<-- github: report findings
+    author ->> github: push changes to branch
+    reviewer <<-- github: report changes
+end
+reviewer ->> github: approve pull-request
+
+alt either the author
+    author ->> github: merge into deployment branch
+else or the reviewer
+    reviewer ->> github: merge into deployment branch
+end
+
+== Deploying the change ==
+github ->> githubactions: deployment branch changed
+activate githubactions
+participant "application in staging" as stagingapp
+create awsapi
+githubactions -> awsapi: push config to AWS API
+create awsstaging
+awsapi -> awsstaging: push config to staging account
+create capi
+githubactions -> capi: push code to staging space
+create stagingapp
+capi -> stagingapp: stage
+capi -> stagingapp: start
+activate stagingapp 
+capi ->> stagingapp: monitor
+loop
+    stagingapp ->> stagingapp: handle requests
+    opt 
+        capi <<- stagingapp: app crash
+        capi ->> stagingapp: restart
+    end
+end
+
+githubactions -> stagingapp: run smoke tests
+alt smoke tests fail
+    author <<-- githubactions: report problems
+else smoke tests pass
+    participant "application in production" as app
+    githubactions -> awsapi: push config to AWS API
+    create awsproduction
+    awsapi -> awsproduction: push config to production account
+    githubactions -> capi: push code to production space
+    create app
+    capi -> app: stage 
+    capi -> app: start
+    activate app 
+    capi ->> app: monitor
+    loop
+        app ->> app: handle requests
+        opt 
+            capi <<- app: app crash
+            capi ->> app: restart
+        end
+    end
+    deactivate app
+end
+deactivate githubactions
+
+
+box "Deployment SaaS" #LightGreen
+    participant github
+    participant githubactions
+    participant snyk
+end box
+
+box "cloud.gov" #Green
+    participant "cloud.gov controller" as capi
+    participant stagingapp
+    participant app
+end box
+
+box "AWS US-West" #YellowGreen
+    participant "AWS API" as awsapi
+    participant awsstaging
+    participant awsproduction
+end box
+
+@enduml
+```

doc/compliance/generic/generic.boundary.md

@@ -0,0 +1,68 @@
+# Boundaries, components, and user interactions
+
+Every component follows the pattern described below with variance only in the application or data services in use unless otherwise specified.
+![typical application interactions](../rendered/generic/generic.boundary.svg)
+
+```plantuml
+@startuml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Deployment.puml
+
+LAYOUT_WITH_LEGEND()
+title typical application interactions
+
+note as EncryptionNote
+  All connections depicted are encrypted with TLS 1.2 unless otherwise noted.
+end note
+
+
+Deployment_Node(aws, "AWS GovCloud", "Amazon Web Services Region") {
+    System_Ext(aws_alb, "Public-facing TLS termination", "AWS ALB")
+    Deployment_Node(cloudgov, "cloud.gov", "Cloud Foundry PaaS") {
+        System_Ext(cloudgov_router, "cloud.gov router", "Cloud Foundry service")
+        System_Ext(cloudgov_logdrain, "logs.fr.cloud.gov", "ELK")
+        
+        Boundary(atob, "ATO boundary") {
+            Deployment_Node(organization, "organization") {
+                Deployment_Node(space, "space") {
+                    System(app, "application", "component")
+                    ContainerDb(cloudgov_services, "cloud.gov data services", "AWS RDS, S3, etc", "Stores persistent data for apps")
+                }
+            }
+        }
+    }
+}
+
+Rel(aws_alb, cloudgov_router, "sends application traffic", "https (443)")
+Rel_Down(app, cloudgov_services, "reads/writes data", "data protocols")
+
+
+' Logs flow
+Rel(app, cloudgov_logdrain, "logs to", "stdout/stderr")
+
+' Customer access
+Person_Ext(public, "User", "Agency personnel or the public")
+Deployment_Node(computer, "Computing Device", "MS Windows, OS X, or Linux"){
+    System_Ext(browser, "Web Browser", "any modern version")
+}
+
+
+' Monitoring
+Boundary(gsa_saas, "GSA-authorized SaaS") { 
+    Deployment_Node(gsuite, "GSA G Suite", "Collaboration SaaS") {
+        System(ggroup, "[email protected]", "Google Group")
+    }
+    System_Ext(dap, "DAP", "Web analytics SaaS")
+    System_Ext(newrelic, "New Relic", "Monitoring SaaS")
+}
+
+Rel(newrelic, aws_alb, "monitors application", "https GET (443)")
+Rel(app, newrelic, "reports telemetry", "tcp (443)")
+Rel(public, ggroup, "gets help", "email")
+Rel(public, browser, "uses")
+browser --> dap : **reports usage** \n//[https (443)]//
+
+Rel(browser, aws_alb, "interacts with application", "https GET/POST (443)")
+Rel(cloudgov_router, app, "proxies to", "https GET/POST (443)")
+
+@enduml
+```