Refactor ssp_author_demo

ssp_author_demo/README.md

@@ -1,49 +1,67 @@
 # ssp_author_demo
 
-This demonstration of \[compliance-trestle\]((https://ibm.github.io/compliance-trestle) is designed to show how `trestle author` can be used to enable version controlled editing of SSP responses.
+This demonstration of [compliance-trestle](https://ibm.github.io/compliance-trestle) is designed to show how `trestle author` can be used to generate System-Security-Plan(SSP) markdown files from its OSCAL profile and its imported catalogs and profiles, and vice versa.
 
-The trestle project has been setup with a catalog and profile from NIST using 800-53. This was used to generate the markdown directory.
+This demo requires trestle version 3.x.x
 
-SSP generate is used to generate the markdown files from a profile and its imported catalogs and profiles.  Prompts are provided in the markdown for
-each control where an implementation response is required, corresponding to parts in the control statement.
+## Steps
 
-This demo requires trestle version 1.0.x
+### Download this repo
 
-## Steps to recreate setup
+```
+> cd
+> mkdir git
+> cd git
+> git clone https://github.com/oscal-compass/compliance-trestle-demos.git
+```
 
-### Initial import
+### Install compliance trestle, ideally in a python virtual environment, and create a trestle workspace
 
-- trestle init was run
-- The [OSCAL-content](https://github.com/usnistgov/OSCAL-content) repository was cloned.
-- The [NIST 800-53 catalog](https://github.com/usnistgov/oscal-content/blob/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json) was imported with `trestle import -f {path to catalog} -o 800-53`
-  - The catalog will be inserted within `./catalogs/800-53/`
-- The [NIST 800-53 LOW profile](https://github.com/usnistgov/oscal-content/blob/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_LOW-baseline_profile.json) was imported with trestle import -f {path to profile} -o 800-53-low\`
-  - The profiles will be inserted within `./profiles/800-53-low/`
-- The profile is updated so the import href points within the trestle project to `trestle://catalogs/800-53/catalog.json`
+```
+> cd
+> python -m venv venv.compliance-trestle-demos
+> source venv.compliance-trestle-demos/bin/activate
+> cd git/compliance-trestle-demos
+> make install
+> cd ssp_author_demo
+> trestle init
+```
+
+### Download example catalog([NIST 800-53 catalog](https://github.com/usnistgov/oscal-content/blob/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json)) and profile([NIST 800-53 LOW profile](https://github.com/usnistgov/oscal-content/blob/master/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_LOW-baseline_profile.json))
+
+```
+> cd
+> git clone https://github.com/usnistgov/OSCAL-content
+> cd git/compliance-trestle-demos/ssp_author_demo
+> trestle import -f ~/OSCAL-content/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -o 800-53
+> trestle import -f ~/OSCAL-content/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_LOW-baseline_profile.json -o 800-53-low
+```
+
+The example catalog and profile are inserted within `./catalogs/800-53/` and `./profiles/800-53-low/`.\
+Note, the `url` in the example profile doesn't correctly link to the imported catalog.
+Select the imported profile, and scroll down to the `resources` section and replace the json media-type's `href` value to: `trestle://catalogs/800-53/catalog.json`
 
 ### Inserting parameters
 
-Profiles from NIST do not insert parameter values by default so the profile needs to be modified.
+Profiles from NIST do not insert parameter values by default, so the profile needs to be modified.
 
 - `cd ./profiles/800-53-low/`
-- Add the missing modify structure`trestle add -f ./profile.json -e 'profile.modify'`
-- Create some sample parameters: `trestle add -f ./profile.json -e 'profile.modify.set-parameters'`
-- The parameters now need to be set by using the `value` field. For this demo all the parameters for ac-1 have been set.
+- Add the missing modify structure`trestle create -f ./profile.json -e 'profile.modify'`
+- Create some sample parameters: `trestle create -f ./profile.json -e 'profile.modify.set-parameters'`
 
-### Populating response content
+### Generating SSP markdown files
 
 - First the response documents must be generated using:
-  - cd to the project root directory
-  - `trestle author ssp-generate -p 800-53-low --output test_system -s 'guidance:Guidance'`
+  - `cd ~/git/compliance-trestle-demos/ssp_author_demo` to demo root directory.
+  - `trestle author ssp-generate -p 800-53-low --output test_system`
   - `--output` puts the markdown directory tree into `./test_system`
-  - `-s` maps named parts names to sections in catalog to the markdown document
 - Content for the implemented requirements can now be entered into the markdown for controls
 
-### Creating the OSCAL System Security Plan
+### Convert SSP markdown files to OSCAL
 
 - Run
   - `trestle author ssp-assemble -m test_system -o acme-test-system`
-- The ssp will be generated in `./system-security-plans/acme-test-system`
+- The SSP will be generated in `./system-security-plans/acme-test-system`
 - The generated json OSCAL document will be a valid system-security-plan with the implemented requirements incorporated for the controls.
-- The requirements are provided "by componenent" and in this demo there is only one default component: "This System".  In general
+- The requirements are provided "by component" and in this demo there is only one default component: "This System".  In general
   there can be more than one component.