From 4044ebb1bfc6d5399cb8c964c44fda9735216726 Mon Sep 17 00:00:00 2001
From: Mariusz Banach <mariusz@outflank.nl>
Date: Tue, 17 Feb 2026 23:45:54 +0100
Subject: [PATCH] MAESTRO: add base scanner protocol

---
 ...-header-analyzer-Phase-02-Engine-Refactoring.md |  2 +-
 backend/app/engine/scanner_base.py                 | 14 ++++++++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 backend/app/engine/scanner_base.py

diff --git a/Auto Run Docs/SpecKit-web-header-analyzer-Phase-02-Engine-Refactoring.md b/Auto Run Docs/SpecKit-web-header-analyzer-Phase-02-Engine-Refactoring.md
index df8e868..7bc7b74 100644
--- a/Auto Run Docs/SpecKit-web-header-analyzer-Phase-02-Engine-Refactoring.md	
+++ b/Auto Run Docs/SpecKit-web-header-analyzer-Phase-02-Engine-Refactoring.md	
@@ -49,7 +49,7 @@ backend/app/engine/
 - [x] T008 Create `backend/app/engine/__init__.py` and `backend/app/engine/models.py` — Pydantic models for `AnalysisRequest`, `AnalysisResult`, `TestResult`, `HopChainNode`, `SecurityAppliance`. Refer to `.specify/specs/1-web-header-analyzer/data-model.md` for field definitions and severity enum values (spam→#ff5555, suspicious→#ffb86c, clean→#50fa7b, info→#bd93f9)
 - [x] T009 Create `backend/app/engine/logger.py` — extract Logger class from `decode-spam-headers.py` (lines 209–419), adapt to use Python `logging` module instead of direct stdout
 - [x] T010 Create `backend/app/engine/parser.py` — extract header parsing from `SMTPHeadersAnalysis.collect()` and `getHeader()` (lines ~2137–2270). Expose `HeaderParser.parse(raw_text: str) -> list[ParsedHeader]` including MIME boundary and line-break handling. Verify `test_parser.py` passes (TDD Green)
-- [ ] T011 Create `backend/app/engine/scanner_base.py` — abstract `BaseScanner` (Protocol or ABC) with interface: `id: int`, `name: str`, `run(headers: list[ParsedHeader]) -> TestResult | None`
+- [x] T011 Create `backend/app/engine/scanner_base.py` — abstract `BaseScanner` (Protocol or ABC) with interface: `id: int`, `name: str`, `run(headers: list[ParsedHeader]) -> TestResult | None` (implemented Protocol in `backend/app/engine/scanner_base.py`)
 - [ ] T012 Create `backend/app/engine/scanner_registry.py` — `ScannerRegistry` with auto-discovery: `get_all()`, `get_by_ids(ids)`, `list_tests()`. Verify `test_scanner_registry.py` passes (TDD Green)
 - [ ] T013 [P] Create scanner modules by extracting test methods from `SMTPHeadersAnalysis` into `backend/app/engine/scanners/`. Each file implements `BaseScanner`:
   - `backend/app/engine/scanners/received_headers.py` (tests 1–3)
diff --git a/backend/app/engine/scanner_base.py b/backend/app/engine/scanner_base.py
new file mode 100644
index 0000000..c2a2794
--- /dev/null
+++ b/backend/app/engine/scanner_base.py
@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from .models import TestResult
+from .parser import ParsedHeader
+
+
+class BaseScanner(Protocol):
+    id: int
+    name: str
+
+    def run(self, headers: list[ParsedHeader]) -> TestResult | None:
+        """Run the scanner against parsed headers."""