octool 0.0.4 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,60 @@
1
+ ---
2
+ type: map
3
+ class: Component
4
+ mapping:
5
+ name:
6
+ desc: Human-friendly name to appear in the SSP.
7
+ type: str
8
+ required: true
9
+ component_key:
10
+ desc: Unique identifier for referential integrity.
11
+ type: str
12
+ required: true
13
+ description:
14
+ desc: A paragraph or two that describes the component.
15
+ type: str
16
+ required: true
17
+ attestations:
18
+ desc: List of attestations.
19
+ type: seq
20
+ sequence:
21
+ - type: map
22
+ class: Attestation
23
+ mapping:
24
+ summary:
25
+ desc: Arbitrary verbiage to appear in SSP as a TLDR.
26
+ type: str
27
+ required: true
28
+ status:
29
+ desc: To what extent is this attestation "done"?
30
+ type: str
31
+ required: true
32
+ enum:
33
+ - partial
34
+ - complete
35
+ - planned
36
+ - none
37
+ date_verified:
38
+ desc: When was this last verified?
39
+ type: date
40
+ required: false
41
+ satisfies:
42
+ desc: List of control IDs covered by this attestation.
43
+ type: seq
44
+ required: false
45
+ sequence:
46
+ - type: map
47
+ class: ControlID
48
+ mapping:
49
+ standard_key:
50
+ type: text
51
+ required: true
52
+ control_key:
53
+ type: text
54
+ required: true
55
+ narrative:
56
+ desc: |
57
+ Explain how attestation satisfies the indicated controls.
58
+ The content should be in markdown format.
59
+ type: str
60
+ required: true
@@ -0,0 +1,79 @@
1
+ ---
2
+ type: map
3
+ class: Config
4
+ mapping:
5
+ schema_version:
6
+ desc: |
7
+ Must match one of the schema directories in the octool source.
8
+ required: true
9
+ type: str
10
+
11
+ logo:
12
+ desc: Image for title page.
13
+ required: false
14
+ type: map
15
+ class: Logo
16
+ mapping:
17
+ path:
18
+ desc: Path to image.
19
+ type: str
20
+ required: true
21
+ width:
22
+ desc: Width of image, such as "1in" or "254mm"
23
+ type: str
24
+ required: true
25
+
26
+ name:
27
+ desc: Human-friendly to appear in the SSP.
28
+ required: true
29
+ type: str
30
+
31
+ overview:
32
+ desc: Human-friendly description to appear in the SSP.
33
+ required: true
34
+ type: str
35
+
36
+ maintainers:
37
+ desc: Who should somebody contact for questions about this SSP?
38
+ required: true
39
+ type: seq
40
+ sequence:
41
+ - type: str
42
+
43
+ metadata:
44
+ desc: Optional metadata.
45
+ required: false
46
+ type: map
47
+ class: Metadata
48
+ mapping:
49
+ abstract:
50
+ desc: Abstract appears in document metadata.
51
+ required: false
52
+ type: str
53
+ description:
54
+ desc: Description appears in document metadata.
55
+ required: false
56
+ type: str
57
+ '=':
58
+ desc: Arbitrary key:value pair of strings.
59
+ type: str
60
+
61
+ includes:
62
+ desc: Additional files to include from the system repo.
63
+ required: true
64
+ type: seq
65
+ sequence:
66
+ - type: map
67
+ class: Include
68
+ mapping:
69
+ type:
70
+ required: true
71
+ type: str
72
+ enum:
73
+ - certification
74
+ - component
75
+ - standard
76
+ path:
77
+ desc: Path must be relative within the repo.
78
+ required: true
79
+ type: str
@@ -0,0 +1,50 @@
1
+ ---
2
+ type: map
3
+ class: Standard
4
+ mapping:
5
+ name:
6
+ desc: Human-friendly name to appear in SSP.
7
+ type: str
8
+ required: true
9
+
10
+ standard_key:
11
+ desc: Unique ID to use within YAML files.
12
+ type: str
13
+ required: true
14
+
15
+ families:
16
+ desc: Optional list of control families.
17
+ type: seq
18
+ required: false
19
+ sequence:
20
+ - type: map
21
+ class: ControlFamily
22
+ mapping:
23
+ family_key:
24
+ desc: Unique ID of the family
25
+ type: str
26
+ unique: true
27
+ name:
28
+ desc: Human-friendly name of the family
29
+ type: str
30
+ controls:
31
+ desc: Mandatory list of controls defined by the standard.
32
+ required: true
33
+ type: seq
34
+ sequence:
35
+ - type: map
36
+ class: Control
37
+ mapping:
38
+ control_key:
39
+ type: str
40
+ unique: true
41
+ required: true
42
+ family_key:
43
+ type: str
44
+ required: false
45
+ name:
46
+ type: str
47
+ required: true
48
+ description:
49
+ type: str
50
+ required: true
@@ -0,0 +1,27 @@
1
+ ---
2
+ type: map
3
+ class: Certification
4
+ mapping:
5
+ certification_key:
6
+ desc: A short, unique identifier for this certification.
7
+ required: true
8
+ type: str
9
+ unique: true
10
+ name:
11
+ desc: A human-friendly name for the certification.
12
+ required: true
13
+ type: str
14
+ requires:
15
+ desc: List of control IDs required by the certification.
16
+ required: true
17
+ type: seq
18
+ sequence:
19
+ - type: map
20
+ class: ControlID
21
+ mapping:
22
+ standard_key:
23
+ required: true
24
+ type: str
25
+ control_key:
26
+ required: true
27
+ type: str
@@ -0,0 +1,60 @@
1
+ ---
2
+ type: map
3
+ class: Component
4
+ mapping:
5
+ name:
6
+ desc: Human-friendly name to appear in the SSP.
7
+ type: str
8
+ required: true
9
+ component_key:
10
+ desc: Unique identifier for referential integrity.
11
+ type: str
12
+ required: true
13
+ description:
14
+ desc: A paragraph or two that describes the component.
15
+ type: str
16
+ required: true
17
+ attestations:
18
+ desc: List of attestations.
19
+ type: seq
20
+ sequence:
21
+ - type: map
22
+ class: Attestation
23
+ mapping:
24
+ summary:
25
+ desc: Arbitrary verbiage to appear in SSP as a TLDR.
26
+ type: str
27
+ required: true
28
+ status:
29
+ desc: To what extent is this attestation "done"?
30
+ type: str
31
+ required: true
32
+ enum:
33
+ - partial
34
+ - complete
35
+ - planned
36
+ - none
37
+ date_verified:
38
+ desc: When was this last verified?
39
+ type: date
40
+ required: false
41
+ satisfies:
42
+ desc: List of control IDs covered by this attestation.
43
+ type: seq
44
+ required: false
45
+ sequence:
46
+ - type: map
47
+ class: ControlID
48
+ mapping:
49
+ standard_key:
50
+ type: text
51
+ required: true
52
+ control_key:
53
+ type: text
54
+ required: true
55
+ narrative:
56
+ desc: |
57
+ Explain how attestation satisfies the indicated controls.
58
+ The content should be in markdown format.
59
+ type: str
60
+ required: true
@@ -0,0 +1,111 @@
1
+ ---
2
+ type: map
3
+ class: Config
4
+ mapping:
5
+ schema_version:
6
+ desc: |
7
+ Must match one of the schema directories in the octool source.
8
+ required: true
9
+ type: str
10
+
11
+ logo:
12
+ desc: Image for title page.
13
+ required: false
14
+ type: map
15
+ class: Logo
16
+ mapping:
17
+ path:
18
+ desc: Path to image.
19
+ type: str
20
+ required: true
21
+ width:
22
+ desc: Width of image, such as "1in" or "254mm"
23
+ type: str
24
+ required: true
25
+
26
+ name:
27
+ desc: Human-friendly to appear in the SSP.
28
+ required: true
29
+ type: str
30
+
31
+ overview:
32
+ desc: Human-friendly description to appear in the SSP.
33
+ required: true
34
+ type: str
35
+
36
+ maintainers:
37
+ desc: Who should somebody contact for questions about this SSP?
38
+ required: true
39
+ type: seq
40
+ sequence:
41
+ - type: str
42
+
43
+ metadata:
44
+ desc: Optional metadata.
45
+ required: false
46
+ type: map
47
+ class: Metadata
48
+ mapping:
49
+ abstract:
50
+ desc: Abstract appears in document metadata.
51
+ required: false
52
+ type: str
53
+ description:
54
+ desc: Description appears in document metadata.
55
+ required: false
56
+ type: str
57
+ '=':
58
+ desc: Arbitrary key:value pair of strings.
59
+ type: str
60
+
61
+ includes:
62
+ desc: Additional files to include from the system repo.
63
+ required: true
64
+ type: seq
65
+ sequence:
66
+ - type: map
67
+ class: Include
68
+ mapping:
69
+ type:
70
+ required: true
71
+ type: str
72
+ enum:
73
+ - certification
74
+ - component
75
+ - standard
76
+ path:
77
+ desc: Path must be relative within the repo.
78
+ required: true
79
+ type: str
80
+
81
+ acronyms:
82
+ desc: |
83
+ List of acronyms to be referenced in the doc.
84
+
85
+ The acronyms follow the forms and usage described by the pandoc filter
86
+ https://gitlab.com/mirkoboehm/pandoc-acronyms
87
+
88
+ If your config.yaml includes acronyms, the filter is automatically invoked.
89
+ required: false
90
+ type: map
91
+ mapping:
92
+ '=':
93
+ desc: |
94
+ Acronym as used in the doc source, such as "bba".
95
+ The source usually refers to the acronym with syntax "[!bba]",
96
+ but other syntax forms are possible (see upstream doc).
97
+ type: map
98
+ class: Acronym
99
+ mapping:
100
+ shortform:
101
+ desc: The short form of the expanded acronym, such as "BBA".
102
+ required: true
103
+ type: str
104
+ longform:
105
+ desc: |
106
+ The expanded form of the abbreviation, such as "Beer Brewing Attitude".
107
+ The first instance of "[!bba]" in the doc is automatically expanded to
108
+ "<longform> (<shortform>)".
109
+ Example: "[!bba]" expands to "Beer Brewing Attitude (BBA)".
110
+ required: true
111
+ type: str
@@ -0,0 +1,50 @@
1
+ ---
2
+ type: map
3
+ class: Standard
4
+ mapping:
5
+ name:
6
+ desc: Human-friendly name to appear in SSP.
7
+ type: str
8
+ required: true
9
+
10
+ standard_key:
11
+ desc: Unique ID to use within YAML files.
12
+ type: str
13
+ required: true
14
+
15
+ families:
16
+ desc: Optional list of control families.
17
+ type: seq
18
+ required: false
19
+ sequence:
20
+ - type: map
21
+ class: ControlFamily
22
+ mapping:
23
+ family_key:
24
+ desc: Unique ID of the family
25
+ type: str
26
+ unique: true
27
+ name:
28
+ desc: Human-friendly name of the family
29
+ type: str
30
+ controls:
31
+ desc: Mandatory list of controls defined by the standard.
32
+ required: true
33
+ type: seq
34
+ sequence:
35
+ - type: map
36
+ class: Control
37
+ mapping:
38
+ control_key:
39
+ type: str
40
+ unique: true
41
+ required: true
42
+ family_key:
43
+ type: str
44
+ required: false
45
+ name:
46
+ type: str
47
+ required: true
48
+ description:
49
+ type: str
50
+ required: true
@@ -1,17 +1,25 @@
1
1
  ---
