octool 0.0.7 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fecd506f9519e5dea7be955335b43359dc1cf4b9b1f996410c952ec72384471
-  data.tar.gz: f841b91bd3e05d74a1dd90c634a9274119870bdb8698ac2c19685dd727ee6f06
+  metadata.gz: b2bc082300d2393b604bc09640def5bf7ad2cb0b05cf23b45f6e008a5d964547
+  data.tar.gz: 02b576ce174d710fd07e922f1f5aa818dec7114ee931ff39cbf3a2db8d64da1c
 SHA512:
-  metadata.gz: 725f37921c2943422622aad442451cf7178edd98b3f23f02ebcc27030f498290689711345a40baa160bc3054929cac00e1e2f2ff8a39cf0db6de75014a9cd324
-  data.tar.gz: 68e8b51a7784db9cb243caae5122faf05dfdcbb05b822b69b9afed5fff58fd857a93606d8adf7c5b62457642b6d6df30b4a5db2dd3f2e480f08905d6ccd36fb7
+  metadata.gz: 62fce55d3097c779050eab057ae9b167c72ef8b9a4b257a47630bff1518b6cce1f27a21a547e262862de3fa8608cf894582a2654ea665cc89d3dd819870bf99e
+  data.tar.gz: 64e7035d4ec01fcbb2c87665f8c1b4177561f0af8d3f4a6c226453f9f8c50e5d91c843351aefeea59f498edff066830a940a789c9cbb59b2372631c1fb01d9d9

data/bin/octool

@@ -77,12 +77,19 @@ class App
         s.arg_name 'path/to/output/dir'
         s.flag [:d, :dir]
 
+        s.desc 'Set SSP version'
+        s.default_value OCTool::DEFAULT_SSP_VERSION
+        s.long_desc 'Underscores are replaced by spaces'
+        s.arg_name 'VERSION'
+        s.flag :version
+
         s.action do |global_options, options, args|
             export_dir = options[:dir]
             config_file = find_config(args)
             system = OCTool::Parser.new(config_file).load_system
             Dir.chdir File.dirname(config_file) do
-                OCTool::SSP.new(system, export_dir).generate
+                OCTool::SSP.new(system, export_dir).generate(options[:version])
+                OCTool::SSP.new(system, export_dir).generate(options[:version], 'glossary')
             end
         end
     end

data/lib/octool.rb

@@ -4,6 +4,7 @@ require 'octool/version.rb'
 
 # Built-ins.
 require 'csv'
+require 'json'
 require 'pp'
 
 # 3rd-party libs.

data/lib/octool/constants.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 module OCTool
-    LATEST_SCHEMA_VERSION = 'v1.0.1'
+    LATEST_SCHEMA_VERSION = 'v1.0.2'
     BASE_SCHEMA_DIR = File.join(File.dirname(__FILE__), '..', '..', 'schemas').freeze
     ERB_DIR = File.join(File.dirname(__FILE__), '..', '..', 'templates').freeze
     DEFAULT_CONFIG_FILENAME = 'config.yaml'
     DEFAULT_OUTPUT_DIR = '/data'
+    DEFAULT_SSP_VERSION = 'unset'
 end

data/lib/octool/ssp.rb

@@ -1,13 +1,25 @@
 # frozen_string_literal: true
 
+require 'date'
 require 'erb'
 
 module OCTool
     # Build DB, CSV, and markdown.
     class SSP
+        attr_reader :build_date
+        attr_reader :version
+
         def initialize(system, output_dir)
             @system = system
             @output_dir = output_dir
+            @template_name = 'ssp'
+            @version = OCTool::DEFAULT_SSP_VERSION
+            @build_date = DateTime.now
+        end
+
+        def version=(version)
+            # LaTeX fancyheader aborts on underscore in footer.
+            @version = version.to_s.gsub(/_+/, ' ')
         end
 
         def pandoc
@@ -22,37 +34,48 @@ module OCTool
             exit(1)
         end
 
-        def generate
+        def generate(version = nil, template_name = 'ssp')
+            self.version = version if version
+            @template_name = template_name if template_name
             unless File.writable?(@output_dir)
                 warn "[FAIL] #{@output_dir} is not writable"
                 exit(1)
             end
             render_template
+            write_acronyms
             write 'pdf'
             write 'docx'
         end
 
         def render_template
             print "Building markdown #{md_path} ... "
