How iris-sast/iris works
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.