Skip to content

README.md

Latest commit

 

History

History
80 lines (62 loc) · 5.66 KB

README.md

File metadata and controls

80 lines (62 loc) · 5.66 KB
Raw

VulnTester — Design Documentation

This directory contains the architectural design artifacts for VulnTester: C4 model diagrams (Mermaid.js) and Architecture Decision Records (ADRs).

C4 Model Diagrams

Hierarchical architecture views following the C4 Model methodology. All diagrams use Mermaid.js for version-controlled, editable rendering.

Level Diagram Description
1 Context VulnTester as a black box — external actors (Security Engineer, System Administrator), external systems (Host OS, LLM APIs, Package Managers), and data flows between them
2 Container Major subsystems — CLI Orchestrator, Scanner Engine, PenTest Engine, Zero-Day Detection Engine, Hardening Engine, Backup Manager, LLM Analyzer, Report Generator, Platform Layer
3 Component Internal modules — all 14 scanners, 12 hardeners, 5 pen test modules, 6 zero-day detectors; registry pattern; scanner-hardener pairing; heuristic correlation engine
4 Code Class hierarchies, data models (Finding, ScanReport, Severity), configuration structures, and the full orchestration sequence diagram

Rendering Diagrams

Mermaid diagrams render natively on GitHub, GitLab, and in VS Code (with the Mermaid extension). To render locally:

# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# Render a diagram to PNG
mmdc -i c4-diagrams/1-context.md -o c4-diagrams/1-context.png

Architecture Decision Records (ADRs)

ADRs document the "why" behind key design choices. Each record captures the context, decision, rationale, trade-offs accepted, and alternatives considered.

ADR Title Category Summary
001 Decorator-Based Module Registry Architecture Chose @register_scanner decorators over plugin systems for zero-dependency, explicit module discovery
002 Platform Dispatch Pattern Cross-Platform Chose abstract _scan_linux() / _scan_windows() / _scan_macos() methods over inline if/elif branching
003 stdlib HTTP for LLM Integration Dependencies Chose urllib.request over requests library to minimize supply chain risk for an optional feature
004 Backup-First Hardening Safety Chose file-copy backups with JSON manifests over OS-level snapshots or transactional rollback
005 Heuristic Correlation Engine Detection Chose deterministic PID-based correlation over ML-based anomaly detection for explainability and zero dependencies
006 Multi-Provider LLM Support Integration Chose custom unified LLMClient over vendor SDKs to support Claude/Grok/Gemini without 20+ transitive dependencies
007 Embedded HTML Reports Reporting Chose single-file standalone HTML over dashboards or PDFs for airgap compatibility and zero-dependency viewing
008 psutil for System Introspection Dependencies Chose psutil over parsing ps/netstat/tasklist for cross-platform structured data with no text parsing fragility
009 Interactive Consent Model Safety / UX Chose interactive confirmation as default over fully automated hardening, with --auto-harden opt-in for CI/CD
010 Dataclass Domain Models Data Modeling Chose stdlib dataclasses over Pydantic/attrs/dicts for zero-dependency typed models with JSON serialization

ADR Conventions

  • Numbering: Sequential, zero-padded three digits (ADR-001, ADR-002, ...)
  • Status values: Proposed → Accepted → Superseded or Deprecated
  • Template sections: Context, Decision, Rationale, Trade-offs Accepted, Alternatives Considered, Consequences
  • New ADRs: Copy an existing ADR and update all sections. Never remove superseded ADRs; mark them as Superseded by ADR-XXX

Architecture Overview

vulntester/
├── __main__.py          ← Orchestrator (5-phase pipeline)
├── cli.py               ← Argument parsing → ScanConfig
├── config.py            ← ScanConfig dataclass, Severity enum
├── platform_info.py     ← OS/distro/arch detection
├── privilege.py         ← Admin/root check
├── utils.py             ← Safe subprocess wrapper
├── backup.py            ← BackupManager (file + registry)
├── scanners/            ← 14 CIS-aligned vulnerability scanners
├── hardeners/           ← 12 backup-first remediation modules
├── pentest/             ← 5 offensive security modules
├── zeroday/             ← 6 anomaly detectors + heuristic engine
├── llm/                 ← Optional multi-provider AI analysis
└── report/              ← Standalone HTML report generator

Key Architectural Properties:

  • Cross-platform (Linux, Windows, macOS) via platform dispatch pattern (ADR-002)
  • 2 runtime dependencies only: psutil (ADR-008) + jinja2
  • Read-only scanning by default; hardening requires explicit consent (ADR-009)
  • Full rollback capability via backup manifests (ADR-004)
  • Optional LLM analysis with no vendor lock-in (ADR-006)