CloudSlash Architecture¶

Last updated: 2026-11-10: AWS is the reference plugin; every other target is a community plugin.

System Overview¶

graph TD
    subgraph "User Interface"
        CLI["cloudslash CLI"]
        TUI["TUI Dashboard<br/>(Bubbletea)"]
        WEB["Horizon Web Dashboard<br/>(app.cloudslash.dev)"]
    end

    subgraph "Core Platform"
        E["Engine<br/>(Pipeline Orchestrator)"]
        G["Universal Graph<br/>(Gonum + RWMutex)"]
    end

    subgraph "Analysis Engines"
        H["Heuristics<br/>(Waste Detection)"]
        POL["PolicyMesh<br/>(CEL Engine)"]
        s.a.u["s.a.u<br/>(Remediation)"]
        SOL["Solver<br/>(MaxFlow)"]
        ROS["Rosetta<br/>(Topology)"]
        DR["Drift Surgeon<br/>(IaC Drift)"]
        PROV["Provenance<br/>(Git Blame)"]
        TRAF["Traffic<br/>(Flow Logs)"]
        RS["Rightsize<br/>(CPU/Mem Analysis)"]
    end

    subgraph "Sources"
        AWS["AWS Plugin<br/>(bundled, MIT)"]
        EXT["Community plugins<br/>(any system)"]
        TF["Terraform<br/>(state files, built in)"]
    end

    subgraph "Output"
        RPT["Report Builder"]
        SARIF["SARIF 2.1.0"]
        JSON["JSON"]
        TBL["Table"]
        GHPR["GitHub PR"]
        GHA["GitHub Actions"]
    end

    CLI --> E
    TUI --> E
    E --> G
    E --> AWS
    E --> EXT
    E --> TF
    E --> H
    E --> POL
    E --> SOL
    E --> ROS
    E --> DR
    E --> PROV
    E --> TRAF
    E --> RS
    s.a.u --> POL
    s.a.u --> G
    E --> RPT
    RPT --> SARIF
    RPT --> JSON
    RPT --> TBL
    RPT --> GHPR
    RPT --> GHA

Package Dependency Graph¶

graph TD
    CLI["cmd/cloudslash-cli<br/>(cobra CLI)"]
    PAWS["plugins/cloudslash-plugin-aws<br/>(gRPC plugin, bundled)"]
    PEXT["third-party plugin<br/>(gRPC plugin)"]
    E["pkg/engine<br/>(Pipeline orchestrator)"]
    G["pkg/graph<br/>(Universal Graph)"]
    PLUG["pkg/engine/plugin<br/>(gRPC Plugin Manager)"]
    POL["pkg/engine/policy<br/>(CEL PolicyMesh)"]
    s.a.u["pkg/engine/sau<br/>(Remediation)"]
    SWARM["pkg/engine/swarm<br/>(AIMD executor)"]
    H["pkg/engine/heuristics<br/>(Waste detection)"]
    SOL["pkg/engine/solver<br/>(MaxFlow solver)"]
    ROS["pkg/engine/rosetta<br/>(Topology)"]
    CRN["pkg/engine/crn<br/>(Resource IDs)"]
    RPT["pkg/engine/report.go<br/>+ sarif.go"]
    TEL["pkg/telemetry<br/>(OpenTelemetry)"]
    REG["pkg/registry<br/>(Plugin marketplace)"]

    CLI --> E
    CLI --> REG
    E --> G
    E --> PLUG
    PLUG -.->|gRPC / Unix Socket| PAWS
    PLUG -.->|gRPC / Unix Socket| PEXT
    E --> POL
    E --> H
    E --> SOL
    E --> ROS
    E --> TEL
    E --> RPT
    s.a.u --> POL
    s.a.u --> SWARM
    s.a.u --> G

Core Data Flow¶

sequenceDiagram
    participant User
    participant CLI
    participant Engine
    participant Plugins as Cloud Plugins
    participant Graph
    participant Analysis as Analysis Engines
    participant Report as Report Builder

    User->>CLI: cloudslash scan
    CLI->>Engine: New(ctx, config)
    Engine->>Plugins: gRPC: Discover()
    Plugins-->>Graph: Stream nodes + edges
    Engine->>Analysis: Heuristics.Evaluate()
    Engine->>Analysis: PolicyMesh.Evaluate()
    Engine->>Analysis: Solver.Optimize()
    Engine->>Analysis: Rosetta.HydrateTopology()
    Engine->>Report: BuildReport(graph)
    Report-->>CLI: ScanReport
    CLI-->>User: Formatted output (table/json/sarif)

Scan Pipeline Stages¶

graph LR
    A["1. Discovery<br/>gRPC Plugin Stream"] --> B["2. Resolution<br/>Boundary Edges"]
    B --> C["3. Enrichment<br/>Rosetta + Heuristics"]
    C --> D["4. Evaluation<br/>PolicyMesh + Solver"]
    D --> E["5. Report<br/>BuildReport()"]
    E --> F["6. Output<br/>table/json/sarif/github-pr"]

    style A fill:#0d1117,stroke:#00ff99,color:#e6edf3
    style B fill:#0d1117,stroke:#00ff99,color:#e6edf3
    style C fill:#0d1117,stroke:#00ff99,color:#e6edf3
    style D fill:#0d1117,stroke:#00ff99,color:#e6edf3
    style E fill:#0d1117,stroke:#00ff99,color:#e6edf3
    style F fill:#0d1117,stroke:#00ff99,color:#e6edf3

Stage Details¶

Key Subsystems¶

Universal Graph (pkg/graph)¶

Gonum-backed directed graph with concurrent-safe operations:

