vulncheck/ARCHITECTURE.md

VulnManager - Architecture Overview

1. System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Frontend (React/Vue)                    │
│                    - Dashboard Views                         │
│                    - Asset Management                        │
│                    - Vulnerability Prioritization            │
11: └───────────────────────┬─────────────────────────────────────┘
12:                         │ HTTPS/REST API
13: ┌───────────────────────┴─────────────────────────────────────┐
│                   FastAPI Backend                            │
│  ┌────────────────────────────────────────────────────┐     │
│  │  Authentication & Authorization Middleware         │     │
│  │  - JWT Token Management                            │     │
│  │  - RBAC (Admin, Editor, Read-only)                 │     │
│  └────────────────────────────────────────────────────┘     │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Vuln      │  │   Asset      │  │    AI        │      │
│  │  Service    │  │  Service     │  │  Service     │      │
│  └─────────────┘  └──────────────┘  └──────────────┘      │
└───────┬────────────────────┬────────────────┬──────────────┘
        │                    │                │
        │ PostgreSQL         │ Wazuh API      │ Infomaniak AI
        ↓                    ↓                ↓
┌───────────────┐    ┌──────────────┐  ┌────────────────┐
│  PostgreSQL   │    │  Wazuh       │  │  Infomaniak    │
│   Database    │    │  Manager     │  │  AI API        │
│               │    │  (Agents)    │  │  (LLM+Search)  │
└───────────────┘    └──────────────┘  └────────────────┘

2. Security Architecture (OWASP Top 10 Mitigation)

A01: Broken Access Control

• JWT-based Authentication with HTTP-only Cookies
• RBAC Model with three roles: Admin, Editor, Read-only
• Granular Permission Checks at Endpoint Level
• Resource-Level Authorization (Users see only their assigned assets)

A02: Cryptographic Failures

• bcrypt for Password Hashing (12 Rounds)
• Secrets Management via Environment Variables
• TLS 1.3 for all API communications
• Encrypted Database Connections

A03: Injection

• SQLAlchemy ORM with Parameterized Queries
• Pydantic Models for Input Validation
• Prepared Statements for all DB operations
• Content-Type Validation

A04: Insecure Design

• Rate Limiting (100 Requests/Minute per User)
• Defense in Depth (Multi-layered validation)
• Least Privilege Principle for DB Access
• Secure by Default Configurations

A05: Security Misconfiguration

• Strict CORS Policy (Whitelist-based)
• Security Headers (CSP, HSTS, X-Frame-Options)
• Disabled Debug Mode in Production
• Minimal Dependency Versions (pinned)

A06: Vulnerable Components

• Dependabot for automatic updates
• Regular Security Audits (pip-audit, safety)
• Vendor Security Advisories Monitoring

A07: Authentication Failures

• Account Lockout after 5 failed login attempts
• Password-Complexity Requirements
• Session Timeout (30 Minutes Inactivity)
• Multi-Factor Authentication (optional, prepared)

A08: Software and Data Integrity

• API Signature Verification for external calls
• Integrity Checks for critical data
• Audit Logging of all changes

A09: Logging Failures

• Structured Logging (JSON Format)
• Security Event Monitoring (Login, Authorization Errors)
• Log Retention (90 Days)
• PII Redaction in Logs

A10: SSRF

• URL Whitelist for external API calls
• Network Segmentation
• Request Validation for User-Input URLs

3. Component Details

3.1 Backend Services

Vulnerability Service

• Data Query from Wazuh API
• CVSS Score Calculation and Prioritization
• Patch Status Tracking
• Rescan Trigger on Status Changes

Asset Service

• Asset Discovery (Wazuh + Manual Input)
• Inventory Management
• Compliance Tracking
• Network Mapping

AI Service

• CVE Analysis via Infomaniak LLM
• Threat Intelligence Aggregation
• Remediation Recommendations
• Risk Assessment

3.2 Data Flow

Vulnerability Import Flow

1. Cronjob (every 6h) triggers Wazuh API Scan
2. Vulnerability Service fetches data by Agent ID
3. Data Normalization and Enrichment (CVSS, Exploitability)
4. Deduplication and Upsert in PostgreSQL
5. Alert Generation for critical CVEs (CVSS >= 9.0)
6. Dashboard Update via WebSocket (optional)

Patch Verification Flow

1. User marks Vulnerability as "Patched"
2. System validates User Permission (Editor/Admin)
3. Status Update in DB (Status = "Pending Verification")
4. API Call to Wazuh: POST /syscollector?agent_id=X
5. Wait for Scan Completion (max. 10 Min)
6. Re-fetch Vulnerability Data
7. Automatic Verification: CVE still present?
   - Yes → Status = "Patch Failed", Alert to User
   - No → Status = "Patched (Verified)"

AI Analysis Flow

1. User selects CVE from Dashboard
2. Request to AI Service with CVE ID
3. AI Service calls Infomaniak API:
   - Prompt: "Analyze CVE-{id}, find exploits, workarounds, threat intel"
   - Web Search activated
4. LLM generates structured response (JSON)
5. Cache in Redis (24h TTL)
6. Display in Frontend with Markdown Rendering

4. Data Model

Entities

• User (Authentication, Roles)
• Asset (Hosts, IPs, Metadata)
• Vulnerability (CVEs, CVSS, Status)
• Scan (Scan History, Timestamps)
• AIAnalysis (Cached LLM Responses)
• AuditLog (Security Events)

Relationships

• User (1) → (N) AuditLog
• Asset (1) → (N) Vulnerability
• Vulnerability (1) → (1) AIAnalysis (optional)
• Asset (1) → (N) Scan

5. API Endpoints

Authentication

• POST /auth/login - JWT Token Generation
• POST /auth/logout - Session Invalidation
• POST /auth/refresh - Token Refresh
• GET /auth/me - Current User Info

Vulnerability Management

• GET /api/v1/vulnerabilities - List with Filter/Sort
• GET /api/v1/vulnerabilities/{cve_id} - Detail View
• PATCH /api/v1/vulnerabilities/{cve_id} - Status Update (Patch)
• POST /api/v1/vulnerabilities/{cve_id}/analyze - Trigger AI Analysis
• POST /api/v1/vulnerabilities/rescan/{asset_id} - Wazuh Rescan

Asset Management

• GET /api/v1/assets - Asset List
• POST /api/v1/assets - Add Manual Asset
• PUT /api/v1/assets/{id} - Update Asset
• DELETE /api/v1/assets/{id} - Delete Asset
• GET /api/v1/assets/{id}/vulnerabilities - Vulns of an Asset

Reporting

• GET /api/v1/reports/dashboard - Dashboard Statistics
• GET /api/v1/reports/cvss-distribution - CVSS Score Distribution
• GET /api/v1/reports/age-analysis - Age of open CVEs

6. Deployment Architecture

Container Setup (Docker Compose)

services:
  - backend (FastAPI)
  - postgres (PostgreSQL 15)
  - redis (Caching)
  - nginx (Reverse Proxy + Frontend)

Environment Variables

DATABASE_URL=postgresql://user:pass@postgres:5432/vulnmanager
WAZUH_API_URL=https://wazuh.example.com:55000
WAZUH_API_TOKEN=<token>
INFOMANIAK_AI_API_KEY=<key>
JWT_SECRET_KEY=<random-256bit>
REDIS_URL=redis://redis:6379/0

7. Performance & Scaling

Caching Strategy

• Redis for AI Analyses (24h TTL)
• In-Memory Cache for User Sessions (LRU, max 10k)
• Database Query Cache for Dashboard Widgets (5 Min)

Indexing

• B-Tree Index on vulnerabilities.cve_id
• Composite Index on (asset_id, severity, status)
• Partial Index for open Vulnerabilities

Background Jobs

• Celery for asynchronous tasks (Wazuh Sync, Scans)
• APScheduler for Cronjobs (Daily Import)

8. Monitoring & Observability

Metrics

• Request Latency (P50, P95, P99)
• Error Rate (4xx, 5xx)
• Wazuh API Response Time
• Active User Sessions

Logging

• Application Logs → Stdout (JSON)
• Access Logs → Nginx Format
• Audit Logs → Separate DB Table

Alerting

• Critical CVE Detection (CVSS >= 9.0)
• Wazuh API Downtime
• Failed Login Attempts (> 10 in 5 Min)
• Database Connection Errors

9. Development Roadmap

Phase 1: MVP (Week 1-2)

• ✓ Core Backend Setup
• ✓ Wazuh API Integration
• ✓ Basic Authentication
• ✓ Vulnerability CRUD

Phase 2: Extended Features (Week 3-4)

• AI Integration (Infomaniak)
• Asset Management
• RBAC System
• Rescan Logic

Phase 3: Frontend & Polish (Week 5-6)

• React Dashboard
• Visualizations (Charts)
• Export Functions
• User Onboarding

Phase 4: Production Ready (Week 7-8)

• Security Hardening
• Performance Tuning
• Documentation
• Deployment Automation