{"id":13876206,"url":"https://github.com/JupiterOne/security-policy-builder","last_synced_at":"2025-07-16T10:33:23.536Z","repository":{"id":37082532,"uuid":"187902460","full_name":"JupiterOne/security-policy-builder","owner":"JupiterOne","description":"CLI for generating policies, standards and control procedures (PSP) documentation in Markdown and publishing to JupiterOne or Confluence","archived":false,"fork":false,"pushed_at":"2024-05-28T17:08:37.000Z","size":3168,"stargazers_count":84,"open_issues_count":13,"forks_count":31,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-11-22T19:02:53.236Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JupiterOne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-21T19:40:48.000Z","updated_at":"2024-10-24T11:53:38.000Z","dependencies_parsed_at":"2023-12-05T18:46:27.215Z","dependency_job_id":"353128b8-1df2-4090-941b-1a23e9bf7898","html_url":"https://github.com/JupiterOne/security-policy-builder","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fsecurity-policy-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fsecurity-policy-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fsecurity-policy-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JupiterOne%2Fsecurity-policy-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JupiterOne","download_url":"https://codeload.github.com/JupiterOne/security-policy-builder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226126067,"owners_count":17577472,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T06:01:08.882Z","updated_at":"2024-11-24T04:31:05.403Z","avatar_url":"https://github.com/JupiterOne.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","others"],"sub_categories":[],"readme":"# InfoSec Policies, Standards and Procedures (PSP) Builder\n\nA CLI tool for building and publishing an organization's full policies,\nstandards, and procedures (PSPs) in support of modern security operations and\ncompliance.\n\nThe output format is Markdown. For instructions on converting markdown to other\nformats like HTML and PDF, see notes below.\n\nFirst-time users of the tool can choose one of the execution methods below and\nrun `psp build` to be interactively prompted for configuration values. This will\ngenerate a `config.json` file that may be used to speed-up future invocations.\n\nJupiterOne users with existing content may begin using the CLI by downloading\nthe PSP zip file in the Policies app.\n\n## Installing the policybuilder\n\n### Using NPM\n\nRun the following command to install the policy builder locally using NPM.\n\n```bash\nnpm install -g @jupiterone/security-policy-builder\n```\n\nIf you do not have Node and/or NPM installed locally, you may do so via:\n\n#### Installing NVM and Node\n\n1. Install NVM with:\n   `curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash`\n1. Install Node with `nvm install stable`\n\n### Using Docker\n\nIf you are comfortable using Docker, you can also use our\n[Dockerhub pspbuilder image](https://hub.docker.com/r/jupiterone/pspbuilder), by\nissuing the command:\n\n```bash\ndocker pull jupiterone/pspbuilder\n```\n\nThis will cache the docker image locally on your machine.\n\n## Building your first set of policies\n\nThe first time you run the `psp build` command, you will be prompted for several\ninputs, such as company name, to be included in your policy text. Save this to a\nfile, say `config.json`, when prompted. This will use the default\n[policy templates](https://github.com/JupiterOne/security-policy-templates)\nmaintained by JupiterOne to render a basic, but fairly complete set of\ninformation security policies and procedures.\n\n`cd` into a directory where you would like your PSP files to reside (we\nrecommend keeping the generated `templates` directory--see below--under version\ncontrol!) and perform one of the following commands:\n\n### Building from NPM script\n\nIf you installed from NPM above, issue:\n\n```bash\npsp build\n```\n\n### Building from docker image\n\nIf you're using the provided docker image, issue:\n\n```bash\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder psp build -o /mnt/docs -p /mnt/partials -s /mnt/templates\n```\n\n### Output of `psp build`\n\nRemember to save your config to a file, which you can reference the next time\nyou'd like to rebuild the policies and procedures with the `-c` or `--config`\noption flag. This JSON document stores your `organization` template variables\nreferenced from documents in the `templates` folder, and also stores the\ninformation architecture for your documents (how the policies and procedures\nfragments should be stitched together). We recommended all policies available in\nthe default `config.json` to be adopted for your security program. The\n`config.json` file includes the procedures/controls you choose to adopt, which\nwill be included in the final rendered policy docs by the tool.\n\nThe output of a successful first run will be the creation of three directories:\n\n- `templates` - raw markdown templates that represent the source of truth for\n  your policies and procedures.\n- `partials` - partially rendered markdown fragments used to assemble the\n  `docs`. This dir is intermediate output sometimes useful for debugging\n  purposes, and may largely be ignored.\n- `docs` - The final Markdown produced by the tool, assembled from `partials`\n  fragments.\n\nYou will invariably want to edit these PSPs to reflect the specifics of your\norganization's information security program. See \"PSP Best Practices\" below for\nadditional details on versioning and deployment.\n\n**IMPORTANT:** To edit the policies and procedures, use the template files in\n`./templates` and re-run the `psp build` command. Do _not_ edit the `./docs` and\n`./partials` files directly as they will be overwritten on the next build.\n\n### Building from existing/edited templates\n\nOnce you've edited your template files, you're ready to build again with:\n\n```bash\npsp build -t ./templates -c ./config.json\n\nor\n\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder psp build -t /mnt/templates -o /mnt/docs -p /mnt/partials\n```\n\n## Publishing\n\nThe policybuilder tools supports publishing to JupiterOne and Confluence, via\nthe `publish` subcommand.\n\n### Publishing policies and procedures to JupiterOne\n\nIf you have an account on the\n[JupiterOne security platform](https://jupiterone.io), you can run the following\ncommand to publish the contents of your policies and procedures to your\nJupiterOne account, so that you and others in your organization can access them\nonline.\n\n```bash\npsp publish -c ./templates/config.json -t ./templates -a $J1_ACCOUNT_ID -k $J1_API_TOKEN\n```\n\nor\n\n```bash\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder psp publish -c /mnt/config.json -t /mnt/templates -a $J1_ACCOUNT_ID -k $J1_API_TOKEN\n```\n\nYour JupiterOne token must have `Policies:Admin` privilege, or be issued by an\naccount Administrator, in order to publish the contents.\n\n### Publishing policies and procedures to Confluence\n\nYou can also publish the policies to a Confluence wiki space. Simply run the\n`psp publish` command with the `--confluence` option.\n\n```bash\npsp publish --confluence\n```\n\nYou will be prompted to enter your Confluence domain and space key, and\nusername/password:\n\n```bash\n? Confluence domain (the vanity subdomain before '.atlassian.net'):\n? Confluence space key:\n? Confluence username:\n? Confluence password: [hidden]\nPublished 35 docs to Confluence.\n```\n\nOr, provide necessary configuration options for non-interactive publishing:\n\n```bash\npsp publish --confluence --site \u003csubdomain\u003e --space \u003cKEY\u003e --docs \u003cpath\u003e -u \u003cusername/email\u003e -k \u003ckey/password\u003e\n```\n\nThe program will save the page ID for each published policy document locally to\na file in the current directory: `confluence-pages.json`. Make sure this file is\n**retained** because the program will use the page ID for each policy to update\nthe Confluence page the next time it is run.\n\n_We recommend creating a dedicated wiki space for these security policies._\n\n## PSP Best Practices\n\nThe PSPs supported by the tool are meant to be automatically generated from\nsource. We recommend the following practices:\n\n### Versioning\n\nWe highly recommend you practice policy-as-code and version your `templates` dir\nand `config.json` file. If you use `git` for version control, we recommend\nputting the following in your project's `.gitignore`:\n\n```\ndocs\npartials\n```\n\nDoing this makes it obvious what is to be edited in order to update your PSPs,\nand prevents confusion.\n\nIf your versioning system supports it, we recommend limiting merge authority to\nauthorized security staff only.\n\n### CI/CD\n\nBuilding and publishing the PSPs upon authorized merge to main branch is\nsupported via the `-n` or `--noninteractive` flags. Do something like:\n\n```bash\n#!/bin/bash\nset -euo pipefail\ncd to/cloned/repo\n\n# build documentation\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder psp build -c /mnt/config.json -o /mnt/docs -t /mnt/templates --noninteractive\n\n# publish templates to JupiterOne graph\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder psp publish -c /mnt/config.json -t /mnt/templates -a $J1_ACCOUNT_ID -k $J1_API_TOKEN --noninteractive\n\n# generate static HTML in 'site' directory\n# mkdocs command expects the YAML file to be at the root of the project\ncp docs/mkdocs.yml .\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder mkdocs build -f /mnt/mkdocs.yml\n\n# copy to static site host (here, AWS S3 bucket)\ncd site\naws s3 cp --recursive . s3://mybucket/location\n```\n\n### Generating a static HTML site from Markdown\n\nWe recommend the `mkdocs` tool for this. See above example in \"CI/CD\" which does\n`mkdocs build`.\n\n## Advanced Usage\n\n### Advanced JSON configuration\n\nYou may edit your `config.json` file directly to provide input to the\nconfigurable questions. The `config.json` file contains the following sections:\n\n`organization`\n\n- You can edit this section directly to provide answers to the questions that\n  are promptly by the `psp-builder` CLI.\n- You can also add your own custom variables in this section -- e.g.\n  `\"variableName\": \"value\"`. You will need to make sure to add the same\n  variable(s) to your templates in the format of `{{variableName}}`.\n- Note that if the variable is a URL/URI, you will need to add the `\u0026` symbol to\n  your variables in the templates -- e.g. `{{\u0026variableURL}}`.\n\n`standards`\n\n- Contains references to various compliance standards and frameworks.\n- **DO NOT** edit this section.\n\n`policies`\n\n- Contains all available policies and the corresponding procedures that\n  implements and enforces each policy.\n- It is recommended that all policies to be included in your security program\n  and documentation, therefore, you should **NOT** edit this section.\n\n`procedures`\n\n- Contains the individual procedure documentations.\n- Each procedure includes the following\n\n  - A `summary` to provide high level guidance about that particular procedure\n    and its implementation. This is for your reference.\n  - A set of `resources` that will help with implementation and/or selecting a\n    third party vendor solution.\n  - A `provider` property, pre-populated with the recommended solution, if\n    applicable. You may update this to the solution you have actually selected.\n    The policy builder will update the documentation text within that procedure\n    accordingly.\n  - If you choose to exclude a procedure from your final policy documentation,\n    you may set the `adopted` flag to `false`. The policy builder with skip\n    those when compiling the policies.\n\n### Build Local Docker Image\n\nIf you'd prefer not to use the image provided by DockerHub, you may build your\nown docker image by cloning this repository, and running:\n\n```\ndocker build -t pspbuilder .\n```\n\n### Preview Mkdocs Output Locally\n\nThe static HTML files generated by mkdocs (see \"CI/CD\" above for example) may be\nviewed locally by doing:\n\n1. `cd site`\n1. `python3 -m http.server 8000`\n1. `open http://localhost:8000`\n\n### Install Mkdocs Locally\n\nNote: local mkdocs usage is not supported.\n\n```bash\npip install --upgrade pip\npip install mkdocs mkdocs-material\n```\n\nSee http://www.mkdocs.org for more info. Additionally, mkdocs is configured to\nuse the `mkdocs-material` theme. Instructions\n[can be found here](https://squidfunk.github.io/mkdocs-material/getting-started/).\n\n### Generating PDF and Word Documents\n\n`Pandoc` can be used to automatically convert the markdown files into PDF or\nWord documents.\n\n#### Pandoc Conversion Using Docker Image\n\nThe supported `jupiterone/pspbuilder` docker image has the necessary pandoc\ndependencies installed. You may issue commands like:\n\n```bash\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder-extras pandoc /mnt/docs/filename.md -f markdown -t latex --pdf-engine=xelatex --variable monofont=\"Monaco\" -o /mnt/pdf/filename.pdf\n```\n\nto convert a single markdown file into a PDF.\n\n#### Local Pandoc Installation Steps for MacOS\n\nNOTE: Local pandoc usage is not supported.\n\nTo install and configure `pandoc` locally on your system, follow the\ninstallation instructions here:\n[pandoc.org/installing.html](https://pandoc.org/installing.html)\n\nor issue the following commands:\n\nInstall **Pandoc**:\n\n```bash\nbrew install pandoc\n```\n\nInstall **pandoc-latex-admonition**, which is a pandoc filter for adding\nadmonition:\n\n```bash\npip install pandoc-latex-admonition\n```\n\nDownload and install **LaTex**, or\n[MacTeX](http://www.tug.org/mactex/morepackages.html). The smaller distribution,\nBasicTeX is sufficient, but additional packages are required:\n\n```bash\nsudo tlmgr install collection-fontsrecommended\nsudo tlmgr install mdframed\nsudo tlmgr install needspace\nsudo tlmgr install ucharcat\nsudo tlmgr install tcolorbox\nsudo tlmgr install environ\nsudo tlmgr install trimspaces\n```\n\nNOTE: on macOS systems, you will likely also need to install XeLaTeX from here:\n[http://www.texts.io/support/0001/](http://www.texts.io/support/0001/)\n\nStart a new terminal session to ensure `pandoc` runs. Note that some UTF-8\ncharacters\n[may not be supported out-of-the-box](https://stackoverflow.com/questions/18178084/pandoc-and-foreign-characters).\nThe `--pdf-engine=xelatex --variable monofont=\"Monaco\"` options help, but other\nfonts may be required if your content needs them.\n\n**Example script for generating individual PDF policy documents:**\n\n```bash\n#!/bin/bash\ncd ./docs\nmkdir pdf\nfor filename in *.md; do\n  echo $filename\n  pandoc $filename -f markdown -t latex --pdf-engine=xelatex --variable monofont=\"Monaco\" -o ./pdf/$filename.pdf\ndone\n```\n\n**Example script for generating a combined PDF policy document, using Docker:**\n\nCreate a small bash script, called `pdf.sh`:\n\n```bash\n#!/bin/bash\ncd /mnt\nmkdir pdf\ncd /mnt/docs\npandoc *.md -f markdown -t latex --latex-engine=xelatex --variable monofont=\"inconsolata\" --toc -o /mnt/pdf/infosec-policies.pdf\n```\n\nThen, issue:\n\n```bash\ndocker run -it -v \"$PWD\":/mnt --rm jupiterone/pspbuilder-extras /mnt/pdf.sh\n```\n\nThis should stitch together all of your markdown files (in alphabetical order\nreturned by the bash glob, `*`). You could replace this with individual ordering\nof file arguments if you wanted more control of the sequencing.\n\n**Example script for generating Word documents:**\n\n```bash\nmkdir docx\npandoc model.md *.md -f markdown -t docx --toc -o ./docx/infosec-policies.docx\n```\n\n### Generating Self Assessment Reports\n\nThe current version of the policy builder supports generating a lightweight\nHIPAA self assessment report, based on a few key questions and the adoption of\npolicies and procedures.\n\n```bash\n./bin/psp assess --standard hipaa --config \u003clocation_of_your_json_config_file\u003e [options]\n```\n\nThe above command generates a HIPAA self assessment report in the\n`./assessments` directory. The report contains mapping of your adopted\npolicies/procedures to each specific HIPAA regulation requirement. It also\ncontains placeholders, where applicable, for you to provide additional details.\nGaps identified will be called out in the command line output as well as in the\nreport itself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJupiterOne%2Fsecurity-policy-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJupiterOne%2Fsecurity-policy-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJupiterOne%2Fsecurity-policy-builder/lists"}