Add evidence locker TOC (#71)

* Add evidence locker TOC
* Replace os with pathlib in report.py
* Temporarily remove mention of demo checks

Author: alfinkel

CHANGES.md

@@ -1,69 +1,74 @@
-# 1.5.0 (2020-09-14)
+# [1.6.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.6.0)
+
+- [ADDED] Check reports table of contents now appended to an evidence locker's README.
+- [ADDED] `ComplianceCheck.get_historical_evidence` supports historical evidence retrieval.
+
+# [1.5.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.5.0)
 
 - [ADDED] Remote locker push failure notifications were added.
 - [ADDED] Logging for git locker operations was added.
 - [ADDED] Notifier logging was added.
 - [CHANGED] The file descriptor (stdout) notifier always notifies now.
 
-# 1.4.0 (2020-09-03)
+# [1.4.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.4.0)
 
 - [CHANGED] PagerDuty notifier can send alerts for a subset of the accreditation checks based on the config.
 - [ADDED] A warning for possible sensitive information contained within notifications was added.
 
-# 1.3.0 (2020-09-01)
+# [1.3.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.3.0)
 
 - [CHANGED] Simplified `controls.json` format.  Original format is also supported.
 - [ADDED] Documentation for `controls.json` and check execution was added.
 - [ADDED] ControlDescriptor unit tests were added.
 - [FIXED] ComplianceFetcher session object is auto-closed now in tearDownClass.
 
-# 1.2.7 (2020-08-28)
+# [1.2.7](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.7)
 
 - [CHANGED] Removed PyYAML dependency to resolve downstream dependency issues.
 - [CHANGED] Removed Github.get_issue_template helper method.
 
-# 1.2.6 (2020-08-28)
+# [1.2.6](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.6)
 
 - [FIXED] ComplianceFetcher.session can now be reset.
 
-# 1.2.5 (2020-08-26)
+# [1.2.5](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.5)
 
 - [FIXED] Credentials section bug affecting the Slack notifier is squashed.
 
-# 1.2.4 (2020-08-24)
+# [1.2.4](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.4)
 
 - [CHANGED] Fetchers and checks that failed to load appear as errors in STDERR now.
 
-# 1.2.3 (2020-08-18)
+# [1.2.3](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.3)
 
 - [CHANGED] Github service `get_commit_details` now take `path` as an optional argument.
 
-# 1.2.2 (2020-08-14)
+# [1.2.2](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.2)
 
 - [FIXED] Github service branch protection method now returns "required_signatures" content.
 
-# 1.2.1 (2020-08-12)
+# [1.2.1](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.1)
 
 - [FIXED] Notifier `msg_` methods are now accurately found based on check `test_` method names.
 
-# 1.2.0 (2020-08-11)
+# [1.2.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.2.0)
 
 - [ADDED] Branch option to retrieving commit details from the Github service was added.
 
-# 1.1.0 (2020-08-11)
+# [1.1.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.1.0)
 
 - [ADDED] Repository details retrieval was added to Github service class.
 - [ADDED] Recent commit details retrieval was added to Github service class.
 - [ADDED] Repository branch protection details retrieval was added to Github service class.
 
-# 1.0.2 (2020-07-28)
+# [1.0.2](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.0.2)
 
 - [FIXED] Added PyYAML library as a dependency to resolve Github service issue.
 
-# 1.0.1 (2020-07-27)
+# [1.0.1](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.0.1)
 
 - [FIXED] Added external evidence as a valid evidence type to evidence map.
 
-# 1.0.0 (2020-07-21)
+# [1.0.0](https://github.com/ComplianceAsCode/auditree-framework/releases/tag/v1.0.0)
 
 - [ADDED] Made the Auditree Framework public.

MANIFEST.in

@@ -0,0 +1 @@
+graft templates

README.md

@@ -95,32 +95,7 @@ This will update the files in `doc` with the latest documentation. These files s
 
 ## Try it
 
-First, create an empty [credentials file][]:
-
-```shell
-touch ~/.credentials
-```
-
-Go to the demo checks and install required dependencies:
-
-```shell
-cd doc/demo-checks
-pip install -r requirements.txt
-```
-
-Run the fetchers:
-
-```shell
-compliance --fetch -v --evidence=local -C setup.json
-```
-
-And then run the checks of the demo accreditations:
-
-```shell
-compliance --check demo.accreditation1,demo.accreditation2 --evidence=local -v -C setup.json
-```
-
-See a more detailed [quick start guide][].
+Coming soon...
 
 ## Contribute
 

compliance/__init__.py

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

compliance/check.py

@@ -286,6 +286,17 @@ def add_issue_if_diff(self, actual, expected, msg, as_warning=False):
         else:
             self.add_failures(msg, sorted(diff))
 
+    def get_historical_evidence(self, evidence_path, evidence_dt):
+        """
+        Retrieve historical evidence from the locker and track as metadata.
+
+        :param evidence_path: the evidence path.
+        :param evidence_dt: the evidence date.
+        """
+        evidence = self.locker.get_evidence(evidence_path, True, evidence_dt)
+        self.add_evidence_metadata(evidence_path, evidence_dt)
+        return evidence
+
     def add_evidence_metadata(self, evidence_path, evidence_dt=None):
         """
         Add evidence metadata to the evidences property of each check.

compliance/locker.py

@@ -41,7 +41,8 @@
 INDEX_FILE = 'index.json'
 DAY = 60 * 60 * 24
 AE_DEFAULT = 30 * DAY
-AE_EXEMPT = [INDEX_FILE, 'README.md', 'readme.md']
+READMES = ['README.md', 'readme.md', 'Readme.md']
+AE_EXEMPT = [INDEX_FILE] + READMES
 
 
 class Locker(object):
@@ -411,24 +412,27 @@ def get_file(self, filename):
         """
         return os.path.join(self.local_path, filename)
 
-    def get_remote_location(self, filename, include_commit=True):
+    def get_remote_location(self, filename, include_commit=True, sha=None):
         """
         Provide the path for a file/commit SHA in the locker.
 
         The file may or may not exist in the locker.
 
         :param filename: the name of a file in the locker.
-        :param include_commit: if the commit SHA should be included.
+        :param include_commit: if the latest commit SHA should be included.
+        :param sha: use this commit SHA; requires include_commit to be False.
 
         :returns: the remote repository path to the filename provided.
         """
         if not self.repo_url_with_creds:
             return os.path.join(self.local_path, filename)
 
-        ref = 'master'
+        ref = self.branch
         if include_commit:
             ref = self.repo.head.commit.hexsha
-        return f'{self.repo_url}/blob/{ref}/{filename}'
+        elif not include_commit and sha:
+            ref = sha
+        return f'{self.repo_url}/blob/{ref}/{filename.strip("/")}'
 
     def get_evidence(self, evidence_path, ignore_ttl=False, evidence_dt=None):
         """
@@ -594,6 +598,22 @@ def add_content_to_locker(self, content, folder='', filename=None):
             f.write(content)
         self.repo.index.add([results_file])
 
+    def get_content_from_locker(self, folder='', filename=None):
+        """
+        Read non-evidence related content from the local locker.
+
+        :param folder: the folder in the local locker to get the content from.
+        :param filename: the name of the file in the local locker.
+        """
+        if not filename:
+            raise ValueError('Filename cannot be empty.')
+        file_path = os.path.join(self.local_path, folder, filename)
+        content = None
+        if os.path.exists(file_path):
+            with open(file_path) as f:
+                content = f.read()
+        return content
+
     def get_reports_metadata(self):
         """
         Provide all metadata related to reports as a dictionary.

compliance/notify.py

@@ -158,9 +158,7 @@ def _get_report_links(self, test_desc, link_format=None):
 
         return [
             link_format.format(
-                url=test_obj.locker.get_remote_location(
-                    report.path, include_commit=True
-                ),
+                url=test_obj.locker.get_remote_location(report.path),
                 name=report.name
             ) for report in test_obj.reports
         ]