System Architecture

Basilisk follows a staged pipeline to orchestrate scans, analyze behaviors, and compile reports.

System Diagrams

Component Diagram

graph TD
    subgraph Core Engine
        ScannerEngine[Scanner Engine] --> SessionManager[Session Manager]
        SessionManager --> DatabaseWorker[Database Worker]
    end
    subgraph Analyzers
        ReconModules[Recon Modules]
        AttackModules[Attack Modules]
        EvolutionEngine[Evolution Engine]
    end
    subgraph Adapters
        LiteLLMAdapter[LiteLLM Adapter]
        CustomRESTClient[Custom REST Client]
    end
    ScannerEngine --> ReconModules
    ScannerEngine --> AttackModules
    ScannerEngine --> EvolutionEngine
    ReconModules --> LiteLLMAdapter
    AttackModules --> LiteLLMAdapter
    EvolutionEngine --> LiteLLMAdapter

Sequence Diagram

sequenceDiagram
    autonumber
    actor Operator
    participant Scanner as Scanner Engine
    participant Recon as Recon Modules
    participant Evolution as SPE-NL Evolution
    participant Target as LLM API
    participant DB as SQLite DB
 
    Operator->>Scanner: Start scan command
    Scanner->>DB: Initialize scan session
    Scanner->>Recon: Execute profiling probes
    Recon->>Target: Query context window & tools
    Target->>Recon: Return capability profiles
    Scanner->>Evolution: Seed initial prompt population
    loop Generation G
        Evolution->>Target: Send mutated prompts (async)
        Target->>Evolution: Return responses
        Evolution->>DB: Log conversation & fitness
    end
    Scanner->>DB: Complete scan findings
    Scanner->>Operator: Generate SARIF & HTML reports

Data Flow Diagram

graph TD
    A[CLI / YAML Config] --> B(Scanner Orchestrator)
    B --> C{Recon Runs?}
    C -->|Yes| D[Recon Module: fingerprint, context]
    C -->|No| E[Load YAML Probe Seeds]
    D --> F[Assemble BasiliskProfile]
    E --> G(SPE-NL Genetic Loop)
    F --> G
    G --> H[FFI C/Go Extensions: Tokenizer, Matcher]
    G --> I[LLM API Endpoints]
    I -->|Response text| J(Composite Fitness Evaluator)
    J -->|Score| G
    G --> K[Evidence Policy Calibration]
    K --> L[SQLite Session Store]
    L --> M[Multi-format Reports: HTML, SARIF, JSON]

---

Component Breakdowns

• basilisk/core/: Orchestrates the scan cycle, manages the SQLite WAL-mode session store, compiles findings, and evaluates the evidence policy.
• basilisk/recon/: Runs recon-only profiling to measure context windows, discover tools, and fingerprint the target model family.
• basilisk/attacks/: Contains the 33 attack modules, categorized into production, beta, and research tiers.
• basilisk/evolution/: Houses the genetic algorithm, mutation operators, crossover strategies, curiosity behavioral space, and intent tracker.
• basilisk/providers/: Provides LiteLLM-based abstractions alongside custom HTTP and WebSocket adapters.
• native/: Contains compiled C and Go shared libraries that accelerate token parsing, pattern matching, and concurrent mutations.

---

FFI Bridge Interactions

Because native C/Go libraries run with the permissions of the parent Python process, they present a potential supply-chain attack vector. To secure the FFI loading path, I implemented Ed25519 manifest verification. The native compiler generates a SHA-256 hash for each compiled library, saving it to manifest.json. The release pipeline signs this manifest using a private key, producing manifest.sig.

At runtime, the Python process loads the native shared libraries only if the manifest signature verifies against the embedded public key: e3c2fb80b9dfbb6604c3829a1075a05b4821e285e23da20f0a53407d3037187f

If a file hash mismatch is detected, the framework halts, logging a warning and falling back to pure Python implementations.

---

SQLite WAL-Mode Concurrency Thread

To handle concurrent API writes, SQLite file locking, and GUI events in the desktop app, I implemented a single-writer daemon thread model. Rather than relying on multi-process database connections, a background worker thread manages a task queue for each database path. The database operates in Write-Ahead Logging (WAL) mode with synchronous = NORMAL and a busy_timeout of 5000ms, which resolved database locking issues during high-concurrency scans.