octool 0.0.4 → 0.0.9

data/schemas/v1.0.1/component.yaml

@@ -0,0 +1,60 @@
+---
+type: map
+class: Component
+mapping:
+    name:
+        desc: Human-friendly name to appear in the SSP.
+        type: str
+        required: true
+    component_key:
+        desc: Unique identifier for referential integrity.
+        type: str
+        required: true
+    description:
+        desc: A paragraph or two that describes the component.
+        type: str
+        required: true
+    attestations:
+        desc: List of attestations.
+        type: seq
+        sequence:
+            - type: map
+              class: Attestation
+              mapping:
+                  summary:
+                      desc: Arbitrary verbiage to appear in SSP as a TLDR.
+                      type: str
+                      required: true
+                  status:
+                      desc: To what extent is this attestation "done"?
+                      type: str
+                      required: true
+                      enum:
+                          - partial
+                          - complete
+                          - planned
+                          - none
+                  date_verified:
+                      desc: When was this last verified?
+                      type: date
+                      required: false
+                  satisfies:
+                      desc: List of control IDs covered by this attestation.
+                      type: seq
+                      required: false
+                      sequence:
+                          - type: map
+                            class: ControlID
+                            mapping:
+                                standard_key:
+                                    type: text
+                                    required: true
+                                control_key:
+                                    type: text
+                                    required: true
+                  narrative:
+                      desc: |
+                          Explain how attestation satisfies the indicated controls.
+                          The content should be in markdown format.
+                      type: str
+                      required: true

data/schemas/v1.0.1/config.yaml

@@ -0,0 +1,79 @@
+---
+type: map
+class: Config
+mapping:
+    schema_version:
+        desc: |
+            Must match one of the schema directories in the octool source.
+        required: true
+        type: str
+
+    logo:
+        desc: Image for title page.
+        required: false
+        type: map
+        class: Logo
+        mapping:
+            path:
+                desc: Path to image.
+                type: str
+                required: true
+            width:
+                desc: Width of image, such as "1in" or "254mm"
+                type: str
+                required: true
+
+    name:
+        desc: Human-friendly to appear in the SSP.
+        required: true
+        type: str
+
+    overview:
+        desc: Human-friendly description to appear in the SSP.
+        required: true
+        type: str
+
+    maintainers:
+        desc: Who should somebody contact for questions about this SSP?
+        required: true
+        type: seq
+        sequence:
+            - type: str
+
+    metadata:
+        desc: Optional metadata.
+        required: false
+        type: map
+        class: Metadata
+        mapping:
+            abstract:
+                desc: Abstract appears in document metadata.
+                required: false
+                type: str
+            description:
+                desc: Description appears in document metadata.
+                required: false
+                type: str
+            '=':
+                desc: Arbitrary key:value pair of strings.
+                type: str
+
+    includes:
+        desc: Additional files to include from the system repo.
+        required: true
+        type: seq
+        sequence:
+            - type: map
+              class: Include
+              mapping:
+                  type:
+                      required: true
+                      type: str
+                      enum:
+                          - certification
+                          - component
+                          - standard
+                  path:
+                      desc: Path must be relative within the repo.
+                      required: true
+                      type: str

data/schemas/v1.0.1/standard.yaml

@@ -0,0 +1,50 @@
+---
+type: map
+class: Standard
+mapping:
+    name:
+        desc: Human-friendly name to appear in SSP.
+        type: str
+        required: true
+
+    standard_key:
+        desc: Unique ID to use within YAML files.
+        type: str
+        required: true
+
+    families:
+        desc: Optional list of control families.
+        type: seq
+        required: false
+        sequence:
+            - type: map
+              class: ControlFamily
+              mapping:
+                  family_key:
+                      desc: Unique ID of the family
+                      type: str
+                      unique: true
+                  name:
+                      desc: Human-friendly name of the family
+                      type: str
+    controls:
+        desc: Mandatory list of controls defined by the standard.
+        required: true
+        type: seq
+        sequence:
+            - type: map
+              class: Control
+              mapping:
+                  control_key:
+                      type: str
+                      unique: true
+                      required: true
+                  family_key:
+                      type: str
+                      required: false
+                  name:
+                      type: str
+                      required: true
+                  description:
+                      type: str
+                      required: true

data/schemas/v1.0.2/certification.yaml

