Merge pull request #4 from emsec/dev

- Begin to adjust stats reader to new JSON Level List
- Fix CI/CD Pipeline not pulling our level repository (missing submodule init), update build steps
- Adjust feedback dialogue to better communicate the maximum score
- Add Bearer authentication to /metrics endpoint
- Update the Grafana examples to show an instance selector and display the client error metrics

Author: Jannled

.dockerignore

@@ -21,6 +21,7 @@ conf/
 log_merging_config.json
 dockerComposeMPI.yml
 *.csv
+reversim-conf
 
 # Debugpy logs, WinMerge Backups etc.
 *.log
@@ -29,6 +30,11 @@ dockerComposeMPI.yml
 # Ignore statistics folder
 statistics/
 
+# Hide deployment storage
+tmp/
+secrets/
+
+
 # Maybe ignore unnecessary code	
 # app/statistics
 # app/tests

.github/workflows/deploy-image.yml

@@ -1,18 +1,21 @@
 #
 name: Create and publish a Docker image
 
-# Configures this workflow to run every time a change is pushed to the branch called `main`.
+# Configures this workflow to run every time a change is pushed to the branch called 
+# `main` or `dev`.
 on:
   push:
     branches: ['main', 'dev']
     tags: ['*']
 
-# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
+# Defines two custom environment variables for the workflow. These are used for the 
+# Container registry domain, and a name for the Docker image that this workflow builds.
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
-# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
+# There is a single job in this workflow. It's configured to run on the latest available
+# version of Ubuntu.
 jobs:
   build-and-push-image:
     runs-on: ubuntu-latest
@@ -25,21 +28,28 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          submodules: true
 
-      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
+      # Uses the `docker/login-action` action to log in to the Container registry registry
+      # using the account and password that will publish the packages. Once published, the
+      # packages are scoped to the account defined here.
       - name: Log in to the Container registry
-        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
+      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) 
+      # to extract tags and labels that will be applied to the specified image. 
+      # The `id` "meta" allows the output of this step to be referenced in a subsequent 
+      # step. The `images` value provides the base name for the tags and labels.
       # It will automatically create the latest Docker tag, if a git tag is found: https://github.com/docker/metadata-action?tab=readme-ov-file#latest-tag
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
+        uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
 
@@ -51,12 +61,17 @@ jobs:
             calculatedSha=$(git rev-parse --short ${{ github.sha }})
             echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV
 
-      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
-      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.
-      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      # This step uses the `docker/build-push-action` action to build the image, based on 
+      # your repository's `Dockerfile`. If the build succeeds, it pushes the image to 
+      # GitHub Packages.
+      # It uses the `context` parameter to define the build's context as the set of files
+      # located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) 
+      # in the README of the `docker/build-push-action` repository.
+      # It uses the `tags` and `labels` parameters to tag and label the image with the 
+      # output from the "meta" step.
       - name: Build and push Docker image
         id: push
-        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
+        uses: docker/build-push-action@v6
         with:
           context: .
           push: true
@@ -66,9 +81,12 @@ jobs:
             GAME_GIT_HASH=${{ github.sha }}
             GAME_GIT_HASH_SHORT=${{ env.COMMIT_SHORT_SHA }}
 
-      # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
+      # This step generates an artifact attestation for the image, which is an unforgeable
+      # statement about where and how it was built. It increases supply chain security for
+      # people who consume the image. For more information, see [Using artifact attestations
+      # to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
       - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v2
+        uses: actions/attest-build-provenance@v3
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
           subject-digest: ${{ steps.push.outputs.digest }}

.gitignore

@@ -21,7 +21,6 @@ __pycache__/
 env/
 venv/
 .venv/
-tmp/
 
 # --- Debugpy logs, WinMerge Backups etc.
 *.log
@@ -44,3 +43,7 @@ reversim-conf
 
 # --- Generated level thumbnails
 doc/levels
+
+# --- Don't push instance relevant configuration
+tmp/
+secrets/

.vscode/settings.json

@@ -143,6 +143,7 @@
 		"hreserver",
 		"hrestudy",
 		"htmlsafe",
