# coinfabrik/scout-audit architecture

> Architecture diagram of the GitHub repository coinfabrik/scout-audit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coinfabrik/scout-audit
- Repository: https://github.com/coinfabrik/scout-audit

## Overview

##### Overall Project Type and Purpose
- Scout is a command‑line and integrated security auditing tool. Its core purpose is to scan smart contract code (ink!, Soroban, Substrate pallets, and even generic Rust code) and detect common vulnerabilities as well as deviations from best practices.
- It provides multiple integration points: a Cargo-based CLI (cargo-scout-audit), a VS Code extension, and CI integration through GitHub Actions.
- The project is organized into several cargo crates, detector plugins (organized by ecosystem in separate directories under “detectors”), and documentation and test-cases.

##### Major Components to Model
A. Frontend / Integration Interfaces
- Command Line Interface (CLI) – The “cargo-scout-audit” app in the apps directory is the primary entry point.
- VS Code Extension – Found under apps/scout-extension, this component allows automatic scanning upon saving a file, providing inline feedback.
- GitHub Action Integration – Multiple files under .github/workflows that integrate Scout into CI/CD pipelines.

B. Core Analyzer and Detector Engine
- Main Audit Engine – Implemented as a library (e.g., apps/cargo-scout-audit/src/lib.rs, common analysis modules under common/analysis) that drives the static (and potentially dynamic) analysis.
- Detector Orchestrator – The module that loads and orchestrates the various detection routines. The detectors are organized per ecosystem:
⁃ ink detectors (detectors/ink and test-cases/ink)
⁃ Soroban detectors (detectors/soroban and test-cases/soroban)
⁃ Substrate detectors (detectors/substrate and test-cases/substrate-pallets)
⁃ Generic Rust detectors (detectors/rust, common/detectors)
- Plugin and Extension Infrastructure – The code structure supports extensibility and modularity so that each detector can be added or updated independently.
- Utility Libraries – Found under common/utils and scout-utils, these provide shared functionality (e.g., configuring Cargo environments, parsing output, logging, JSON utilities, etc.).

C. Reporting / Output Modules
- Multiple Output Formats – Located inside apps/cargo-scout-audit/src/output, you have submodules for console, html, markdown, pdf, JSON, and SARIF output.
- Each output module is responsible for formatting findings, rendering templates (e.g., using Tera for HTML/markdown), and integrating with external CI/CD systems.

D. Test Infrastructure
- Test Cases – A massive “test-cases” folder contains examples of both vulnerable and remediated implementations across ecosystems. This folder serves to validate detector accuracy.
- Integration Tests – Also available within the apps/cargo-scout-audit tests and scripts for running detector tests.
- CI configuration – Multiple GitHub workflow files to run tests automatically, ensuring that detectors function as expected.

##### Architectural Patterns / Design Principles
- Modularity and Extensibility – The detectors are isolated into distinct plugins (directories) so that new vulnerability types can be added without interfering with the main core.
- Separation of Concerns – There is a clear separation between the user–interface or trigger point (CLI/extension), the core analysis logic, the detector plugins, and the output/formatting layers.
- Use of Cargo Workspaces – The project is structured as multiple crates sharing common code and configurations.
- CI/CD Integration – The presence of GitHub Actions workflows means that automated testing and continuous integration pipelines are part of the system design.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Integration Interfaces"
        CLI["CLI (cargo-scout-audit)"]:::integration
        VSC["VS Code Extension"]:::integration
        GHA["GitHub Actions Integration"]:::integration
    end

    subgraph "Core System"
        CAE["Core Analyzer Engine"]:::core
        DM["Detector Manager & Plugins"]:::core
        RO["Reporting/Output Modules"]:::output
    end

    UL["Utility Libraries"]:::utility
    TI["Test Infrastructure"]:::test

    %% Relationships from Integration Interfaces to Core System
    CLI -->|"scan"| CAE
    VSC -->|"invokes"| CAE
    GHA -->|"triggers"| CAE

    %% Core processing flow
    CAE -->|"loads"| DM
    CAE -->|"formatsFindings"| RO

    %% Support relationships
    UL ---|"supports"| CAE
    UL ---|"supports"| DM

    TI ---|"validates"| CAE
    TI ---|"validates"| DM

    %% Click Events
    click CLI "https://github.com/coinfabrik/scout-audit/tree/main/apps/cargo-scout-audit/src/cli"
    click CLI "https://github.com/coinfabrik/scout-audit/blob/main/apps/cargo-scout-audit/src/main.rs"
    click VSC "https://github.com/coinfabrik/scout-audit/blob/main/apps/scout-extension/src/extension.ts"
    click GHA "https://github.com/coinfabrik/scout-audit/tree/main/.github/workflows"
    click CAE "https://github.com/coinfabrik/scout-audit/blob/main/apps/cargo-scout-audit/src/lib.rs"
    click CAE "https://github.com/coinfabrik/scout-audit/tree/main/common/analysis/src"
    click DM "https://github.com/coinfabrik/scout-audit/tree/main/apps/cargo-scout-audit/src/detectors"
    click DM "https://github.com/coinfabrik/scout-audit/tree/main/common/detectors"
    click UL "https://github.com/coinfabrik/scout-audit/blob/main/common/utils/src/lib.rs"
    click UL "https://github.com/coinfabrik/scout-audit/blob/main/scout-utils/src/lib.rs"
    click RO "https://github.com/coinfabrik/scout-audit/tree/main/apps/cargo-scout-audit/src/output"
    click TI "https://github.com/coinfabrik/scout-audit/tree/main/test-cases"
    click TI "https://github.com/coinfabrik/scout-audit/tree/main/apps/cargo-scout-audit/tests"

    %% Styles
    classDef integration fill:#CDEEFF,stroke:#333,stroke-width:2px,color:#000;
    classDef core fill:#CFFFCF,stroke:#333,stroke-width:2px,color:#000;
    classDef output fill:#FFDAB9,stroke:#333,stroke-width:2px,color:#000;
    classDef utility fill:#E6E6FA,stroke:#333,stroke-width:2px,color:#000;
    classDef test fill:#D3D3D3,stroke:#333,stroke-width:2px,color:#000;
```