2
- title: "<%= @system.config.name -%>"
2
+ <% if @system.config['logo'] -%>
3
+ title: |
4
+ ![](<%= @system.config['logo']['path'] -%>){width=<%= @system.config['logo']['width'] %>}
5
+
6
+ <%= @system.config['name'] %>
7
+ <% else %>
8
+ title: "<%= @system.config['name'] -%>"
9
+ <% end %>
10
+
3
11
  subtitle: "System Security Plan"
4
12
 
5
13
  author:
6
- <% @system.config.maintainers.each do |maintainer| %>
14
+ <% @system.config['maintainers'].each do |maintainer| %>
7
15
  - <%= maintainer -%>
8
16
  <% end %>
9
17
 
10
18
  absract: |
11
- <%= @system.config.metadata.abstract rescue 'None' %>
19
+ <%= @system.config['metadata']['abstract'] rescue 'None' %>
12
20
 
13
21
  description: |
14
- <%= @system.config.metadata.description rescue 'None' %>
22
+ <%= @system.config['metadata']['description'] rescue 'None' %>
15
23
 
16
24
  fontsize: 11pt
17
25
  mainfont: NotoSans
@@ -44,52 +52,128 @@ geometry:
44
52
  - left=2cm
45
53
  - right=2cm
46
54
  - bottom=2cm
