# awslabs/automated-security-helper architecture

> Architecture diagram of the GitHub repository awslabs/automated-security-helper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awslabs/automated-security-helper
- Repository: https://github.com/awslabs/automated-security-helper

## Overview

##### Project type and purpose
- ASH is an open-source, Python-based CLI security scanning framework with a pluggable architecture and an optional AI-integration MCP server.
- It orchestrates multiple “scanner” tools (Bandit, Checkov, Semgrep, etc.) in isolated UV environments, applies optional conversion or inspection phases, aggregates results, and emits reports in many formats (SARIF, JSON, HTML, Markdown, CSV).

##### File structure to extract the main architectural components
- **CLI**      : `automated_security_helper/cli` (entrypoints: `ash`, `ash-multi`, shell scripts under `ash/` and support in `utils/ash_helpers.*`)
- **Core engine** : `automated_security_helper/core` (orchestrator, execution engine, phases pipeline: convert, scan, inspect, report)
- **Plugin system** :
- Plugin base classes: `automated_security_helper/base`
- Plugin manager / loader: `automated_security_helper/plugins`
- Built-in plugins: `plugin_modules/ash_builtin` (converters, scanners, reporters, event handlers) and `plugin_modules/ash_aws_plugins`
- **Resource management** : `core/resource_management` (task manager, scan registry/tracking, shutdown manager, state manager)
- **Models & schemas** : `automated_security_helper/models` (ASharpModel, ScanResultsContainer, vulnerability models) and `automated_security_helper/schemas` (JSON schema definitions)
- **Configuration** : `automated_security_helper/config` + `.ash/.yaml` config files + CLI flags
- **Interactions** : `automated_security_helper/interactions` (container runner, MCP server entrypoint)
- **Utilities** : `utils/` and `automated_security_helper/utils`
- **Documentation & examples** : `docs/`, `examples/`
- **Tests & CI** : `tests/`, `.github/workflows/`, `Dockerfile`, `mkdocs.yml`

##### Readme insights
- Emphasizes phases (scan, inspect, report), multiple modes (local, container, precommit), UV tool isolation, pluggability, and AI integration via MCP.
- Highlights built-in scanners, reporting formats, and configuration override mechanisms.

##### Main components and their interactions
a. **User Interfaces**
- Shell script (`ash` / `ash-multi`) or `uvx ... ash` CLI entrypoint
- CLI module parses arguments and loads configuration.
b. **Orchestrator / Execution Engine**
- Coordinates pipeline phases:
1. Convert phase (normalize inputs)
2. Scan phase (invoke scanner plugins)
3. Inspect phase (post-processing of findings)
4. Report phase (emit structured outputs)
- Uses `PluginManager` to discover and schedule plugins.
c. **Plugin System**
- **Scanners**: execute external tools (via UV or system installation), fetch raw results (SARIF, JSON), then convert to internal models.
- **Converters**: e.g., archive or Jupyter converters to unwrap inputs.
- **Reporters**: flatten aggregated results into various formats.
- **Event Handlers**: listen to lifecycle events (scan start, scan end, suppression expiration).
- **Plugin Base / Interfaces**: ensure consistent plugin lifecycle and configuration.
d. **Resource Management**
- Manages concurrent scans, tracks progress, handles shutdowns, retries, error handling.
e. **Models & Metrics**
- Internal data classes represent findings, metrics, unified output.
- Validation system ensures scanner registration → enablement → execution → result collection.
f. **Interactions & MCP Server**
- MCP server module exposes engine via a streaming, concurrent-scan API for AI integrations (Amazon Q, Claude Desktop, VSCode).
- Tools: `scan_directory`, `scan_directory_with_progress`, `get_scan_progress`, etc.
g. **Configuration Loader**
- Loads `.ash/ash.yaml` or CLI parameters into typed configuration objects (JSON Schema validated).
h. **Output**
- Write aggregated JSON to `.ash/ash_output/ash_aggregated_results.json`
- Subfolders for per-scanner raw data and multi-format reports under `.ash/ash_output/reports`

