# mariomc14/devsecops-adversary-llm architecture

> Architecture diagram of the GitHub repository mariomc14/devsecops-adversary-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mariomc14/devsecops-adversary-llm
- Repository: https://github.com/mariomc14/devsecops-adversary-llm

## Overview

##### Project Type and Purpose
- This is a research‐oriented security tool combining:
- An “Attack Tree Generation” framework that uses LLMs (QwQ-32B, GPT-4) to produce .DOT attack trees from structured prompts.
- An “SCE Experiment” suite that automates a DevSecOps security scenario in AWS, validating an attacker’s ability to misuse permissions via a CI/CD pipeline (ChaosXploit framework).
- It is not a classic full‐stack app but a hybrid open‐source research toolkit with two main subsystems:
1. LLM-driven attack tree generation (local Python scripts + prompts + artifacts)
2. AWS CI/CD experiment orchestration (automation scripts, knowledge database, AWS topology)

##### File Structure Analysis
A. Attack_Tree_Generation/
- Prompts.txt, AttackProcedures.pdf, Flow_Diagram.png
- Output PDFs (gpt4.pdf, qwq.pdf)
→ Core component: prompt design → LLM invocation → .DOT attack-tree artifacts
B. SCE_Experiment/
- KnowledgeDB/AttackTrees/*.dot → stored attack tree definitions
- Runner/
- actions/actions.py (defines exploit steps)
- probes/probes.py (verifies system state)
- run.sh + SCE_Experiment.json (experiment entrypoint & config)
- requirements.txt
→ Core component: orchestration script → virtualenv + dependency install → run experiment against AWS topology

##### README Insights
- The AWS topology: IAM, CodeCommit/GitHub, CodePipeline, CodeBuild, CodeDeploy, S3, CloudFormation, EC2 Spot Instances, RDS, GuardDuty, CloudWatch, (optional CDN/WAF/API Gateway/NLB)
- Quick‐start guidance for the Runner
- Security scenario details (misconfigured IAM, Spot instance abuse)

1. Attack Tree Generation Module
- Prompts Manager (Prompts.txt)
- LLM Engine (QwQ-32B / GPT-4 service)
- Output Formatter (.DOT generator, cosmetic rules)
- Artifact Store (qwq.pdf, gpt4.pdf, AttackProcedures.pdf)
2. SCE Experiment Module
- KnowledgeDB (AttackTrees/*.dot)
- Experiment Runner
– actions.py (exploit steps)
– probes.py (state checks)
– run.sh & config JSON
- Virtual Environment / Dependency Installer
3. AWS CI/CD Pipeline (external services):
- Developers (IAM role)
- CodeCommit / GitHub
- CodePipeline
– CodeBuild
– CodeDeploy
- S3 (artifacts storage)
- CloudFormation (IaC)
- EC2 Spot Instances
- RDS
- GuardDuty & CloudWatch
- Optional: API Gateway, WAF, CloudFront, NLB
- Prompts Manager → LLM Engine (input prompts) → Output Formatter → Artifact Store
- Runner → virtualenv → actions.py invokes AWS CLI → AWS services (SpotInstance, IAM:PassRole)
- probes.py polls CloudWatch/GuardDuty → reports results back to Runner
- KnowledgeDB feeds .dot definitions into Runner (to compare with generated attack trees)
c. Architectural Patterns & Principles:
- Modular separation: “Generation” vs “Experiment” subsystems
- Pipeline/orchestration pattern: Runner script automates environment setup → execution → verification
- IaC pattern: CloudFormation driven by CodePipeline
- Data‐driven workflows: Prompts → LLM → .DOT → PDF artifacts; Experiment config JSON → run.sh → AWS actions & probes
d. Technologies / Frameworks:
- Python 3.12 (scripts: hypGenerator.py, actions.py, probes.py)
- Bash (run.sh)
- LLM APIs (QwQ-32B, GPT-4)
- Graphviz (.DOT format)
- AWS CLI & services
- Virtualenv / requirements.txt

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Attack Tree Generation Module
    subgraph "Attack Tree Generation Module"
        direction TB
        PromptsManager["Prompts Manager<br/>(Prompts.txt)"]:::gen
        LLMEngine["LLM Engine<br/>(QwQ-32B / GPT-4)"]:::gen
        OutputFormatter["Output Formatter<br/>(.DOT generator)"]:::gen
        ArtifactStore[(Artifact Store)]:::datastore
    end

    %% SCE Experiment Module
    subgraph "SCE Experiment Module"
        direction TB
        SCEExperimentModule["SCE Experiment Module"]:::exp
        KnowledgeDB[(KnowledgeDB)]:::datastore
        AttackTrees[(AttackTrees)]:::datastore
        HypothesisGenerator["Hypothesis Generator<br/>(hypGenerator.py)"]:::exp
        ExperimentRunner["Experiment Runner"]:::exp
        VirtualEnv["VirtualEnv & Installer<br/>(requirements.txt)"]:::exp
        ActionsComp["Actions Component<br/>(actions.py)"]:::exp
        ProbesComp["Probes Component<br/>(probes.py)"]:::exp
        RunScript["run.sh & config<br/>(SCE_Experiment.json)"]:::exp
    end

    %% AWS CI/CD Pipeline
    subgraph "AWS CI/CD Pipeline"
        direction TB
        Devs["Developers<br/>(IAM Role)"]:::aws
        CodeRepo["CodeCommit/GitHub"]:::aws
        CodePipeline["CodePipeline"]:::aws
        CodeBuild["CodeBuild"]:::aws
        CodeDeploy["CodeDeploy"]:::aws
        S3Bucket[(S3 Storage)]:::datastore
        CloudFormation["CloudFormation"]:::aws
        EC2Spot["EC2 Spot Instances"]:::aws
        RDS["RDS"]:::aws
        GuardDuty["GuardDuty"]:::aws
        CloudWatch["CloudWatch"]:::aws
        OptionalServices["Optional: API Gateway<br/>WAF, CloudFront, NLB"]:::aws
    end

    %% Flows Attack Tree Generation
    PromptsManager -->|"provides prompts"| LLMEngine
    LLMEngine -->|"generates .DOT"| OutputFormatter
    OutputFormatter -->|"creates artifacts"| ArtifactStore

    %% Flows Experiment Module
    KnowledgeDB -->|"reads .dot definitions"| ExperimentRunner
    AttackTrees -->|"reads specific trees"| ExperimentRunner
    HypothesisGenerator -->|"generates hypotheses"| KnowledgeDB
    ExperimentRunner --> VirtualEnv
    VirtualEnv --> RunScript
    RunScript --> ActionsComp
    RunScript --> ProbesComp
    ActionsComp -->|"invokes AWS CLI"| CodePipeline
    ProbesComp -->|"polls metrics"| CloudWatch
    ProbesComp -- "polls findings" --> GuardDuty
    ActionsComp --> EC2Spot
    ActionsComp -->|"uses IAM:PassRole"| Devs

    %% Integration with AWS pipeline
    Devs --> CodeRepo
    CodeRepo --> CodePipeline
    CodePipeline --> CodeBuild
    CodeBuild --> CodeDeploy
    CodeDeploy --> S3Bucket
    CodePipeline --> CloudFormation
    CodePipeline --> EC2Spot
    CodePipeline --> RDS
    CodePipeline --> GuardDuty
    CodePipeline --> CloudWatch
    CodePipeline --> OptionalServices

    %% Click Events
    click PromptsManager "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/Attack_Tree_Generation/Prompts.txt"
    click ArtifactStore "https://github.com/mariomc14/devsecops-adversary-llm/tree/main/Attack_Tree_Generation/"
    click SCEExperimentModule "https://github.com/mariomc14/devsecops-adversary-llm/tree/main/SCE_Experiment/"
    click KnowledgeDB "https://github.com/mariomc14/devsecops-adversary-llm/tree/main/SCE_Experiment/KnowledgeDB/"
    click AttackTrees "https://github.com/mariomc14/devsecops-adversary-llm/tree/main/SCE_Experiment/KnowledgeDB/AttackTrees/"
    click HypothesisGenerator "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/SCE_Experiment/KnowledgeDB/hypGenerator.py"
    click ExperimentRunner "https://github.com/mariomc14/devsecops-adversary-llm/tree/main/SCE_Experiment/Runner/"
    click RunScript "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/SCE_Experiment/Runner/run.sh"
    click RunScript "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/SCE_Experiment/Runner/SCE_Experiment.json"
    click ActionsComp "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/SCE_Experiment/Runner/actions/actions.py"
    click ProbesComp "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/SCE_Experiment/Runner/probes/probes.py"
    click VirtualEnv "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/SCE_Experiment/requirements.txt"
    click README "https://github.com/mariomc14/devsecops-adversary-llm/blob/main/README.md"

    %% Styles
    classDef gen fill:#cce5ff,stroke:#004085,color:#004085
    classDef exp fill:#d4edda,stroke:#155724,color:#155724
    classDef aws fill:#fff3cd,stroke:#856404,color:#856404
    classDef datastore fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    class PromptsManager,LLMEngine,OutputFormatter,ArtifactStore gen
    class SCEExperimentModule,HypothesisGenerator,ExperimentRunner,VirtualEnv,ActionsComp,ProbesComp,RunScript exp
    class Devs,CodeRepo,CodePipeline,CodeBuild,CodeDeploy,CloudFormation,EC2Spot,RDS,GuardDuty,CloudWatch,OptionalServices aws
    class KnowledgeDB,AttackTrees,S3Bucket datastore
```
