Roadmap — Custom Scanner Plugin System

Feature: Dynamic Custom Scanner Plugin System Created: 2026-03-10 Base project: Phases 1–12 COMPLETE (scanner core, backend, dashboard, extended scanning, attack paths, polish, ARM scanning — all delivered) Critical Path: Phase 1 → Phase 2 → Phase 3 & 4 (parallel) → Phase 5 Total Phases: 5 | Backend usable: After Phase 2 | Full feature: After Phase 5

---

Phase 1: Plugin Framework (Python Scanner)

Goal: Create a self-describing custom scanner plugin framework so Python scripts can define their own metadata (name, icon, columns) and scan logic, run with timeout/error isolation, and produce structured results within the existing scan pipeline.

Requirements: REQ-PLUGIN-001 through REQ-PLUGIN-009, REQ-SAFETY-001 through REQ-SAFETY-003, REQ-DOC-001

Status: ✅ COMPLETE (commit abe58e1)

Success Criteria:

1. ✅ A Python script inheriting CustomScanner with name, description, icon, columns attributes and async scan() method is discovered and executed from a configured directory
2. ✅ A script that raises an exception or exceeds the timeout produces a CustomScanResult with errors captured — the main scan pipeline continues unaffected
3. ✅ python -m scanner --test-run <path> runs a single script in isolation and outputs its CustomScanResult as JSON
4. ✅ ScanResult.custom_results contains all custom scanner outputs and serializes to JSON compatible with the existing backend ingest endpoint
5. ✅ template.py demonstrates all 8 ColumnType values with inline documentation

Depends on: None (base project Phase 12 complete)

Produces:

• scanner/src/scanner/custom/ — package with base.py, discovery.py, runner.py, template.py, __init__.py
• Modified __main__.py — custom scanner integration + --test-run CLI flag
• Modified config.py — custom_scripts_dir setting
• Modified models/scan_result.py — custom_results field

---

Phase 2: Backend — Script Management API

Goal: Build CRUD API endpoints for managing custom scanner scripts (stored as .py files on a shared volume + metadata in Cosmos DB), a test-run trigger, and result ingestion/retrieval — extending the existing Azure Functions backend.

Requirements: REQ-API-001 through REQ-API-010, REQ-SAFETY-004, REQ-DOC-002

Estimated Complexity: MEDIUM — follows existing backend patterns (14 containers, app.http() registration, Zod validation, ingestScanResult.ts splitting)

Key Risks:

• Script validation: must validate Python metadata (name, columns) before writing to volume — reject invalid scripts early
• Volume path coordination: backend writes scripts to path scanner reads from — must agree on mount point
• Test-run trigger: backend needs to invoke scanner container for single-script execution — sidecar vs Docker exec decision