##### Architectural patterns & principles
- **Plugin architecture** (Inversion of Control) allowing extension of scanners, reporters, converters, and event handlers.
- **Pipeline / phased processing** for modularity and predictable data flow.
- **Resource manager** to support concurrency, progress tracking, and graceful shutdown.
- **UV tool isolation** decouples scanner dependencies from project.
- **MCP server** implements an RPC-style interface over CLI for AI-driven workflows.
- **Configuration-as-code** validated by JSON Schema, override by env vars or CLI flags.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Interface"
        direction TB
        CLI_Script["ash, ash-multi\n(entry scripts)"]:::io
        CLI_Module["automated_security_helper/cli"]:::io
        Shell_Helpers["utils/ash_helpers.sh, .ps1"]:::io
    end

    %% Configuration
    Config_Loader["Configuration Loader\n(automated_security_helper/config)"]:::config
    Env_Config[".ash/.ash.yaml, .checkov.yaml"]:::config

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        Orchestrator["orchestrator.py"]:::core
        Execution_Engine["execution_engine.py"]:::core
        subgraph "Phases"
            direction TB
            Convert_Phase["convert_phase.py"]:::core
            Scan_Phase["scan_phase.py"]:::core
            Inspect_Phase["inspect_phase.py"]:::core
            Report_Phase["report_phase.py"]:::core
        end
    end

    %% Plugin System
    subgraph "Plugin System"
        direction TB
        Plugin_Base["automated_security_helper/base"]:::plugin
        Plugin_Manager["automated_security_helper/plugins"]:::plugin
        Builtin_Plugins["plugin_modules/ash_builtin"]:::plugin
        AWS_Plugins["plugin_modules/ash_aws_plugins"]:::plugin
    end

    %% Resource Management
    Resource_Mgmt["resource_management\n(core/resource_management)"]:::core

    %% Models & Schemas
    Models["automated_security_helper/models"]:::model
    Schemas["automated_security_helper/schemas"]:::model

    %% Interactions & MCP
    Interactions["interactions\n(run_ash_scan, run_ash_container)"]:::io
    MCP_Server["mcp.py, mcp_server.py, mcp_tools.py"]:::io

    %% Utilities
    Utilities["utils & utilities"]:::utility

    %% Output
    Output["Report Output\n(.ash/ash_output/*)"]:::io

    %% Documentation & Examples
    Docs["docs/"]:::io
    Examples["examples/"]:::io

    %% Tests & CI
    TestsCI["tests/, .github/workflows/, Dockerfile, mkdocs.yml"]:::io

    %% Connections
    CLI_Script -->|invokes| CLI_Module
    CLI_Module -->|loads| Config_Loader
    Env_Config -->|overrides| Config_Loader
    CLI_Module -->|starts| Orchestrator
    Config_Loader -->|provides| Orchestrator

    Orchestrator --> Execution_Engine
    Execution_Engine --> Convert_Phase
    Convert_Phase --> Scan_Phase
    Scan_Phase --> Inspect_Phase
    Inspect_Phase --> Report_Phase
    Report_Phase --> Output

    %% Plugins
    Execution_Engine -->|uses| Plugin_Manager
    Plugin_Manager --> Plugin_Base
    Plugin_Manager --> Builtin_Plugins
    Plugin_Manager --> AWS_Plugins
    Scan_Phase -->|executes| Builtin_Plugins
    Scan_Phase -->|executes| AWS_Plugins

    %% Resource Manager
    Resource_Mgmt -->|manages| Scan_Phase
    Resource_Mgmt -->|tracks| Orchestrator

    %% Models & Schemas
    Convert_Phase --> Models
    Scan_Phase --> Models
    Inspect_Phase --> Models
    Report_Phase --> Schemas

    %% Interactions & MCP
    MCP_Server --> Interactions
    Interactions -->|calls| Orchestrator

    %% Utilities
    Plugin_Manager --> Utilities
    Execution_Engine --> Utilities
    Interactions --> Utilities

    %% Docs & Examples & Tests
    Examples -->|illustrate| CLI_Module
    Docs -->|documents| Config_Loader
    TestsCI -->|tests| Execution_Engine

    %% Click Events
    click CLI_Module "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/cli/"
    click CLI_Script "https://github.com/awslabs/automated-security-helper/tree/main/./ash"
    click CLI_Script "https://github.com/awslabs/automated-security-helper/tree/main/./ash-multi"
    click Shell_Helpers "https://github.com/awslabs/automated-security-helper/blob/main/utils/ash_helpers.sh"
    click Shell_Helpers "https://github.com/awslabs/automated-security-helper/blob/main/utils/ash_helpers.ps1"
    click Config_Loader "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/config/"
    click Env_Config "https://github.com/awslabs/automated-security-helper/blob/main/.ash/.ash.yaml"
    click Orchestrator "https://github.com/awslabs/automated-security-helper/blob/main/automated_security_helper/core/orchestrator.py"
    click Execution_Engine "https://github.com/awslabs/automated-security-helper/blob/main/automated_security_helper/core/execution_engine.py"
    click Convert_Phase "https://github.com/awslabs/automated-security-helper/blob/main/automated_security_helper/core/phases/convert_phase.py"
    click Scan_Phase "https://github.com/awslabs/automated-security-helper/blob/main/automated_security_helper/core/phases/scan_phase.py"
    click Inspect_Phase "https://github.com/awslabs/automated-security-helper/blob/main/automated_security_helper/core/phases/inspect_phase.py"
    click Report_Phase "https://github.com/awslabs/automated-security-helper/blob/main/automated_security_helper/core/phases/report_phase.py"
    click Plugin_Base "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/base/"
    click Plugin_Manager "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/plugins/"
    click Builtin_Plugins "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/plugin_modules/ash_builtin/"
    click AWS_Plugins "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/plugin_modules/ash_aws_plugins/"
    click Resource_Mgmt "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/core/resource_management/"
    click Models "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/models/"
    click Schemas "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/schemas/"
    click Interactions "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/interactions/"
    click MCP_Server "https://github.com/awslabs/automated-security-helper/blob/main/automated_security_helper/cli/mcp_server.py"
    click Utilities "https://github.com/awslabs/automated-security-helper/tree/main/automated_security_helper/utils/"
    click Docs "https://github.com/awslabs/automated-security-helper/tree/main/docs/"
    click Examples "https://github.com/awslabs/automated-security-helper/tree/main/examples/"
    click TestsCI "https://github.com/awslabs/automated-security-helper/tree/main/tests/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef plugin fill:#d4edda,stroke:#155724,color:#155724;
    classDef io fill:#fff3cd,stroke:#856404,color:#856404;
    classDef model fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef config fill:#f0f0f0,stroke:#999999,color:#333333;
    classDef utility fill:#f5e1da,stroke:#a65d5d,color:#a65d5d;
```
