Add a demo and update docs (#77)

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ repos:
         files: "^(compliance|test)"
         stages: [commit]
 -   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.3
+    rev: 3.8.4
     hooks:
     -   id: flake8
         args: [

CHANGES.md

@@ -1,3 +1,9 @@
+# [1.6.4](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.6.4)
+
+- [ADDED] Demo set of fetchers and checks added.
+- [ADDED] "Try It" section added to the README.
+- [CHANGED] Quick Start guide updated to include references to demo fetchers and checks implementation.
+
 # [1.6.3](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.6.3)
 
 - [ADDED] Fetcher and check execution times are now included in execution logging.

README.md

@@ -95,7 +95,38 @@ This will update the files in `doc` with the latest documentation. These files s
 
 ## Try it
 
-Coming soon...
+Successfully complete the steps below and you should be able to find your local
+evidence locker in your `$TMPDIR/compliance` folder.  There you will find a `raw`
+folder that contains all of the raw evidence fetched by the fetchers found in the
+`demo/demo_examples/fetchers` folder along with a `reports` folder that contains
+the reports generated by the checks found in the `demo/demo_examples/checks` folder.
+
+- Create an empty [credentials][] file:
+
+```shell
+$ touch ~/.credentials
+```
+
+- Set up your environment:
+
+```shell
+cd demo
+python -m venv
+. ./venv/bin/activate
+pip install -r requirements.txt
+```
+
+- Run the fetchers:
+
+```shell
+compliance --fetch --evidence local -C auditree_demo.json -v
+```
+
+- Run the checks:
+
+```shell
+compliance --check demo.arboretum.accred,demo.custom.accred --evidence local -C auditree_demo.json -v
+```
 
 ## Contribute
 
@@ -124,3 +155,4 @@ We have a tool called [Plant](https://github.com/ComplianceAsCode/auditree-plant
 [yapf]: https://github.com/google/yapf
 [lint-test]: https://github.com/ComplianceAsCode/auditree-framework/actions?query=workflow%3A%22format+%7C+lint+%7C+test%22
 [pypi-upload]: https://github.com/ComplianceAsCode/auditree-framework/actions?query=workflow%3A%22PyPI+upload%22
+[credentials]: https://complianceascode.github.io/auditree-framework/design-principles.html#credentials

compliance/__init__.py

@@ -14,4 +14,4 @@
 # limitations under the License.
 """Compliance automation package."""
 
-__version__ = '1.6.3'
+__version__ = '1.6.4'

demo/README.md

@@ -0,0 +1 @@
+# Execution Configuration Example

demo/auditree_demo.json

@@ -0,0 +1,17 @@
+{
+  "locker": {
+      "url": "https://github.com/MY_ORG/MY_EVIDENCE_REPO"
+  },
+  "notify": {
+    "slack": {
+      "demo.arboretum.accred": ["#some-slack-channel", "#some-other-slack-channel"],
+      "demo.custom.accred": ["#some-slack-channel"]
+    },
+    "gh_issues": {
+      "demo.arboretum.accred": {
+        "repo": ["MY_ORG/MY_GH_ISSUES_REPO", "MY_ORG/MY_OTHER_GH_ISSUES_REPO"],
+        "title": "Check results for demo.arboretum.accred accreditation"
+      }
+    }
+  }
+}

demo/controls.json

@@ -0,0 +1,4 @@
+{
+  "arboretum.auditree.checks.test_python_packages.PythonPackageCheck": ["demo.arboretum.accred"],
+  "demo_examples.checks.test_world_clock.WorldClockCheck": ["demo.custom.accred"]
+}

demo/demo_examples/__init__.py

@@ -0,0 +1,14 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

demo/demo_examples/checks/__init__.py

@@ -0,0 +1,14 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

demo/demo_examples/checks/test_common.py

@@ -0,0 +1,16 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from arboretum.auditree.checks.test_python_packages import PythonPackageCheck

demo/demo_examples/checks/test_world_clock.py

@@ -0,0 +1,77 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+
+from compliance.check import ComplianceCheck
+from compliance.evidence import with_raw_evidences
+
+class WorldClockCheck(ComplianceCheck):
+    """Perform analysis on world clock evidence."""
+
+    @property
+    def title(self):
+        """
+        Return the title of the checks.
+
+        :returns: the title of the checks
+        """
+        return 'World Clock'
+
+    @with_raw_evidences('time/world_clock_utc.json')
+    def test_day_of_year(self, evidence):
+        """Check whether the day of the year is odd or even."""
+        ordinal_dt = json.loads(evidence.content)['ordinalDate']
+        _, day = ordinal_dt.split('-')
+        if int(day) % 2 == 0:
+            self.add_failures(
+                'Even Day Violation', f'{day} in {ordinal_dt} is even!!'
+            )
+        else:
+            self.add_warnings(
+                'Even Day Approaching',
+                f'{day} in {ordinal_dt} will be even soon!!'
+            )
+
+    @with_raw_evidences('time/world_clock_utc.json')
+    def test_day_of_week(self, evidence):
+        """Check whether the day is Wednesday."""
+        day_of_week = json.loads(evidence.content)['dayOfTheWeek']
+        if day_of_week == 'Wednesday':
+            self.add_failures('Wednesday Violation', f'It is Wednesday!!')
+
+    def get_reports(self):
+        """
+        Provide the check report name.
+
+        :returns: the report(s) generated for this check
+        """
+        return ['time/world_clock.md']
+
+    def msg_day_of_year(self):
+        """
+        Day of year check notifier.
+
+        :returns: notification dictionary.
+        """
+        return {'subtitle': 'Even Day Violation', 'body': None}
+
+    def msg_day_of_week(self):
+        """
+        Day of week check notifier.
+
+        :returns: notification dictionary.
+        """
+        return {'subtitle': 'Wednesday Violation', 'body': None}

demo/demo_examples/evidences/__init__.py

@@ -0,0 +1,34 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from compliance.config import get_config
+from compliance.evidence import DAY, ReportEvidence, RawEvidence
+
+get_config().add_evidences(
+    [
+        RawEvidence(
+            'world_clock_utc.json',
+            'time',
+            DAY,
+            'Coordinated Universal Time'
+        ),
+        ReportEvidence(
+            'world_clock.md',
+            'time',
+            DAY,
+            'World Clock Analysis report.'
+        )
+    ]
+)

demo/demo_examples/fetchers/__init__.py

@@ -0,0 +1,14 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

demo/demo_examples/fetchers/fetch_common.py

@@ -0,0 +1,16 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from arboretum.auditree.fetchers.fetch_python_packages import PythonPackageFetcher

demo/demo_examples/fetchers/fetch_world_clock.py

@@ -0,0 +1,28 @@
+# -*- mode:python; coding:utf-8 -*-
+# Copyright (c) 2020 IBM Corp. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from compliance.evidence import store_raw_evidence
+from compliance.fetch import ComplianceFetcher
+
+class WorldClockFetcher(ComplianceFetcher):
+    """Fetch the current coordinated universal time."""
+
+    @store_raw_evidence('time/world_clock_utc.json')
+    def fetch_world_clock_utc(self):
+        """Fetch the universal time."""
+        session = self.session('http://worldclockapi.com/api/json')
+        clock = session.get('utc/now')
+        clock.raise_for_status()
+        return clock.text

demo/demo_examples/templates/reports/time/world_clock.md.tmpl

@@ -0,0 +1,39 @@
+{#
+Copyright (c) 2020 IBM Corp. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+#}
+# {{ test.title }} Report: {{ now.strftime('%Y-%m-%d') }}
+
+This report contains all world clock check violations.
+
+{% if test.total_issues_count(results) == 0 %}
+**No violations found!**
+{% else %}
+{% if test.failures_for_check_count(results) > 0 %}
+{% for section in all_failures.keys()|sort -%}
+## {{ section }}
+{% for failure in all_failures[section]|sort -%}
+- {{ failure }}
+{% endfor %}
+{% endfor %}
+{% endif %}
+{% if test.warnings_for_check_count(results) > 0 %}
+{% for section in all_warnings.keys()|sort -%}
+## {{ section }}
+{% for warning in all_warnings[section]|sort -%}
+- {{ warning }}
+{% endfor %}
+{% endfor %}
+{% endif %}
+{% endif %}

demo/requirements.txt

@@ -0,0 +1,2 @@
+auditree-arboretum>=0.6.1
+auditree-framework>=1.6.3