Merge pull request #129 from IBM/develop

Release to master

Author: butler54

.github/workflows/python-push.yml

@@ -0,0 +1,74 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+name: Trestle Deploy
+
+on:
+  push:
+    branches:
+      - master
+      - develop
+  schedule:
+    # Run once per day to ensure we have no build failures due to dependency updates.
+    # * is a special character in YAML so you have to quote this string
+    - cron:  '0 22 * * *'
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: [3.7, 3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: true
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install build tools
+      run: |
+        make develop
+    - name: Install dependencies
+      run: |
+        make install
+    - name: Run code formatting (yapf)
+      run: |
+        make code-format
+    - name: Run code linting (flake8)
+      run: |
+        make code-lint
+    - name: Pytest
+      run: |
+        make test
+    - name: Push code-cov
+      uses: codecov/codecov-action@v1
+      with: 
+        token: ${{ secrets.CODECOV_TOKEN }}
+        file: ./coverage.xml
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/master'
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: true
+        fetch-depth: 0
+        token: ${{ secrets.ADMIN_PAT }} 
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+    - name: Install build tools
+      run: |
+        make develop
+    - name: Create release
+      shell: bash
+      env:
+        PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        GH_TOKEN: ${{ secrets.ADMIN_PAT }}
+      run: |
+        make release

.github/workflows/python-test.yml

@@ -1,16 +1,17 @@
 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
 # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-name: Trestle CI
+name: Trestle PR Pipeline
 
 
-on: [push, pull_request]
+on: [pull_request]
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [ 3.7, 3.8]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: [3.7, 3.8]
 
     steps:
     - uses: actions/checkout@v2
@@ -39,28 +40,4 @@ jobs:
       uses: codecov/codecov-action@v1
       with: 
         token: ${{ secrets.CODECOV_TOKEN }}
-        file: ./coverage.xml
-  deploy:
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/master'
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        submodules: true
-        fetch-depth: 0
-        token: ${{ secrets.ADMIN_PAT }} 
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v2
-      with:
-        python-version: 3.7
-    - name: Install build tools
-      run: |
-        make develop
-    - name: Create release
-      shell: bash
-      env:
-        PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
-        GH_TOKEN: ${{ secrets.ADMIN_PAT }}
-      run: |
-        make release
+        file: ./coverage.xml

.gitignore

@@ -17,6 +17,7 @@
 venv
 *.egg-info
 .vscode/settings.json
+.vscode
 
 _*/
 
@@ -26,6 +27,8 @@ _*/
 
 build
 dist
+tmp
 
 .coverage
 coverage.xml
+

.pre-commit-config.yaml

@@ -4,14 +4,14 @@ repos:
     hooks:
       - id: yapf
         args: [--in-place, --parallel, --recursive, --style, .yapf-config]
-        files: "^(trestle|tests)"
+        files: "^(trestle|tests|scripts)"
         exclude: "oscal"
         stages: [commit]
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.8.4
     hooks:
       - id: flake8
-        args: [--extend-ignore, "P1,C812,C813,C814,C815,C816,W503"]
+        args: [--extend-ignore, "P1,C812,C813,C814,C815,C816,W503,W605"]
         additional_dependencies:
           [
             flake8-2020,
@@ -31,7 +31,7 @@ repos:
             flake8-use-fstring,
             pep8-naming,
           ]
-        files: "^(trestle|tests)"
+        files: "^(trestle|tests|scripts)"
         exclude: "oscal"
         stages: [commit]
   - repo: https://github.com/hukkinj1/mdformat

CONTRIBUTING.md

@@ -99,7 +99,7 @@ pip install -q -e ".[dev]" --upgrade --upgrade-strategy eager
 
 ### Testing python in `vscode`
 
-Tests  should be in the test subdirectory.  Each file should be named test\_\*.py and each test function should be named \*\_test().
+Tests should be in the test subdirectory.  Each file should be named test\_\*.py and each test function should be named \*\_test().
 
 Note that with Python3 there should be no need for __init__.py in directories.
 

Makefile

@@ -39,4 +39,4 @@ release::
 	semantic-release publish
 
 gen-oscal::
-	./scripts/gen_oscal.sh
+	python ./scripts/gen_oscal.py

README.md

@@ -1,35 +1,42 @@
-# Trestle
+# Compliance-trestle aka trestle
 
-Trestle is a tool to which enables the creation and validation of documentation artifacts for compliance requirements. It leverages NIST's [OSCAL](<https://pages.nist.gov/OSCAL/documentation/>) as a standard data format for interchange between tools & people and provides an opinionated approach to OSCAL adoption.
+Trestle is a tool that enables the creation and validation of documentation artifacts for compliance requirements. It leverages NIST's [OSCAL](<https://pages.nist.gov/OSCAL/documentation/>) as a standard data format for interchange between tools and people, and provides an opinionated approach to OSCAL adoption.
 
-By design Trestle runs as a CICD pipeline running on top of compliance artifacts in `git` to provide transparency to the state of compliance across multiple stakeholders in an environment friendly to developers. Trestle passes the artifacts generated on to tools to orchestrate the enforcement, measurement and reporting of compliance.
+By design Trestle runs as a CICD pipeline running on top of compliance artifacts in `git` to provide transparency to the state of compliance across multiple stakeholders in an environment friendly to developers. Trestle passes the artifacts generated to tools that orchestrate the enforcement, measurement and reporting of compliance.
 
-It also provides tooling to manage OSCAL in a more human-friendly manner. By expanding the large OSCAL data structures into smaller, easier to edit, sub-structures, creation and maintenance of these artifacts can follow normal `git` workflows (peer review via pull request, versioning, releases/tagging).
+It also provides tooling to manage OSCAL in a more human-friendly manner. By expanding the large OSCAL data structures into smaller and easier to edit sub-structures, creation and maintenance of these artifacts can follow normal `git` workflows (peer review via pull request, versioning, releases/tagging).
 
-## Why Trestle?
+## Why Trestle
 
-Compliance suffers from being a complex problem that is hard to articulate simply. It requires complete & accurate execution of multiple procedures, across many disciplines (IT, HR, management), with periodic verification and audit of said procedures against controls.
+Compliance suffers from being a complex problem that is hard to articulate simply. It requires complete and accurate execution of multiple procedures across many disciplines (e.g. IT, HR, management) with periodic verification and audit of those procedures against controls.
 
-While its possible to manage the description of controls & how an organisation implements them in ad hoc ways, with general tools (spreadsheets, documents), this is hard to maintain for multiple accreditations and, in the IT domain at least, creates a barrier between the compliance efforts and people doing daily work (DevOps staff).
+While it is possible to manage the description of controls and how an organisation implements them in ad hoc ways with general tools (spreadsheets, documents), this is hard to maintain for multiple accreditations and, in the IT domain at least, creates a barrier between the compliance efforts and the people doing daily work (DevOps staff).
 
-Trestle aims to reduce or remove this barrier by bringing the maintenance of control descriptions into the DevOps domain. The aim is to have changes to the system (for example, updates to configuration management) easily related to the controls impacted & those controls be modified if required in concert with the system change.
+Trestle aims to reduce or remove this barrier by bringing the maintenance of control descriptions into the DevOps domain. The goal is to have changes to the system (for example, updates to configuration management) easily related to the controls impacted, and to enable modification of those controls as required in concert with the system changes.
 
-Trestle implicitly provides an core opinionated workflow driven by it's pipeline steps to allow standardized interlocks with other compliance tooling platforms.
+Trestle implicitly provides a core opinionated workflow driven by its pipeline steps to allow standardized interlocks with other compliance tooling platforms.
+
+## Development status
+
+Compliance trestle is currently alpha. The expectation is that throughout the remainder of 2020 there may be unnannounced changes that are breaking within the trestle codebase. If you are using trestle please contact us so we are aware your usecase.
+
+The underlying OSCAL schema is also currently changing. The current approach until the formal release of OSCAL 1.0.0 is for compliance trestle to regularly update our models to reflect NIST's changes.
 
 ### Machine readable compliance format
 
-Compliance activities at scale, be that size of estate, or number of accreditations, require automation to be successful & repeatable. OSCAL as a standard allows teams to bridge between the "Governance" layer and operational tools.
+Compliance activities at scale, whether size of estate or number of accreditations, require automation to be successful and repeatable. OSCAL as a standard allows teams to bridge between the "Governance" layer and operational tools.
 
-By building human managed artifacts into OSCAL, Trestle is not only able to validate the integrity of the artifacts that people generate, it also enables reuse and sharing of artifacts and can also provide suitable input into tools which automate operational compliance.
+By building human managed artifacts into OSCAL, Trestle is not only able to validate the integrity of the artifacts that people generate - it also enables reuse and sharing of artifacts, and furthermore can provide suitable input into tools that automate operational compliance.
 
 ## Using Trestle
 
-Trestle converts complex schema/data structures into simple files in a directory structure. The aim of this is to make it easier to manage for humans - individual objects can be versioned & reviewed, then 'compiled' into the larger structure of a Catalog, SSP or Assessment Plan.
+Trestle converts complex schema/data structures into simple files in a directory structure. The aim of this is to make it easier to manage for humans: Individual objects can be versioned & reviewed, then 'compiled' into the larger structure of a Catalog, SSP or Assessment Plan.
 
-### Install and Run:
+### Install and Run
 
 Install from PYPI and run:
-~~~shell
+
+```shell
 # Setup virtual environement
 python3 -m venv venv
 . ./venv/bin/activate
@@ -39,10 +46,11 @@ pip install compliance-trestle
 
 # Run Trestle CLI
 trestle -h # For command line help
-~~~
+```
 
 In order to install Trestle from source, run the following command:
-~~~shell
+
+```shell
 # Clone
 git clone https://github.com/IBM/compliance-trestle.git
 cd compliance-trestle
@@ -54,14 +62,30 @@ pip install -q -e ".[dev]" --upgrade --upgrade-strategy eager
 
 # Run Trestle CLI
 trestle -h
-~~~
+```
+
+## Supported OSCAL elements and extensions
+
+`trestle` implicitly supports all OSCAL schemas for use within the object model. The development roadmap for `trestle` includes
+adding workflow around specific elements / objects that is opinionated.
+
+In addition to the core OSCAL objects, trestle supports the definition of a `target`. The `target` (and its container
+`target-definition`) is a generalization of the `component` model that is designed specifically to support configuration.
+
+`catalog` and `profile` objects can define parameters. However, by their nature the parameter definitions are at the
+regulatory level. The `trestle` team has seen a need for an object that can define parameters at the `control-implemenation`
+level, e.g. `component` is an implementation and `target` is the definition of capabilities of the component.
+
+### Conformance criteria ontop of OSCAL
 
 ## Contributing to Trestle
-Our project welcomes external contributions. Please checkout [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+Our project welcomes external contributions. Please consult [CONTRIBUTING.md](<CONTRIBUTING.md>) to get started.
 
 ## License & Authors
-If you would like to see the detailed LICENSE click [here](LICENSE).
-Check out [MAINTAINERS](MAINTAINERS.md) for list of authors.
+
+If you would like to see the detailed LICENSE click [here](<LICENSE>).
+Consult [MAINTAINERS](<MAINTAINERS.md>) for a list of authors.
 
 ```text
 # Copyright (c) 2020 IBM Corp. All rights reserved.
@@ -78,4 +102,4 @@ Check out [MAINTAINERS](MAINTAINERS.md) for list of authors.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-```
+```