Metadata-Version: 2.1
Name: rednblue
Version: 2.2.0
Summary: Adversarial security testing CLI for AI models
Home-page: https://github.com/mahdidrm/RednBlue_CLI
Author: Dr. Mahdi Deramgozin, Dr. Saeid Samizade
Author-email: contact@rednblue.io
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/mahdidrm/RednBlue_CLI/issues
Project-URL: Documentation, https://github.com/mahdidrm/RednBlue_CLI#readme
Keywords: adversarial-ml security ai-testing machine-learning deep-learning
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: yolo
License-File: LICENSE

# RednBlue CLI v2.2.0

**Adversarial Security Testing for AI Models**

RednBlue CLI is a command-line tool for testing the adversarial robustness of machine learning models. It supports both **image classifiers** (ResNet, VGG, etc.) and **YOLO object detection** models (YOLOv5/v8/v10/v11).

---

## What's New in v2.2.0

- **YOLO Detection Support** — Full adversarial attack suite for object detection models
- **Gradient Masking Diagnostic (YGMD)** — Detects false robustness in YOLO models
- **Black-box Attacks** — NES and Square Attack for gradient-free testing
- **Improved Model Loading** — Better architecture detection for `.pt`/`.pth` files
- **Unified CLI** — Single `--model-type` flag to switch between classifier and YOLO modes

---

## Installation

```bash
# Clone or download the CLI
pip install rednblue

# Verify installation
rnb status
```

### Requirements

```
torch>=2.0.0
torchvision
numpy
Pillow
click
tqdm
colorama
cryptography
requests
```

For YOLO models, also install:
```
ultralytics
```

---

## Quick Start

### Test an Image Classifier

```bash
# Preview mode (free, no token required)
rnb preview --model resnet18.pth --input ./images

# With submission to RednBlue platform
export RNB_TOKEN=RB-XXXXXX-YYYYYY
rnb preview --model resnet18.pth --input ./images --submit
```

### Test a YOLO Detection Model

```bash
# Preview mode (free, no token required)
rnb preview --model-type yolo --model yolo26n.pt --input ./images

# With submission to RednBlue platform
export RNB_TOKEN=RB-XXXXXX-YYYYYY
rnb preview --model-type yolo --model yolo26n.pt --input ./images --submit
```

---

## Commands

### `rnb preview`

Run adversarial attacks locally and optionally submit results for certification.

```bash
rnb preview [OPTIONS]
```

| Option | Description | Default |
|--------|-------------|---------|
| `--model PATH` | Path to model file (`.pt`, `.pth`, `.onnx`) | Required |
| `--input PATH` | Directory containing test images (`.jpg`, `.png`) | Required |
| `--model-type TYPE` | Model architecture: `classifier` or `yolo` | `classifier` |
| `--submit` | Submit results to RednBlue for certification | `False` |

**Examples:**

```bash
# Classifier model
rnb preview --model vgg16.pth --input ./test_images

# YOLO model
rnb preview --model-type yolo --model best.pt --input ./coco_samples

# Submit for certification
rnb preview --model-type yolo --model yolov8n.pt --input ./images --submit
```

### `rnb status`

Check CLI version and token status.

```bash
rnb status
```

---

## Supported Attacks

### Image Classifier Attacks

| Code | Attack Name | Type | Description |
|------|-------------|------|-------------|
| `GNI` | Gaussian Noise Injection | Black-box | Random Gaussian perturbations |
| `SHFP` | High-Frequency Perturbation | Black-box | Sinusoidal high-frequency patterns |
| `UAP` | Universal Adversarial Patch | Black-box | Random adversarial patches |
| `FSP` | FGSM Surrogate Transfer | White-box | Fast Gradient Sign Method |
| `CCM` | Color Channel Manipulation | Black-box | Per-channel intensity shifts |
| `PGD` | Projected Gradient Descent | White-box | Iterative gradient attack (40 steps) |
| `CW` | Carlini-Wagner L2 | White-box | Optimization-based attack |
| `DEEP` | DeepFool | White-box | Minimal perturbation attack |

