# ruvnet/agentic-security architecture

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

- Interactive diagram: https://gitdiagram.com/ruvnet/agentic-security
- Repository: https://github.com/ruvnet/agentic-security

## Overview

##### Main Components
- User Interface Layer:
– Command Line Interface (CLI): Represented by the commands (scan, analyze, run, validate) shown in the README.
– Graphical User Interface (GUI): Located in the “gui” folder; note its cyberpunk aesthetic.
- Core Security Pipeline (Backend Engine):
– This is implemented within the "src/agentic_security" directory. Components include:
▪ Scanning and Security Modules (e.g., security_pipeline.py, security_cli.py, prompts.py).
▪ Fix & Remediation Logic (modules like fix_cycle.py, progress.py).
▪ Caching (cache.py).
- External Security & AI Integrations:
– Vulnerability Scanners (OWASP ZAP, Nuclei, Dependency-Check).
– AI Engines (GPT-4 and Claude-3 integrations for analysis, fix suggestions and test generation).
– GitHub Integration for auto branch creation and PR generation (see modules in gui: git_handler.py, github_handler.py).
– Notification Services (Slack, via provided API keys).
- Supporting Components and Artifacts:
– Docker and Docker Compose configurations (Dockerfile, docker-compose.yml) denote containerization.
– CI/CD pipelines (present under .github/workflows and scripts like run_pipeline.sh) to automate scanning and deployment.
– Testing Suite (tests folder, along with sample files) which portrays how the system is validated.

##### Relationships and Data Flow
- The Pipeline directs a scan that interfaces with external scanners (OWASP ZAP, Nuclei, dependency analysis tools).
- Results from scanning feed into AI modules for vulnerability assessment and remediation suggestions.
- The AI components analyze code, generate fixes and validate changes (iterative, recursive fix logic).
- A Git integration module then creates fix branches and triggers pull requests.
- Notification flows (directed towards Slack or similar channels) inform administrators.
- CI/CD components (GitHub Actions workflows and shell scripts) continuously trigger, update, and deploy the changes.

##### Architectural Patterns and Key Technologies
- Modular “pipeline” architecture: separate modules (scanning, analysis, remediation, and reporting) are coordinated by the core engine.
- Integration of AI-driven components: these interact with external APIs (OpenAI, Anthropic).
- Containers for deployment: Dockerfile and docker-compose.yml illustrate deployment boundaries.
- CI/CD integration: Automated workflow nodes (GitHub workflows) reside outside the main codebase but interact closely.
- Testing and validation: The tests directory signals an emphasis on end-to-end and security-based testing.

##### Elements
- User Interfaces: "CLI Interface", "Cyberpunk GUI".
- Core Engine Components: "Security Pipeline", "AI Analysis Module", "Remediation Engine", "Cache Service".
- External Services: "OWASP ZAP", "Nuclei", "OpenAI/Anthropic AI", "GitHub Integration", "Slack Notifications".
- CI/CD and Deployment: "Docker Environment", "GitHub Actions / CI Pipeline".
- Data/instruction flow from interfaces to processing modules.
- Dependency lines from core modules to external scanners and AI services.
- Iteration or feedback:
- Recursive or iterative fix logic that loops back into the analysis cycle.
- Insert colorful annotations or legends to differentiate between internal components, external services, and infrastructure/deployment elements.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI("CLI Interface"):::ui
        GUI("Cyberpunk GUI"):::ui
    end

    %% Core Security Pipeline
    subgraph "Core Security Pipeline"
        SP("Security Pipeline"):::core
        SM("Scanning Module"):::core
        AA("AI Analysis Module"):::core
        FR("Fix & Remediation Engine"):::core
        CS("Cache Service"):::core
    end

    %% External Integrations
    subgraph "External Integrations"
        OW("OWASP ZAP"):::external
        NU("Nuclei"):::external
        DC("Dependency-Check"):::external
        GH1("Git Handler"):::external
        GH2("GitHub Handler"):::external
        SL("Slack Notifications"):::external
        AI("OpenAI/Anthropic AI"):::external
    end

    %% Deployment & Testing
    subgraph "Deployment & Testing"
        subgraph "CI/CD & Deployment"
            CICD("CI/CD Pipeline"):::deployment
            RPS("Pipeline Script"):::deployment
            DF("Dockerfile"):::deployment
            DCY("Docker Compose"):::deployment
        end
        TS("Testing Suite"):::testing
    end

    %% Data Flow Connections
    CLI --> SP
    GUI --> SP

    SP --> SM
    SM --> OW
    SM --> NU
    SM --> DC

    OW --> AA
    NU --> AA
    DC --> AA

    AA --> AI
    AI --> FR

    FR -->|"iterative"| SP

    SP --> CS

    SP --> GH1
    SP --> GH2

    GH1 --> SL
    GH2 --> SL

    %% Deployment & Testing integration
    CICD --> SP
    RPS --> SP
    DF --> SP
    DCY --> SP
    TS --> SP

    %% Click Events
    click CLI "https://github.com/ruvnet/agentic-security/blob/main/src/agentic_security/security_cli.py"
    click GUI "https://github.com/ruvnet/agentic-security/blob/main/gui/app.py"
    click SP "https://github.com/ruvnet/agentic-security/blob/main/src/agentic_security/security_pipeline.py"
    click SM "https://github.com/ruvnet/agentic-security/blob/main/src/agentic_security/prompts.py"
    click FR "https://github.com/ruvnet/agentic-security/blob/main/src/agentic_security/fix_cycle.py"
    click CS "https://github.com/ruvnet/agentic-security/blob/main/src/agentic_security/cache.py"
    click GH1 "https://github.com/ruvnet/agentic-security/blob/main/gui/git_handler.py"
    click GH2 "https://github.com/ruvnet/agentic-security/blob/main/gui/github_handler.py"
    click CICD "https://github.com/ruvnet/agentic-security/blob/main/.github/workflows/security_pipeline.yml"
    click RPS "https://github.com/ruvnet/agentic-security/blob/main/run_pipeline.sh"
    click DF "https://github.com/ruvnet/agentic-security/tree/main/Dockerfile"
    click DCY "https://github.com/ruvnet/agentic-security/blob/main/docker-compose.yml"
    click TS "https://github.com/ruvnet/agentic-security/tree/main/tests"

    %% Styles
    classDef ui fill:#a8dadc,stroke:#1d3557,stroke-width:2px;
    classDef core fill:#f4a261,stroke:#e76f51,stroke-width:2px;
    classDef external fill:#e9c46a,stroke:#f4a261,stroke-width:2px;
    classDef deployment fill:#2a9d8f,stroke:#264653,stroke-width:2px;
    classDef testing fill:#e76f51,stroke:#264653,stroke-width:2px;
```
