# iris-sast/iris architecture

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

- Interactive diagram: https://gitdiagram.com/iris-sast/iris
- Repository: https://github.com/iris-sast/iris

## Overview

##### Project Type and Purpose
- IRIS is an open‑source, full‑pipeline security analysis tool that merges static analysis (via CodeQL) with large language models (LLMs) to detect and filter security vulnerabilities in Java projects.
- It is not a typical web‑app but a **batch/CLI‑driven neurosymbolic framework**: users feed it Java code (from CWE‑Bench‑Java or custom), and it emits vulnerability reports (SARIF, CSV, JSON).

##### High‑Level Architecture Overview
A. Data Preparation & CodeQL DB Generation
B. Taint‑Spec Generation (LLM‑Assisted)
C. CWE‑Specific Query Construction & Execution
D. Contextual Filtering & Reporting

##### Main Components
1. **Input Layer**
- *Java Project Sources* (data/cwe‑bench‑java/project‑sources or custom)
- *Build Metadata* (data/cwe‑bench‑java/data/build_info.csv, JDK/Maven/Gradle archives)
2. **Environment & Toolchain**
- *Patched CodeQL Binary* (unpacked at root, added to PATH via setup scripts)
- *Conda/Docker* environment (environment.yml, Dockerfile, setup_environment.sh)
- *JDKs + Build Tools* (Java 7/8/17, Maven, Gradle)
3. **Preparation Phase**
- scripts/build_codeql_dbs.py → generates CodeQL databases under `data/cwe‑bench‑java/databases/…`
- scripts/get_packages_codeql.py → extracts internal package names for query scoping
4. **Specification Generation Phase**
- src/modules/contextual_analysis_pipeline.py orchestrates:
- *External API Discovery* (CodeQL “fetch_external_apis.ql”)
- *Function Parameter Extraction* (QL queries under src/queries/)
- *LLM Classification* (src/models/* + src/prompts.py) → produces source, sink, propagator specs (MySources.qll, MySinks.qll)
5. **Query Construction & Execution Phase**
- src/codeql_queries.py & src/codeql_vul.py assemble CWE‑specific query packs (cwe‑queries/*) + LLM specs → produces a combined .ql query
- src/modules/codeql_query_runner.py runs CodeQL query on the CodeQL DB → raw results.sarif
- src/modules/postprocess_cwe_query.py transforms raw results into structured CSV/JSON
6. **Contextual Filtering Phase**
- src/modules/evaluation_pipeline.py takes raw findings + code context → prompts LLM again to filter false positives
- Outputs filtered SARIF (results_pp.sarif) and statistics (results.json)
7. **Output Layer**
- Directory tree under output/[project]/[run‑id]/… containing logs, intermediate CSVs, SARIFs, JSON stats

##### Relationships & Data Flow
Input → Preparation → Spec Generation → Query Execution → Filtering → Output
- **Bidirectional calls**: Spec Generation ↔ LLM Models; Filtering ↔ LLM Models
- **Dependencies**:
- CodeQL DB depends on Input + Build Tools
- LLM calls depend on prompts (src/prompts.py) + model wrappers (src/models)

##### Architectural Patterns & Principles
- **Modular Pipeline**: each stage is a self‑contained Python module under src/modules
- **Separation of Concerns**:
- Static analysis (CodeQL) vs. dynamic/intelligent spec/classification (LLM)
- Query authoring (cwe‑queries) vs. query execution vs. result filtering
- **Extensibility**:
- New CWE by dropping a new folder under src/cwe‑queries and updating docs/adding_cwes.md
- Plug in new LLM by extending src/models and updating config in src/config.py

##### Technologies & Frameworks to Annotate
- Python 3 (main orchestration)
- CodeQL (static analysis engine, QL queries)
- Conda / Docker (reproducible environments)
- JDK / Maven / Gradle (project build)
- LLMs via HuggingFace / OpenAI / Ollama (encapsulated in src/models)
- SARIF (output format for vulnerability reports)

##### Detail Checklist
- LLM models as a reusable service block connected to two stages.
- Output directory hierarchy as the final sink.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Layer"
        DS["Java Project Sources"]:::data
        BM["Build Metadata"]:::data
    end

    click DS "https://github.com/iris-sast/iris/tree/main/data/cwe-bench-java/project-sources/"
    click BM "https://github.com/iris-sast/iris/blob/main/data/cwe-bench-java/data/build_info.csv"

    subgraph "Environment & Toolchain"
        CodeQLBin["codeql (binary)"]:::binary
        Docker["Dockerfile"]:::binary
        Conda["environment.yml"]:::binary
        SetupEnv["setup_environment.sh"]:::python
        JDKs["JDKs + Build Tools"]:::binary
    end

    click Docker "https://github.com/iris-sast/iris/tree/main/Dockerfile"
    click Conda "https://github.com/iris-sast/iris/blob/main/environment.yml"
    click SetupEnv "https://github.com/iris-sast/iris/blob/main/scripts/setup_environment.sh"
    click JDKs "https://github.com/iris-sast/iris/tree/main/data/cwe-bench-java/jdks/"

    Orchestrator["Orchestrator (CLI)"]:::python

    DS --> Orchestrator
    BM --> Orchestrator
    CodeQLBin --> Orchestrator
    Docker --> Orchestrator
    Conda --> Orchestrator
    SetupEnv --> Orchestrator
    JDKs --> Orchestrator

    subgraph "Preparation Phase"
        BuildDB["build_codeql_dbs.py"]:::python
        GetPkg["get_packages_codeql.py"]:::python
        PackagesQL["packages.ql"]:::query
        DBStore["CodeQL DBs"]:::data
    end

    click BuildDB "https://github.com/iris-sast/iris/blob/main/scripts/build_codeql_dbs.py"
    click GetPkg "https://github.com/iris-sast/iris/blob/main/scripts/get_packages_codeql.py"
    click PackagesQL "https://github.com/iris-sast/iris/blob/main/scripts/codeql-queries/packages.ql"

    Orchestrator --> BuildDB
    BuildDB --> DBStore
    Orchestrator --> GetPkg
    GetPkg --> PackagesQL

    subgraph "Specification Generation Phase"
        CAP["contextual_analysis_pipeline.py"]:::python
        FetchExt["fetch_external_apis.ql"]:::query
        FetchParams["fetch_func_params.ql"]:::query
        OtherQueries["fetch_class_locs.ql\nfetch_func_locs.ql\nfetch_field_reads.ql"]:::query
        Prompts["prompts.py"]:::python
        LLMService["LLM Models"]:::external
        InlineSpecs["Generated QL Specs"]:::query
    end

    click CAP "https://github.com/iris-sast/iris/blob/main/src/modules/contextual_analysis_pipeline.py"
    click FetchExt "https://github.com/iris-sast/iris/blob/main/src/queries/fetch_external_apis.ql"
    click FetchParams "https://github.com/iris-sast/iris/blob/main/src/queries/fetch_func_params.ql"
    click OtherQueries "https://github.com/iris-sast/iris/blob/main/src/queries/fetch_class_locs.ql"
    click Prompts "https://github.com/iris-sast/iris/blob/main/src/prompts.py"

    Orchestrator --> CAP
    CAP --> FetchExt
    CAP --> FetchParams
    CAP --> OtherQueries
    CAP --> Prompts
    FetchExt & FetchParams & OtherQueries & Prompts --> LLMService
    LLMService --> InlineSpecs

    subgraph "Query Construction & Execution Phase"
        Assemble["codeql_queries.py\ncodeql_vul.py\ncodeql_vul_for_query.py"]:::python
        QueryPacks["src/cwe-queries/*"]:::query
        QueryRunner["codeql_query_runner.py"]:::python
        RawSARIF["raw results.sarif"]:::data
        PostProc["postprocess_cwe_query.py"]:::python
        Structured["CSV/JSON"]:::data
    end

    click Assemble "https://github.com/iris-sast/iris/blob/main/src/codeql_queries.py"
    click QueryRunner "https://github.com/iris-sast/iris/blob/main/src/modules/codeql_query_runner.py"
    click PostProc "https://github.com/iris-sast/iris/blob/main/src/modules/postprocess_cwe_query.py"
    click QueryPacks "https://github.com/iris-sast/iris/tree/main/src/cwe-queries/"

    InlineSpecs & QueryPacks --> Assemble
    Assemble --> QueryRunner
    QueryRunner --> RawSARIF
    RawSARIF --> PostProc
    PostProc --> Structured

    subgraph "Contextual Filtering Phase"
        EvalPipe["evaluation_pipeline.py"]:::python
        Prompts2["prompts.py"]:::python
        LLMService2["LLM Models"]:::external
        Filtered["results_pp.sarif"]:::data
        Stats["results.json"]:::data
    end

    click EvalPipe "https://github.com/iris-sast/iris/blob/main/src/modules/evaluation_pipeline.py"

    Structured --> EvalPipe
    EvalPipe --> Prompts2
    Prompts2 --> LLMService2
    EvalPipe --> Filtered
    EvalPipe --> Stats

    subgraph "Output Layer"
        OutputDir["output/[project]/[run-id]/"]:::data
    end

    Filtered --> OutputDir
    Stats --> OutputDir

    classDef python fill:#cfe2f3,stroke:#000
    classDef data fill:#d9ead3,stroke:#000
    classDef binary fill:#f4cccc,stroke:#000
    classDef external fill:#ead1dc,stroke:#000
    classDef query fill:#fff2cc,stroke:#000
```
