Skip to content

Latest commit

 

History

History
250 lines (165 loc) · 6.97 KB

README.md

File metadata and controls

250 lines (165 loc) · 6.97 KB
Raw

OCTool

Overview

OCTool aspires to be an open compliance tool and library.

It uses Pandoc, TeXLive, LuaTeX, and an open data schema to produce compliance documents, such as System Security Plans (SSPs).

This repo provides:

How-to

Get started with an example

This repo provides an example tree at example-inputs/minimal.

The easy way

Pull an already-built Docker image
docker pull jumanjiman/octool
Generate an SSP from the example data with Docker
docker run --rm -it -v /tmp:/data jumanjiman/octool ssp /example-inputs/minimal

The above command builds the SSP and saves it at /tmp/ssp.pdf on your Docker host.

Roll-your-own deployment

Prereqs

Your host needs these packages:

  • Ruby 2.4+
  • Pandoc 2.9+
  • Python 3.6+
  • TexLive full distribution, including LuaTeX and XeLaTeX
Install OCTool
gem install --user-install octool
Generate an SSP from the example data with your own deployment

  1. Confirm the example data is valid

    octool validate example-inputs/minimal/config.yaml

  2. Build a PDF

    octool ssp example-inputs/minimal/config.yaml

  3. The result should look like the example output at example-outputs/minimal/ssp.pdf.

Write your own data files

The schemas are at src/schemas/.
Things to know:

  • All text strings are interpreted as markdown.
    You can use markdown in your data anywhere a string is required.
    See example-inputs/minimal for demo data.

    💡 Pandoc has its own flavor of markdown.
    See https://pandoc.org/MANUAL.html#pandocs-markdown
    for differences from other flavors.

    💡 When you reference paths to images within your markdown, the
    path is relative to the directory in which config.yaml is stored.
    See the example-inputs files for clarity.

  • You can run octool validate path/to/inputs
    to confirm your data structure.

  • Do you want to run octool in a read-only container?
    TeX needs to write to at least one directory.
    Make at least one of these a volume in your container:

    • ${HOME} (inconvenient for unprivileged user with read-only homedir)
    • /usr/share/texmf-var (writable only by root)

    The Docker image in this repo works around the issue to
    enable read-only containers.

Pandoc filters

OCTool builds in support for these Pandoc filters via the schema:

Build and test

This repo builds, tests, and publishes a Docker image that includes the full TeXLive distribution and OCTool. The test harness runs the container with a read-only root filesystem and reduced privileges to demonstrate good security practices for containerized applications.

# Setup your dev environment.
sdlc/bootstrap

# Build and test.
sdlc/build && sdlc/test

Concepts

Entities

This diagram helps to illustrate the definitions that follow.
It reads top-down and left-to-right.

  • System: A potentially-complex technology architecture that includes one or more components.

  • ConfigFile: An OCTool configuration file.

  • Component: A list of components within the system along with attestations to satisfy one or more controls.

  • Standard: A list that defines one or more security controls.

    An example of a standard is NIST 800-53 or Payment Card Industry Data Security Standards (PCI DSS).

  • Control: A specific requirement or process to describe and mitigate risk.

  • Certification: A list that requires one or more controls.

    A certification requires all or a subset of controls from one or more standards.
    A hypothetical certification could include all of NIST 800-53 plus a specific subset of PCI DSS.

    An Authority to Operate (ATO) is one example of a certification. A request list from an auditor is another example.

System vs component

A component and a system can be identical from a compliance perspective in the simplest cases. It is common, however, that a complex system delegates compliance to multiple responsible parties along organizational boundaries in a shared services model.

Consider, for example, an organization that owns its datacenter and assigns responsibility for physical access to a dedicated team.

  • The organization can describe the datacenter as a component and describe its compliance to physical access controls within a shareable component called datacenter.

  • Teams that operate software within the datacenter can then include the datacenter component within their own compliance documentation.

With the shared services model, the system compliance documentation includes various components. Its compliance documentation is assembled from various components.

Thus some systems are described by multiple components; smaller systems, by a single component.

Benefits

  • If an application owner requests an exception to a control from a shared component, the InfoSec team can run an impact assessment to see which other applications (systems) and/or certifications would be impacted by the exception.

  • The organization can use the system to ask what-if questions.

  • Compliance and regulatory teams have a central source of truth from which to answer questions.

  • Git provides an audit log of changes to the compliance docs.

  • The intermediate output (SQL database, CSV, etc.) is available so teams can choose whatever analytical tools they prefer.

Administrivia

Goals

  • Read input configuration in multiple formats
  • Generate output documentation for governance and compliance
    • Excel
    • Markdown
    • PDF
    • Word
  • Convert inputs to a well-defined data structure
    • Intermediate output
      • CSV
      • Excel
      • SQLite
    • Facilitate gap analysis
    • Facilitate impact analysis for exceptions