Dev

README.md

@@ -113,6 +113,7 @@ openshield/
 
 ---
 
+
 ## Quick Start
 
 ```bash
@@ -185,4 +186,20 @@ MIT — free to use, modify, and distribute.
 
 ---
 
+> Built with ❤️ by security engineers and students who believe cloud security tooling should be accessible to everyone.
+
+---
+
+## Learn OpenShield
+
+Explore the OpenShield learning portal to understand:
+
+- Azure CSPM fundamentals
+- OpenShield architecture
+- Compliance mappings
+- Remediation workflows
+- Contributor onboarding
+- Documentation navigation
+
+👉 [OpenShield Learn](docs/learn/index.html)
 > Built by security engineers and students who believe cloud security tooling should be accessible to everyone.

api/app.py

@@ -63,9 +63,9 @@ def create_app() -> Flask:
     # ------------------------------------------------------------------ #
 
     @app.teardown_appcontext
-    def close_db(error):
+    def close_db(error=None):
         """Ensure the database connection is closed after the request."""
-        db = g.pop("db_conn", None)
+        db = g.pop("db", None)
         if db is not None:
             try:
                 if hasattr(db, "conn") and db.conn is not None:
@@ -171,4 +171,4 @@ def internal_error(exc):
         host="0.0.0.0",
         port=int(os.environ.get("PORT", 5000)),
         debug=os.environ.get("FLASK_DEBUG", "false").lower() == "true",
-    )
+    )

api/models/finding.py

@@ -96,6 +96,13 @@ def _get_conn(self) -> Any:
             self.connect()
         return self.conn
 
+    def close(self) -> None:
+        """Close the database connection."""
+        if self.conn and not self.conn.closed:
+            self.conn.close()
+            self.conn = None
+            logger.debug("Database connection closed")
+
     # ------------------------------------------------------------------ #
     # Schema                                                                #
     # ------------------------------------------------------------------ #

api/routes/compliance.py

@@ -13,10 +13,13 @@
 
 
 def _get_db() -> DatabaseManager:
-    if "db_conn" not in g:
-        g.db_conn = DatabaseManager(os.environ["DATABASE_URL"])
-        g.db_conn.connect()
-    return g.db_conn
+    if "db" not in g:
+        db_url = os.environ.get("DATABASE_URL")
+        if not db_url:
+            raise RuntimeError("DATABASE_URL environment variable is not set")
+        g.db = DatabaseManager(db_url)
+        g.db.connect()
+    return g.db
 
 
 @compliance_bp.get("/api/compliance/<framework>")
@@ -41,6 +44,8 @@ def get_compliance(framework: str):
             return jsonify(result), 500
 
         return jsonify(result)
+    except FileNotFoundError as exc:
+        return jsonify({"error": f"Frameworks directory not found: {exc}"}), 500
     except Exception as exc:
         logger.error("Failed to retrieve compliance score for %s: %s", framework, exc)
-        return jsonify({"error": "Compliance calculation failed", "detail": str(exc)}), 500
+        return jsonify({"error": "Compliance calculation failed", "detail": str(exc)}), 500

api/routes/scans.py

@@ -11,19 +11,22 @@
 
 
 def _get_db() -> DatabaseManager:
-    if "db_conn" not in g:
-        g.db_conn = DatabaseManager(os.environ["DATABASE_URL"])
-        g.db_conn.connect()
-    return g.db_conn
+    if "db" not in g:
+        db_url = os.environ.get("DATABASE_URL")
+        if not db_url:
+            raise RuntimeError("DATABASE_URL environment variable is not set")
+        g.db = DatabaseManager(db_url)
+        g.db.connect()
+    return g.db
 
 
 @scans_bp.get("/api/scans")
 def list_scans():
     """Return all historical scan results ordered by most recent first."""
     try:
         db = _get_db()
-        scans = db.get_scans()
-        return jsonify({"count": len(scans), "scans": scans})
+        result = db.get_scans()
+        return jsonify(result)
     except Exception as exc:
         logger.error("Failed to list scans: %s", exc)
         return jsonify({"error": "Failed to retrieve scans", "detail": str(exc)}), 500
@@ -39,15 +42,20 @@ def trigger_scan():
     Note: For production use, replace this with an async task queue (e.g.
     Celery or Azure Functions) to avoid request timeouts on large subscriptions.
     """
+    try:
+        from scanner.engine import ScanEngine
+    except ImportError:
+        return jsonify({"error": "Scanner module is not available"}), 500
+
     try:
         body = request.get_json(silent=True) or {}
-        subscription_id = body.get("subscription_id")
+        subscription_id = body.get("subscription_id") or os.environ.get(
+            "AZURE_SUBSCRIPTION_ID"
+        )
 
         if not subscription_id:
             return jsonify({"error": "subscription_id is required"}), 400
 
-        from scanner.engine import ScanEngine  # deferred — import only after input is validated
-
         logger.info("Scan triggered for subscription %s", subscription_id)
 
         try:
@@ -57,16 +65,18 @@ def trigger_scan():
             logger.error("Scan engine execution failed: %s", exc, exc_info=True)
             return jsonify({"error": "Scan failed", "detail": str(exc)}), 500
 
+        if not isinstance(result, dict) or "scan_id" not in result:
+            return jsonify({"error": "Invalid scan result returned"}), 500
+
         try:
             db = _get_db()
-            # Note: Table creation is handled at startup; no need to repeat it here.
             db.save_scan(result)
         except Exception as exc:
-            logger.error("Failed to save scan result to database: %s", exc, exc_info=True)
+            logger.error("Failed to save scan result: %s", exc, exc_info=True)
             return jsonify({"error": "Database save failed", "detail": str(exc)}), 500
 
         return jsonify(result), 201
 
     except Exception as exc:
         logger.error("Critical error in trigger_scan route: %s", exc, exc_info=True)
-        return jsonify({"error": "Critical route failure", "detail": str(exc)}), 500
+        return jsonify({"error": "Critical route failure", "detail": str(exc)}), 500

api/routes/score.py

@@ -11,10 +11,13 @@
 
 
 def _get_db() -> DatabaseManager:
-    if "db_conn" not in g:
-        g.db_conn = DatabaseManager(os.environ["DATABASE_URL"])
-        g.db_conn.connect()
-    return g.db_conn
+    if "db" not in g:
+        db_url = os.environ.get("DATABASE_URL")
+        if not db_url:
+            raise RuntimeError("DATABASE_URL environment variable is not set")
+        g.db = DatabaseManager(db_url)
+        g.db.connect()
+    return g.db
 
 
 @score_bp.get("/api/score")
@@ -27,8 +30,8 @@ def get_score():
     """
     try:
         db = _get_db()
-        score = db.get_score()
-        return jsonify({"score": score, "max_score": 100})
+        result = db.get_score()
+        return jsonify(result)
     except Exception as exc:
         logger.error("Failed to calculate score: %s", exc)
-        return jsonify({"error": "Failed to calculate score", "detail": str(exc)}), 500
+        return jsonify({"error": "Failed to calculate score", "detail": str(exc)}), 500

compliance/frameworks/cis_azure_benchmark.json

@@ -98,6 +98,11 @@
       "control_name": "Ensure that 'OS disk' are encrypted",
       "description": "Virtual machine OS and data disks are using platform-managed encryption only (EncryptionAtRestWithPlatformKey). CIS 7.2 requires disks to be protected using customer-managed keys or Azure Disk Encryption. Platform-managed encryption does not give the organisation control over the encryption keys and does not satisfy this control."
     },
+    "AZ-CMP-003": {
+      "control_id": "8.2",
+      "control_name": "Ensure that 'Endpoint protection solution' is installed on VMs",
+      "description": "The virtual machine does not have a recognised endpoint protection extension installed. CIS 8.2 requires that an approved endpoint protection solution is installed and running on all virtual machines. Without endpoint protection, malware and ransomware can execute without detection."
+    },
     "AZ-KV-001": {
       "control_id": "8.5",
       "control_name": "Ensure the Key Vault is Recoverable",

compliance/frameworks/iso27001.json

@@ -98,6 +98,11 @@
       "control_name": "Policy on the use of cryptographic controls",
       "description": "Virtual machine OS and data disks are using platform-managed encryption only (EncryptionAtRestWithPlatformKey). A.10.1.1 requires that a policy on the use of cryptographic controls is developed and implemented. Platform-managed encryption does not give the organisation control over the encryption keys. Customer-managed keys or Azure Disk Encryption are required to satisfy this control."
     },
+    "AZ-CMP-003": {
+      "control_id": "A.12.2.1",
+      "control_name": "Controls against malware",
+      "description": "The virtual machine does not have a recognised endpoint protection extension installed. A.12.2.1 requires that detection, prevention and recovery controls are implemented to protect against malware. Without endpoint protection, malware executing on the VM will not be detected or prevented."
+    },
     "AZ-KV-001": {
       "control_id": "A.17.2.1",
       "control_name": "Availability of information processing facilities",

compliance/frameworks/nist_csf.json

@@ -98,6 +98,11 @@
       "control_name": "Data-at-rest is protected",
       "description": "Virtual machine OS and data disks are using platform-managed encryption only (EncryptionAtRestWithPlatformKey). PR.DS-1 requires that data at rest is protected using appropriate controls. Platform-managed encryption does not give the organisation control over the encryption keys. Customer-managed keys or Azure Disk Encryption are required to satisfy this control."
     },
+    "AZ-CMP-003": {
+      "control_id": "DE.CM-4",
+      "control_name": "Malicious code is detected",
+      "description": "The virtual machine does not have a recognised endpoint protection extension installed. DE.CM-4 requires that malicious code is detected on organisational systems. Without endpoint protection, malware and ransomware executing on the VM will not be detected or blocked."
+    },
     "AZ-KV-001": {
       "control_id": "PR.IP-4",
       "control_name": "Backups of information are conducted, maintained, and tested",

compliance/frameworks/soc2.json

@@ -103,6 +103,11 @@
       "control_name": "Protects Data in Transit and At Rest",
       "description": "Virtual machine OS and data disks are using platform-managed encryption only (EncryptionAtRestWithPlatformKey). CC6.7 requires that data is protected using encryption. Platform-managed encryption does not give the organisation control over the encryption keys. Customer-managed keys or Azure Disk Encryption are required to satisfy this control."
     },
+    "AZ-CMP-003": {
+      "control_id": "CC6.8",
+      "control_name": "Prevents or Detects Unauthorized or Malicious Software",
+      "description": "The virtual machine does not have a recognised endpoint protection extension installed. CC6.8 requires that controls are implemented to prevent or detect and act upon the introduction of unauthorized or malicious software. Without endpoint protection, malicious code executing on the VM will not be detected or blocked."
+    },
     "AZ-KV-001": {
       "control_id": "A1.2",
       "control_name": "Environmental Threats and Recovery",