55
+
56
+ header-includes:
57
+ - |
58
+ ```{=latex}
59
+ % https://github.com/jgm/pandoc/wiki/Pandoc-Tricks#left-aligning-tables-in-latex
60
+ \usepackage[margins=raggedright]{floatrow}
61
+ ```
62
+ - |
63
+ ```{=latex}
64
+ % https://github.com/jgm/pandoc/wiki/Pandoc-Tricks#definition-list-terms-on-their-own-line-in-latex
65
+ % "Clone" the original \item command
66
+ \let\originalitem\item
67
+
68
+ % Redefine the \item command using the "clone"
69
+ \makeatletter
70
+ \renewcommand{\item}[1][\@nil]{%
71
+ \def\tmp{#1}%
72
+ \ifx\tmp\@nnil\originalitem\else\originalitem[#1]\hfill\par\fi}
73
+ \makeatother
74
+ ```
75
+ - |
76
+ ```{=latex}
77
+ % The are at least two ways to configure how LaTeX floats figures.
78
+ %
79
+ % 1. One approach is described in section 17.2 of
80
+ % http://tug.ctan.org/tex-archive/info/epslatex/english/epslatex.pdf
81
+ % However, the approach described there requires to teach people
82
+ % how to write LaTeX cross-references in markdown.
83
+ %
84
+ % 2. Force figures, listings, etc., to float "[H]ere".
85
+ % This is a LaTeX anti-pattern because it causes large gaps of whitespace on some pages.
86
+ % This approach avoids having to teach people to create LaTeX cross-references.
87
+ % https://tex.stackexchange.com/a/101726
88
+ %
89
+ % Use option 2.
90
+ \usepackage{float}
91
+ \floatplacement{figure}{H}
92
+ ```
47
93
  ---