### YOLO Detection Attacks

| Code | Attack Name | Type | Description |
|------|-------------|------|-------------|
| `YGNI` | YOLO Gaussian Noise | Black-box | Baseline noise injection |
| `YFGS` | YOLO FGSM | White-box | Single-step gradient attack on detection loss |
| `YPGD` | YOLO PGD | White-box | Iterative evasion attack (40 steps) |
| `YDAG` | Dense Adversary Generation | White-box | Attacks all anchor positions (Xie et al. 2017) |
| `YTOG` | Targeted Object Disappearance | White-box | Suppresses specific class (Chow et al. 2020) |
| `YNMS` | NMS Bypass Injection | White-box | Injects ghost detections |
| `YNES` | Natural Evolution Strategy | Black-box | Gradient-free finite-difference attack |
| `YSQA` | Square Attack | Black-box | Score-based random search (Andriushchenko 2020) |
| `YGMD` | Gradient Masking Diagnostic | Diagnostic | Detects false robustness |

---

## Tier System

### Freelancer Tier (Default)

- **Classifier:** 5 attacks × 2 epsilon levels = 10 tests
- **YOLO:** 4 attacks × 2 epsilon levels = 8 tests
- Attacks: `GNI`, `SHFP`, `UAP`, `FSP`, `CCM` (classifier) / `YGNI`, `YFGS`, `YPGD`, `YGMD` (YOLO)
- Epsilon values: `0.005`, `0.01`

### Enterprise Tier

- **Classifier:** 8 attacks × 4 epsilon levels = 32 tests
- **YOLO:** 9 attacks × 4 epsilon levels = 36 tests
- All attacks included
- Epsilon values: `0.005`, `0.01`, `0.03`, `0.10`
- Additional features: Epsilon optimization, LLM testing

---

## Gradient Masking Detection (YGMD)

RednBlue v2.2 includes the **Gradient Masking Diagnostic** — a novel tool that detects when YOLO models exhibit "false robustness" due to gradient masking.

### What is Gradient Masking?

Some models appear robust to white-box attacks (FGSM, PGD) but are actually vulnerable to black-box attacks. This happens when gradients are obfuscated, zero, or misleading — giving a false sense of security.

### How YGMD Works

YGMD runs three probes on each image:

1. **White-box probe (YFGS)** — Measures gradient-based attack effectiveness
2. **Black-box probe (YNES)** — Gradient-free Natural Evolution Strategy
3. **Black-box probe (YSQA)** — Score-based Square Attack

It computes a **masking index**:

```
masking_index = 1 - (white_box_drop / black_box_drop)
```

### Interpretation

| Masking Index | Verdict | Meaning |
|---------------|---------|---------|
| 0.0 | `NO_MASKING` | Model is genuinely robust |
| 0.2 - 0.5 | `GRADIENT_MASKING_WEAK` | Minor gradient issues |
| 0.5 - 0.8 | `GRADIENT_MASKING_MODERATE` | Significant masking detected |
| 0.8 - 1.0 | `GRADIENT_MASKING_HARD` | Severe masking — model is vulnerable |

### Example Output

```
YGMD Results:
  Masking Index: 0.847
  Verdict: GRADIENT_MASKING_HARD
  White-box confidence drop: 2.3%
  Black-box confidence drop: 15.1%
  ⚠️ Model shows false robustness — vulnerable to black-box attacks
```

---

## Output & Certification

### Preview Mode (Free)

```
============================================================
  RednBlue Security Preview — YOLO Detection
============================================================

  Attacks run    : 8
  Successful hits: 3/8 (37%)
  Robustness rate: 63%
  Estimated Grade: SILVER

  ⚠️  This is a preview only
  → Visit: https://rednblue.io/checkout
  → Re-run with: rnb preview --model-type yolo --submit
```

### Certified Mode (With Token)

When you use `--submit`, results are:

