Merge pull request #131 from advanced-security/v2_8

V2.8.0

.release.yml

@@ -1,5 +1,5 @@
 name: "policy-as-code"
-version: "2.7.4"
+version: "2.8.0"
 
 locations:
   - name: "Update Docs"

Pipfile

@@ -6,7 +6,7 @@ verify_ssl = true
 [packages]
 pyyaml = "*"
 semantic-version = "*"
-ghastoolkit = "==0.12.7"
+ghastoolkit = "==0.13.1"
 
 [dev-packages]
 sphinx = "*"

README.md

@@ -45,7 +45,7 @@ Here is how you can quickly setup policy-as-code.
 ```yaml
 # Policy as Code
 - name: Advance Security Policy as Code
-  uses: advanced-security/policy-as-code@v2.7.4
+  uses: advanced-security/policy-as-code@v2.8.0
 ```
 
 > [!WARNING]
@@ -61,15 +61,15 @@ The Policy as Code project is a self-contained Python based CLI tool.
 **Bash / Zsh:**
 
 ```bash
-git clone --branch "v2.7.4" https://github.com/advanced-security/policy-as-code.git && cd ./policy-as-code
+git clone --branch "v2.8.0" https://github.com/advanced-security/policy-as-code.git && cd ./policy-as-code
 
 ./policy-as-code --help
 ```
 
 **Powershell:**
 
 ```Powershell
-git clone --branch "v2.7.4" https://github.com/advanced-security/policy-as-code.git
+git clone --branch "v2.8.0" https://github.com/advanced-security/policy-as-code.git
 cd policy-as-code
 
 .\policy-as-code.ps1 --help
@@ -128,7 +128,7 @@ Here is an example of using a simple yet cross-organization using Policy as Code
 ```yaml
 # Compliance
 - name: Advance Security Policy as Code
-  uses: advanced-security/policy-as-code@v2.7.4
+  uses: advanced-security/policy-as-code@v2.8.0
   with:
     # The owner/repo of where the policy is stored
     policy: GeekMasher/security-queries

ghascompliance/__main__.py

@@ -2,7 +2,7 @@
 import argparse
 import logging
 
-from ghastoolkit.octokit.github import GitHub
+from ghastoolkit import GitHub, GHASToolkitAuthenticationError
 
 from ghascompliance.__version__ import __name__ as tool_name, __banner__, __url__
 from ghascompliance.consts import SEVERITIES
@@ -203,6 +203,15 @@
             if not getattr(arguments, f"disable_{check[0]}"):
                 errors += check[1]()
 
+        except GHASToolkitAuthenticationError as err:
+            Octokit.error("Authentication Error")
+            Octokit.error(str(err))
+
+            errors += 1
+            # Add to summary
+            Summary.addLine(f"{Summary.__ICONS__['cross']} :: Authentication Error")
+            Summary.addLine(Summary.formatItalics(str(err)))
+
         except Exception as err:
             Octokit.error("Unknown Exception was hit, please repo this to " + __url__)
             Octokit.error(str(err))

ghascompliance/__version__.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-__version__ = "2.7.4"
+__version__ = "2.8.0"
 
 __title__ = "GitHub Advanced Security Policy as Code"
 __name__ = "ghascompliance"

vendor/ghastoolkit/__init__.py

@@ -3,7 +3,7 @@
 __name__ = "ghastoolkit"
 __title__ = "GHAS Toolkit"
 
-__version__ = "0.12.7"
+__version__ = "0.13.1"
 
 __description__ = "GitHub Advanced Security Python Toolkit"
 __summary__ = """\
@@ -27,6 +27,8 @@
 """
 
 
+from ghastoolkit.errors import *
+
 # Octokit
 from ghastoolkit.octokit.github import GitHub
 from ghastoolkit.octokit.repository import Repository

vendor/ghastoolkit/errors.py

