README.md

Markdown Syntax

The full Markdown syntax parseable by Pandoc is well documented. To begin with make sure that you are familiar with basic Markdown syntax.

Pandoc supports a number of extensions which are helpful for authoring complex documents. Everyone should learn:

• Fenced code blocks
• Block quotes
• Tables and Table Captions
• Footnotes
• Figures (see Figures examples below)
• How Pandoc automatically adds header identifiers

Advanced users may want to learn:

• How to add YAML metadata blocks perform variable substitution in markdown text.

Figures

All images will automatically be resized to fit in the standard text column. You can also add captions. You shouldn't rely on your image always being directly after the text you have written.

Sometimes Latex will reposition the image onto a different page to make the text flow better. In the future you will be able to use figure cross-references to make it more clear what figure you are referring to in the text.

By default a wide image will be scaled to fit in the text column.

Building the Report

GNU Make controls the overall build process[1]:

# Set the environment variable for the CDPS tools
$ export CDPSTOOLS=~/cdpstools

# Build the default PDF
$ cd myreport
$ make

# Clean up the trailer
$ make clean

The default behaviour is that all *.md files will be include in the report in file order. If you want to reorder markdown files then either:

• Rename the files
• Edit the makefile to define the SOURCES variable

Specifying the report name

Edit Makefile in the report directory and set REPORT_NAME to your preferred base name. The appropriate extension, such as .pdf will be appended automatically.

Alternate make targets

• docx: Builds a Word document using the standard Word formatting
• findings: Processes findings.yml without building a final report.
• html: Builds an HTML document
• pdf: Builds PDF report. This is the default make target.
• tex: Builds and retains the Latex source used to build the PDF. Useful for debugging.

Tools for Managing Findings

If your report directory has a findings.yml file then this file will be parsed by a custom tool. A very simple minimal findings.yml file example:

---
findings:
  - title: 'Example Command Injection'
    tag: cmdi
  - title: 'Example SQL Injection'
    tag: sqli
...

The title and tag elements are mandatory in order for the findings.yml file to be valid. Once you have a valid file with one or more findings executing make findings will:

• Validate the YAML syntax and minimal content necessary to document a finding.
• Add additional elements to each finding that you can edit to set the severity, ease of exploitation, damage potential, and system component (eg. APP).
• Automatically number findings based on the component, severity, and order in the findings structure.
• Create a findings directory and create a <tag>.md file for you to document the finding.
• Create a "Findings" and "Findings Details" section in the report_findings.mdd file. This will automatically be included at the end of the report.

If you do not wish for these actions to occur then delete findings.yml[2].

[1] Syntax highlighting is supported for a number of languages. Run pandoc --version to see the full list. Line numbering and syntax highlighting is optional, of course.

[2] Well, that's how I'd like it to work but I don't have the Makefile-foo to do that yet!