How finansminister/llm-code-security-audit-script works
1. Purpose and top-level flow
This repo is an orchestration pipeline for auditing Python code generated by LLMs. The main path is: prompt dataset → LLM generation → code extraction/cleanup → static security scan with CodeQL → CWE/OWASP categorization → aggregate statistics and audit logs.
2. Entry points and orchestration
main.py is the central runner. It likely coordinates batch execution, session resumption, and handoff between generation and scanning. freeze_hashes.py is a separate maintenance utility used to create the baseline master_hashes.json for integrity checks.
3. Configuration boundary
config.py centralizes runtime settings, API parameters, paths, and telemetry/logging configuration. This file is the shared dependency for most subsystems, which keeps environment-specific wiring out of the core logic.
4. Input corpus
seceval-dataset/dataset.jsonl is the prompt source. The system appears to iterate over this dataset to generate code samples for multiple models, so the dataset is the upstream input boundary for the whole experiment.
5. LLM access layer
src/llm/clients.py encapsulates provider-specific API clients. The repo supports several model providers, so this layer isolates authentication, endpoint differences, and model selection from the rest of the pipeline.
src/llm/generator.py drives the batch prompting workflow and persists model responses for later analysis.
6. Core safety and normalization layer
src/core/integrity.py handles source/state validation using hashes against master_hashes.json. This is a guardrail to detect drift in the codebase or experiment artifacts.
src/core/parser.py sanitizes raw LLM output into usable Python source, which forms the handoff from text generation to static analysis.
7. Static analysis subsystem
src/scanners/codeql.py wraps the CodeQL CLI and is responsible for building databases, running queries, and emitting SARIF or similar machine-readable scan results. This is the external security-analysis engine in the architecture.
src/scanners/owasp.py maps CodeQL-derived CWE findings into OWASP Top 10 categories, providing the semantic layer used by the reporting and statistics code.
8. Audit and experiment logging
src/analysis/audit.py provides persistent logging and tee-style console/file output so the run can be replayed or inspected after interruption. It likely records per-attempt metadata, errors, and scan outcomes as an audit trail.
9. Statistical analysis layer
src/analysis/stats.py aggregates the scan results across prompts/models and computes comparative statistics such as distribution tests or significance tests. This is the analytical boundary that turns raw vulnerability findings into experimental conclusions.
10. State and resumption model
The repo is designed around resumable batch processing. Generated code, scan artifacts, hashes, and logs are likely written to disk so a partial run can continue without repeating expensive LLM calls or re-scans.
11. Important external dependencies
The main external runtime dependencies are the LLM provider APIs and the CodeQL CLI. Python is the execution environment, while the repo’s own modules mostly coordinate I/O, validation, scan execution, and report aggregation.
12. Architectural diagram takeaway
A good diagram should show three major planes:
- Experiment control: main.py, config.py, freeze_hashes.py
- Generation and security pipeline: dataset → src/llm → src/core → src/scanners
- Observability and analysis: src/analysis + persisted artifacts (master_hashes.json, logs, scan outputs, stats outputs)
Main entry points: main.py main.py · generator.py Generator · codeql.py CodeQL · stats.py Statistics
Components 16
Experiment control
Entry points, runtime settings, and maintenance utilities.
- main.py · Central runner that coordinates batches, resumption, and pipeline handoff.
main.py - config.py · Shared runtime configuration for paths, model parameters, and logging.
config.py - freeze_hashes.py · Utility for generating the baseline hash manifest.
freeze_hashes.py
Generation and scanning
Dataset-driven LLM generation, cleanup, integrity checks, and security scanning.
- Prompt set · Upstream prompt dataset used to drive code generation experiments.
seceval-dataset/dataset.jsonl - LLM clients · Provider-specific client wrappers for model access and authentication.
src/llm/clients.py - Generator · Runs prompt batches, captures model output, and persists responses.
src/llm/generator.py - Parser · Sanitizes raw model output into usable Python source.
src/core/parser.py - Integrity · Validates repository state and artifacts against master hashes.
src/core/integrity.py - CodeQL · Builds databases and runs security queries through the CodeQL CLI.
src/scanners/codeql.py - OWASP map · Maps CWE-style findings into OWASP Top 10 categories.
src/scanners/owasp.py - CodeQL CLI · External security-analysis engine invoked by the scanner wrapper.
Audit and analysis
Logging, categorization, and aggregate statistics over scan outcomes.
- Audit log · Persistent audit trail and tee-style console/file logging for runs.
src/analysis/audit.py - Statistics · Aggregates findings and computes comparative experiment statistics.
src/analysis/stats.py - Hash manifest · Baseline hashes used for integrity validation.
master_hashes.json - Scan outputs · Persisted scan results and intermediate artifacts produced during analysis.
- Run logs · Console/file logs and audit records from resumable runs.
Connections 18
- main.py → config.py: loads settings · Main execution reads shared runtime configuration.
- main.py → Prompt set: iterates prompts · Batch workflow consumes the prompt corpus.
- main.py → Generator: starts generation · Coordinates generation runs over the dataset.
- main.py → Integrity: checks state · Uses hash-based validation to protect resumable execution.
- main.py → Audit log: records run · Writes execution progress and outcomes to the audit trail.
- freeze_hashes.py → Hash manifest: writes baseline · Creates or refreshes the integrity manifest.
- Generator → LLM clients: calls models · Uses provider adapters to request completions.
- Generator → Parser: cleans output · Normalizes raw model text into source code.
- Generator → Audit log: logs attempts · Persists per-run generation metadata and errors.
- Parser → CodeQL: hands off code · Produces source that becomes input for static analysis.
- Integrity → Hash manifest: verifies against · Compares current state with the frozen hash manifest.
- CodeQL → CodeQL CLI: invokes · Wraps the external CodeQL runtime and queries.
- CodeQL → Scan outputs: emits results · Stores scan databases, findings, and machine-readable outputs.
- CodeQL → OWASP map: provides findings · Feeds vulnerability results into semantic categorization.
- OWASP map → Statistics: categorizes input · Transforms findings into analysis-ready categories.
- Audit log → Run logs: persists trail · Writes replayable logs and audit records.
- Statistics → Scan outputs: reads outputs · Aggregates scan artifacts for comparative analysis.
- Statistics → Run logs: summarizes run · Produces analysis summaries alongside logs.