-            template_path = File.join(ERB_DIR, 'ssp.erb')
             template = File.read(template_path)
             output = ERB.new(template, nil, '-').result(binding)
             File.open(md_path, 'w') { |f| f.puts output }
             puts 'done'
         end
 
+        def write_acronyms
+            return unless @system.acronyms
+
+            out_path = File.join(@output_dir, 'acronyms.json')
+            File.open(out_path, 'w') { |f| f.write JSON.pretty_generate(@system.acronyms) }
+            ENV['PANDOC_ACRONYMS_ACRONYMS'] = out_path
+        end
+
         # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         def write(type = 'pdf')
-            out_path = File.join(@output_dir, "ssp.#{type}")
+            out_path = File.join(@output_dir, "#{@template_name}.#{type}")
             print "Building #{out_path} ... "
             converter = pandoc.configure do
-                from 'markdown'
+                from 'markdown+autolink_bare_uris'
                 to type
                 pdf_engine 'lualatex'
-                toc
-                toc_depth 3
-                number_sections
                 highlight_style 'pygments'
+                filter 'pandoc-acronyms' if ENV['PANDOC_ACRONYMS_ACRONYMS']
+                # https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings#Encoding_issue
+                # Uncomment the following line after the "listings" package is compatible with utf8
+                # listings
             end
             output = converter << File.read(md_path)
             File.new(out_path, 'wb').write(output)
@@ -61,7 +84,11 @@ module OCTool
         # rubocop:enable Metrics/AbcSize,Metrics/MethodLength
 
         def md_path
-            @md_path ||= File.join(@output_dir, 'ssp.md')
+            File.join(@output_dir, "#{@template_name}.md")
+        end
+
+        def template_path
+            File.join(ERB_DIR, "#{@template_name}.erb")
         end
     end
 end

data/lib/octool/system.rb

@@ -22,6 +22,10 @@ module OCTool
             @data = []
         end
 
+        def acronyms
+            @acronyms ||= config['acronyms']
+        end
+
         def certifications
             @certifications ||= data.select { |e| e['type'] == 'certification' }
         end

data/lib/octool/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OCTool
-    VERSION = '0.0.7'
+    VERSION = '0.0.12'
 end

data/octool.rdoc

@@ -1,6 +1,6 @@
 == octool - Open Compliance Tool
 
-v0.0.7
+v0.0.12
 
 === Global Options
 === --help
@@ -48,6 +48,13 @@ where to store outputs
 [Default Value] /tmp
 Default output directory respects env vars TMPDIR, TMP, TEMP
 
+===== --version VERSION
+
+Set SSP version
+
+[Default Value] unset
+Underscores are replaced by spaces
+
 ==== Command: <tt>validate </tt>
 Check sanity of configuration
 

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/glossary.erb

