# securityftw/cs-suite architecture

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

- Interactive diagram: https://gitdiagram.com/securityftw/cs-suite
- Repository: https://github.com/securityftw/cs-suite

## Overview

##### Project Overview and Main Purpose
- The cs-suite is a command-line auditing tool targeting cloud security assessments on AWS, GCP, Azure, and DigitalOcean.
- It integrates external security tools such as Scout2, G-Scout, Lynis, and Prowler to perform audits and generate security reports.
- It is designed to be modular, where the main script dispatches to various modules and scripts based on the chosen cloud provider environment.

##### Primary Components
a. Command-Line Interface (CLI):
- Component: cs.py
- Purpose: Acts as the main entry point, reading command-line arguments (cloud environment, audit IP, credentials, etc.) and orchestrating the audit process.
b. Audit Modules:
- Component: The "modules" directory (containing awsaudit.py, azureaudit.py, gcpaudit.py, doaudit.py, etc.)
- Purpose: Each module handles the logic specific to its cloud provider. They encapsulate audit rules, report merging, logging (logger.py), and report retention.
c. Helper/Shell Scripts:
- Component: The "scripts" directory
- Purpose: Contains various shell scripts geared toward AWS (and possibly others), providing specific audit functions and possibly environment setup tasks.
d. External Tools and Integrations:
- Component: The "tools" directory, which includes:
- G-Scout – for Google Cloud audits.
- Scout2 – for AWS audits and report generation.
- Lynis – for host-based (OS) auditing.
- Additional utilities like prowler and a template tool.
- Purpose: These are integrated external utilities that the main audit modules may invoke to perform detailed security checks.
e. Docker and Deployment:
- Component: Dockerfile and associated configuration files (e.g., _config.yml)
- Purpose: Provides containerization support to run the tool in a Docker environment, including mounting external configuration and report directories.
f. Reporting:
- That although the “reports” directory isn’t visible in the file tree, the README emphasizes that final audit reports are written there in JSON/HTML format.
- Purpose: Storing the consolidated output from the various audits.

##### Relationships and Interactions
- cs.py (CLI Entry) -> Reads command-line arguments and determines the targeted cloud environment.
- cs.py -> Dispatches control to the appropriate audit module (e.g., modules/awsaudit.py for AWS).
- Audit Modules -> May in turn execute helper scripts (found in the "scripts" directory) or call functionalities within the external tools (located under "tools").
- External Tools -> Operate as independent executables or libraries that feed back their analysis through file outputs and logs.
- Dockerfile -> Encapsulates the entire environment; volumes are mounted for configuration (AWS credentials, etc.) and report output.
- All Components -> Ultimately contribute to generating a final consolidated audit report (placed in “reports”) meant for SIEM integration or direct user review.

##### Architectural Patterns and Design Principles
- Modularity: Clear separation between the CLI (cs.py), audit modules, helper scripts, and external tool integrations.
- Extensibility: Different cloud providers are supported by distinct modules and scripts; the design allows easy addition of new provider-specific audit logic.
- Integration Layer: The “tools” directory shows how existing open-source auditing projects are integrated, acting as a bridge rather than reinventing functionalities.
- Containerization: The Dockerfile indicates deployment via containers, which isolates dependencies and configurations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Environment and Entry Point
    dockerEnv["Docker Deployment"]:::docker
    csCLI["cs.py (CLI)"]:::cli
    dockerEnv -->|"runs"| csCLI

    %% Audit Modules Subgraph
    subgraph "Audit Modules"
        aws["awsaudit.py"]:::module
        azure["azureaudit.py"]:::module
        gcp["gcpaudit.py"]:::module
        doa["doaudit.py"]:::module
        local["localaudit.py"]:::module
        logger["logger.py"]:::module
        merger["merger.py"]:::module
        retain["retainnumberofreports.py"]:::module
    end

    %% Helper Scripts Subgraph
    subgraph "Helper Scripts"
        helpers["scripts/"]:::scripts
    end

    %% External Tools Subgraph
    subgraph "External Tools"
        gscout["G-Scout"]:::external
        scout2["Scout2"]:::external
        lynis["Lynis"]:::external
        prowler["Prowler"]:::external
    end

    %% Reports Node
    reports["Reports (JSON/HTML)"]:::report

    %% Connections from CLI to Audit Modules
    csCLI -->|"dispatch_audit"| aws
    csCLI -->|"dispatch_audit"| azure
    csCLI -->|"dispatch_audit"| gcp
    csCLI -->|"dispatch_audit"| doa
    csCLI -->|"dispatch_audit"| local

    %% Audit Modules invoking Helper Scripts
    aws -->|"invoke_scripts"| helpers
    azure -->|"invoke_scripts"| helpers
    gcp -->|"invoke_scripts"| helpers
    doa -->|"invoke_scripts"| helpers
    local -->|"invoke_scripts"| helpers

    %% Audit Modules calling External Tools
    aws -->|"call_tool"| scout2
    azure -->|"call_tool"| gscout
    gcp -->|"call_tool"| gscout
    local -->|"call_tool"| lynis
    aws -->|"call_external"| prowler

    %% External Tools feeding back results to Audit Merging and Logging
    scout2 -->|"generate_report"| merger
    gscout -->|"generate_report"| merger
    lynis  -->|"generate_report"| merger
    prowler -->|"generate_report"| merger
    merger -->|"merge_logs"| reports
    logger -->|"log_audit"| reports
    retain -->|"manage_reports"| reports

    %% Docker Deployment includes configuration file
    _config["_config.yml"]:::docker
    dockerEnv --> _config

    %% Click Events
    click csCLI "https://github.com/securityftw/cs-suite/blob/master/cs.py"
    click aws "https://github.com/securityftw/cs-suite/blob/master/modules/awsaudit.py"
    click azure "https://github.com/securityftw/cs-suite/blob/master/modules/azureaudit.py"
    click gcp "https://github.com/securityftw/cs-suite/blob/master/modules/gcpaudit.py"
    click doa "https://github.com/securityftw/cs-suite/blob/master/modules/doaudit.py"
    click local "https://github.com/securityftw/cs-suite/blob/master/modules/localaudit.py"
    click logger "https://github.com/securityftw/cs-suite/blob/master/modules/logger.py"
    click merger "https://github.com/securityftw/cs-suite/blob/master/modules/merger.py"
    click retain "https://github.com/securityftw/cs-suite/blob/master/modules/retainnumberofreports.py"
    click helpers "https://github.com/securityftw/cs-suite/tree/master/scripts/"
    click gscout "https://github.com/securityftw/cs-suite/tree/master/tools/G-Scout/"
    click scout2 "https://github.com/securityftw/cs-suite/tree/master/tools/Scout2/"
    click lynis "https://github.com/securityftw/cs-suite/tree/master/tools/lynis/"
    click prowler "https://github.com/securityftw/cs-suite/tree/master/tools/prowler/"
    click dockerEnv "https://github.com/securityftw/cs-suite/tree/master/Dockerfile"
    click _config "https://github.com/securityftw/cs-suite/blob/master/_config.yml"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef module fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef scripts fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef external fill:#C1FFC1,stroke:#333,stroke-width:2px;
    classDef docker fill:#FFDAB9,stroke:#333,stroke-width:2px;
    classDef report fill:#FFFFCC,stroke:#333,stroke-width:2px;
```