48
94
 
49
- # <%= @system.config.name %>
95
+ # Introduction
50
96
 
51
- ## Overview
97
+ ## About this document
98
+
99
+ A System Security Plan (SSP) is a document to describe security controls in use
100
+ on an information system and their implementation. An SSP provides:
101
+
102
+ - Narrative of security control implementation
103
+ - Description of components and services
104
+ - System data flows and authorization boundaries
52
105
 
53
- <%= @system.config.overview %>
54
106
 
55
107
  ## Standards
56
108
 
57
- This System Security Plan (SSP) addresses these standards:
109
+ This SSP draws from these standards:
58
110
 
59
111
  <% @system.standards.each do |s| -%>
60
- - <%= s.name %>
112
+ - <%= s['name'] %>
61
113
  <% end %>
62
114
 
63
115
  The full copy of each standard is included in the appendix.
64
116
 
65
117
 
66
- ## Components
118
+ ## Certifications
67
119
 
68
- <% @system.components.each do |c| %>
69
- ### <%= c.name %>
120
+ A certification is a logical grouping of controls that are of interest to
121
+ a given subject. A particular certification does not necessarily target all
122
+ controls from a standard, nor does a particular certification need to draw
123
+ from a single standard.
70
124
 
71
- <%= c.description %>
125
+ This SSP addresses these certifications:
126
+
127
+ <% @system.certifications.each do |c| -%>
128
+ - <%=c['name']%>
129
+
130
+ <% c['requires'].each do |r| -%>
131
+ - <%=r['standard_key']-%> control <%=r['control_key']%>
132
+ <% end -%>
72
133
 