@@ -0,0 +1,173 @@
+---
+<% if @system.config['logo'] -%>
+title: |
+    ![](<%= @system.config['logo']['path'] -%>){width=<%= @system.config['logo']['width'] %>}
+
+    Glossary
+<% else %>
+title: "Glossary"
+<% end %>
+
+subtitle: |
+    <%=build_date.strftime('%Y-%b-%d')%>
+
+<% unless version == OCTool::DEFAULT_SSP_VERSION -%>
+    Version <%=version%>
+<% end -%>
+
+fontsize: 11pt
+mainfont: NotoSans
+monofont: NotoSansMono-ExtraCondensed
+mainfontoptions:
+    - Numbers=Lowercase
+    - Numbers=Proportional
+    - UprightFont=*
+    - ItalicFont=*-Italic
+    - BoldFont=*-Bold
+    - BoldItalicFont=*-BoldItalic
+
+colorlinks: true
+linkcolor: black  # internal links (e.g., lof and lot)
+urlcolor: blue
+
+documentclass: article
+classoption:
+    - onecolumn
+    - oneside
+    - portrait
+
+pagestyle: headings
+papersize: letter
+geometry:
+    - top=2cm
+    - left=3cm
+    - right=2cm
+    - bottom=2cm
+
+header-includes:
+    - |
+        ```{=latex}
+        % https://ctan.org/pkg/metalogo?lang=en
+        \usepackage{metalogo}
+        ```
+    - |
+        ```{=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
+
+        % Create variable with default value false to use later
+        % http://handyfloss.net/2007.08/latex-programming-how-to-implement-conditionals/
+        \newif \ifonelinedef
+        \onelinedeffalse
+
+        % Redefine the \item command using the "clone"
+        \makeatletter
+        \renewcommand{\item}[1][\@nil] {%
+            \def \tmp {#1}%
+            \ifx \tmp \@nnil
+                \originalitem
+            \else
+                \ifonelinedef
+                    \originalitem[#1]\vspace{4mm}\par
+                \else
+                    \originalitem[#1]\hfill\par
+                \fi
+            \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}
+        ```
+    - |
+        ```{=latex}
+        % https://tex.stackexchange.com/a/32537
+        \usepackage{lastpage}
+
+        % https://ctan.org/pkg/fancyhdr?lang=en
+        \usepackage{fancyhdr}
+
+        \pagestyle{fancy}
+        <% unless version == OCTool::DEFAULT_SSP_VERSION %>
+        \fancyfoot[L]{Version: <%=version-%>}
+        <% end %>
+        \fancyfoot[C]{<%=build_date.strftime('%Y-%b-%d')-%>}
+        \fancyfoot[R]{\thepage\ of\ \pageref{LastPage}}
+        \renewcommand{\footrulewidth}{0.4pt} % thickness
+        \renewcommand{\headrulewidth}{0.4pt} % thickness
+        \fancypagestyle{plain}{\fancyhead{}\renewcommand{\headrule}{}}
+        ```
+    - |
+        ```{=latex}
+        % Which bullet glyphs are avaiable?
+        % http://texdoc.net/texmf-dist/doc/latex/comprehensive/symbols-a4.pdf TABLE 50
+        %
+        % https://learnbyexample.github.io/tutorial/ebook-generation/customizing-pandoc/
+        % https://tex.stackexchange.com/questions/174244/change-the-shape-of-the-bullet-list
+        % https://texblog.org/2008/10/16/lists-enumerate-itemize-description-and-how-to-change-them/
+        % https://tex.stackexchange.com/a/64899
+        % https://ctan.org/pkg/enumitem?lang=en
+        % https://www.latex4technics.com/?note=2vy0
+        %
+        %\usepackage{amsfonts}
+        %
+        % Make bullets small
+        %\renewcommand{\labelitemi}{\tiny $\textbullet$}
+        %\renewcommand{\labelitemii}{\tiny $\textopenbullet$}
+        %\renewcommand{\labelitemiii}{\tiny $\triangleright$}
+        %
+        % Align bullets to left margin and make small
+        % https://tex.stackexchange.com/a/86408
+        %\usepackage{enumitem}
+        %\usepackage{graphicx}
+        %\setlist[itemize,1]{leftmargin=*,label=\scalebox{.8}{$\textbullet$}}
+        %\setlist[itemize,2]{leftmargin=*,label=\scalebox{.8}{$\textopenbullet$}}
+        %\setlist[itemize,3]{leftmargin=*,label=\scalebox{.8}{\triangleright}}
+        %
+        % Align bullets to left margin and use normal font
+        \usepackage{enumitem}
+        \setlist[itemize,1]{leftmargin=*,label=$\textbullet$}
+        \setlist[itemize,2]{leftmargin=*,label=$\textopenbullet$}
+        \setlist[itemize,3]{leftmargin=*,label=\triangleright}
+        %
+        % Align bullets to left margin and use slightly smaller font
+        %\usepackage{MnSymbol}
+        %\setlist[itemize,1]{leftmargin=*,label=$\bullet$}
+        %\setlist[itemize,2]{leftmargin=*,label=$\circ$}
+        %\setlist[itemize,3]{leftmargin=*,label=\blacktriangleright}
+        ```
+---
+
+<% if @system.config['acronyms'] %>
+
+<!-- Force glossary to be typeset as oneline definitions. -->
+\onelinedeftrue
+
+<% @system.config['acronyms'].values.sort_by { |a| a['shortform'] }. each do |a| %>
+<%=a['shortform']%>
+  ~ <%=a['longform']%>
+
+<% end %>
+\onelinedeffalse
+<% end %>

data/templates/ssp.erb

@@ -8,10 +8,17 @@ title: |
 title: "<%= @system.config['name'] -%>"
 <% end %>
 
-subtitle: "System Security Plan"
+subtitle: |
+    System Security Plan
+
+    <%=build_date.strftime('%Y-%b-%d')%>
+
+<% unless version == OCTool::DEFAULT_SSP_VERSION -%>
+    Version <%=version%>
+<% end -%>
 
 author:
-<% @system.config['maintainers'].each do |maintainer| %>
+<% @system.config['maintainers'].each do |maintainer| -%>
     - <%= maintainer -%>
 <% end %>
 
