# meta-llama/purplellama architecture

> Architecture diagram of the GitHub repository meta-llama/purplellama, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meta-llama/purplellama
- Repository: https://github.com/meta-llama/purplellama

## Overview

##### Project Type and Purpose
- This repository is a monorepo of multiple security-focused tools and libraries rather than a single end-to-end application.
- Top-level components include:
- CodeShield: a Python library/CLI for detecting insecure code patterns.
- CybersecurityBenchmarks: a benchmarking framework and website for LLM security use cases.
- Llama-Guard / Prompt-Guard: collections of model cards and policies.
- LlamaFirewall: a Python library/CLI with pluggable scanners and a documentation website.
- SensitiveDocClassification: a Python service/CLI for classifying documents in Google Drive via an LLM and SQLite.

##### File Structure
- Each tool follows a consistent structure:
- src or top-level module folder containing main library code.
- CLI entry points under `cli/` or scripts.
- Configuration or rules (e.g., YAML/JSON under `rules/` or `content_categories/`).
- Tests under `tests/`.
- Documentation websites under `website/` for CybersecurityBenchmarks and LlamaFirewall.
- Common cross-cutting elements: LLM clients/interfaces, rule engines, pattern-based analyzers, benchmark runners, Dockerfiles or workflows for CI/CD.

##### Main Components and Their Interactions
A. CodeShield Subsystem
- Core Library (`codeshield.py`, `insecure_code_detector/`)
- Rule Engine (regex / Semgrep rules under `rules/`)
- Analyzers & Issue Generators
- Example / CLI (example.py)
- Tests
- External Dependencies: GitHub / OSS APIs (for vulnerability data)
B. CybersecurityBenchmarks Subsystem
- Benchmark Core (`benchmark/benchmark_utils.py`, `run.py`)
- Autopatch Module (patch_generator, llm_interface)
- Datasets (JSON, generators)
- Infrastructure Scripts (Dockerfiles, CI scripts)
- Website (Docusaurus site under `website/`)
- External Services: LLM providers via `llm.py`
C. LlamaFirewall Subsystem
- CLI & Configuration (`cli/`, `config.py`)
- Core Firewall Engine (`llamafirewall.py`)
- Scanners (code_shield_scanner, prompt_guard_scanner, etc.)
- LLM Adapter (`utils/base_llm.py`)
- Examples & Notebooks
- Website Documentation
D. SensitiveDocClassification Subsystem
- CLI (`cli/argument_parser.py`)
- Core Classifier (`classifyit/classifier.py`)
- Google Drive Client (`google_drive_client/drive_client.py`)
- LLM Client (`llm_client/llm_client.py`)
- Local Database (SQLite via `database/database.py`)
- Content Categories (YAML config for PII detection)
- Tests

