# aidenszolosi/cyber-flowchain architecture

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

- Interactive diagram: https://gitdiagram.com/aidenszolosi/cyber-flowchain
- Repository: https://github.com/aidenszolosi/cyber-flowchain

## Overview

##### Project Type and Purpose
- This is a Python-based command-line automated penetration testing pipeline.
- Its purpose is to streamline network and host reconnaissance by integrating tools such as netstat, Nmap, and Metasploit.
- It has a modular architecture, allowing for future integration of AI-powered vulnerability reporting.

##### File Structure
- Key Files:
- main.py: Likely the main entry point that orchestrates the scanning pipeline.
- pyproject.toml: Defines project metadata, dependencies, and build settings.
- .python-version and uv.lock: Indicate environment consistency and dependency locking.
- The simple file structure (with no explicit subdirectories) suggests that the architecture is initially contained in a single module/script, but the design intends to remain modular.

##### Main Architectural Components
a. Core Application (main.py):
- Acts as the orchestrator that triggers each of the scanning modules.
b. Scanning Modules:
- netstat Module: For host enumeration and capturing active network connections.
- Nmap Module: For detailed network scanning and port enumeration.
- Metasploit Module: For identifying and possibly exploiting vulnerabilities.
- (Future) AI Integration Module: For advanced vulnerability reporting using DeepSeek R1 + Ollama.
c. Data Pipeline:
- Input: User or configuration-specified target IPs/networks.
- Execution: Sequential or parallel running of the scanning modules.
- Output: Aggregated, structured results ready for further analysis or reporting.
d. External Dependencies & Tools:
- External tools (netstat, Nmap, Metasploit) that are being invoked.
- Use labels to indicate that these external integrations are parts of the pipeline, even if they are executed as scripts or subprocesses.

##### Relationships and Interactions
- Data flow from input (user/config file or command-line arguments) to the result aggregators.
- That results collected from the scanning modules are consolidated into a structured output.
- A feedback loop or extension point that represents where future AI modules might process the aggregated data.

##### Architectural Patterns and Design Principles
- Modular, pipeline-based architecture:
- Each scanning tool (netstat, Nmap, Metasploit) is encapsulated as a distinct module/component.
- The core orchestrator (main.py) separates concerns by handling the workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input and Setup Layer
    UI("User/Configuration Input"):::input

    %% Core Pipeline Layer
    Core("Core Application (main.py)"):::orchestrator
    NS("Netstat Scanner"):::scanner
    NMAP("Nmap Scanner"):::scanner
    MS("Metasploit Scanner"):::scanner
    AGG("Aggregated Output/Report"):::output
    AI("Future AI Module"):::futureAI

    %% Project Metadata & Configuration Layer
    subgraph "Project Metadata & Configuration"
        Metadata1("pyproject.toml"):::metadata
        Metadata2(".python-version"):::metadata
        Metadata3("uv.lock"):::metadata
        Doc("README.md"):::documentation
        VC(".gitignore"):::configuration
    end

    %% Connections between Input and Core Pipeline
    UI -->|"provides"| Core

    %% Core orchestrates scanning modules
    Core -->|"triggers"| NS
    Core -->|"triggers"| NMAP
    Core -->|"triggers"| MS

    %% Scanning modules send results back to Aggregator
    NS -->|"sends_results"| AGG
    NMAP -->|"sends_results"| AGG
    MS -->|"sends_results"| AGG

    %% Optional AI processing of aggregated results
    AGG -->|"further_analysis"| AI

    %% Core Application uses configuration and metadata
    Core ---|"uses_config"| Metadata1
    Core ---|"uses_config"| Metadata2
    Core ---|"uses_config"| Metadata3
    Core ---|"refers_docs"| Doc
    Core ---|"version_control"| VC

    %% Class Definitions for Styling
    classDef orchestrator fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef scanner fill:#a8d8ea,stroke:#333,stroke-width:2px;
    classDef input fill:#ffee93,stroke:#333,stroke-width:2px;
    classDef output fill:#dcedc1,stroke:#333,stroke-width:2px;
    classDef futureAI fill:#ffb3ba,stroke:#333,stroke-width:2px;
    classDef metadata fill:#c1d7fa,stroke:#333,stroke-width:2px;
    classDef documentation fill:#fef29c,stroke:#333,stroke-width:2px;
    classDef configuration fill:#d0a9f5,stroke:#333,stroke-width:2px;

    %% Click Event Declarations
    click Core "https://github.com/aidenszolosi/cyber-flowchain/blob/main/main.py"
    click Metadata1 "https://github.com/aidenszolosi/cyber-flowchain/blob/main/pyproject.toml"
    click Metadata2 "https://github.com/aidenszolosi/cyber-flowchain/blob/main/.python-version"
    click Metadata3 "https://github.com/aidenszolosi/cyber-flowchain/blob/main/uv.lock"
    click Doc "https://github.com/aidenszolosi/cyber-flowchain/blob/main/README.md"
    click VC "https://github.com/aidenszolosi/cyber-flowchain/blob/main/.gitignore"
```