+		"httpauth",
 		"iframe",
 		"imgdata",
 		"imgstring",

Dockerfile

@@ -18,7 +18,7 @@ ARG PROMETHEUS_MULTIPROC_DIR="/tmp/prometheus_multiproc"
 MAINTAINER Max Planck Institute for Security and Privacy
 LABEL org.opencontainers.image.authors="Max Planck Institute for Security and Privacy"
 # NOTE Also change the version in config.py
-LABEL org.opencontainers.image.version="2.1.0"
+LABEL org.opencontainers.image.version="2.1.1"
 LABEL org.opencontainers.image.licenses="AGPL-3.0-only"
 LABEL org.opencontainers.image.description="Ready to deploy Docker container to use ReverSim for research. ReverSim is an open-source environment for the browser, originally developed at the Max Planck Institute for Security and Privacy (MPI-SP) to study human aspects in hardware reverse engineering."
 LABEL org.opencontainers.image.source="https://github.com/emsec/ReverSim"
@@ -62,6 +62,7 @@ ENV PROMETHEUS_MULTIPROC_DIR=${PROMETHEUS_MULTIPROC_DIR}
 # Create empty statistics folders
 WORKDIR /usr/var/reversim-instance/statistics/LogFiles
 WORKDIR /usr/var/reversim-instance/statistics/canvasPics
+WORKDIR /usr/var/reversim-instance/secrets
 WORKDIR /usr/src/hregame
 
 # Specify mount points for the statistics folder, levels, researchInfo & disclaimer

app/authentication.py

@@ -0,0 +1,45 @@
+import logging
+import os
+import secrets
+
+from flask_httpauth import HTTPTokenAuth  # type: ignore
+
+from app.config import BEARER_TOKEN_BYTES
+from app.model.ApiKey import ApiKey
+from app.storage.database import db
+from app.utilsGame import safe_join
+
+auth = HTTPTokenAuth(scheme='Bearer')
+
+USER_METRICS = 'api_metrics'
+
+@auth.verify_token # type: ignore
+def verifyToken(token: str) -> ApiKey|None:
+	"""Check if this token exists. If yes return the user object, otherwise return `None`
+
+	https://flask-httpauth.readthedocs.io/en/latest/#flask_httpauth.HTTPTokenAuth.verify_token
+	"""
+
+	return db.session.query(ApiKey).filter_by(token=token).first()
+
+
+def populate_data(instance_path: str):
+	if ApiKey.query.count() < 1:
+		apiKey = ApiKey(secrets.token_urlsafe(BEARER_TOKEN_BYTES), USER_METRICS)
+		db.session.add(apiKey)
+		db.session.commit()
+
+	defaultToken = db.session.query(ApiKey).where(ApiKey.user == USER_METRICS).first()
+	if defaultToken is not None:
+		
+		# Try to write the bearer secret to a file so other containers can use it
+		try:
+			folder = safe_join(instance_path, 'secrets')
+			os.makedirs(folder, exist_ok=True)
+			with open(safe_join(folder, 'bearer_api.txt'), encoding='UTF-8', mode='wt') as f:
+				f.write(defaultToken.token)
+
+		except Exception as e:
+			# When the file can't be created print the bearer to stdout
+			logging.error('Could not write bearer token to file: ' + str(e))
+			logging.info('Bearer token for /metrics endpoint: ' + defaultToken.token)

app/config.py

@@ -16,14 +16,17 @@
 
 # CONFIG Current Log File Version. 
 # NOTE Also change this in the Dockerfile
-LOGFILE_VERSION = "2.1.0" # Major.Milestone.Subversion
+LOGFILE_VERSION = "2.1.1" # Major.Milestone.Subversion
 
 PSEUDONYM_LENGTH = 32
 LEVEL_ENCODING = 'UTF-8' # was Windows-1252
 TIME_DRIFT_THRESHOLD = 200 # ms
 STALE_LOGFILE_TIME = 48 * 60 * 60 # close logfiles after 48h
 MAX_ERROR_LOGS_PER_PLAYER = 25
 