1. Encrypted with AES-256-CBC
2. Signed with HMAC-SHA256
3. Submitted to RednBlue's zero-knowledge backend
4. Processed to generate a PDF certificate

```
📤 Submitting results to server...
   ✓ Session created (ID: abc123)

✅ Results submitted successfully!
   Session ID: abc123
   Status: processing

📋 View results at: https://dashboard.rednblue.io/dashboard/tests
   Certificate will be ready in ~1 minute
```

---

## Grading System

| Grade | Pass Rate | Meaning |
|-------|-----------|---------|
| 🥇 **GOLD** | ≥ 90% | Excellent adversarial robustness |
| 🥈 **SILVER** | ≥ 75% | Good robustness with minor vulnerabilities |
| 🥉 **BRONZE** | ≥ 50% | Moderate vulnerabilities detected |
| ❌ **FAIL** | < 50% | Significant vulnerabilities — model at risk |

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `RNB_TOKEN` | Your RednBlue session token (required for `--submit`) |
| `REDNBLUE_API_URL` | Custom API endpoint (default: `https://api.rednblue.io`) |

---

## Supported Model Formats

| Format | Extension | Notes |
|--------|-----------|-------|
| PyTorch (full model) | `.pt`, `.pth` | Saved with `torch.save(model, path)` |
| PyTorch (state_dict) | `.pt`, `.pth` | Auto-detects ResNet/VGG architecture |
| ONNX | `.onnx` | Requires `onnx` and `onnx2torch` packages |
| Ultralytics YOLO | `.pt` | YOLOv5, v8, v10, v11 supported |

---

## Examples

### Full Classifier Workflow

```bash
# 1. Set your token
export RNB_TOKEN=RB-ABC123-XYZ789

# 2. Prepare test images
ls ./images/
# cat.jpg  dog.jpg  car.jpg  ...

# 3. Run certified test
rnb preview --model resnet18.pth --input ./images --submit

# 4. Check dashboard for certificate
# https://dashboard.rednblue.io/dashboard/tests
```

### Full YOLO Workflow

```bash
# 1. Set your token
export RNB_TOKEN=RB-ABC123-XYZ789

# 2. Prepare COCO-style images
ls ./images/
# coco_000000001.jpg  coco_000000002.jpg  ...

# 3. Run certified test
rnb preview --model-type yolo --model yolov8n.pt --input ./images --submit

# 4. Check dashboard for certificate
# https://dashboard.rednblue.io/dashboard/tests
```

---

## Troubleshooting

### "Model file not found"
Ensure the path to your model is correct and the file exists.

### "Unknown architecture in state_dict"
Your model's architecture couldn't be auto-detected. Save the full model instead:
```python
torch.save(model, 'model.pt')  # Instead of torch.save(model.state_dict(), ...)
```

### "ONNX support requires..."
Install ONNX dependencies:
```bash
pip install onnx onnx2torch
```

### "RNB_TOKEN environment variable not set"
Set your token before using `--submit`:
```bash
# Linux/Mac
export RNB_TOKEN=RB-XXXXXX-YYYYYY

# Windows CMD
set RNB_TOKEN=RB-XXXXXX-YYYYYY

# Windows PowerShell
$env:RNB_TOKEN="RB-XXXXXX-YYYYYY"
```

### Gradient masking detected but attacks still fail
This is expected! Gradient masking means white-box attacks fail, but black-box attacks (YNES, YSQA) should succeed. Check the YGMD diagnostic for details.

---

## Citation

If you use RednBlue in academic research, please cite:

```bibtex
@software{rednblue2026,
  title = {RednBlue: Adversarial Security Testing for AI Models},
  author = {Deramgozin, Mahdi and Samizadeh, Saeid},
  year = {2026},
  version = {2.2.0},
  url = {https://rednblue.io}
}
```

---

## License

Proprietary — © 2026 R&B AI Security Solutions

---

## Links

- **Website:** https://rednblue.io
- **Dashboard:** https://dashboard.rednblue.io
- **Documentation:** https://docs.rednblue.io
- **Support:** support@rednblue.io


