Debian Codegraph @

texmf-dist/source/latex/cyber/cyber.dtx

raw
1 % \iffalse meta-comment
2 % Copyright (c) 2015 Jared Jennings <[email protected]>
3 %
4 % Permission is hereby granted, free of charge, to any person
5 % obtaining a copy of this software and associated documentation
6 % files (the "Software"), to deal in the Software without
7 % restriction, including without limitation the rights to use, copy,
8 % modify, merge, publish, distribute, sublicense, and/or sell copies
9 % of the Software, and to permit persons to whom the Software is
10 % furnished to do so, subject to the following conditions:
11 %
12 % The above copyright notice and this permission notice shall be
13 % included in all copies or substantial portions of the Software.
14 %
15 % THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 % EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 % MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 % NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 % BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 % ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 % CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 % SOFTWARE.
23 % \fi
24 %
25 % ^^A We cannot \usepackage{cyber}, because it pulls in index,
26 % ^^A which screws up Doc's attempts to index all the macros we use.
27 % ^^A Therefore we do not get \filedate and \fileversion for free.
28 % \def\filedate{2018/01/24}
29 % \def\fileversion{v2.2}
30 % \iffalse
31 %<package>\NeedsTeXFormat{LaTeX2e}
32 %<package>\ProvidesPackage{cyber}
33 %<package> [2018/01/24 v2.2 Add some semicolons in accordance with DTIC guidance]
34 %
35 %<*driver>
36 \documentclass{ltxdoc}
37
38 \usepackage{fancyvrb}
39 \DefineShortVerb{\|}
40
41
42 % Make PDF magic happen.
43 % Thanks, Patrick Joeckel:
44 % http://www.mpch-mainz.mpg.de/~joeckel/pdflatex/
45 % Note that I expect always to use pdflatex, not latex+dvipdf
46 \usepackage[bookmarks=true,bookmarksnumbered=true,breaklinks=true,pdftex]{hyperref}
47 \hypersetup{
48 colorlinks=false,
49 linkbordercolor={0.7 0.7 1.0}
50 }
51
52 \EnableCrossrefs
53 \RecordChanges
54 \CodelineIndex
55
56 \begin{document}
57 \DocInput{cyber.dtx}
58 \end{document}
59 %</driver>
60 % \fi
61 %
62 % \CheckSum{0}
63 %
64 % \CharacterTable
65 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
66 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
67 % Digits \0\1\2\3\4\5\6\7\8\9
68 % Exclamation \! Double quote \" Hash (number) \#
69 % Dollar \$ Percent \% Ampersand \&
70 % Acute accent \' Left paren \( Right paren \)
71 % Asterisk \* Plus \+ Comma \,
72 % Minus \- Point \. Solidus \/
73 % Colon \: Semicolon \; Less than \<
74 % Equals \= Greater than \> Question mark \?
75 % Commercial at \@ Left bracket \[ Backslash \\
76 % Right bracket \] Circumflex \^ Underscore \_
77 % Grave accent \` Left brace \{ Vertical bar \|
78 % Right brace \} Tilde \~}
79 %
80 % \changes{v1.0}{2011/07/18}{Renamed afseocmp to skiadoc}
81 % \changes{v1.1}{2012/06/06}{Made skiadoc into a \LaTeX\ package}
82 % \changes{v1.2}{2012/12/14}{Added support for other distribution statements
83 % besides D; organization logo must now be provided by the document being
84 % typeset}
85 % \changes{v1.3}{2012/12/17}{Renamed skiadoc to iadoc}
86 % \changes{v1.4}{2012/12/31}{Added indexing suppression macros}
87 % \changes{v1.5}{2013/02/01}{Flattened all compliance indices into one}
88 % \changes{v1.6}{2015/03/07}{Renamed iadoc to cyber: `IA' does not immediately mean anything outside the DoD, and the DoD has stopped using the term in preference to `cyber' anyway}
89 % \changes{v2.0}{2015/03/21}{Use index package instead of multind}
90 % \changes{v2.1}{2015/06/24}{Fix packaging issues}
91 % \changes{v2.2}{2018/01/24}{Add some semicolons in accordance with DTIC guidance}
92 %
93 % \title{The \textsf{cyber} package\thanks{This document corresponds to
94 % \textsf{cyber}~\fileversion, dated~\filedate.}}
95 % \author{Jared Jennings \\ \texttt{[email protected]}}
96 %
97 % \maketitle
98 % \tableofcontents
99 % \clearpage
100 %
101 %
102 % \section{What \textsf{cyber} is for}
103 %
104 % This package helps you construct documents that talk about compliance with
105 % named requirements.
106 %
107 % For example, U.S. National Institute of Standards and Technology
108 % (NIST) Special Publication (SP) 800-53 sets out \emph{security
109 % controls} for U.S. Federal agency information systems, one of which
110 % is AC-2c, ``[The organization] establishes conditions for group and
111 % role membership.'' You may wish to write a document that says, ``We
112 % comply with AC-2c, and here's how.'' This package is for you.
113 %
114 %
115 % \section{Document identifiers}
116 %
117 % Your document may talk about compliance with named requirements from multiple
118 % sources. For example, besides compliance with NIST SP 800-53 you might want to
119 % also talk about compliance with the U.S. Defense Information Systems Agency
120 % (DISA) UNIX Operating System (OS) Security Requirements Guide (SRG). Now to
121 % fully identify a requirement, you need to identify both the requirement and
122 % the document it comes from, for example ``IA control IAAC-1,'' or ``UNIX SRG
123 % Potential Discrepancy Item (PDI) GEN006480.''
124 %
125 % At the beginning of your document, you must identify all sources of named
126 % requirements; then you can talk about those sources when you are identifying
127 % the requirements. As examples here we use NIST SP 800-53, and assign it the
128 % document identifier |secctrl|; and we use the UNIX SRG, identifying it by
129 % |unixsrg|. See~\S\ref{document_identifiers} for more.
130 %
131 %
132 % \section{Macros used in the body of your document}
133 %
134 % When you use the macros below to indicate requirements levied by policies
135 % handed down from above, or parts of code or documentation that relate to
136 % those requirements, you get some style for free, and an entry in an index.
137 % Also, other automated document features are made possible which are not
138 % strictly based on \LaTeX ; for example, a Puppet manifest annotated using
139 % \textsf{cyber} may have a table of compliance which a script constructs
140 % automatically by searching the manifest for uses of these macros.
141 %
142 % \subsection{Mentioning named requirements}
143 %
144 % Here are macros to use to indicate when you are talking about a specific
145 % requirement. These tags do not indicate any compliance posture, just that
146 % we're mentioning the requirement. So use these to refer to requirements in
147 % passing. Just like the names of celebrities are sometimes set in bold type in
148 % magazines, so that you can skip around and look for your favorite famous
149 % person, we want to make it easy to find all mentions of a given named
150 % requirement.
151 %
152 % \begin{itemize}
153 % \item
154 % \DescribeMacro{\secctrl}
155 % |\secctrl| \marg{control identifier}
156 % \item
157 % \DescribeMacro{\unixsrg}
158 % |\unixsrg| \marg{PDI}
159 % \end{itemize}
160 %
161 % The exact set of these macros depends on the set of requirements documents
162 % named at the beginning of your document; see~\S\ref{document_identifiers}.
163 %
164 % Example:
165 % \begin{Verbatim}[gobble=2]
166 % Compliance with such and such requirement is similar to compliance with
167 % \unixsrg{GEN002600}, \emph{q.v.}.
168 % \end{Verbatim}
169 %
170 %
171 % \subsection{Making assertions about compliance posture}
172 %
173 % Most mentions of named requirements are going to be something like, ``We
174 % comply with bla requirement,'' or ``We don't comply with this one, and here's
175 % why.'' The following tags make it quick and simple for you to write such
176 % assertions.
177 %
178 %
179 % \DescribeMacro{\documents}
180 % Use |\documents| for notating some text in your document that says a fact
181 % about a system which supports a requirement. It takes two parameters: the
182 % type of requirement, and the name of the requirement. Example:
183 %
184 % \begin{Verbatim}[gobble=2]
185 % \documents{secctrl}{SC-18} We use only JavaScript, which is Category I
186 % mobile code according to DoD guidelines.
187 % \end{Verbatim}
188 %
189 % Some requirements say something like, ``All \emph{mumble}s must be justified
190 % and documented with the Information Assurance Officer (IAO).'' Use
191 % |\documents| to assert either that those things are documented, right here,
192 % or that you should look in \emph{bla} document to find that documentation.
193 %
194 % For example, the UNIX SRG requires that UNIX systems unable to require a
195 % password to enter single-user mode must be documented with the IAO.
196 %
197 % \begin{Verbatim}[gobble=2]
198 % \documents{unixsrg}{GEN000040} UNIX hosts unable to require a password
199 % to enter single-user mode must be documented with the IAO. We administer
200 % no such UNIX hosts.
201 % \end{Verbatim}
202 % (This is written in a document which is produced under the IAO's purview
203 % and approval; otherwise it would have to point to another document which is
204 % ``with the IAO.'')
205 %
206 %
207 % \DescribeMacro{\notapplicable}
208 % Just before some discussion about why a requirement is not applicable in a
209 % certain situation, put the |\notapplicable| tag. For example:
210 %
211 % \begin{Verbatim}[gobble=2]
212 % \notapplicable{secctrl}{SC-18(5)} We do not use mobile code at all.
213 % \end{Verbatim}
214 %
215 % \DescribeMacro{\implements}
216 % The |\implements| tag notates a section of code or documentation which
217 % directly implements a requirement. It's usually used in automated policy. For
218 % example, the UNIX SRG says under GEN001362, ``The \Verb!/etc/resolv.conf!
219 % file must be owned by root.'' A piece of Puppet policy that implements this
220 % requirement may go like:
221 %
222 % \begin{Verbatim}[gobble=2]
223 % # \implements{unixsrg}{GEN001362} Make sure resolv.conf
224 % # is owned by root.
225 % file { '/etc/resolv.conf':
226 % owner => root,
227 % }
228 % \end{Verbatim}
229 %
230 %
231 % \DescribeMacro{\doneby}
232 % The |\doneby| tag is for requirements that are not fulfilled in an automated
233 % fashion: people are responsible for carrying them out on a day-by-day basis.
234 % It takes three parameters: who exactly does this thing, the kind of
235 % requirement, and the requirement's name. For example, the RHEL5 STIG requires
236 % that SELinux be turned on when installing RHEL5. Administrators have to make
237 % sure it's enabled during the install process.
238 %
239 % \begin{Verbatim}[gobble=2]
240 % \doneby{admins}{rhel5stig}{GEN000000-LNX00800} Make sure SELinux is
241 % enabled when installing RHEL5.
242 % \end{Verbatim}
243 %
244 % \DescribeMacro{\bydefault}
245 % Use the |\bydefault| tag to talk about how a product we use implements a
246 % given requirement in its default configuration. It takes three parameters:
247 % the product we're talking about, the kind of requirement, and the
248 % requirement's name.---For example, the UNIX SRG says under GEN001300 that all
249 % library files must have mode \Verb!0755! or less permissive. Both RHEL 5 and
250 % RHEL 6 systems have this property by default.
251 %
252 % \begin{Verbatim}[gobble=2]
253 % \bydefault{RHEL5, RHEL6}{unixsrg}{GEN001300} All library files under
254 % RHEL are mode \Verb!0755! or less permissive by default.
255 % \end{Verbatim}
256 %
257 %
258 % \DescribeMacro{\unimplemented}
259 % Use the |\unimplemented| tag to talk about a requirement we need to fulfill
260 % but haven't yet. (Don't use |\unimplemented| to talk about a requirement
261 % we don't intend ever to fulfill: it turns some things red to bring our
262 % attention to them; we don't want false alarms.)
263 %
264 % Note carefully that this tag has three parameters: the kind of
265 % requirement, the exact requirement, and \emph{the reason} the requirement
266 % is unimplemented. You can't use \Verb!\Verb! in the reason. Stick with plain
267 % text.
268 %
269 % \begin{Verbatim}[gobble=2]
270 % \unimplemented{unixsrg}{GEN008380}{Unless root kit checking
271 % functionality is provided by the virus scanner, we would likely
272 % want to deploy {\tt chkrootkit}. But this software is not yet
273 % approved...}
274 % \end{Verbatim}
275 %
276 %
277 %
278 %
279 % \section{Security labels}
280 %
281 % Some regulations require that documents be marked and labelled. These
282 % tags help you do that.
283 %
284 % \DescribeMacro{\articlesecuritylabel}
285 % When you are writing an article (|\documentclass{article}|), this tag helps
286 % you label it. It will put the text you give at the top of every page. Put
287 % the tag right after |\usepackage{cyber}|, as close to the top of the
288 % document source as possible. That way it will be visible to viewers of the
289 % document source as well.
290 %
291 % Most reStructuredText documents use the article class.
292 %
293 % Example, in \LaTeX :
294 % \begin{Verbatim}[gobble=2]
295 % \articlesecuritylabel{UNCLASSIFIED//FOUO}
296 % \end{Verbatim}
297 %
298 % \DescribeMacro{\booksecuritylabel}
299 % |\booksecuritylabel| acts the same as |\articlesecuritylabel|, but this is
300 % the one you should use if you are using the \textsf{book} document class.
301 %
302 % Part of marking a document properly is writing the distribution statement and
303 % statement of disposition on the title page.
304 %
305 % See \url{http://www.dtic.mil/dtic/submit/guidance/distribstatement.html} on
306 % distribution statements and on destruction of limited-distribution
307 % unclassified documents.
308 %
309 % \section{Distribution statements}
310 %
311 % Write the distribution statement right after the security label. Statements
312 % allowed by DoDI 5320.24 as of 23 August 2012 are A through F. Macros for
313 % these are provided. Dates are set to |\today|. For guidance on the reasons,
314 % see the DoD instruction.
315 %
316 % Just like you need |\maketitle| to make your |\title| show up, you need to
317 % (instead) use |\makedodtitle| to make your distribution statement show up.
318 %
319 % \DescribeMacro{\distributionA}
320 % To mark your document with Distro A (public release), write |\distributionA|
321 % \marg{other information}. Local policies may require that you include a
322 % reference number, or the name of the organization which cleared the document,
323 % or some such. That's ``other information.''
324 %
325 % \DescribeMacro{\distributionB}
326 % To U.S. Government agencies only: |\distributionB| \marg{reason why}
327 % \marg{controlling office}.
328 %
329 % \DescribeMacro{\distributionC}
330 % To U.S. Government agencies and their contractors: |\distributionC| \marg{reason
331 % why} \marg{controlling office}.
332 %
333 % \DescribeMacro{\distributionD}
334 % To DoD and DoD contractors only: |\distributionD| \marg{reason why}
335 % \marg{controlling office}.
336 %
337 % \DescribeMacro{\distributionE}
338 % To DoD Components only: |\distributionE| \marg{reason why} \marg{controlling
339 % office}.
340 %
341 % \DescribeMacro{\distributionF}
342 % Only as directed by the controlling office or higher DoD authority:
343 % |\distributionF| \marg{controlling office}.
344 %
345 % You are responsible for understanding what these statements mean and whether
346 % you're allowed to use them.
347 %
348 %
349 % \section{Document formatting aids}
350 %
351 % \subsection{DoD title page}
352 % \DescribeMacro{\makedodtitle} In a book-class document, use
353 % |\makedodtitle| instead of \Verb!\maketitle! and you will get an
354 % organization logo on your title page. You'll also get the distribution
355 % statement. You must provide the organization logo, as a graphics file of a
356 % suitable format (\emph{e.g.}, PNG or PDF if you're using \Verb!pdflatex!, EPS
357 % if you're using \Verb!latex!, that sort of thing), entitled \Verb!org_logo!,
358 % \emph{e.g.} \Verb!org_logo.png!.
359 %
360 % \subsection{Narrower margins}
361 % \DescribeMacro{\narrowermargins}
362 % Nobody appreciates the rules of typography these days. And making a bad
363 % impression on auditors by submitting a document that doesn't look how they
364 % expect is a needless risk.
365 %
366 % This macro narrows the margins, while leaving a sizable margin in which to
367 % write text. It probably only works on books (not articles). It takes the
368 % security label into account.
369 %
370 % In the top of your document, put |\narrowermargins| to make all of the
371 % margins narrower by a half inch, increasing the text area by one inch
372 % horizontally and one inch vertically. You have to put it above the security
373 % label.
374 %
375 % This has not been tested much, and only on a book-class document.
376 %
377 % \subsection{Change log}
378 %
379 % Most documents submitted in support of cybersecurity goals must
380 % indicate what version they are, and what changes have happened between
381 % versions. In software development terminology, these correspond to
382 % \emph{releases}, not \emph{revisions} or \emph{changesets}; that is to say,
383 % these versions are likely not to change more than once a month, and changes
384 % are likely to be, ``Added a new chapter about foo,'' rather than ``Corrected
385 % spelling on page 358.''
386 %
387 % Write a changelog and call it \Verb!changelog.tex!. Include it in your
388 % front matter just after the table of contents. Its format is like so:
389 %
390 % \begin{Verbatim}[gobble=2]
391 % \begin{changelog}
392 %
393 % \change{3 Aug 2011}{Jared Jennings}{Added Backup Plan}
394 %
395 % \change{2 Aug 2011}{Jared Jennings}{New server purchased; changed Hardware
396 % Baseline to match}
397 %
398 % \end{changelog}
399 % \end{Verbatim}
400 %
401 % Add new entries to the top of the changelog, not the bottom.
402 %
403 % \subsection{Executive summary}
404 % An ``executive summary'' is supported. This is just a section containing a
405 % table which lists the larger security controls this document is about.
406 % Its format is like so:
407 %
408 % \begin{Verbatim}[gobble=2]
409 % \begin{executivesummary}
410 % \executivesummaryiacontrol{IAIA-1}{Individual Authentication}
411 % \end{executivesummary}
412 % \end{Verbatim}
413 %
414 % Put it after the changelog, after the ToC.
415 %
416 %
417 % \section{Document identifiers}
418 % \label{document_identifiers}
419 %
420 % To identify a requirement you want to talk about without ambiguity,
421 % you need to give a name for both the requirement and the document it
422 % came from. Since document identifiers are written in potentially
423 % hundreds of compliance tags across a document, they need to be
424 % short, but unique. Here are some example document identifiers:
425 %
426 % \begin{description}
427 % \item[iacontrol] Information Assurance Controls, laid out in DoDI
428 % 8500.2, e.g. DCMC-1.
429 % \item[secctrl] Security Controls, laid out in NIST SP 800-53, e.g. SC-18c.
430 % \item[unixsrg] UNIX Security Requirements Guide (SRG) Potential
431 % Discrepancy Identifiers (PDIs), e.g. GEN008520.
432 % \item[rhel5stig] Red Hat Enterprise Linux (RHEL) 5 STIG PDIs.
433 % \end{description}
434 %
435 % \subsection{Defining requirements documents}
436 %
437 % In the preamble of your document, you must tell \textsf{cyber} from which
438 % documents your requirements will come. \DescribeMacro{\requirementsdocument}
439 % Use the |\requirementsdocument| macro to do this. For example,
440 %
441 % \begin{Verbatim}[gobble=2]
442 % \requirementsdocument{joesaidso}{Joe's Demands}{Demand }
443 % \end{Verbatim}
444 %
445 % The first parameter is the document identifier, which is used in the
446 % compliance tags. For example, after this |\requirementsdocument|, in the body
447 % of our document we could write
448 %
449 % \begin{Verbatim}[gobble=2]
450 % \documents{joesaidso}{Joe34} We close the door when going outside, because
451 % Joe said to. Door-closing logs are kept just inside the door.
452 % \end{Verbatim}
453 %
454 % The second parameter is the header under which all requirements from this
455 % document will be placed in the Compliance index. Given the above code, the
456 % index might look like:
457 %
458 % \begin{Verbatim}[gobble=2]
459 % Compliance
460 %
461 % Joe's Demands
462 % Joe34
463 % documented, 3
464 % \end{Verbatim}
465 %
466 % The third parameter is the prefix with which requirements from this document
467 % will be named. For example, if we were to write |\joesaidso{Joe34}| in the
468 % body of a document, we would see ``Demand Joe34'' in the rendering of that
469 % document.
470 %
471 %
472 % \section{Adding \textsf{cyber} to a document}
473 %
474 % If you are editing or adding to an existing document which already uses
475 % \textsf{cyber}, you need not concern yourself with this section.
476 %
477 % To use \textsf{cyber} in a new document: you should have the \textsf{cyber} package
478 % installed; see
479 % \url{http://en.wikibooks.org/wiki/LaTeX/Packages/Installing_Extra_Packages}.
480 %
481 % At the top of your document, in its preamble, put the following lines:
482 %
483 % \begin{Verbatim}[gobble=2]
484 % \usepackage{cyber}
485 % \end{Verbatim}
486 %
487 % This makes the indices that the \textsf{cyber} tags put entries into.
488 %
489 % Somewhere in the preamble of your document, after you use the \textsf{cyber}
490 % package, tell \textsf{cyber} about all your |\requirementsdocument|s.
491 %
492 % Somewhere at the end of your document, put
493 %
494 % \begin{Verbatim}[gobble=2]
495 % \printindex{cyber_compliance}{Compliance}
496 % \end{Verbatim}
497 %
498 % This grabs the index made and makes it part of the final document.
499 %
500 %
501 % \subsection{Controls in contents}
502 %
503 % If you want the IA controls covered in a section to be summarized in the
504 % section's title written in the table of contents, use this additional
505 % package:
506 %
507 % \begin{Verbatim}[gobble=2]
508 % \usepackage{iacic}
509 % \end{Verbatim}
510 %
511 % Write this after the usepackage directive for \textsf{cyber}. If you use the
512 % hyperref package, write this statement after the usepackage directive for
513 % hyperref.
514 %
515 % If you use iacic, your section titles cannot contain any formatting, and your
516 % document cannot be originally written in reStructuredText. Section titles
517 % written in the body text will not change: only the ones in the contents.
518 % Section titles written in page headers will vary. In general this is a buggy,
519 % wonky feature. See \url{http://tex.stackexchange.com/questions/29818}. Dive
520 % into the wonderful world of \TeX\ and \LaTeX . Learn you a fix for great
521 % good!
522 %
523 %
524 % \subsection{Temporarily suppressing index entries}
525 %
526 % If some part of your document is an auto-summary of another part of your
527 % document, to index mentions of requirements in the summarized part may be
528 % redundant and undesirable.
529 %
530 % \DescribeMacro{\Cyberindexingenabledfalse}
531 %
532 % \DescribeMacro{\Cyberindexingenabledtrue}
533 %
534 % Use these macros to turn off and on (respectively) indexing of compliance
535 % assertions for part of your document. For example:
536 %
537 % \begin{Verbatim}[gobble=2]
538 % \Cyberindexingenabledfalse
539 % \include{auto_summary}
540 % \Cyberindexingenabledtrue
541 % \end{Verbatim}
542 %
543 %
544 % \section{Interactions with other packages}
545 % If you use \textsf{hyperref}, do so \emph{before} you use \textsf{cyber}.
546 %
547 % Because \textsf{cyber} requires \textsf{longtable}, you can't use two
548 % columns in a document that uses \textsf{cyber}. The requirement for
549 % longtable stems from the executive summary and changelog, which may have
550 % enough rows to span pages.
551 %
552 % Because \textsf{cyber} requires \textsf{index}, any other package which
553 % automatically indexes things may not work in conjunction with
554 % \textsf{cyber}.
555 %
556 % \textsf{cyber} also pulls in \textsf{color}, \textsf{fancyhdr} and
557 % \textsf{graphicx}.
558 %
559 %
560 %
561 %
562 % \section{Implementation}
563 %
564 % \StopEventually{}
565 % \begin{macrocode}
566 \makeatletter
567 % \end{macrocode}
568 % We require longtable for the changelog and executive summary, which could span pages.
569 % \begin{macrocode}
570 \RequirePackage{longtable}
571 % \end{macrocode}
572 % We require color so that we can make red some text regarding unimplemented
573 % requirements.
574 % \begin{macrocode}
575 \RequirePackage{color}
576 % \end{macrocode}
577 % There are potentially hundreds of requirements with which to comply. So we
578 % want them in their own index.
579 % \begin{macrocode}
580 \RequirePackage{index}
581 % \end{macrocode}
582 % The \textsf{fancyhdr} package is how we add security labels.
583 % \begin{macrocode}
584 \RequirePackage{fancyhdr}
585 % \end{macrocode}
586 % And the graphicx package is needed so the organization's logo can be put on
587 % the front page.
588 % \begin{macrocode}
589 \RequirePackage{graphicx}
590
591 % \end{macrocode}
592 % Index entries are written into the compliance index.
593 % \begin{macrocode}
594 \newindex{cybercompliance}{cybercompliance.idx}{cybercompliance.ind}{Compliance}
595 % \end{macrocode}
596 % Notations of compliance throughout the document are written in compliance.aux
597 % and explanations.aux.
598 % \begin{macrocode}
599 \AtBeginDocument{
600 \newwrite\complianceaux
601 \immediate\openout\complianceaux=cyber_compliance.aux
602 \newwrite\explanationsaux
603 \immediate\openout\explanationsaux=cyber_explanations.aux
604 }
605
606 \AtEndDocument{
607 \immediate\closeout\complianceaux
608 \immediate\closeout\explanationsaux
609 }
610 % \end{macrocode}
611
612 % The foreach code below is from:
613 % \url{http://stackoverflow.com/questions/2402354/split-comma-separated-parameters-in-latex}
614 % and/or \url{http://maraist.org/comma-separated-lists-in-latex_08-2009/}.
615 % Added two extra pass-through parameters.
616 %
617 % \begin{macro}{\foreach}
618 % Functional foreach construct.
619 % Usage: |\foreach| \marg{macro} \marg{firstarg} \marg{secondarg}
620 % \marg{third1,third2,third3,...}. Evaluates to
621 % |\macro{firstarg}{secondarg}{third1}| |\macro{firstarg}{secondarg}{third2}|
622 % etc.
623 %
624 % Put another way: \meta{\#1} is a function to call once for each
625 % comma-separated item in \meta{\#4}. \meta{\#2} and \meta{\#3} are parameters to
626 % pass to function in \meta{\#1} as the first parameters. \meta{\#4} is a
627 % comma-separated list of items, each of which to pass as the third parameter
628 % to an invocation of function \meta{\#1}.
629 % \begin{macrocode}
630 \def\foreach#1#2#3#4{%
631 \@test@foreach{#1}{#2}{#3}#4,\@end@token%
632 }
633 % \end{macrocode}
634 % \end{macro}
635
636 % Internal helper function - Eats one input.
637 % \begin{macrocode}
638 \def\@swallow#1{}
639 % \end{macrocode}
640
641 % Internal helper function - Checks the next character after \#1 and \#2 and
642 % continues loop iteration if |\@end@token| is not found.
643 % \begin{macrocode}
644 \def\@test@foreach#1#2#3{%
645 \@ifnextchar\@end@token%
646 {\@swallow}%
647 {\@foreach{#1}{#2}{#3}}%
648 }
649 % \end{macrocode}
650
651 % Internal helper function - Calls |#1{#2}{#3}{#4}| and recurses.
652 % The magic of splitting the third parameter occurs in the pattern matching of
653 % the |\def|.
654 % \begin{macrocode}
655 \def\@foreach#1#2#3#4,#5\@end@token{%
656 #1{#2}{#3}{#4}%
657 \@test@foreach{#1}{#2}{#3}#5\@end@token%
658 }
659 % \end{macrocode}
660
661
662 % \begin{macro}{\requirementsdocument}
663 % Usage: |\requirementsdocument| \marg{tag} \marg{index heading}
664 % \marg{requirement title}. The tag is a one-word lowercase name, like
665 % iacontrol or unixsrg or rhel5stig, that you'll use in |\implements|
666 % and other tags to say from which document comes the requirement
667 % you're talking about. An index of compliance will be made;
668 % |index heading| is the title under which all compliance with this document
669 % will be listed in the compliance index, for example ``NIST SP 800-53
670 % Security Controls.'' The |requirement title| is how to name a
671 % requirement from that document. For example, the DISA UNIX SRG
672 % contains many requirements, called Potential Discrepancy Items
673 % (PDI). So you may give ``UNIX SRG PDI '' (note the space at the end)
674 % as the requirement title, and when a requirement is named using
675 % |\requirement| it will be prefixed with the title, e.g. ``UNIX SRG
676 % PDI GEN006480.''
677 %
678 % Write all |\requirementsdocument|s in the preamble of the document.
679 %
680 % \begin{macrocode}
681 \newcommand{\requirementsdocument}[3]{%
682 % Say how to name requirements that come from this document.
683 \expandafter\providecommand\csname #1\endcsname[1]{%
684 \namedrequirement{#1}{#3}{##1}}
685 \expandafter\newcommand\csname indexhead#1\endcsname{#2}
686 }
687 % \end{macrocode}
688 % \end{macro}
689
690 % \begin{macro}{\requirement}
691 % Usage: |\requirement| \marg{document tag} \marg{requirement name}. Example:
692 % |\requirement{unixsrg}{GEN006480}|. Use this macro to mention requirements
693 % that come from other documents, without implying a particular compliance
694 % posture. For example, ``The check content of
695 % |\requirement{unixsrg}{GEN006480}| suggests the following solution.''
696 % \begin{macrocode}
697 \newcommand{\requirement}[2]{%
698 \expandafter\csname requirement@#1\endcsname{#2}}
699 % \end{macrocode}
700 % \end{macro}
701
702 % \begin{macro}{\namedrequirement}
703 % Usage: |\namedrequirement| \marg{index name} \marg{official title prefix} \marg{requirement name}.
704 % Example: |\namedrequirement{iacontrol}{IA Control }{IAAC-1}| will say ``IA
705 % Control IAAC-1'' in the body of the document, and make an index entry in the
706 % compliance index under the ``IA Controls'' heading. (``IA Controls'' in this
707 % example is the value of a parameter given to |\requirementsdocument|, not to
708 % this macro.)
709 %
710 % This macro exists so it will be possible to redefine it to change how such a
711 % thing looks. When referring to a named requirement in a document that you are
712 % writing, use |\requirement| above, not this macro.
713 %
714 % The index macro is the same as in indexhelper below but without the last
715 % |!{#2}| for the subhead.
716 % \begin{macrocode}
717 \newcommand{\namedrequirement}[3]{%
718 \index[cybercompliance]{\csname indexhead#1\endcsname @\iaindexheadstyle{\csname indexhead#1\endcsname}!{#3}!}%
719 {\small #2\mbox{#3}}%
720 }
721 % \end{macrocode}
722 % \end{macro}
723 %
724 % This will be redefined by \textsf{iacic} if that package is included.
725 % \begin{macrocode}
726 \def\addtosectionname#1{}
727 % \end{macrocode}
728 %
729 % This is here so you can turn off indexing for a portion of your document.
730 % \begin{macrocode}
731 \newif\ifCyberindexingenabled
732 \Cyberindexingenabledtrue
733 % \end{macrocode}
734 %
735 % Style the text for per-document heads in the compliance index.
736 % \begin{macrocode}
737 \newcommand{\iaindexheadstyle}[1]{%
738 \vspace{1em}{\large \textbf{#1}}\vspace{1em}}
739 % \end{macrocode}
740 %
741 % parameters: index name, implementation status, requirement name
742 % \begin{macrocode}
743 \newcommand{\indexhelper}[3]{%
744 \ifCyberindexingenabled\index[cybercompliance]{\csname indexhead#1\endcsname @\iaindexheadstyle{\csname indexhead#1\endcsname}!{#3}!{#2}}\fi}
745 % \end{macrocode}
746 %
747 % parameters: index name, prefix (e.g. {RHEL5: }), requirement name
748 % \begin{macrocode}
749 \newcommand{\marginhelper}[3]{#2~\mbox{#3}\\ }
750 % \end{macrocode}
751 %
752 % parameters: index name, compliance status, requirement name.
753 % Compliance status is not necessarily the same as implementation status.
754 % \begin{macrocode}
755 \newcommand{\compliancehelper}[3]{%
756 \write\complianceaux{#1:#3:#2}}
757 % \end{macrocode}
758 %
759 % parameters: index name, explanation, requirement name
760 % \begin{macrocode}
761 \newcommand{\explanationshelper}[3]{%
762 \write\explanationsaux{#1:#3:}%
763 \write\explanationsaux{#2}%
764 \write\explanationsaux{:}%
765 }
766 % \end{macrocode}
767
768 % parameters: index name, nothing, requirement name
769 % \begin{macrocode}
770 \newcommand{\sectionnamehelper}[3]{%
771 \def\@numberone{#1}%
772 \def\@iacontrol{iacontrol}%
773 \ifx\@numberone\@iacontrol\addtosectionname{#3}\fi}
774 % \end{macrocode}
775 %
776 % \begin{macrocode}
777 \def\iamarginsize{\footnotesize}
778 % \end{macrocode}
779 %
780 % These all take two parameters.
781 % The first parameter is the identifier of the document from which the
782 % requirement comes (e.g. iacontrol, unixstig, spanstig, apachestig,
783 % etc)---same names as the indices. The second parameter is which
784 % requirement(s) is/are in the given status (e.g. GEN000320). You may supply
785 % multiple values for this one, separated by commas.
786 %
787 % Example: |\implements{unixsrg}{GEN000320,GEN000340}|
788 %
789 % \begin{macrocode}
790 \newcommand{\implements}[2]{%
791 \@bsphack
792 \hspace{0pt}% this makes sure the marginpar doesn't go with the previous
793 % paragraph
794 \foreach{\indexhelper}{#1}{implemented}{#2}%
795 \marginpar{\iamarginsize \raggedright%
796 \foreach{\marginhelper}{#1}{auto:}{#2}%
797 }%
798 \foreach{\compliancehelper}{#1}{compliant}{#2}%
799 \foreach{\sectionnamehelper}{#1}{}{#2}%
800 \@esphack}
801 \newcommand{\unimplemented}[3]{%
802 \@bsphack
803 \hspace{0pt}% this makes sure the marginpar doesn't go with the previous
804 % paragraph
805 \foreach{\indexhelper}{#1}{\textcolor{red}{unimplemented}}{#2}%
806 \marginpar{\iamarginsize \color{red} \raggedright%
807 \foreach{\marginhelper}{#1}{}{#2}%
808 }%
809 \foreach{\compliancehelper}{#1}{non-compliant}{#2}%
810 \foreach{\explanationshelper}{#1}{#3}{#2}%
811 \foreach{\sectionnamehelper}{#1}{}{#2}%
812 {#3}%
813 \@esphack}
814 % \end{macrocode}
815 %
816 % Except this one takes three parameters: operating system(s),
817 % identifier of requiring document, requirement(s).
818 % \begin{macrocode}
819 \newcommand{\bydefault}[3]{%
820 \@bsphack
821 \hspace{0pt}% this makes sure the marginpar doesn't go with the previous
822 % paragraph
823 \foreach{\indexhelper}{#2}{default for {#1}}{#3}%
824 \marginpar{\iamarginsize \raggedright%
825 \foreach{\marginhelper}{#2}{#1: }{#3}%
826 }%
827 \foreach{\compliancehelper}{#2}{compliant}{#3}%
828 \foreach{\sectionnamehelper}{#1}{}{#2}%
829 \@esphack}
830 % \end{macrocode}
831 %
832 % \begin{macrocode}
833 \newcommand{\notapplicable}[2]{%
834 \@bsphack
835 \hspace{0pt}% this makes sure the marginpar doesn't go with the previous
836 % paragraph
837 \foreach{\indexhelper}{#1}{N/A}{#2}%
838 \marginpar{\iamarginsize \raggedright%
839 \foreach{\marginhelper}{#1}{N/A: }{#2}%
840 }%
841 \foreach{\compliancehelper}{#1}{N/A}{#2}%
842 \@esphack}
843 % \end{macrocode}
844
845 % \begin{macrocode}
846 \newcommand{\doneby}[3]{%
847 \@bsphack
848 \hspace{0pt}% this makes sure the marginpar doesn't go with the previous
849 % paragraph
850 \foreach{\indexhelper}{#2}{prescribed}{#3}%
851 \marginpar{\iamarginsize \raggedright%
852 \foreach{\marginhelper}{#2}{#1 do }{#3}%
853 }%
854 \foreach{\compliancehelper}{#2}{compliant}{#3}%
855 \foreach{\sectionnamehelper}{#1}{}{#2}%
856 \@esphack}
857 % \end{macrocode}
858
859 % deprecated
860 % \begin{macrocode}
861 \newcommand{\prescribed}[2]{\doneby{admins}{#1}{#2}}
862 % \end{macrocode}
863
864 % \begin{macrocode}
865 \newcommand{\documented}[2]{%
866 \@bsphack
867 \hspace{0pt}% this makes sure the marginpar doesn't go with the previous
868 % paragraph
869 \foreach{\indexhelper}{#1}{documented}{#2}%
870 \marginpar{\iamarginsize \raggedright%
871 \foreach{\marginhelper}{#1}{}{#2}%
872 }%
873 \foreach{\compliancehelper}{#1}{compliant}{#2}%
874 \foreach{\sectionnamehelper}{#1}{}{#2}%
875 \@esphack}
876 % \end{macrocode}
877
878 % \begin{macrocode}
879 \newcommand{\documents}[2]{\documented{#1}{#2}}
880 % \end{macrocode}
881
882
883 % \begin{macro}{\articlesecuritylabel}
884 % Use this to label documents of class \textsl{article}.
885 % Use like |\articlesecuritylabel| \marg{thing to write on each page}.
886 % The thing will be written as part of the page header.
887 % \begin{macrocode}
888 \newcommand{\articlesecuritylabel}[1]{%
889 \pagestyle{fancy}%
890 \renewcommand{\headrulewidth}{0pt}%
891 \fancyhf{}%
892 \chead{#1}%
893 \cfoot{\thepage}%
894 \fancypagestyle{plain}{%
895 \fancyhf{}%
896 \fancyhead[C]{#1}%
897 }%
898 }
899 % \end{macrocode}
900 % \end{macro}
901 %
902 % \begin{macro}{\booksecuritylabel}
903 % Use this one to label books. Syntax is the same as above.
904 % \begin{macrocode}
905 \newcommand{\booksecuritylabel}[1]{%
906 \pagestyle{fancy}%
907 \renewcommand{\headrulewidth}{0.1pt}%
908 \fancyhf{}%
909 \fancyhead[CE,CO]{#1\vspace{2\baselineskip}}%
910 \fancyhead[LE,RO]{\thepage}%
911 \fancyhead[RE]{\nouppercase{\leftmark}}%
912 \fancyhead[LO]{\nouppercase{\rightmark}}%
913 %
914 \fancypagestyle{empty}{%
915 \renewcommand{\headrulewidth}{0pt}%
916 \fancyhf{}%
917 \fancyhead[C]{#1\vspace{2\baselineskip}}%
918 }%
919 \fancypagestyle{plain}{%
920 \renewcommand{\headrulewidth}{0pt}%
921 \fancyhf{}%
922 \fancyhead[C]{#1\vspace{2\baselineskip}}%
923 \fancyfoot[C]{\thepage}%
924 }%
925 }
926 % \end{macrocode}
927 % \end{macro}
928 %
929 % See \url{http://www.dtic.mil/dtic/submit/guidance/distribstatement.html} on
930 % distribution statements and on destruction of limited-distribution
931 % unclassified documents.
932 %
933 % \begin{macrocode}
934 \def\@distribution{\@latex@warning@no@line{No distribution statement given}}
935 % \end{macrocode}
936 %
937 % \begin{macrocode}
938 \def\@destruction{%
939 \textbf{DESTRUCTION NOTICE}: Destroy by any method that will prevent disclosure or reconstruction of the document.}
940 % \end{macrocode}
941 %
942 % \begin{macro}{\distributionA}
943 % \begin{macrocode}
944 \def\distributionA#1{%
945 \gdef\@distribution{%
946 \textbf{DISTRIBUTION STATEMENT A}: Approved for public release. #1}}
947 % \end{macrocode}
948 % \end{macro}
949 % \begin{macro}{\distributionB}
950 % \begin{macrocode}
951 \def\distributionB#1#2{%
952 \gdef\@distribution{%
953 \textbf{DISTRIBUTION STATEMENT B}: Distribution authorized to U.S. Government agencies only; #1; \@date. Other requests for this document shall be referred to #2.}}
954 % \end{macrocode}
955 % \end{macro}
956 % \begin{macro}{\distributionC}
957 % \begin{macrocode}
958 \def\distributionC#1#2{%
959 \gdef\@distribution{%
960 \textbf{DISTRIBUTION STATEMENT C}: Distribution authorized to U.S. Government agencies and their contractors; #1; \@date. Other requests for this document shall be referred to #2.}}
961 % \end{macrocode}
962 % \end{macro}
963 % \begin{macro}{\distributionD}
964 % Use this macro to indicate that your document uses Distribution Statement D,
965 % and why, like so: |\distributionD| \marg{reason why distribution is limited}.
966 % Write this in the top of your document, before |\begin{document}|.
967 % \begin{macrocode}
968 \def\distributionD#1#2{%
969 \gdef\@distribution{%
970 \textbf{DISTRIBUTION STATEMENT D}: Distribution authorized to the Department of Defense and U.S. DoD contractors only; #1; \@date. Other requests shall be referred to #2.}}
971 % \end{macrocode}
972 % \end{macro}
973 % \begin{macro}{\distributionE}
974 % \begin{macrocode}
975 \def\distributionE#1#2{%
976 \gdef\@distribution{%
977 \textbf{DISTRIBUTION STATEMENT E}: Distribution authorized to DoD Components only; #1; \@date. Other requests shall be referred to #2.}}
978 % \end{macrocode}
979 % \end{macro}
980 % \begin{macro}{\distributionF}
981 % \begin{macrocode}
982 \def\distributionF#1{%
983 \gdef\@distribution{%
984 \textbf{DISTRIBUTION STATEMENT F}: Further dissemination only as directed by #1 \@date\ or higher DoD authority.}}
985 % \end{macrocode}
986 % \end{macro}
987 %
988 %
989
990 % \begin{macrocode}
991 \def\@version{}
992 % \end{macrocode}
993
994 % \begin{macro}{\version}
995 % Use the |\version| \marg{some indication of version} to indicate the version
996 % of the document.
997 % \begin{macrocode}
998 \def\version#1{\gdef\@version{#1}}
999 % \end{macrocode}
1000 % \end{macro}
1001
1002 % \begin{macro}{\today}
1003 % This redefinition of the |\today| macro formats the date like ``4 Oct 2011,''
1004 % as military folks are used to. Use it in the |\date| macro.
1005 % \begin{macrocode}
1006 \def\today{\number\day\space\ifcase\month\or Jan\or Feb\or Mar\or Apr\or
1007 May\or Jun\or Jul\or Aug\or Sep\or Oct\or Nov\or Dec\fi
1008 \space\number\year}
1009 % \end{macrocode}
1010 % \end{macro}
1011
1012 % \begin{macro}{\narrowermargins}
1013 % \begin{macrocode}
1014 \newcommand{\narrowermargins}{%
1015 \addtolength{\hoffset}{-0.5in}%
1016 \addtolength{\textwidth}{1in}%
1017 \addtolength{\marginparwidth}{-0.5in}%
1018 \addtolength{\voffset}{-0.5in}%
1019 \addtolength{\textheight}{1in}%
1020 % bring up bottom of text to match whitespace at top caused by security
1021 % label
1022 \addtolength{\textheight}{-2\baselineskip}%
1023 }
1024 % \end{macrocode}
1025 % \end{macro}
1026 %
1027 % \begin{macro}{\makedodtitle}
1028 % Use this macro instead of |\maketitle|, right after |\begin{document}|.
1029 % \begin{macrocode}
1030 \newcommand{\makedodtitle}[0]{%
1031 \begin{titlepage}%
1032 \begin{center}%
1033 ~\vskip 1.5in%
1034 {\LARGE \@title \par}%
1035 \vskip 3em%
1036 {\large \lineskip .75em \begin{tabular}[t]{c}%
1037 \@author%
1038 \end{tabular}\par}%
1039 {\large \@date \par \large \@version}\vskip 0.5in%
1040 \includegraphics[width=0.4\textwidth]{org_logo}
1041 \end{center}\par%
1042 \@thanks\vskip 0.5in\par%
1043 \@distribution\par%
1044 \@destruction%
1045 \vfil\null
1046 \end{titlepage}}
1047 % \end{macrocode}
1048 % \end{macro}
1049 %
1050 %
1051 % \begin{environment}{changelog}
1052 % \begin{macro}{\change}
1053 % Usage: |\change| \marg{when} \marg{who} \marg{what}. For example,
1054 % \begin{Verbatim}[gobble=2]
1055 % \change{3 Aug 2011}{Jared Jennings}{Added backup plan}
1056 % \end{Verbatim}
1057 %
1058 % \begin{macrocode}
1059 \newcommand{\change}[3]{%
1060 {#1} & {#2} & {#3}\\
1061 }
1062 % \end{macrocode}
1063 % \end{macro}
1064 %
1065 % \begin{macrocode}
1066 \newenvironment{changelog}{
1067 \phantomsection
1068 \chapter*{Changelog}
1069 \addcontentsline{toc}{chapter}{Changelog}
1070 \begin{longtable}{@{\extracolsep{\fill}} l l p{4in}}
1071 \hline
1072 {\bf Date} & {\bf Person} & {\bf Change Description}\\
1073 \hline\hline
1074 \endhead
1075 }{\end{longtable}}
1076 % \end{macrocode}
1077 % \end{environment}
1078 %
1079 % \begin{environment}{executivesummary}
1080 % An ``executive summary,'' in the context of documents submitted as
1081 % information assurance artifacts, means specifically a table of IA controls to
1082 % which this document applies. Executive summaries can be built automatically
1083 % by the shaney script, but must be included in the main document by means of
1084 % the |\include| command.
1085 %
1086 % \begin{macro}{\executivesummaryiacontrol}
1087 % Usage: |\executivesummaryiacontrol| \marg{IA control ID} \marg{IA control
1088 % name}. Use only inside the executivesummary environment.
1089 % \begin{macrocode}
1090 \newcommand{\executivesummaryiacontrol}[2]{%
1091 {#1} & {#2}\\
1092 }
1093 % \end{macrocode}
1094 % \end{macro}
1095 %
1096 % \begin{macrocode}
1097 \newenvironment{executivesummary}{
1098 \phantomsection
1099 \chapter*{Executive Summary}
1100 \addcontentsline{toc}{chapter}{Executive Summary}
1101 The following table lists the NIST SP 800-53 Security Controls that are satisfied
1102 through this artifact.
1103
1104 \begin{longtable}{@{\extracolsep{\fill}} l p{4in}}
1105 \hline
1106 {\bf IA Control Number} & {\bf IA Control Name}\\
1107 \hline\hline
1108 \endhead
1109 }{\end{longtable}}
1110 % \end{macrocode}
1111 % \end{environment}
1112 \makeatother
1113 % \Finale