Merge pull request #67 from anomaly/alpha-7

Alpha 7

Author: devraj

.github/workflows/run-tests.yml

@@ -26,5 +26,7 @@ jobs:
           poetry install
       - name: Run tests
         run: |
-          export GACC_API_KEY=${{ secrets.GACC_API_KEY }}
+          export GACC_API_KEY="${{ secrets.GACC_API_KEY }}"
+          export CERTIFICATE_ANOMALY="${{ secrets.CERTIFICATE_ANOMALY }}"
+          export PRIVATE_KEY_ANOMALY="${{ secrets.PRIVATE_KEY_ANOMALY }}"
           task test

.gitignore

@@ -5,6 +5,7 @@
 .envrc
 
 # Byte-compiled / optimized / DLL files
+.certs
 .secret
 .DS_Store
 __pycache__/

README.md

@@ -40,15 +40,9 @@ import os
 import asyncio
 
 # Import the client and models
-from gallagher import (
-    cc,
-)
-from gallagher.dto.summary import (
-    CardholderSummary,
-)
-from gallagher.cc.cardholders import (
-    Cardholder,
-)
+from gallagher import cc
+from gallagher.dto.summary import CardholderSummary
+from gallagher.cc.cardholders import Cardholder
 
 # Set the API key from the environment
 api_key = os.environ.get("GACC_API_KEY")
@@ -287,8 +281,6 @@ class VisitorTypeDetail(
     AppBaseModel,
     IdentityMixin
 ):
-    """
-    """
     access_group : AccessGroupRef
     host_access_groups: list[AccessGroupSummary]
     visitor_access_groups: list[AccessGroupSummary]
@@ -317,8 +309,6 @@ class VisitorTypeDetail(
     AppBaseModel,
     IdentityMixin
 ):
-    """
-    """
     access_group : AccessGroupRef
     host_access_groups: list[AccessGroupSummary]
     visitor_access_groups: list[AccessGroupSummary]

Taskfile.yml

@@ -1,11 +1,11 @@
-version: '3'
+version: "3"
 
-dotenv: ['.env']
+dotenv: [".env"]
 
 tasks:
   publish:tag:
     vars:
-      PROJ_VERSION: 
+      PROJ_VERSION:
         sh: poetry version | awk '{print $2}'
     prompt: "Before we build, is the version {{.PROJ_VERSION}} number up to date?"
     desc: tags the current commit
@@ -19,24 +19,21 @@ tasks:
       - poetry build
   test:
     desc: runs tests inside the virtualenv
-    summary:
-      runs all the tests inside the virtualenv, optionally
+    summary: runs all the tests inside the virtualenv, optionally
       provide the name of the test as an argument to run a single test
 
       this does not run coverage or provide tap output
     cmds:
       - poetry run coverage run -m pytest -s tests/{{.CLI_ARGS}}
   test:tap:
     desc: runs tests with tap output
-    summary:
-      runs all the tests inside the virtualenv, optionally
+    summary: runs all the tests inside the virtualenv, optionally
       provide the name of the test as an argument to run a single test
     cmds:
       - poetry run coverage run -m pytest -s --tap tests/{{.CLI_ARGS}}
   test:list:
     desc: lists the available tests
-    summary:
-      runs collect only on pytest to list the tests available
+    summary: runs collect only on pytest to list the tests available
     cmds:
       - poetry run pytest --co
   test:coverreport:
@@ -54,19 +51,19 @@ tasks:
   dev:textual:
     desc: runs the textual cli
     cmds:
-      - poetry run textual -- {{.CLI_ARGS}} 
+      - poetry run textual -- {{.CLI_ARGS}}
   dev:tui:
     desc: runs text gallagher console in dev mode
     cmds:
       - poetry run textual run --dev gallagher.tui
   dev:py:
     desc: runs python in the poetry shell
-    cmds: 
+    cmds:
       - poetry run python -- {{.CLI_ARGS}}
   dev:docs:
     desc: run the mkdocs server with appropriate flags
-    cmds: 
-      - cd docs && mkdocs serve --open -a localhost:8001
+    cmds:
+      - cd docs && poetry run mkdocs serve --open -a localhost:8001
   debug:get:
     desc: use httpie to get payload from CC
     summary: |
@@ -99,4 +96,3 @@ tasks:
         http delete \
         https://commandcentre-api-au.security.gallagher.cloud/api/{{.CLI_ARGS}} \
         "Authorization: GGL-API-KEY $GACC_API_KEY"
-

docs/docs/design.md

@@ -132,6 +132,14 @@ Our current aliases are:
 
 `type` is another `key` that that constant appears in the `JSON` payloads, while this is a reserved function name in Python, it does not conflict with the compiler when used as a variable name. For now we've chosen not to wrap this in an alias.
 
+## Custom Headers
+
+The `httpx` wrappers sets the following headers for all requests sent to the command centre:
+
+- `Content-Type` set to `application/json` to let the command centre know that we are sending JSON payloads
+- `User-Agent` set of `GallagherPyToolkit/1.0` where `1.0` is the version number discovered from `gallagher/__init__.py`
+- `Authorization` set to `GGL-API-KEY 9939-00-` as prescribed by the official documentation
+
 ## API Client Core
 
 The `core` package in `cc` provides two important classes:

docs/docs/installation.md

@@ -41,6 +41,77 @@ following this you can call any of the SDK methods and the client will performan
 - `NoAPIKeyProvidedError` - If the API key is not set.
 - `ValueError` - If the API key does not conform to the expected format (which looks like eight tokens separated by `-`).
 
