Overview

BlackRainbow is a security assurance framework. Plugin architecture, YAML-driven engagements, a 5-stage execution engine, and a domain-expert AI model trained on 58,000+ security pairs. One repo, two things:

1. The Framework (the product): CLI tool for red team operations. Plugins generate attack sequences, strategies transform delivery, targets execute against infrastructure, graders evaluate results. Like promptfoo, but for security assurance.
2. The Training Infrastructure (the factory): QLoRA training pipeline for the BlackRainbow domain-expert model. Qwen2.5-7B-Instruct base, 53+ domains, 11 color categories.

CLI Tool

The CLI is br (or blackrainbow). Eight commands. Rich terminal output.

br init --template htb       # Generate engagement config
br run                        # Execute engagement pipeline
br run --dry-run              # Preview sequences without executing
br plugins                    # List registered plugins
br strategies                 # List registered strategies
br targets                    # List registered targets
br status                     # Framework summary
br banner                     # ASCII banner

Product Hierarchy

Product	What It Is	Status
BlackRainbow CLI (br)	Security assurance framework	Sprint 0+1 complete
ZeroBoy	Operator copilot (model in the loop)	Planned
Operator Platform	Web dashboard	Planned

The CLI is the foundation. ZeroBoy adds AI-driven decision making (the model suggests next steps based on discovered services). The Operator Platform puts it all behind a web interface.

Architecture

blackrainbow/
├── cli.py                 # Click CLI, 8 commands
├── config.py              # YAML parser + 7 Pydantic models
├── engine.py              # Pipeline: generate → transform → execute → grade
├── plugins/
│   ├── __init__.py        # PLUGIN_REGISTRY + register/get/list
│   ├── base.py            # PluginBase ABC + data types
│   └── recon.py           # ReconPlugin: nmap scanning + grading
├── strategies/
│   ├── __init__.py        # STRATEGY_REGISTRY + register/get/list
│   └── base.py            # StrategyBase ABC
├── targets/
│   ├── __init__.py        # TARGET_REGISTRY + register/get/list
│   ├── base.py            # TargetBase ABC
│   └── network_service.py # NetworkServiceTarget: subprocess execution
├── eval/                  # Stub (Sprint 2)
├── report/                # Stub (Sprint 2)
└── capture/               # Stub (Sprint 4)

Key Patterns

• Registry pattern. Plugins, strategies, and targets all use decorator-based registration (@register_plugin, @register_strategy, @register_target). Registries are module-level dicts populated at import time.
• Pipeline flow. Config loads, plugins generate attack sequences, strategies transform them, targets execute them, plugins grade the results.
• Service accumulation. Discovered services from grading results feed into EngagementContext.discovered_services, enabling multi-phase kill chains where recon output drives exploitation input.
• Pydantic validation. Seven models validate YAML config. Plugin references normalize from both string and dict forms.
• Lazy imports. The CLI lazy-imports config and engine in the run command for fast startup. _import_builtins() triggers decorator registration only when needed.

Model Hierarchy

BlackRainbow trains multiple model variants from the same corpus using color filters:

Model	Scope	Color Filter
BlackRainbow	Full spectrum, all domains	ALL
Shinobit	Attack operations	RED, ORANGE, YELLOW
Onibit	Detection and defense	BLUE, GREY
Immortal Blade	Purple team (the flip)	PURPLE (RED+BLUE combined)

Test Coverage

116 tests, all passing. The framework ships with comprehensive unit and integration test coverage.

Part of the Ecosystem

BlackRainbow is a zero-lab.ai product. The training data pipeline connects to the Rainbow Series corpus (58,648 pairs, 31 sources, 53+ domains). The framework consumes training data read-only. All data changes go through the Rainbow Series pipeline.