@@ -0,0 +1,27 @@
+---
+type: map
+class: Certification
+mapping:
+    certification_key:
+        desc: A short, unique identifier for this certification.
+        required: true
+        type: str
+        unique: true
+    name:
+        desc: A human-friendly name for the certification.
+        required: true
+        type: str
+    requires:
+        desc: List of control IDs required by the certification.
+        required: true
+        type: seq
+        sequence:
+            - type: map
+              class: ControlID
+              mapping:
+                  standard_key:
+                      required: true
+                      type: str
+                  control_key:
+                      required: true
+                      type: str

data/schemas/v1.0.2/component.yaml

@@ -0,0 +1,60 @@
+---
+type: map
+class: Component
+mapping:
+    name:
+        desc: Human-friendly name to appear in the SSP.
+        type: str
+        required: true
+    component_key:
+        desc: Unique identifier for referential integrity.
+        type: str
+        required: true
+    description:
+        desc: A paragraph or two that describes the component.
+        type: str
+        required: true
+    attestations:
+        desc: List of attestations.
+        type: seq
+        sequence:
+            - type: map
+              class: Attestation
+              mapping:
+                  summary:
+                      desc: Arbitrary verbiage to appear in SSP as a TLDR.
+                      type: str
+                      required: true
+                  status:
+                      desc: To what extent is this attestation "done"?
+                      type: str
+                      required: true
+                      enum:
+                          - partial
+                          - complete
+                          - planned
+                          - none
+                  date_verified:
+                      desc: When was this last verified?
+                      type: date
+                      required: false
+                  satisfies:
+                      desc: List of control IDs covered by this attestation.
+                      type: seq
+                      required: false
+                      sequence:
+                          - type: map
+                            class: ControlID
+                            mapping:
+                                standard_key:
+                                    type: text
+                                    required: true
+                                control_key:
+                                    type: text
+                                    required: true
+                  narrative:
+                      desc: |
+                          Explain how attestation satisfies the indicated controls.
+                          The content should be in markdown format.
+                      type: str
+                      required: true

data/schemas/v1.0.2/config.yaml

@@ -0,0 +1,111 @@
+---
+type: map
+class: Config
+mapping:
+    schema_version:
+        desc: |
+            Must match one of the schema directories in the octool source.
+        required: true
+        type: str
+
+    logo:
+        desc: Image for title page.
+        required: false
+        type: map
+        class: Logo
+        mapping:
+            path:
+                desc: Path to image.
+                type: str
+                required: true
+            width:
+                desc: Width of image, such as "1in" or "254mm"
+                type: str
+                required: true
+
+    name:
+        desc: Human-friendly to appear in the SSP.
+        required: true
+        type: str
+
+    overview:
+        desc: Human-friendly description to appear in the SSP.
+        required: true
+        type: str
+
+    maintainers:
+        desc: Who should somebody contact for questions about this SSP?
+        required: true
+        type: seq
+        sequence:
+            - type: str
+
+    metadata:
+        desc: Optional metadata.
+        required: false
+        type: map
+        class: Metadata
+        mapping:
+            abstract:
+                desc: Abstract appears in document metadata.
+                required: false
+                type: str
+            description:
+                desc: Description appears in document metadata.
+                required: false
+                type: str
+            '=':
+                desc: Arbitrary key:value pair of strings.
+                type: str
+
+    includes:
+        desc: Additional files to include from the system repo.
+        required: true
+        type: seq
+        sequence:
+            - type: map
+              class: Include
+              mapping:
+                  type:
+                      required: true
+                      type: str
+                      enum:
+                          - certification
+                          - component
+                          - standard
+                  path:
+                      desc: Path must be relative within the repo.
+                      required: true
+                      type: str
+
+    acronyms:
+        desc: |
+            List of acronyms to be referenced in the doc.
+
+            The acronyms follow the forms and usage described by the pandoc filter
+            https://gitlab.com/mirkoboehm/pandoc-acronyms
+
+            If your config.yaml includes acronyms, the filter is automatically invoked.
+        required: false
+        type: map
+        mapping:
+            '=':
+                desc: |
+                    Acronym as used in the doc source, such as "bba".
+                    The source usually refers to the acronym with syntax "[!bba]",
+                    but other syntax forms are possible (see upstream doc).
+                type: map
+                class: Acronym
+                mapping:
+                    shortform:
+                        desc: The short form of the expanded acronym, such as "BBA".
+                        required: true
+                        type: str
+                    longform:
+                        desc: |
+                            The expanded form of the abbreviation, such as "Beer Brewing Attitude".
+                            The first instance of "[!bba]" in the doc is automatically expanded to
+                            "<longform> (<shortform>)".
+                            Example: "[!bba]" expands to "Beer Brewing Attitude (BBA)".
+                        required: true
+                        type: str