@@ -0,0 +1,50 @@
+# GHASToolkit Errors
+
+
+from typing import List, Optional
+
+
+class GHASToolkitError(Exception):
+    """Base class for GHASToolkit errors."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        docs: Optional[str] = None,
+        permissions: Optional[List[str]] = [],
+        status: Optional[int] = None,
+    ) -> None:
+        self.message = message
+        self.docs = docs
+        self.permissions = permissions
+        self.status = status
+
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        msg = ""
+
+        if hasattr(self, "message"):
+            msg = self.message
+        else:
+            msg = "An error occurred"
+
+        if status := self.status:
+            msg += f" (status code: {status})"
+
+        if permissions := self.permissions:
+            msg += "\n\nPermissions Required:"
+            for perm in permissions:
+                msg += f"\n- {perm}"
+        if docs := self.docs:
+            msg += f"\n\nFor more information, see: {docs}"
+
+        return msg
+
+
+class GHASToolkitTypeError(GHASToolkitError):
+    """Raised when an invalid type is passed."""
+
+
+class GHASToolkitAuthenticationError(GHASToolkitError):
+    """Raised when an authentication error occurs."""

vendor/ghastoolkit/octokit/advisories.py

@@ -1,6 +1,7 @@
 """GitHub Security Advisories API."""
 
 from typing import Dict, Optional
+from ghastoolkit.errors import GHASToolkitError, GHASToolkitTypeError
 from ghastoolkit.octokit.github import GitHub, Repository
 from ghastoolkit.octokit.octokit import RestRequest
 from ghastoolkit.supplychain.advisories import Advisories, Advisory, AdvisoryAffect
@@ -20,7 +21,10 @@ def __init__(self, repository: Optional[Repository] = None) -> None:
         self.rest = RestRequest(self.repository)
 
     def getAdvisories(self) -> Advisories:
-        """Get list of security advisories from a repository."""
+        """Get list of security advisories from a repository.
+
+        https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories
+        """
         results = self.rest.get(
             "/repos/{owner}/{repo}/security-advisories", authenticated=True
         )
@@ -29,24 +33,38 @@ def getAdvisories(self) -> Advisories:
             for advisory in results:
                 advisories.append(self.loadAdvisoryData(advisory))
             return advisories
-        raise Exception(f"Error getting advisories from repository")
+
+        raise GHASToolkitTypeError(
+            f"Error getting advisories from repository",
+            docs="https://docs.github.com/en/rest/security-advisories/repository-advisories#list-repository-security-advisories",
+        )
 
     def getAdvisory(self, ghsa_id: str) -> Advisory:
-        """Get advisory by ghsa id."""
+        """Get advisory by ghsa id.
+
+        https://docs.github.com/en/rest/security-advisories/repository-advisories#get-a-repository-security-advisory
+        """
         result = self.rest.get(
             "/repos/{owner}/{repo}/security-advisories/{ghsa_id}",
             {"ghsa_id": ghsa_id},
             authenticated=True,
         )
         if isinstance(result, dict):
             return self.loadAdvisoryData(result)
-        raise Exception(f"Error getting advisory by id")
+
+        raise GHASToolkitTypeError(
+            f"Error getting advisory by id",
+            docs="https://docs.github.com/en/rest/security-advisories/repository-advisories#get-a-repository-security-advisory",
+        )
 
     def createAdvisory(
         self, advisory: Advisory, repository: Optional[Repository] = None
     ):
-        """Create a GitHub Security Advisories for a repository."""
-        raise Exception("Unsupported feature")
+        """Create a GitHub Security Advisories for a repository.
+
+        https://docs.github.com/en/rest/security-advisories/repository-advisories#create-a-repository-security-advisory
+        """
+        raise GHASToolkitError("Unsupported feature")
 
     def createPrivateAdvisory(
         self, advisory: Advisory, repository: Optional[Repository] = None
@@ -57,8 +75,11 @@ def createPrivateAdvisory(
     def updateAdvisory(
         self, advisory: Advisory, repository: Optional[Repository] = None
     ):
-        """Update GitHub Security Advisory."""
-        raise Exception("Unsupported feature")
+        """Update GitHub Security Advisory.
+
+        https://docs.github.com/en/rest/security-advisories/repository-advisories#update-a-repository-security-advisory
+        """
+        raise GHASToolkitError("Unsupported feature")
 
     def loadAdvisoryData(self, data: Dict) -> Advisory:
         """Load Advisory from API data."""

vendor/ghastoolkit/octokit/clearlydefined.py

@@ -2,6 +2,7 @@
 from typing import Any, Optional
 from requests import Session
 
+from ghastoolkit.errors import GHASToolkitError
 from ghastoolkit.supplychain.dependencies import Dependency
 
 
@@ -41,7 +42,7 @@ def createCurationUrl(self, dependency: Dependency) -> Optional[str]:
 
     def getCurations(self, dependency: Dependency) -> dict[str, Any]:
         if not dependency.manager:
-            raise Exception(f"Dependency manager / type must be set")
+            raise GHASToolkitError(f"Dependency manager / type must be set")
 
         url = self.createCurationUrl(dependency)
         if not url: