How vistaminc/auditluma works
Project type and purpose
• AuditLuma is a Python-based, AI-driven code-audit system with both a CLI entry point (main.py) and an optional Web/API server (app/api).
• It orchestrates multiple AI “agents” under a Multi-agent Cooperation Protocol (MCP) and Self-Retrieval-Augmented-Generation (Self-RAG) to analyze codebases for security vulnerabilities, generate remediation advice, and produce interactive visual reports.
File structure
• Top-level:
• main.py & CLI logic
• app/api/… – HTTP server (routes, models, API docs)
• auditluma/… – Core engine package:
– agents/ – orchestrator, code_analyzer, security_analyst, remediation agents
– mcp/, rag/ – inter-agent protocol & retrieval components
– parsers/, models/, scanner.py – code ingestion & AST extraction
– visualizer/ – graph & report generation
– utils.py, config.py – shared utilities & configuration
• config/ – example YAML configs
• lib/ – front-end assets (Tom-Select, Vis.js) for interactive graph views
• Patterns:
• Modular multi-agent micro-architecture
• Asynchronous/concurrent processing
• Optional vector store (built-in or FAISS) for embeddings
Insights from the README
• Components: Agent Orchestrator, Code Analysis Agent, Security Analysis Agent, Remediation Agent, Visualization
• Tech stack: Python 3.8+, asyncio, multiple LLM vendors, optional FAISS
• Outputs: HTML/PDF/JSON reports, interactive dependency graphs
a. Entry Points
• CLI (main.py)
• Web/API Server (app/api/server.py, routes.py)
b. Core Engine
1. Scan & Parse
• scanner.py → parsers/code_parser.py → code AST & dependency model
2. Orchestrator
• agents/orchestrator.py
• Coordinates sub-agents via mcp/protocol.py
3. Agents
• Code Analyzer (agents/code_analyzer.py)
• Security Analyst (agents/security_analyst.py)
• Remediation (agents/remediation.py)
4. Self-RAG Retrieval
• rag/self_rag.py → embedding store (in-memory or FAISS)
5. LLM Clients
• Abstract via mocks/llm_client.py or real vendor adapters
c. Visualization & Reporting
• Graph Visualizer (visualizer/graph_visualizer.py) using Vis.js assets
• Report Generator (visualizer/report_generator.py) + HTML templates
d. Configuration & Data Store
• Config loader (config.py) reads config/*.yaml
• Output directory for generated reports
Relationships & data flow
• User → CLI/API → Core Engine
• Core Engine: Scan → Parse → Orchestrator → Agents ↔ LLM APIs (Self-RAG embeds)
• Aggregated results → Visualizer → Reports written to disk (or served via API)
• Optional: Front-end assets fetch JSON data endpoints for interactive graphs
Architectural patterns & design principles
• Multi-agent coordination (MCP)
• Retrieval-augmented generation (Self-RAG)
• Asynchronous, parallel task execution
• Clear separation of concerns: scanning, analysis, remediation, visualization
• Plugin-style LLM provider support