data/schemas/v1.0.2/standard.yaml

@@ -0,0 +1,50 @@
+---
+type: map
+class: Standard
+mapping:
+    name:
+        desc: Human-friendly name to appear in SSP.
+        type: str
+        required: true
+
+    standard_key:
+        desc: Unique ID to use within YAML files.
+        type: str
+        required: true
+
+    families:
+        desc: Optional list of control families.
+        type: seq
+        required: false
+        sequence:
+            - type: map
+              class: ControlFamily
+              mapping:
+                  family_key:
+                      desc: Unique ID of the family
+                      type: str
+                      unique: true
+                  name:
+                      desc: Human-friendly name of the family
+                      type: str
+    controls:
+        desc: Mandatory list of controls defined by the standard.
+        required: true
+        type: seq
+        sequence:
+            - type: map
+              class: Control
+              mapping:
+                  control_key:
+                      type: str
+                      unique: true
+                      required: true
+                  family_key:
+                      type: str
+                      required: false
+                  name:
+                      type: str
+                      required: true
+                  description:
+                      type: str
+                      required: true

data/templates/ssp.erb

@@ -1,17 +1,25 @@
 ---
-title: "<%= @system.config.name -%>"
+<% if @system.config['logo'] -%>
+title: |
+    ![](<%= @system.config['logo']['path'] -%>){width=<%= @system.config['logo']['width'] %>}
+
+    <%= @system.config['name'] %>
+<% else %>
+title: "<%= @system.config['name'] -%>"
+<% end %>
+
 subtitle: "System Security Plan"
 
 author:
-<% @system.config.maintainers.each do |maintainer| %>
+<% @system.config['maintainers'].each do |maintainer| %>
     - <%= maintainer -%>
 <% end %>
 
 absract: |
-    <%= @system.config.metadata.abstract rescue 'None' %>
+    <%= @system.config['metadata']['abstract'] rescue 'None' %>
 
 description: |
-    <%= @system.config.metadata.description rescue 'None' %>
+    <%= @system.config['metadata']['description'] rescue 'None' %>
 
 fontsize: 11pt
 mainfont: NotoSans
@@ -44,52 +52,128 @@ geometry:
     - left=2cm
     - right=2cm
     - bottom=2cm
+
+header-includes:
+    - |
+        ```{=latex}
+        % https://github.com/jgm/pandoc/wiki/Pandoc-Tricks#left-aligning-tables-in-latex
+        \usepackage[margins=raggedright]{floatrow}
+        ```
+    - |
+        ```{=latex}
+        % https://github.com/jgm/pandoc/wiki/Pandoc-Tricks#definition-list-terms-on-their-own-line-in-latex
+        % "Clone" the original \item command
+        \let\originalitem\item
+
+        % Redefine the \item command using the "clone"
+        \makeatletter
+        \renewcommand{\item}[1][\@nil]{%
+            \def\tmp{#1}%
+            \ifx\tmp\@nnil\originalitem\else\originalitem[#1]\hfill\par\fi}
+        \makeatother
+        ```
+    - |
+        ```{=latex}
+        % The are at least two ways to configure how LaTeX floats figures.
+        %
+        % 1. One approach is described in section 17.2 of
+        %    http://tug.ctan.org/tex-archive/info/epslatex/english/epslatex.pdf
+        %    However, the approach described there requires to teach people
+        %    how to write LaTeX cross-references in markdown.
+        %
+        % 2. Force figures, listings, etc., to float "[H]ere".
+        %    This is a LaTeX anti-pattern because it causes large gaps of whitespace on some pages.
+        %    This approach avoids having to teach people to create LaTeX cross-references.
+        %    https://tex.stackexchange.com/a/101726
+        %
+        % Use option 2.
+        \usepackage{float}
+        \floatplacement{figure}{H}
+        ```
 ---
 