##### Architectural Patterns & Design Principles
- Modular “library + CLI + tests” structure for each tool.
- Rule-based engines for code and content scanning.
- Pluggable adapters/injectors for LLM services.
- Separation of concerns: scanning logic, configuration/rules, I/O layers (CLI, network, DB), and tests.
- Static site generation (Docusaurus) for documentation.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Monorepo"
        direction TB

        subgraph "CodeShield Subsystem"
            direction TB
            CS_CLI["CLI / Example"]:::frontend
            CS_Core["CodeShield Core Library"]:::core
            CS_Detector["Insecure Code Detector Module"]:::core
            CS_RuleConfig["Rule Engine Config"]:::datastore
            CS_Regex["Regex Rules"]:::datastore
            CS_Semgrep["Semgrep Rules"]:::datastore
            CS_Tests["Tests"]:::docs

            CS_CLI -->|runs| CS_Core
            CS_Core -->|uses| CS_Detector
            CS_Detector -->|loads| CS_RuleConfig
            CS_Detector -->|loads| CS_Regex
            CS_Detector -->|loads| CS_Semgrep
            CS_Core -->|fetches vuln data from| External_GitHub
            CS_Tests -->|validates| CS_Core
            CS_Tests -->|validates| CS_Detector
        end

        External_GitHub["GitHub / OSS API"]:::external

        subgraph "CybersecurityBenchmarks Subsystem"
            direction TB
            CB_CLI["CLI / run.py"]:::frontend
            CB_BenchCore["Benchmark Core (benchmark.py)"]:::core
            CB_Utils["Benchmark Utils"]:::core
            CB_Autopatch["Autopatch Module"]:::core
            CB_LLMClient["LLM Client"]:::external
            CB_Datasets["Datasets (JSON)"]:::datastore
            CB_Scripts["Infrastructure Scripts"]:::core
            CB_Website["Website Docs"]:::docs

            CB_CLI -->|invokes| CB_BenchCore
            CB_BenchCore -->|uses| CB_Utils
            CB_BenchCore -->|calls| CB_Autopatch
            CB_BenchCore -->|calls| CB_LLMClient
            CB_BenchCore -->|loads| CB_Datasets
            CB_BenchCore -->|uses| CB_Scripts
        end

        subgraph "Llama-Guard / Prompt-Guard Collections"
            direction TB
            LG1["Llama-Guard Variants"]:::docs
            PG["Prompt-Guard"]:::docs
        end

        subgraph "LlamaFirewall Subsystem"
            direction TB
            LF_CLI["CLI & Config"]:::frontend
            LF_Core["Firewall Core Engine"]:::core
            LF_Scanners["Pluggable Scanners"]:::core
            LF_LLMAdapter["LLM Adapter"]:::external
            LF_Examples["Examples & Notebooks"]:::docs
            LF_Website["Website Docs"]:::docs
            LF_Tests["Tests"]:::docs

            LF_CLI -->|triggers| LF_Core
            LF_Core -->|loads| LF_Scanners
            LF_Core -->|calls| LF_LLMAdapter
        end

        subgraph "SensitiveDocClassification Subsystem"
            direction TB
            SD_CLI["CLI"]:::frontend
            SD_Core["Classifier Core"]:::core
            SD_GDrive["Google Drive Client"]:::external
            SD_LLMClient["LLM Client"]:::external
            SD_DB["SQLite Database"]:::datastore
            SD_Config["Content Category Configs"]:::datastore
            SD_Scanner["Scanner Script"]:::frontend
            SD_Tests["Tests"]:::docs

            SD_CLI -->|runs| SD_Core
            SD_Core -->|queries| SD_GDrive
            SD_Core -->|calls| SD_LLMClient
            SD_Core -->|stores| SD_DB
            SD_Core -->|uses| SD_Config
        end
    end

    classDef frontend fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef core fill:#a2d0fc,stroke:#333,stroke-width:1px
    classDef external fill:#fcba03,stroke:#333,stroke-width:1px
    classDef datastore fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef docs fill:#d5b8fc,stroke:#333,stroke-width:1px

    click CS_CLI "https://github.com/meta-llama/purplellama/blob/main/CodeShield/example.py"
    click CS_Core "https://github.com/meta-llama/purplellama/blob/main/CodeShield/codeshield.py"
    click CS_Detector "https://github.com/meta-llama/purplellama/tree/main/CodeShield/insecure_code_detector/"
    click CS_RuleConfig "https://github.com/meta-llama/purplellama/blob/main/CodeShield/insecure_code_detector/rules/config.yaml"
    click CS_Regex "https://github.com/meta-llama/purplellama/tree/main/CodeShield/insecure_code_detector/rules/regex/"
    click CS_Semgrep "https://github.com/meta-llama/purplellama/tree/main/CodeShield/insecure_code_detector/rules/semgrep/"
    click CS_Tests "https://github.com/meta-llama/purplellama/blob/main/CodeShield/tests/test_codeshield.py"
    click CS_Tests "https://github.com/meta-llama/purplellama/tree/main/CodeShield/insecure_code_detector/tests/"

    click CB_CLI "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/run.py"
    click CB_BenchCore "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/benchmark.py"
    click CB_Utils "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/benchmark_utils.py"
    click CB_Autopatch "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/autopatch/llm_interface.py"
    click CB_Autopatch "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/autopatch/patch_generator.py"
    click CB_Autopatch "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/autopatch/autopatch_tools.py"
    click CB_Autopatch "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/autopatch/types.py"
    click CB_Autopatch "https://github.com/meta-llama/purplellama/tree/main/CybersecurityBenchmarks/benchmark/autopatch/build/"
    click CB_LLMClient "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/llm.py"
    click CB_LLMClient "https://github.com/meta-llama/purplellama/blob/main/CybersecurityBenchmarks/benchmark/query_llm.py"
    click CB_Datasets "https://github.com/meta-llama/purplellama/tree/main/CybersecurityBenchmarks/datasets/"
    click CB_Scripts "https://github.com/meta-llama/purplellama/tree/main/CybersecurityBenchmarks/scripts/"
    click CB_Website "https://github.com/meta-llama/purplellama/tree/main/CybersecurityBenchmarks/website/"

    click LF_Core "https://github.com/meta-llama/purplellama/blob/main/LlamaFirewall/src/llamafirewall/llamafirewall.py"
    click LF_CLI "https://github.com/meta-llama/purplellama/blob/main/LlamaFirewall/src/llamafirewall/cli/configure.py"
    click LF_CLI "https://github.com/meta-llama/purplellama/blob/main/LlamaFirewall/src/llamafirewall/config.py"
    click LF_Scanners "https://github.com/meta-llama/purplellama/tree/main/LlamaFirewall/src/llamafirewall/scanners/"
    click LF_LLMAdapter "https://github.com/meta-llama/purplellama/blob/main/LlamaFirewall/src/llamafirewall/utils/base_llm.py"
    click LF_Examples "https://github.com/meta-llama/purplellama/tree/main/LlamaFirewall/examples/"
    click LF_Examples "https://github.com/meta-llama/purplellama/tree/main/LlamaFirewall/notebook/"
    click LF_Tests "https://github.com/meta-llama/purplellama/tree/main/LlamaFirewall/tests/"
    click LF_Website "https://github.com/meta-llama/purplellama/tree/main/LlamaFirewall/website/"

    click SD_CLI "https://github.com/meta-llama/purplellama/blob/main/SensitiveDocClassification/cli/argument_parser.py"
    click SD_Core "https://github.com/meta-llama/purplellama/blob/main/SensitiveDocClassification/classifyit/classifier.py"
    click SD_GDrive "https://github.com/meta-llama/purplellama/blob/main/SensitiveDocClassification/classifyit/google_drive_client/drive_client.py"
    click SD_LLMClient "https://github.com/meta-llama/purplellama/blob/main/SensitiveDocClassification/classifyit/llm_client/llm_client.py"
    click SD_DB "https://github.com/meta-llama/purplellama/blob/main/SensitiveDocClassification/classifyit/database/database.py"
    click SD_Config "https://github.com/meta-llama/purplellama/tree/main/SensitiveDocClassification/content_categories/"
    click SD_Scanner "https://github.com/meta-llama/purplellama/blob/main/SensitiveDocClassification/scanner.py"
    click SD_Tests "https://github.com/meta-llama/purplellama/tree/main/SensitiveDocClassification/tests/"
```