@@ -23,7 +30,6 @@ description: |
 
 fontsize: 11pt
 mainfont: NotoSans
-#monofont: NotoSansMono-ExtraCondensedLight
 monofont: NotoSansMono-ExtraCondensed
 mainfontoptions:
     - Numbers=Lowercase
@@ -39,6 +45,10 @@ colorlinks: true
 linkcolor: black  # internal links (e.g., lof and lot)
 urlcolor: blue
 
+toc: true
+toc_depth: 3
+numbersections: true
+
 documentclass: report
 classoption:
     - onecolumn
@@ -49,28 +59,176 @@ pagestyle: headings
 papersize: letter
 geometry:
     - top=2cm
-    - left=2cm
+    - left=3cm
     - right=2cm
     - bottom=2cm
+
+header-includes:
+    - |
+        ```{=latex}
+        % https://ctan.org/pkg/metalogo?lang=en
+        \usepackage{metalogo}
+        ```
+    - |
+        ```{=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
+
+        % Create variable with default value false to use later
+        % http://handyfloss.net/2007.08/latex-programming-how-to-implement-conditionals/
+        \newif \ifonelinedef
+        \onelinedeffalse
+
+        % Redefine the \item command using the "clone"
+        \makeatletter
+        \renewcommand{\item}[1][\@nil] {%
+            \def \tmp {#1}%
+            \ifx \tmp \@nnil
+                \originalitem
+            \else
+                \ifonelinedef
+                    \originalitem[#1]\vspace{4mm}\par
+                \else
+                    \originalitem[#1]\hfill\par
+                \fi
+            \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}
+        ```
+    - |
+        ```{=latex}
+        % https://tex.stackexchange.com/a/32537
+        \usepackage{lastpage}
+
+        % https://ctan.org/pkg/fancyhdr?lang=en
+        \usepackage{fancyhdr}
+
+        \pagestyle{fancy}
+        <% unless version == OCTool::DEFAULT_SSP_VERSION %>
+        \fancyfoot[L]{Version: <%=version-%>}
+        <% end %>
+        \fancyfoot[C]{<%=build_date.strftime('%Y-%b-%d')-%>}
+        \fancyfoot[R]{\thepage\ of\ \pageref{LastPage}}
+        \renewcommand{\footrulewidth}{0.4pt} % thickness
+        \renewcommand{\headrulewidth}{0.4pt} % thickness
+        \fancypagestyle{plain}{\fancyhead{}\renewcommand{\headrule}{}}
+        ```
+    - |
+        ```{=latex}
+        % Which bullet glyphs are avaiable?
+        % http://texdoc.net/texmf-dist/doc/latex/comprehensive/symbols-a4.pdf TABLE 50
+        %
+        % https://learnbyexample.github.io/tutorial/ebook-generation/customizing-pandoc/
+        % https://tex.stackexchange.com/questions/174244/change-the-shape-of-the-bullet-list
+        % https://texblog.org/2008/10/16/lists-enumerate-itemize-description-and-how-to-change-them/
+        % https://tex.stackexchange.com/a/64899
+        % https://ctan.org/pkg/enumitem?lang=en
+        % https://www.latex4technics.com/?note=2vy0
+        %
+        %\usepackage{amsfonts}
+        %
+        % Make bullets small
+        %\renewcommand{\labelitemi}{\tiny $\textbullet$}
+        %\renewcommand{\labelitemii}{\tiny $\textopenbullet$}
+        %\renewcommand{\labelitemiii}{\tiny $\triangleright$}
+        %
+        % Align bullets to left margin and make small
+        % https://tex.stackexchange.com/a/86408
+        %\usepackage{enumitem}
+        %\usepackage{graphicx}
+        %\setlist[itemize,1]{leftmargin=*,label=\scalebox{.8}{$\textbullet$}}
+        %\setlist[itemize,2]{leftmargin=*,label=\scalebox{.8}{$\textopenbullet$}}
+        %\setlist[itemize,3]{leftmargin=*,label=\scalebox{.8}{\triangleright}}
+        %
+        % Align bullets to left margin and use normal font
+        \usepackage{enumitem}
+        \setlist[itemize,1]{leftmargin=*,label=$\textbullet$}
+        \setlist[itemize,2]{leftmargin=*,label=$\textopenbullet$}
+        \setlist[itemize,3]{leftmargin=*,label=\triangleright}
+        %
+        % Align bullets to left margin and use slightly smaller font
+        %\usepackage{MnSymbol}
+        %\setlist[itemize,1]{leftmargin=*,label=$\bullet$}
+        %\setlist[itemize,2]{leftmargin=*,label=$\circ$}
+        %\setlist[itemize,3]{leftmargin=*,label=\blacktriangleright}
+        ```
 ---
 