• Builder loop batches 5,000 ops with 50ms flush interval
• Sync() blocks until all queued operations are processed (used in tests)
• Temporal edges support s.a.u's mathematical air-gapping (SeverEdgeTemporally)
• Store interface allows swapping backends (in-memory, BadgerDB KV)
• Thread-safe via sync.RWMutex

Command surfaces (no daemon)¶

There is no background daemon. Every entry point is a thin view over the same core:

The engine lifecycle belongs to the process that runs the command. The hosted control plane obtains data through the CLI sync API or its own runner, never through a local socket.

Security layers: - requestGuard middleware enforces body size limits (1MB) on all POST/PUT - setCORSHeaders restricts to localhost origins only - WebSocket CheckOrigin restricted to localhost - API keys masked in GET /api/v1/config responses - Rate limiting on write endpoints (1 req/s, burst 10)

PolicyMesh (pkg/engine/policy)¶

CEL-based policy engine with hot-reload:

graph TD
    YAML["rules.yaml"] --> Loader["policy.Loader<br/>(file watcher)"]
    Loader --> Engine["CEL Engine<br/>(AddRules)"]
    Engine --> Eval["EvalNode(node)<br/>for each graph node"]
    Eval --> Block["action: block<br/>(prevents s.a.u)"]
    Eval --> Warn["action: warn<br/>(logs only)"]
    API["REST API<br/>/policies/*"] --> Engine

    style Engine fill:#0d1117,stroke:#f0883e,color:#e6edf3

• Rules stored as YAML in ~/.cloudslash/policies/
• Hot-reload on file change (fsnotify)
• Modes: enforcing (block) or monitoring (log only)
• Dry-run endpoint evaluates rules without side effects

s.a.u (pkg/engine/sau)¶

Autonomous remediation engine with safety guarantees:

graph LR
    A["Candidate<br/>Selection"] --> B["TOCTOU<br/>Guard"]
    B --> C["Blast Radius<br/>Check"]
    C --> D["Reversibility<br/>Verification"]
    D --> E["Policy<br/>Interception"]
    E --> F["AIMD Batch<br/>Execution"]
    F --> G["Quarantine<br/>(Air Gap)"]

    style A fill:#0d1117,stroke:#f85149,color:#e6edf3
    style G fill:#0d1117,stroke:#f85149,color:#e6edf3

1. Candidate selection — Nodes above RiskScore threshold
2. TOCTOU guard — Re-verifies node exists before action (prevents race conditions)
3. Blast radius — Counts downstream dependencies; aborts if too many
4. Reversibility — Formal verification that action can be undone
5. Policy interception — CEL PolicyMesh blocks/allows
6. Execution — AIMD-controlled batch execution via Swarm engine
7. Quarantine — Mathematical air-gap via temporal edge severing

Report Builder (pkg/engine/report.go, sarif.go)¶

Single-source-of-truth report generator:

SARIF mapping: - Finding → SARIF result - Cloud resource → SARIF logicalLocation - Severity → SARIF level (error/warning/note) - 4 rules: cloudslash/waste, cloudslash/policy, cloudslash/security, cloudslash/cost

Source Coverage¶

Reference plugin (AWS)¶

16 scanners: EC2 instances/volumes/snapshots/AMIs, S3, RDS, EKS, ECS, ElastiCache, Redshift, DynamoDB, Lambda, ALB, NAT, EIPs, and VPC endpoints, plus cost and carbon enrichment.

Every other system is a plugin in its own repository. Plugins extend visibility only: capability effects are read or compute, and mutation requests are rejected at manifest validation.

CI/CD Pipeline¶

graph LR
    PR["Pull Request"] --> T["test.yml<br/>(lint + race tests)"]
    T --> M["Merge to main"]
    M --> TAG["git tag v*"]
    TAG --> SEC["security.yml<br/>(govulncheck + gosec)"]
    TAG --> TEST2["test.yml"]
    SEC --> REL["release.yml<br/>(GoReleaser)"]
    TEST2 --> REL

Health & Observability¶

How to Write a New Heuristic¶

1. Create pkg/engine/heuristics/h_your_name.go
2. Implement the Heuristic interface:

   type YourHeuristic struct{}
   func (h *YourHeuristic) Name() string { return "your_name" }
   func (h *YourHeuristic) Evaluate(g *graph.Graph, node *graph.Node) bool { ... }
   

3. Register in pkg/engine/heuristics/registry.go
4. Add config dial to UpdateConfigPayload in api_middleware.go
5. Add test in pkg/engine/heuristics/h_your_name_test.go

How to Write a Custom Plugin (Cloud, Database, SaaS, Custom Infra)¶

Plugins in CloudSlash are domain-agnostic, standalone gRPC processes that implement the CloudSlash Plugin Protocol (sdk/proto/plugin/v2/plugin.proto).

1. Initialize a standalone Go module:

   mkdir cloudslash-plugin-myprovider && cd cloudslash-plugin-myprovider
   go mod init github.com/myorg/cloudslash-plugin-myprovider
   go get github.com/DrSkyle/cloudslash/sdk/v2@latest
   

2. Implement the v3 source interface (read-only):
3. Handshake: Return plugin name, version, and capability flags.
4. Scan: Yield resources and typed edges into the streaming channel.
5. GetMetadata: Return required IAM credentials and target regions.
6. GetPricing & GetLadders: Return SKU costs and migration ladders.
7. RenderDetail: Return custom TUI view models for deep inspection.
8. ApplyQuarantine & CheckReversibility: Handle remediation lifecycles.
9. Serve using the HashiCorp go-plugin dispatcher in main.go.
10. Create a manifest.yaml specifying name, version, protocol version 2, and capabilities.
11. Publish binary artifacts as GitHub Releases. Anyone can install your plugin via cs plugin install <owner>/<repo>.

Test Coverage¶