Skip to content

Immune System

G6 Artificial Immune System - lightweight trust layer for threat detection.

Cluster: Uncategorised | Type: component | MCP Tools: None

Overview

Artificial immune system providing a lightweight, cross-cutting trust layer for G6. Scans component interfaces, configurations, deployments, and code for threat patterns across 8 check domains (consistency, interface, config, security, deployment, BDD, integrity, code review). Returns structured ScanReport findings with severity, provenance, and remediation lifecycle tracking.

The package facade now carries a real @block_contract on ImmuneSystemBlock (isolation-preserving: only __init__.py touches mvp.core, and the isolated checker core stays mvp-import-free) and attaches the canonical reliability envelope to the package-level scan() Result. The envelope mapping is honest and authoritative on scan_status: complete -> verified, degraded -> qualified-draft (G6_E_IMMUNE_SCAN_DEGRADED), blocked -> blocked-escalated (G6_E_IMMUNE_SCAN_BLOCKED); there is no path by which a degraded or blocked scan reads as verified. A routable skill/SKILL.md manifest documents the component.

When to use:

  • Running a system-wide health scan before deployment
  • Detecting configuration drift, interface mismatches, or security regressions
  • Tracking remediation status of known issues across the component registry

Example:

from mvp.immune_system import ImmuneSystemBlock

block = ImmuneSystemBlock()
report = block.scan(target_path="components/mvp/goal_engine")
# report.findings: list[Finding] with severity, domain, and remediation_status

Caveats and known limitations:

  • Does not inherit from AIBlock — uses duck-typed infer() returning plain dicts, not Result objects
  • The isolated checker core (everything below __init__.py) keeps zero mvp.* imports by design (cannot depend on code it monitors); only the package facade __init__.py imports mvp.core to attach the contract and reliability envelope, so shared Result/protocol types are available at the boundary but never inside the core
  • Innate and keyword checkers are advisory heuristics: a complete scan means the configured scan ran clean, not that all possible threats are absent — scan_status="complete" maps to verified only when NO findings were surfaced; a complete scan with findings is gated down to qualified-draft (or blocked-escalated for CRITICAL findings), so a scan is never verified when it found problems
  • Held at qualified-draft / beta pending full three-lane (formal + property + adversarial) evidence; the scan-status floor and envelope mapping are rigorous and the contract's mitigates_failure_modes are registered in the shared FailureModeRegistry, but advisory heuristics still cannot prove threat absence
  • Findings are suppressed by signature hash — hash collisions are theoretically possible (low risk)
  • Adaptive severity boosting improves with repeated findings but has no decay — old patterns stay elevated indefinitely
  • Claude code review checker is OFF by default — it runs only with the claude CLI present AND two separate config keys: scan()'s claude_review_enabled (set by the IMMUNE_REVIEW_ENABLED env var) AND the reviewer's own review_enabled (a separate key the env config does not set)
  • No explicit timeout on individual innate checkers — a slow checker can block the entire scan

Works well with: system_doctor, observability, csf, diagnostic_collector

Public API

ImmuneSystemBlock

Artificial immune system — detects threats across code, docs, and deployment layers.

Constructor:

Parameter Type Default
workspace_root Path \| str required
db_path Path \| str \| None None
config dict \| None None

Methods:

scan(domains: list[str] | None = None) -> ScanReport

Run a full immune-system scan, optionally filtered by domains.

infer(input_data: dict | None = None) -> dict

Duck-type the AIBlock infer() interface.

report(scan_id: str) -> dict

Retrieve a previously stored scan by scan_id.

history(limit: int = 10) -> list[dict]

Return the most recent scan summaries.

mark(finding_id: str, status: str) -> None

Update the remediation status of a finding.

verify_integrity() -> list[Finding]

Run the integrity check only.

list_patterns() -> dict

Surface the deterministic applied-pattern + skill catalog for immune_system.

close() -> None

Close the DB connection.

Severity(Enum)

How severe a finding is.

CheckDomain(Enum)

High-level domain a checker covers.

RemediationStatus(Enum)

Lifecycle state of a finding's remediation.

Provenance

Where a finding came from and how confident we are.

Field Type Default
checker str required
method str required
evidence tuple[str, ...] ()
confidence float 1.0

Finding

A single issue discovered during a scan.

Field Type Default
id str required
domain CheckDomain required
severity Severity required
title str required
description str required
provenance Provenance required
file_path str \| None None
line_number int \| None None
expected str \| None None
actual str \| None None
suggestion str \| None None
timestamp str ''
is_adaptive bool False

ScanReport

Aggregate result of a full immune-system scan.

Field Type Default
scan_id str required
timestamp str required
duration_seconds float required
findings tuple[Finding, ...] ()
domains_checked tuple[CheckDomain, ...] ()
components_scanned int 0
files_scanned int 0
integrity_verified bool False
scan_status Literal['complete', 'degraded', 'blocked'] 'complete'

ThreatPattern

A known threat signature the immune system watches for.

Field Type Default
pattern_id str required
domain CheckDomain required
signature str required
description str required