Architecture Overview

SuperClaw follows a modular architecture designed for extensibility and integration with the Superagentic AI ecosystem.

High-Level Architecture

flowchart TB
    subgraph CLI["CLI Layer"]
        A[superclaw CLI]
    end

    subgraph Core["Core Engine"]
        B[Attack Engine]
        C[Behavior Engine]
        D[Bloom Integration]
    end

    subgraph Adapters["Agent Adapters"]
        E[OpenClaw Adapter]
        F[ACP Adapter]
        G[Custom Adapters]
    end

    subgraph Integration["Integrations"]
        H[CodeOptiX]
        J[Reporting]
    end

    A --> B
    A --> C
    A --> D
    B --> E
    B --> F
    B --> G
    C --> H
    D --> H
    H --> J
    %% External integrations removed

Module Structure

superclaw/
├── attacks/          # Attack implementations
│   ├── base.py       # Attack abstract base class
│   ├── prompt_injection.py
│   ├── encoding.py
│   ├── jailbreaks.py
│   ├── tool_bypass.py
│   └── multi_turn.py
│
├── behaviors/        # Security behavior specs
│   ├── base.py       # BehaviorSpec base class
│   ├── injection_resistance.py
│   ├── tool_policy.py
│   ├── sandbox_isolation.py
│   ├── session_boundary.py
│   ├── config_drift.py
│   └── protocol_security.py
│
├── adapters/         # Agent communication
│   ├── base.py       # AgentAdapter base class
│   └── openclaw.py   # OpenClaw WebSocket adapter
│
├── bloom/            # Scenario generation
│   ├── scenarios.py  # Template-based scenarios
│   ├── ideation.py   # LLM-powered ideation
│   ├── rollout.py    # Scenario execution
│   └── judgment.py   # LLM-as-judge evaluation
│
├── codeoptix/        # CodeOptiX integration
│   ├── adapter.py    # Behavior adapter bridge
│   ├── evaluator.py  # Multi-modal evaluator
│   └── engine.py     # Evaluation engine
│
├── reporting/        # Report generation
│   ├── html.py       # Styled HTML reports
│   ├── json_report.py
│   └── sarif.py      # GitHub Code Scanning
│
├── config/           # Configuration
│   ├── settings.py   # Runtime settings
│   └── schemas.py    # Pydantic models
│
└── cli.py            # Typer CLI application

Data Flow

sequenceDiagram
    participant CLI
    participant Attack as Attack Engine
    participant Adapter as Agent Adapter
    participant Agent as Target Agent
    participant Behavior as Behavior Spec
    participant Report as Reporter

    CLI->>Attack: run_attack(target, behaviors)
    Attack->>Attack: generate_payloads()

    loop For each payload
        Attack->>Adapter: send_prompt(payload)
        Adapter->>Agent: WebSocket/ACP message
        Agent-->>Adapter: Response
        Adapter-->>Attack: AgentOutput

        Attack->>Behavior: evaluate(output)
        Behavior-->>Attack: BehaviorResult
    end

    Attack->>Report: generate_report(results)
    Report-->>CLI: HTML/JSON/SARIF

Key Classes

Attack Base

class Attack(ABC):
    attack_type: str
    description: str

    @abstractmethod
    def generate_payloads(self) -> list[str]:
        """Return the payloads to execute for this attack."""
        raise NotImplementedError

    @abstractmethod
    def evaluate_response(self, payload, response) -> AttackResult:
        """Score a response for the given payload."""
        raise NotImplementedError

BehaviorSpec Base

class BehaviorSpec(ABC):
    default_severity: Severity

    @abstractmethod
    def get_name(self) -> str:
        """Unique behavior identifier used in registries and reports."""
        raise NotImplementedError

    @abstractmethod
    def get_description(self) -> str:
        """Human-readable description of the security behavior."""
        raise NotImplementedError

    @abstractmethod
    def get_contract(self) -> BehaviorContract:
        """Structured security behavior contract."""
        raise NotImplementedError

    @abstractmethod
    def evaluate(self, agent_output, context) -> BehaviorResult:
        """Return a BehaviorResult based on the agent output."""
        raise NotImplementedError

AgentAdapter Base

class AgentAdapter(ABC):
    @abstractmethod
    async def connect(self) -> bool:
        """Establish a connection to the target agent."""
        raise NotImplementedError

    @abstractmethod
    async def disconnect(self) -> None:
        """Cleanly close the connection to the agent."""
        raise NotImplementedError

    @abstractmethod
    async def send_prompt(self, prompt, context) -> AgentOutput:
        """Send a prompt and return the agent output."""
        raise NotImplementedError

Integration Points

CodeOptiX Integration

SuperClaw behaviors can be registered with CodeOptiX for multi-modal evaluation:

from superclaw.codeoptix import register_superclaw_behaviors

# Registers as 'security-prompt-injection-resistance', etc.
register_superclaw_behaviors()

CI/CD Integration

SARIF output enables GitHub Code Scanning integration:

- name: Run SuperClaw Security Scan
  run: |
    superclaw audit openclaw --report-format sarif --output results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

Evidence Ledger

Adapters emit a normalized evidence ledger used by evaluators and reports:

• messages: prompt/response pairs
• tool_calls: tool invocations
• tool_results: tool outputs
• artifacts: files touched, URLs accessed, etc.
• secrets_detected: detected secrets/patterns

Extension Points

1. Custom Attacks - Extend Attack base class
2. Custom Behaviors - Extend BehaviorSpec base class
3. Custom Adapters - Extend AgentAdapter for new agents
4. Custom Reporters - Extend ReportGenerator base class