| --- |
| title: SwarmAudit |
| emoji: 🚀 |
| colorFrom: blue |
| colorTo: indigo |
| sdk: gradio |
| sdk_version: 6.14.0 |
| app_file: app.py |
| pinned: false |
| license: mit |
| short_description: A multi-agent scanner that audits repositories |
| --- |
| |
| # SwarmAudit |
|
|
| SwarmAudit is a multi-agent production-readiness scanner for AI-generated code. |
|
|
| Paste a public GitHub repository URL and SwarmAudit clones the repo, maps source files, runs specialized static and optional LLM-enriched agents, then returns a prioritized audit report with severity filters, file references, remediation guidance, scores, and Markdown/JSON exports. |
|
|
| The project was built for the AMD Developer Hackathon Track 1: AI Agents & Agentic Workflows. It is designed to run reliably in mock/static mode for public demos and switch to AMD Developer Cloud + ROCm + vLLM + Qwen2.5-Coder when GPU credits are available. |
|
|
| ## Why It Exists |
|
|
| AI coding tools are fast, but they often miss production concerns: broken security assumptions, unsafe configuration, missing timeouts, swallowed exceptions, weak observability, dependency risk, and GPU portability issues. SwarmAudit turns those review concerns into a coordinated agent workflow. |
|
|
| The goal is not to replace linters. The goal is to give teams a fast second-pass review for code that might be functionally correct but not production-ready. |
|
|
| ## Current Status |
|
|
| Working now: |
|
|
| - Gradio dashboard with agent progress, activity log, summary cards, clickable severity filters, finding inspector, and report downloads. |
| - FastAPI backend with `/health`, `/llm/health`, and `/audit`. |
| - GitHub repo cloning with file limits and Windows-safe temp paths. |
| - Static multi-agent audit path that works without GPU access. |
| - Optional vLLM/Qwen enrichment behind config. |
| - LLM Diagnostics tab for `/v1/models` and chat-completion checks. |
| - Benchmark tab for latency checks against mock or vLLM backends. |
| - Markdown and JSON report export. |
| - Hugging Face Spaces entrypoint through root `app.py`. |
| - AMD/vLLM runbook for credit-safe MI300X testing. |
|
|
| Validated during development: |
|
|
| - Hugging Face Space running in mock/static mode. |
| - AMD Developer Cloud GPU instance with ROCm visible through `rocm-smi`. |
| - vLLM serving `Qwen/Qwen2.5-Coder-32B-Instruct` through an OpenAI-compatible `/v1` API. |
| - SwarmAudit Diagnostics and Benchmark tabs connected successfully to the AMD-hosted vLLM endpoint. |
|
|
| ## Agent Workflow |
|
|
| ```text |
| GitHub URL |
| -> Crawler Agent |
| -> Chunker |
| -> Parallel Analysis Agents |
| Security |
| Performance |
| Quality |
| Docs |
| Config |
| Dependency |
| Error Handling |
| Observability |
| CUDA-to-ROCm |
| -> Synthesizer |
| -> Scores + Roadmap + Report |
| ``` |
|
|
| ## Agents |
|
|
| - **Security Agent**: hardcoded secrets, disabled TLS verification, dynamic execution, insecure dependency version ranges. |
| - **Performance Agent**: missing HTTP timeouts, blocking work in async paths, nested loops, repeated file reads, synchronous hot-path operations. |
| - **Quality Agent**: long functions, high branch density, very short identifiers, TODO/FIXME/HACK comments, maintainability signals. |
| - **Docs Agent**: README gaps, missing install/run/test guidance, public Python symbols without docstrings. |
| - **Config Agent**: production-dangerous defaults such as debug mode, open CORS, disabled TLS checks, weak secrets, unsafe config patterns. |
| - **Dependency Agent**: parses manifests and optionally queries OSV.dev for CVE data when enabled. |
| - **Error Handling Agent**: swallowed exceptions, missing timeouts, missing retry/fallback behavior, resilience gaps. |
| - **Observability Agent**: `print` logging, sensitive data in logs, missing health checks, missing metrics/tracing signals. |
| - **CUDA-to-ROCm Agent**: flags CUDA/NVIDIA-specific assumptions such as `torch.cuda`, `.cuda()`, `pynvml`, `nvidia-smi`, `cudaMalloc`, and `cudaMemcpy`, then suggests ROCm/generic alternatives. |
| - **Synthesizer Agent**: deduplicates findings, ranks by severity, computes scores, groups categories, and builds the remediation roadmap. |
|
|
| ## Report Output |
|
|
| Each audit report includes: |
|
|
| - Repository URL |
| - scanned/skipped file counts |
| - severity summary |
| - total/displayed/hidden finding counts |
| - agent finding counts |
| - category summary |
| - security score |
| - production readiness score |
| - remediation roadmap: |
| - This Week |
| - Next Sprint |
| - Backlog |
| - structured findings with: |
| - title |
| - severity |
| - file path and line range |
| - explanation |
| - why it matters |
| - suggested fix |
| - agent source |
| - category |
| - confidence when available |
| - Markdown export |
| - JSON export |
|
|
| The UI displays a prioritized subset for readability while preserving full totals in the structured report. |
|
|
| ## AMD + Qwen Integration |
|
|
| SwarmAudit uses Qwen through an OpenAI-compatible vLLM endpoint. The app does not install or run vLLM directly; it calls vLLM over HTTP. |
|
|
| The AMD path improves the project by allowing the same agent workflow to use a stronger code model on AMD GPU infrastructure: |
|
|
| - AMD Developer Cloud provides the GPU runtime. |
| - ROCm exposes AMD GPU acceleration. |
| - vLLM serves Qwen2.5-Coder as an OpenAI-compatible API. |
| - SwarmAudit uses that endpoint for Diagnostics, Benchmark, and optional LLM enrichment. |
| - Static agents remain the reliable fallback if the endpoint is unavailable. |
|
|
| Default public/demo mode stays cheap and reliable: |
|
|
| ```text |
| LLM_PROVIDER=mock |
| ENABLE_LLM_ENRICHMENT=false |
| ``` |
|
|
| Credit-safe AMD test mode: |
|
|
| ```text |
| LLM_PROVIDER=vllm |
| LLM_BASE_URL=http://YOUR_VLLM_ENDPOINT/v1 |
| LLM_API_KEY=swarm-audit-demo-key |
| LLM_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct |
| ENABLE_LLM_ENRICHMENT=true |
| MAX_FILES=100 |
| MAX_FILE_SIZE_KB=150 |
| MAX_CHARS_PER_CHUNK=8000 |
| MAX_LLM_CHUNKS=2 |
| ``` |
|
|
| See [`AMD_VLLM_RUNBOOK.md`](AMD_VLLM_RUNBOOK.md) for the exact AMD setup and shutdown checklist. |
|
|
| ## Hugging Face Spaces |
|
|
| SwarmAudit is deployable as a Gradio Space using the root `app.py`. |
|
|
| Recommended public Space settings: |
|
|
| - SDK: Gradio |
| - Hardware: CPU basic |
| - App file: `app.py` |
| - Environment: |
|
|
| ```text |
| LLM_PROVIDER=mock |
| ENABLE_LLM_ENRICHMENT=false |
| ENABLE_DEPENDENCY_CVE_LOOKUP=false |
| ``` |
|
|
| Keep the public Space in mock/static mode unless a stable vLLM endpoint is available for the full judging window. Do not expose private endpoint keys in the README or UI. |
|
|
| See [`HF_SPACES_DEPLOY.md`](HF_SPACES_DEPLOY.md) for the deployment checklist. |
|
|
| ## Quick Start |
|
|
| ```bash |
| python -m venv .venv |
| .venv\Scripts\activate |
| pip install -r requirements.txt |
| ``` |
|
|
| Run the Gradio app: |
|
|
| ```bash |
| python app.py |
| ``` |
|
|
| Open the URL printed by Gradio. The app tries port `7860` first and falls back to another local Gradio port if `7860` is busy. |
|
|
| Run the FastAPI backend: |
|
|
| ```bash |
| uvicorn app.main:app --reload |
| ``` |
|
|
| If port `8000` is busy: |
|
|
| ```bash |
| uvicorn app.main:app --reload --port 8001 |
| ``` |
|
|
| Health checks: |
|
|
| ```bash |
| curl http://127.0.0.1:8000/health |
| curl http://127.0.0.1:8000/llm/health |
| ``` |
|
|
| Audit API: |
|
|
| ```bash |
| curl -X POST http://127.0.0.1:8000/audit \ |
| -H "Content-Type: application/json" \ |
| -d '{"repo_url":"https://github.com/pallets/itsdangerous"}' |
| ``` |
|
|
| Recommended first test repos: |
|
|
| ```text |
| https://github.com/pallets/itsdangerous |
| https://github.com/psf/requests |
| ``` |
|
|
| ## Configuration |
|
|
| Copy `.env.example` to `.env` for local overrides. |
|
|
| Important settings: |
|
|
| ```text |
| LLM_PROVIDER=mock |
| LLM_BASE_URL=http://localhost:9000/v1 |
| LLM_API_KEY=not-needed-for-mock |
| LLM_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct |
| ENABLE_LLM_ENRICHMENT=false |
| ENABLE_DEPENDENCY_CVE_LOOKUP=false |
| MAX_LLM_CHUNKS=5 |
| LLM_TIMEOUT_SECONDS=120 |
| MAX_FILES=200 |
| MAX_FILE_SIZE_KB=250 |
| MAX_CHARS_PER_CHUNK=12000 |
| CLONE_TIMEOUT_SECONDS=60 |
| CLONE_BASE_DIR=.swarm_audit_tmp |
| ``` |
|
|
| Dependency CVE lookup is off by default so demos do not depend on network calls beyond cloning the target repo: |
|
|
| ```text |
| ENABLE_DEPENDENCY_CVE_LOOKUP=false |
| ``` |
|
|
| Enable it only when you want OSV.dev CVE checks: |
|
|
| ```text |
| ENABLE_DEPENDENCY_CVE_LOOKUP=true |
| ``` |
|
|
| ## Tests |
|
|
| ```bash |
| python -m compileall -q app tests app.py |
| python -m pytest --basetemp=.tmp_pytest -p no:cacheprovider |
| ``` |
|
|
| Current local suite: |
|
|
| ```text |
| 104 tests |
| ``` |
|
|
| ## Project Structure |
|
|
| ```text |
| app.py # Hugging Face/Gradio entrypoint |
| app/ |
| main.py # FastAPI API |
| config.py # environment settings |
| schemas.py # Pydantic models |
| agents/ |
| graph.py # orchestration |
| security_agent.py |
| performance_agent.py |
| quality_agent.py |
| docs_agent.py |
| config_agent.py |
| dependency_agent.py |
| error_handling_agent.py |
| observability_agent.py |
| cuda_migration_agent.py |
| synthesizer_agent.py |
| llm_enrichment.py |
| services/ |
| llm_client.py |
| benchmark.py |
| report_formatter.py |
| ui/ |
| gradio_app.py |
| tests/ |
| examples/ |
| ``` |
|
|
| ## Submission Notes |
|
|
| For the hackathon submission, highlight: |
|
|
| - agentic workflow with multiple specialized agents |
| - Qwen2.5-Coder integration through vLLM |
| - AMD Developer Cloud + ROCm validation |
| - Hugging Face Space deployment |
| - practical business value: production readiness for AI-generated code |
| - originality: combining security, operations, dependency, and CUDA-to-ROCm portability checks in one audit workflow |
|
|