+#### Using TLS Certificates
+
+Command Centre optionally allows you to use self signed client side TLS certificates for authentication. You can use this along side your API key as an additional layer of security.
+
+You can use `openssl` to generate yourself a client side certificate and key.
+
+```bash
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout client.key -out client.pem
+```
+
+Fill in the required details for the certificate and then generate a `sha1` hash of the certificate.
+
+```bash
+openssl x509 -in client.pem -noout -fingerprint -sha1
+```
+
+> Note that the Command Centre does not use the `colon` separated format, see their documentation for more information.
+
+Once you have completed these steps all you have to do is provide the path to the certificate and key files to the client.
+
+```python
+from gallagher import cc
+api_key = os.environ.get("GACC_API_KEY")
+cc.api_key = api_key
+
+cc.file_tls_certificate = '/path/to/client.pem'
+cc.file_private_key = '/path/to/client.key'
+```
+
+The rest of the requests and operations remain the same, the library will use an `SSL Context` to do the needful.
+
+> Our testsuites are configured to run with and without TLS certificates to ensure that we support both modes of operation.
+
+In instances (such as Github actions, where we store the certificate and key in the Github secrets manager) where you can't store the certficiate and key in the filesystem, you can use Python's `tempfile` module to create temporary files and clean up once you are done using them.
+
+```python
+import tempfile
+
+# Read these from the environment variables, if they exists
+# they will be written to temporary files
+certificate_anomaly = os.environ.get("CERTIFICATE_ANOMALY")
+private_key_anomaly = os.environ.get("PRIVATE_KEY_ANOMALY")
+
+# Create temporary files to store the certificate and private key
+temp_file_certificate = tempfile.NamedTemporaryFile(
+    suffix=".crt",
+    delete=False
+)
+temp_file_private_key = tempfile.NamedTemporaryFile(
+    suffix=".key",
+    delete=False
+)
+
+# Write the certificate and private key to temporary files
+if certificate_anomaly and temp_file_certificate:
+    temp_file_certificate.write(certificate_anomaly.encode('utf-8'))
+
+if private_key_anomaly and temp_file_private_key:
+    temp_file_private_key.write(private_key_anomaly.encode('utf-8'))
+```
+
+You can assign these temporary files to the client as shown above.
+
+```python
+from gallagher import cc
+
+cc.api_key = api_key
+cc.file_tls_certificate = temp_file_certificate.name
+cc.file_private_key = temp_file_private_key.name
+```
+
 ### Command Line Interface
 
 ### Terminal User Interface

gallagher/__init__.py

@@ -7,4 +7,4 @@
  Distributed under the terms of the MIT License.
 """
 
-__version__ = "0.1.0-alpha.6"
+__version__ = "0.1.0-alpha.7"

gallagher/cc/__init__.py

@@ -29,6 +29,12 @@
 # to obtain an API key
 api_key: str = None
 
+# Certificate file to be used for authentication
+file_tls_certificate: str = None
+
+# Private key file to be used for authentication
+file_private_key: str = None
+
 # By default the base API is set to the Australian Gateway
 # Override this with the US gateway or a local DNS/IP address
 api_base: str = URL.CLOUD_GATEWAY_AU

gallagher/cc/core.py

@@ -26,6 +26,7 @@
 
 from http import HTTPStatus  # Provides constants for HTTP status codes
 
+import ssl
 import httpx
 
 from . import proxy as proxy_address
@@ -232,6 +233,23 @@ async def get_config(cls) -> EndpointConfig:
         provide additional configuration options.
         """
         raise NotImplementedError("get_config method not implemented")
+    
+    @classmethod
+    def _ssl_context(cls):
+        """Returns the SSL context for the endpoint
+
+        This method can be overridden by the child class to
+        provide additional SSL context options.
+        """
+        from . import file_tls_certificate, file_private_key
+
+        if not file_tls_certificate:
+            """TLS certificate is required for SSL context"""
+            return None
+        
+        context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
+        context.load_cert_chain(file_tls_certificate, file_private_key)
+        return context
 
     @classmethod
     async def _discover(cls):
@@ -269,7 +287,10 @@ async def _discover(cls):
         # be called as part of the bootstrapping process
         from . import api_base
 
-        async with httpx.AsyncClient(proxy=proxy_address) as _httpx_async:
+        async with httpx.AsyncClient(
+                proxy=proxy_address,
+                verify=cls._ssl_context(),
+            ) as _httpx_async:
             # Don't use the _get wrapper here, we need to get the raw response
             response = await _httpx_async.get(
                 api_base,
@@ -490,7 +511,11 @@ async def follow(
         # Initial url is set to endpoint_follow
         url = f"{cls.__config__.endpoint_follow.href}"
 
-        async with httpx.AsyncClient(proxy=proxy_address) as _httpx_async:
+        async with httpx.AsyncClient(
+                proxy=proxy_address,
+                verify=cls._ssl_context(),
+            ) as _httpx_async:
+
             while event.is_set():
                 try:
                     response = await _httpx_async.get(
@@ -546,7 +571,10 @@ async def _get(
         :param str url: URL to fetch the data from
         :param AppBaseModel response_class: DTO to be used for list requests
         """
-        async with httpx.AsyncClient(proxy=proxy_address) as _httpx_async:
+        async with httpx.AsyncClient(
+                proxy=proxy_address,
+                verify=cls._ssl_context(),
+            ) as _httpx_async:
 
             try:
 
@@ -594,7 +622,10 @@ async def _post(
         The behaviour is very similar to the _get method, except
         parsing and sending out a body as part of the request. 
         """
-        async with httpx.AsyncClient(proxy=proxy_address) as _httpx_async:
+        async with httpx.AsyncClient(
+                proxy=proxy_address,
+                verify=cls._ssl_context(),
+            ) as _httpx_async:
 
             try: