Quickstart

Four steps from clone to first engagement.

Step 1: Install

git clone <repo-url> blackrainbow
cd blackrainbow
pip install -e .

This installs the br (and blackrainbow) CLI globally.

Verify the install:

br --version
# blackrainbow, version 0.1.0

Step 2: Initialize

Generate an engagement config from a template:

br init --template htb

This creates blackrainbow.yaml in your current directory. Two templates are available:

Template	Use Case	Target Type
htb	HackTheBox / CTF / single host	network-service
webapp	Web application assessment	web-application

You can also specify a custom output path:

br init --template webapp --output webapp-engagement.yaml

Step 3: Configure

Edit blackrainbow.yaml. Replace all CHANGEME values:

# BlackRainbow Engagement Config
target:
  type: network-service
  host: 10.10.10.5                     # Target IP
  label: htb-example                   # Box name for reports
  scope:
    networks:
      - 10.10.10.0/24
    exclude:
      - 10.10.10.1                     # Gateway

engagement:
  purpose: |
    Full compromise of target host. Obtain root-level access.
    Capture user.txt and root.txt flags as proof.
  rules:
    - No denial of service
    - No data destruction
    - No attacking out-of-scope hosts
  operator: pitl0rd

plugins:
  - recon

strategies: []

model:
  provider: ollama
  model: blackrainbow-v0
  host: http://localhost:11434
  temperature: 0.3

output:
  report: ./reports/
  capture: ./captures/
  format: markdown
  training_export: true

Plugin Configuration

Plugins accept both short and long form:

plugins:
  # Short form: just the plugin ID
  - recon

  # Long form: plugin ID with config overrides
  - id: recon
    numTests: 10
    severity: high
    config:
      scan_type: full

Step 4: Run

Execute the engagement:

br run

Preview without executing (dry run):

br run --dry-run

Expected Output

BlackRainbow v0.1.0
  Target:  10.10.10.5 (network-service)
  Plugins: recon

  Connecting to 10.10.10.5...

  Plugin: recon
    Generated 3 sequences
    Executing: Full TCP port scan of 10.10.10.5
      [1/1] nmap ...
      OK (45.2s)
      PASS score=0.50: Recon successful: 5 services, 0 vulns
    Executing: Top 1000 ports scan of 10.10.10.5
      [1/1] nmap ...
      OK (12.8s)
      PASS score=0.50: Recon successful: 5 services, 0 vulns
    Executing: NSE vulnerability scripts against 10.10.10.5
      [1/1] nmap ...
      OK (78.3s)
      PASS score=1.00: Recon successful: 5 services, 2 vulns

Engagement complete.
  Sequences: 3
  Passed:    3
  Failed:    0

Dry Run Output

With --dry-run, sequences are generated and displayed but not executed:

BlackRainbow v0.1.0
  Target:  10.10.10.5 (network-service)
  Plugins: recon
  Mode:    DRY RUN

  Plugin: recon
    Generated 3 sequences
    DRY RUN: Full TCP port scan of 10.10.10.5
      nmap -sC -sV -p- -oX /tmp/br-nmap-full-10.10.10.5.xml 10.10.10.5
    DRY RUN: Top 1000 ports scan of 10.10.10.5
      nmap -sC -sV -oX /tmp/br-nmap-quick-10.10.10.5.xml 10.10.10.5
    DRY RUN: NSE vulnerability scripts against 10.10.10.5
      nmap --script vuln -oX /tmp/br-nmap-vuln-10.10.10.5.xml 10.10.10.5

Engagement complete.
  Sequences: 3
  Passed:    0
  Failed:    0

CLI Overrides

Override config values from the command line:

# Override target host
br run --target 10.10.10.99

# Override plugins
br run --plugins recon,credential-access

# Set max iterations per plugin
br run --max-attempts 10

# Use a different config file
br run --config custom-engagement.yaml

# Combine overrides
br run --target 10.10.10.99 --plugins recon --dry-run

Explore the Framework

Check what is registered:

br plugins      # List available plugins
br strategies   # List available strategies
br targets      # List available target types
br status       # Framework summary