-# <%= @system.config.name %>
+# Introduction
 
-## Overview
+## About this document
+
+A System Security Plan (SSP) is a document to describe security controls in use
+on an information system and their implementation. An SSP provides:
+
+- Narrative of security control implementation
+- Description of components and services
+- System data flows and authorization boundaries
 
-<%= @system.config.overview %>
 
 ## Standards
 
-This System Security Plan (SSP) addresses these standards:
+This SSP draws from these standards:
 
 <% @system.standards.each do |s| -%>
-- <%= s.name %>
+- <%= s['name'] %>
 <% end %>
 
 The full copy of each standard is included in the appendix.
 
 
-## Components
+## Certifications
 
-<% @system.components.each do |c| %>
-### <%= c.name %>
+A certification is a logical grouping of controls that are of interest to
+a given subject. A particular certification does not necessarily target all
+controls from a standard, nor does a particular certification need to draw
+from a single standard.
 
-<%= c.description %>
+This SSP addresses these certifications:
+
+<% @system.certifications.each do |c| -%>
+- <%=c['name']%>
+
+<% c['requires'].each do |r| -%>
+    - <%=r['standard_key']-%> control <%=r['control_key']%>
+<% end -%>
 
-<% if c.attestations.empty? %>
-_The organization has not yet documented attestations for this component_.
-<% else %>
-The organization offers the following attestations for this component.
 <% end %>
 
-<% c.attestations.each do |a| %>
-####  <%= a.summary %>
 
-Status: <%= a.status %>
+# <%= @system.config['name'] %>
 
-Date verified: <%= a.date_verified if a.date_verified %>
+## Overview
 
-Satisfies:
+<%= @system.config['overview'] %>
 
-<% a.satisfies.each do |cid| -%>
-- <%= cid.standard_key %> control <%= cid.control_key %>
-<% end -%>
 
-<%= a.narrative %>
+## Components
+
+<% @system.components.each do |c| %>
+### <%= c['name'] %>
+
+<%= c['description'] %>
+
+<% if c['attestations'].empty? %>
+_The organization has not yet documented attestations for this component_.
+<% else %>
+The organization offers the following attestations for this component.
+<% end %>
+
+<% c['attestations'].compact.each do |a| %>
+####  <%= a['summary'] %>
+
++----------+---------------+--------------------------------------------------------------+
+| Status   | Date verified | Satisfies                                                    |
++==========+===============+==============================================================+
+<%
+s = a['satisfies'][0]
+verbiage = sprintf('%-58s', [s['standard_key'], 'control', s['control_key']].join(' '))
+-%>
+| <%=sprintf('%-8s', a['status'])-%> | <%=sprintf('%-13s', a['date_verified'])-%> | - <%=verbiage-%> |
+<%
+a['satisfies'][1..].each do |s|
+    verbiage = sprintf('%-58s', [s['standard_key'], 'control', s['control_key']].join(' '))
+-%>
+|          |               | - <%=verbiage-%> |
+<%  end -%>
++----------+---------------+--------------------------------------------------------------+
+
+<%= a['narrative'] %>
 
 <% end %>
 <% end %>
@@ -98,25 +182,29 @@ Satisfies:
 # Appendix: Standards
 
 <% @system.standards.each do |s| %>
-## <%=s.name %>
+## <%=s['name'] %>
 
-<% if s.families and !s.families.empty? %>
+<% if s['families'] and !s['families'].empty? %>
 ### Families
 
-<% s.families.each do |family| %>
-<%= family.family_key %>
-  ~ <%= family.name %>
+<%=s['name']-%> categorizes controls into logical groups called families.
 
-<% end %>
+| Family abbreviation        | Family name          |
+| -------------------------- | -------------------- |
+<% s['families'].each do |family| -%>
+| <%=family['family_key']-%> | <%=family['name']-%> |
+<% end -%>
+
+  : Control families for <%=s['name']%>
 
 <% end %>
 
 ### Controls
 
-<% s.controls.each do |c| %>
-#### Control <%= c.control_key -%>: <%= c.name %>
+<% s['controls'].each do |c| %>
+#### Control <%= c['control_key'] -%>: <%= c['name'] %>
 
-<%= c.description %>
+<%= c['description'] %>
 
 <% end %>
 <% end %>