73
- <% if c.attestations.empty? %>
74
- _The organization has not yet documented attestations for this component_.
75
- <% else %>
76
- The organization offers the following attestations for this component.
77
134
  <% end %>
78
135
 
79
- <% c.attestations.each do |a| %>
80
- #### <%= a.summary %>
81
136
 
82
- Status: <%= a.status %>
137
+ # <%= @system.config['name'] %>
83
138
 
84
- Date verified: <%= a.date_verified if a.date_verified %>
139
+ ## Overview
85
140
 
86
- Satisfies:
141
+ <%= @system.config['overview'] %>
87
142
 
88
- <% a.satisfies.each do |cid| -%>
89
- - <%= cid.standard_key %> control <%= cid.control_key %>
90
- <% end -%>
91
143
 
92
- <%= a.narrative %>
144
+ ## Components
145
+
146
+ <% @system.components.each do |c| %>
147
+ ### <%= c['name'] %>
148
+
149
+ <%= c['description'] %>
150
+
151
+ <% if c['attestations'].empty? %>
152
+ _The organization has not yet documented attestations for this component_.
153
+ <% else %>
154
+ The organization offers the following attestations for this component.
155
+ <% end %>
156
+
157
+ <% c['attestations'].compact.each do |a| %>
158
+ #### <%= a['summary'] %>
159
+
160
+ +----------+---------------+--------------------------------------------------------------+
161
+ | Status | Date verified | Satisfies |
162
+ +==========+===============+==============================================================+
163
+ <%
164
+ s = a['satisfies'][0]
165
+ verbiage = sprintf('%-58s', [s['standard_key'], 'control', s['control_key']].join(' '))
166
+ -%>
167
+ | <%=sprintf('%-8s', a['status'])-%> | <%=sprintf('%-13s', a['date_verified'])-%> | - <%=verbiage-%> |
168
+ <%
169
+ a['satisfies'][1..].each do |s|
170
+ verbiage = sprintf('%-58s', [s['standard_key'], 'control', s['control_key']].join(' '))
171
+ -%>
172
+ | | | - <%=verbiage-%> |
173
+ <% end -%>
174
+ +----------+---------------+--------------------------------------------------------------+
175
+
176
+ <%= a['narrative'] %>
93
177
 
94
178
  <% end %>
95
179
  <% end %>
@@ -98,25 +182,29 @@ Satisfies:
98
182
  # Appendix: Standards
99
183
 
100
184
  <% @system.standards.each do |s| %>
101
- ## <%=s.name %>
185
+ ## <%=s['name'] %>
102
186
 
103
- <% if s.families and !s.families.empty? %>
187
+ <% if s['families'] and !s['families'].empty? %>
104
188
  ### Families
105
189
 
106
- <% s.families.each do |family| %>
107
- <%= family.family_key %>
108
- ~ <%= family.name %>
190
+ <%=s['name']-%> categorizes controls into logical groups called families.
109
191
 
110
- <% end %>
192
+ | Family abbreviation | Family name |
193
+ | -------------------------- | -------------------- |
194
+ <% s['families'].each do |family| -%>
195
+ | <%=family['family_key']-%> | <%=family['name']-%> |
196
+ <% end -%>
197
+
198
+ : Control families for <%=s['name']%>
111
199
 
112
200
  <% end %>
113
201
 
114
202
  ### Controls
115
203
 
116
- <% s.controls.each do |c| %>
117
- #### Control <%= c.control_key -%>: <%= c.name %>
204
+ <% s['controls'].each do |c| %>
205
+ #### Control <%= c['control_key'] -%>: <%= c['name'] %>
118
206
 
119
- <%= c.description %>
207
+ <%= c['description'] %>
120
208
 
121
209
  <% end %>
122
210
  <% end %>