InfoSec Policies, Standards and Procedures (PSP) Builder
This provides a CLI tool and library for generating and maintaining an organization's full policies, standards, and procedures in support of modern security operations and compliance.
It will default to outputting documentation in Markdown format. This project
also supports the use of Mkdocs
to convert Markdown to HTML, e.g.:
https://security.lifeomic.com/psp/. pandoc
(not supported) may optionally
be used to convert from Markdown to PDF format.
First-time users of the tool can choose one of the execution methods below
and run psp build
to be interactively prompted for configuration values.
This will generate a config.json
file that may be used to speed-up future
invocations.
TL;DR
Run the following command to install the policy builder and build the policies. You will be prompted for a few inputs, such as company name, to be included in your policy text.
npm install -g @jupiterone/jupiter-policy-builder
psp build
You will be prompted to save the config to a file, which you can reference the next time you'd like to rebuild the policies and procedures:
psp build -t ./templates -c path/to/your/config.json
The result files are put in ./docs
(Markdown) and ./site
(HTML).
IMPORTANT: To edit the policies and procedures, use the template files in
./templates
and re-run the psp build
command. Do not edit the ./docs
and
./partials
files directly as they will be overwritten on the next build.
For more detailed builder instructions, see the README [here][builder].
Publishing policies and procedures to JupiterOne
If you have an account on the JupiterOne security platform, you can run the following command to publish the contents of your policies and procedures to your JupiterOne account, so that you and others in your organization can access them online.
./bin/psp publish -a j1accountId -c path/to/your/config.json -t ./templates -u j1userId
The publish
command will prompt you to enter the password for your JupiterOne
user account. You can also supply the API Token instead of a password with the
-k | --api-token
option.
Your JupiterOne user must have administrator privilege to publish the contents.
Advanced steps to build and deploy policies
From docker zipfile
If you've received this project as a zip intended for Docker usage, simply:
unzip pspbuilder-docker.zip
docker build -t pspbuilder .
docker run -it -v$(pwd):/opt --rm pspbuilder psp build -c config.json
docker run -it -v$(pwd):/opt --rm pspbuilder mkdocs build -f docker-mkdocs.yml
This will generate a docs
directory containing Markdown files, and a site
directory containing HTML files which may be statically served.
These static files may be uploaded to a webserver, served from S3, etc. To view them locally, do:
cd site
python3 -m http.server 8000
open http://localhost:8000
Local CLI prerequisites and first steps
From zipfile
If you received this project as a zipfile intended for local installation, you'll need to install the latest Node v9 executable, via:
- Install NVM with:
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
- Install Node with
nvm install $(cat .nvmrc)
From source
If you have cloned this repository, you'll need to:
- Ensure you have the latest Node v9.
- Execute
yarn install
to install the Node package dependencies. - Execute
yarn mkdocs
to install mkdocs.
★ Note: On a fresh macOS machine run the following commands to set up MkDocs.
pip install --upgrade pip
pip install virtualenv
pip install mkdocs mkdocs-material
See http://www.mkdocs.org for more info.
Locally building the policies
PSP-Builder is used to build markdown source files from templates, using configurable values.
To build all markdown files, do:
./bin/psp build
If you have previously saved a configuration JSON file, and wish to rebuild the PSP docs against this configuration, do:
./bin/psp build -c path/to/your/config.json
Locally serving the static site
MkDocs is used to build a static site to serve the documentation pages. To view
the site locally, run ./bin/mkdocs serve -f docs/mkdocs.yml
in the project
root directory.
For further instructions, see MkDocs website.
Additionally, it uses mkdocs-material
theme. Instructions can be found
here.
★ Note: Four spaces are used instead of two in nested lists to get around a rendering issue in MkDocs.
Generating PDF and Word documents
Pandoc
can be used to automatically convert the markdown files into PDF or
Word documents. This requires pandoc
to be installed separately on your local
system. Follow the installation instructions here:
https://pandoc.org/installing.html
NOTE: on OSX systems, you will likely also need to install XeLaTeX from here: http://www.texts.io/support/0001/
Example steps for macOS
Install Pandoc:
sudo brew install pandoc
Install pandoc-latex-admonition, which is a pandoc filter for adding admonition:
-pip install pandoc-latex-admonition
+pip3 install pandoc-latex-admonition
Download and install LaTex, or MacTeX. The smaller distribution, BasicTeX is sufficient, but additional packages are required:
sudo tlmgr install collection-fontsrecommended
sudo tlmgr install mdframed
sudo tlmgr install needspace
sudo tlmgr install ucharcat
+sudo tlmgr install tcolorbox
+sudo tlmgr install environ
+sudo tlmgr install trimspaces
Example script for generating individual PDF policy documents:
#!/bin/bash
cd ./docs
mkdir pdf
for filename in *.md; do
pandoc $filename -f markdown -t latex -o ./pdf/$filename.pdf
done
Example script for generating a combined PDF policy document:
pandoc intro.md model.md *.md -f markdown -t latex --pdf-engine=xelatex --toc -o ./pdf/infosec-policies.pdf
Example script for generating Word documents:
mkdir docx
pandoc intro.md model.md *.md -f markdown -t docx --toc -o ./docx/infosec-policies.docx
Generating Self Assessment Reports
The current version of the policy builder supports generating a lightweight HIPAA self assessment report, based on a few key questions and the adoption of policies and procedures.
./bin/psp assess --standard hipaa --config <location_of_your_json_config_file> [options]
The above command generates a HIPAA self assessment report in the
./assessments
directory. The report contains mapping of your adopted
policies/procedures to each specific HIPAA regulation requirement. It also
contains placeholders, where applicable, for you to provide additional details.
Gaps identified will be called out in the command line output as well as in the
report itself.
Contents
Each policy and procedure is included as its own markdown file. We recommended
all policies to be adopted for your security program. The config.json
file
includes the procedures/controls you choose to adopt, which will be included in
the final policy docs by the psp-builder
.
Structure
./templates/
- This directory contains the modular templates for policies and procedures
- It is generated upon first run of the policy builder (
./bin/psp-builder
) - If you need to fine tune your policy and procedures, edit the individual markdown files inside this directory to preserve changes for subsequent runs.
./partials/
- This directory contains the modular policy and procedure markdown files with your organizational details incorporated.
- The partials directory will be generated after you run the
psp-builder
for the first time.
./docs/
- This directory contains the policy documents with the applicable/adopted procedures merged in.
./site/
- This is the default location where
mkdocs
generates the static HTML pages from you policy docs. - You can then publish the site to your desired target, such as an S3 bucket or an internal website.
Advanced configuration
You may also edit your config.json
file directly to provide input to the
configurable questions. The config.json
file contains the following sections:
organization
- You can edit this section directly to provide answers to the questions that
are promptly by the
psp-builder
CLI. - You can also add your own custom variables in this section -- e.g.
"variableName": "value"
. You will need to make sure to add the same variable(s) to your templates in the format of{{variableName}}
. - Note that if the variable is a URL/URI, you will need to add the
&
symbol to your variables in the templates -- e.g.{{&variableURL}}
.
standards
- Contains references to various compliance standards and frameworks.
- DO NOT edit this section.
policies
- Contains all available policies and the corresponding procedures that implements and enforces each policy.
- It is recommended that all policies to be included in your security program and documentation, therefore, you should NOT edit this section.
procedures
-
Contains the individual procedure documentations.
-
Each procedure includes the following
- A
summary
to provide high level guidance about that particular procedure and its implementation. This is for your reference. - A set of
resources
that will help with implementation and/or selecting a third party vendor solution. - A
provider
property, pre-populated with the recommended solution, if applicable. You may update this to the solution you have actually selected. The policy builder will update the documentation text within that procedure accordingly. - If you choose to exclude a procedure from your final policy documentation,
you may set the
adopted
flag tofalse
. The policy builder with skip those when compiling the policies.
- A