-# <%= @system.config['name'] %>
+# Introduction
 
-## Overview
+## About this document
 
-<%= @system.config['overview'] %>
+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
+
+The SSP is also a tool to guide the assessment of the effectiveness
+of controls within the system.
 
 ## Standards
 
-This System Security Plan (SSP) addresses these standards:
+This SSP draws from these standards:
 
 <% @system.standards.each do |s| -%>
-- <%= s['name'] %>
+- <%=s['name']-%> (<%=s['standard_key']-%>)
 <% end %>
 
 The full copy of each standard is included in the appendix.
 
 
+## Certifications
+
+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.
+
+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 -%>
+
+<% end %>
+
+
+# <%= @system.config['name'] %>
+
+## Overview
+
+<%= @system.config['overview'] %>
+
+
 ## Components
 
 <% @system.components.each do |c| %>
@@ -84,18 +242,24 @@ _The organization has not yet documented attestations for this component_.
 The organization offers the following attestations for this component.
 <% end %>
 
-<% c['attestations'].each do |a| %>
+<% c['attestations'].compact.each do |a| %>
 ####  <%= a['summary'] %>
 
-Status: <%= a['status'] %>
-
-Date verified: <%= a['date_verified'] if a['date_verified'] %>
-
-Satisfies:
-
-<% a['satisfies'].each do |cid| -%>
-- <%= cid['standard_key'] %> control <%= cid['control_key'] %>
-<% end -%>
++----------+---------------+--------------------------------------------------------------+
+| 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'] %>
 
@@ -111,11 +275,15 @@ Satisfies:
 <% 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 %>
 
@@ -128,3 +296,49 @@ Satisfies:
 
 <% end %>
 <% end %>
+
+
+<% if @system.config['acronyms'] %>
+# Glossary
+
+<!-- Force glossary to be typeset as oneline definitions. -->
+\onelinedeftrue
+
+<% @system.config['acronyms'].values.sort_by { |a| a['shortform'] }. each do |a| %>
+<%=a['shortform']%>
+  ~ <%=a['longform']%>
+
+<% end %>
+\onelinedeffalse
+<% end %>
+
+
+# Colophon
+
+This document was typeset in NotoSans with \LuaTeX\.
+The main body font is 11-point, and
+code snippets use NotoSansMono-ExtraCondensed.
+
+The Noto family of fonts is freely available and developed by Google,
+which describes Noto as:
+
+> When text is rendered by a computer, sometimes characters are displayed as
+> "tofu". They are little boxes to indicate your device doesn't have a
+> font to display the text.
+>
+> Google has been developing a font family called Noto, which aims to support
+> all languages with a harmonious look and feel. Noto is Google's answer to
+> tofu. The name noto is to convey the idea that Google's goal is to see
+> "no more tofu". Noto has multiple styles and weights, and is freely
+> available to all.
+
+Core tools used to produce this document:
+
+- [Docker](https://www.docker.com/) provides a repeatable environment in
+  which to run the tools.
+- [OCTool](https://github.com/jumanjihouse/octool)
+  provides a schema and wrapper to express compliance data as configuration.
+- [Pandoc](https://pandoc.org/) converts extended markdown to PDF output.
+- [Python](https://www.python.org/) is a core language for automation.
+- [Ruby](https://www.ruby-lang.org/en/) is a core language for automation.
+- [TeXLive](https://www.tug.org/texlive/) provides the \TeX\ family of tools.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octool
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.12
 platform: ruby
 authors:
 - Paul Morgan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-24 00:00:00.000000000 Z
+date: 2020-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -92,6 +92,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 2.19.0
+- !ruby/object:Gem::Dependency
+  name: json_pure
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: kwalify
   requirement: !ruby/object:Gem::Requirement
@@ -160,6 +174,11 @@ files:
 - schemas/v1.0.1/component.yaml
 - schemas/v1.0.1/config.yaml
 - schemas/v1.0.1/standard.yaml
+- schemas/v1.0.2/certification.yaml
+- schemas/v1.0.2/component.yaml
+- schemas/v1.0.2/config.yaml
+- schemas/v1.0.2/standard.yaml
+- templates/glossary.erb
 - templates/ssp.erb
 homepage: https://github.com/jumanjiman/octool
 licenses: