Immune System¶

A lightweight trust layer that detects threats and inconsistencies across G6's code, documentation, and deployment layers.

Overview¶

The immune system is an alert-only component that monitors the health of the G6 ecosystem without modifying anything. It uses AST-based static analysis to inspect code, cross-references documentation with actual exports, validates deployment configurations, and scans for security vulnerabilities.

Like a biological immune system, it has two response types:

Innate immunity: Built-in checkers with hardcoded knowledge of what "healthy" looks like
Adaptive immunity: Learned threat patterns that evolve from scan history

Design Principles¶

Principle	Implementation
Zero coupling	No imports from `mvp.*` — inspects code via AST without executing it
Alert only	Detects and reports; never auto-heals or modifies code
Self-integrity	SHA-256 manifest verifies its own files haven't been tampered with
Multi-channel	Findings routed to Prometheus, GitHub Issues, and email by severity

Architecture¶

immune_system/
├── innate/          # Built-in checkers (deterministic)
│   ├── consistency  # Code ↔ docs drift
│   ├── interface    # Type/signature contracts
│   ├── config       # Environment coherence
│   ├── security     # OWASP patterns, secrets
│   ├── deployment   # Infrastructure coherence
│   └── bdd          # Scenario deviation (stub)
├── adaptive/        # Learned threat memory (SQLite)
├── integrity/       # Self-integrity verification
├── sentinel/        # Execution modes (CLI, CI, scheduler)
├── review/          # Claude Code reviewer (optional)
└── notify/          # Multi-channel dispatch

Check Domains¶

Domain	What it checks	Severity range
Consistency	Code exports vs documentation	INFO — WARNING
Interface	Type annotations, AIBlock contracts	WARNING — ERROR
Config	.env ↔ compose ↔ nginx ↔ settings	WARNING — ERROR
Security	Secrets, eval/exec, SQL injection	WARNING — CRITICAL
Deployment	Dockerfiles ↔ compose ↔ nginx ports	WARNING — ERROR
Integrity	Self-file SHA-256 verification	CRITICAL
Code Review	Claude CLI review of changed files	INFO — ERROR

Usage¶

CLI¶

# Full scan
python -m mvp.immune_system scan

# Scan specific domains
python -m mvp.immune_system scan --domains security,config

# View scan history
python -m mvp.immune_system history

# Mark a finding
python -m mvp.immune_system mark <finding-id> false_positive

# Verify self-integrity
python -m mvp.immune_system manifest verify

CI/CD¶

The immune system runs as a quality gate in the deployment pipeline. It exits with code 1 if any CRITICAL or ERROR findings are detected, blocking the deployment.

Scheduled Scans¶

# Run scheduled scans every 6 hours
IMMUNE_SCAN_INTERVAL=6h python -m mvp.immune_system schedule

Configuration¶

Variable	Default	Description
`IMMUNE_SCAN_INTERVAL`	`6h`	Scheduled scan interval
`IMMUNE_REVIEW_ENABLED`	`false`	Enable Claude Code review
`IMMUNE_REVIEW_TIMEOUT`	`120`	Claude CLI timeout (seconds)
`IMMUNE_REVIEW_MAX_FILES`	`10`	Max files per review
`IMMUNE_DB_PATH`	`~/.g6/immune.db`	SQLite database path
`IMMUNE_EMAIL_RECIPIENT`	—	Email for critical alerts
`IMMUNE_PUSHGATEWAY_URL`	—	Prometheus pushgateway URL
`IMMUNE_GITHUB_REPO`	—	GitHub repo for issue creation

Theoretical Foundations¶

The immune system embodies several G6 theoretical principles:

Sheaf theory: Each checker verifies local constraints; the orchestrator ensures global coherence
Reflexivity: AST builds a model of the system and checks it against declarations
Autopoiesis: Adaptive memory evolves the threat model while integrity checking maintains itself
Grounding: Findings are justified by AST evidence and config parsing, not statistical guessing