+# The bearer token for the /metrics endpoint
+BEARER_TOKEN_BYTES = 32
+
 # Number of seconds, after which the player is considered disconnected. A "Back Online"
 # message will be printed to the log, if the player connects afterwards. Also used for the
 # Prometheus Online Player Count metric

app/model/ApiKey.py

@@ -0,0 +1,16 @@
+from datetime import datetime, timezone
+from sqlalchemy import DateTime, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.storage.database import db
+
+
+class ApiKey(db.Model):
+	token: Mapped[str] = mapped_column(primary_key=True)
+	user: Mapped[str] = mapped_column(String(64))
+	created: Mapped[datetime] = mapped_column(DateTime)
+
+	def __init__(self, token: str, user: str) -> None:
+		self.token = token
+		self.user = user
+		self.created = datetime.now(timezone.utc)

app/model/LevelLoader/JsonLevelList.py

@@ -54,9 +54,11 @@ def getPossibleLevels(self) -> list[Level]:
 			current_list = MappingProxyType(self.levelList[list_name])
 
 			for entry in current_list['levels']:
+				# If this is a list, add all levels that are contained in that list
 				if isinstance(entry, list):
 					for subEntry in cast(list[dict[str, str]], entry):
-						levels.append(Level(type=subEntry['type'], fileName=subEntry['name']))	
+						levels.append(Level(type=subEntry['type'], fileName=subEntry['name']))
+				# Else add the single level
 				else:
 					levels.append(Level(type=entry['type'], fileName=entry['name']))
 
@@ -152,7 +154,8 @@ def fromFile(
 		try:
 			conf = load_config(fileName=fileName, instanceFolder=instanceFolder)
 
-			# TODO Run checks
+			# TODO Run checks to catch any errors directly on launch and not later when
+			# someone tries to load the first level
 
 			logging.info(f'Successfully loaded {len(conf)} level lists.')
 			return conf

app/prometheusMetrics.py

@@ -1,6 +1,7 @@
 import logging
 from threading import Thread
 import time
+from typing import Any
 from flask import Flask
 
 # Prometheus Metrics
@@ -14,27 +15,29 @@
 
 class ServerMetrics:
 	@staticmethod
-	def __prometheusFactory():
+	def __prometheusFactory(auth_provider: Any):
 		EXCLUDED_PATHS = ["/?res\\/.*", "/?src\\/.*", "/?doc\\/.*"]
 
 		# Try to use the uWSGI exporter. This will fail, if uWSGI is not installed
 		try:
 			metrics = UWsgiPrometheusMetrics.for_app_factory( # type: ignore
-				excluded_paths=EXCLUDED_PATHS
+				excluded_paths=EXCLUDED_PATHS,
+				metrics_decorator=auth_provider
 			)
 
 		# Use the regular Prometheus exporter
 		except Exception as e:
 			logging.error(e)
 
 			metrics = PrometheusMetrics.for_app_factory( # type: ignore
-				excluded_paths=EXCLUDED_PATHS
+				excluded_paths=EXCLUDED_PATHS,
+				metrics_decorator=auth_provider
 			)
 
 		logging.info(f'Using {type(metrics).__name__} as the Prometheus exporter')
 		return metrics
 
-	metrics = __prometheusFactory()
+	metrics: PrometheusMetrics|UWsgiPrometheusMetrics|None = None
 
 	# ReverSim Prometheus Metrics
 	#met_openLogs = Gauge("reversim_logfile_count", "The number of open logfiles") # type: ignore
@@ -47,8 +50,9 @@ def __prometheusFactory():
 	met_clientErrors: Gauge|None = None
 
 	@classmethod
-	def createPrometheus(cls, app: Flask):
+	def createPrometheus(cls, app: Flask, auth_provider: Any):
 		"""Init Prometheus"""
+		cls.metrics = cls.__prometheusFactory(auth_provider)
 		cls.metrics.init_app(app) # type: ignore
 		cls.metrics.info('app_info', 'Application info', version=gameConfig.LOGFILE_VERSION) # type: ignore