4.6.0

---

What It Is

ACR-QA is a provenance-first, AI-augmented code review platform built as a graduation thesis at KSIU. It solves three real problems that frustrate every developer using static analysis tools:

Key numbers: 97.1% precision · 9/10 OWASP Top 10 · 2,339 tests (2,274 Python + 65 TypeScript) · 36 async API endpoints · $0 recurring cost

---

Architecture

C4Container
    title ACR-QA — System Overview

    Person(dev, "Developer")

    Container_Boundary(sys, "ACR-QA") {
        Container(cli, "CLI / GitHub Action", "Python", "Entry point. Detects language, routes to adapter.")
        Container(core, "Analysis Engine", "Python 3.11", "10 tools → normalise → score → dedup → AI explain → quality gate")
        Container(api, "Async REST API", "FastAPI :8000", "36 /v1/ endpoints · JWT + API key auth · Swagger at /docs")
        Container(worker, "Background Worker", "Celery + Redis", "Async scan execution — POST /v1/scans returns 202 + job_id")
        ContainerDb(pg, "PostgreSQL 15", "", "Provenance: runs · findings · LLM calls · feedback · users · api_keys")
        ContainerDb(redis, "Redis 5.2", "", "Rate limiting · explanation cache · Celery broker + result backend")
    }

    Container_Ext(groq, "Groq API", "LLM", "Llama 3.3-70b explanations · Llama 3.1-8b feasibility · free tier")
    Container_Ext(gh, "GitHub / GitLab", "CI", "PR comments · SARIF upload · merge blocking")

    Rel(dev, cli, "runs analysis")
    Rel(cli, core, "invokes pipeline")
    Rel(core, pg, "stores provenance")
    Rel(core, redis, "rate limit / cache")
    Rel(core, groq, "RAG explanations")
    Rel(core, gh, "PR comments + SARIF")

Full C4 diagrams: C1 Context · C2 Containers · C3 Components · C4 Code

---

Quick Start

Option A — Docker (one command)

git clone https://github.com/ahmed-145/acr-qa.git && cd acr-qa
cp .env.example .env          # add your GROQ_API_KEY_1..4
make up

Option B — Local

pip install -r requirements.txt
createdb acrqa && psql -d acrqa -f DATABASE/schema.sql
cp .env.example .env && source .env
uvicorn FRONTEND.api.main:app --port 8000    # → http://localhost:8000/docs

Run your first analysis

# Python project
python3 CORE/main.py --target-dir ./myproject --rich

# JavaScript / TypeScript project
python3 CORE/main.py --target-dir ./my-express-app --lang javascript --no-ai

# Go project
python3 CORE/main.py --target-dir ./my-go-api --lang go

# JSON output for CI pipelines
python3 CORE/main.py --target-dir . --json --no-ai > findings.json

---

What Makes It Different

---

Features

Detection Pipeline

10 tools run in parallel, all output normalised into one CanonicalFinding schema:

AI Explanation (RAG-Enhanced)

• 66-rule knowledge base (config/rules.yml) — every rule has description, rationale, remediation, and code examples
• Evidence-grounded prompts — the LLM is given the rule text; it cannot invent advice for rules it can't cite
• Semantic entropy — 3× LLM runs with varying temperature; contradictions lower the confidence score
• Self-evaluation — LLM rates its own output 1–5 on relevance/accuracy/clarity
• Path feasibility (Feature 7) — second AI call validates whether a HIGH finding's code path is actually reachable in production (LLM4PFA approach)

Quality Gate

# .acrqa.yml
quality_gate:
  mode: block         # block = fail CI + prevent merge | warn = comment only
  max_high: 0         # zero tolerance for HIGH severity
  max_medium: 5
  max_security: 0

Fails CI with exit code 1. GitHub Action posts severity table as PR comment.

Per-Repo Policy (.acrqa.yml)

rules:
  disabled_rules: [IMPORT-001, STYLE-007]
  severity_overrides: {COMPLEXITY-001: low}

analysis:
  ignore_paths: [.venv, migrations/, node_modules]

ai:
  max_explanations: 50
  model: llama-3.1-8b-instant

Inline Suppression

result = eval(user_input)      # acr-qa:ignore
password = "secret123"         # acrqa:disable SECURITY-005

FastAPI Dashboard (http://localhost:8000/docs)

• Severity counters with live counts
• Finding cards with collapsible AI explanations + 🎯 confidence badge
• Cost-benefit widget: analysis cost, hours saved, ROI ratio
• Trend charts across last 30 runs
• False-positive feedback (👍/👎) — feeds triage memory for future suppression
• Filters by severity, category, rule ID, full-text search
• Export: SARIF, provenance trace, Markdown reports

---

CLI Reference

python3 CORE/main.py [options]

  --target-dir DIR     Directory to analyse (default: samples/realistic-issues)
  --repo-name NAME     Repository name for provenance tracking
  --pr-number N        PR number (enables GitHub PR comment posting)
  --limit N            Max findings to AI-explain (default: 50)
  --diff-only          Analyse only files changed in git diff
  --diff-base BRANCH   Base branch for diff (default: main)
  --auto-fix           Generate auto-fix suggestions for fixable rules
  --rich               Rich terminal output with colour-coded tables
  --lang LANG          auto (default) | python | javascript | typescript | go
  --no-ai              Skip AI explanation step (faster, no API key needed)
  --json               Output findings as JSON to stdout (pipe-friendly)
  --version            Print version and exit

---

Language Support

Python (v1.0+)

Ruff · Bandit · Semgrep · Vulture · Radon · Secrets · SCA · CBoM

JavaScript / TypeScript (v3.0.1+)

python3 CORE/main.py --target-dir ./my-react-app          # auto-detect
python3 CORE/main.py --target-dir ./my-express-api --lang javascript

ESLint (security plugin) · Semgrep JS rules · npm audit 56 rule mappings · 15 HIGH-severity security rules covered

Go (v3.2.0+)

python3 CORE/main.py --target-dir ./my-go-api --lang go

Prerequisites: go install github.com/securego/gosec/v2/cmd/gosec@latest && go install honnef.co/go/tools/cmd/staticcheck@latest

gosec · staticcheck · Semgrep Go rules · 45+ rule mappings

---

CI/CD Integration

GitHub Actions

# .github/workflows/acr-qa.yml (already in repo)
# Triggers on every PR:
# 1. Runs all 10 tools on changed files (--diff-only)
# 2. Normalises, scores, generates AI explanations
# 3. Posts severity-sorted PR comment with code suggestions
# 4. Uploads findings.sarif to GitHub Security Tab
# 5. Fails merge if quality gate violated (exit code 1)

Required secrets: GROQ_API_KEY_1..4 · GITHUB_TOKEN (auto-provided)

Manual trigger on PR

Comment on any PR:

acr-qa review

GitLab CI

.gitlab-ci.yml included. Set GROQ_API_KEY_1 and GITLAB_TOKEN in CI/CD Variables.

---

Monitoring

Prometheus scrapes /metrics every 15 s. Grafana dashboard at http://localhost:3005 (admin/admin):

---

Testing

make test-all          # 2,339 tests (full suite)
make test              # acceptance tests only
make run               # pipeline on sample files

---

Thesis Evaluation

Research Questions

Benchmark Results (4 repositories)

DVPWA recall 50%: 3 of 6 known vulns detected; CSRF (runtime-only), hardcoded debug mode, and one abstracted cred require DAST — documented limitation, not a bug.

---

Architecture Decision Records

Key design decisions are documented in docs/adr/:

---

Technology Stack

---

Interactive Demo Notebooks

Run these Marimo notebooks locally or view the exported HTML:

# Run interactively (edit cells live)
pip install marimo
marimo run notebooks/walkthrough.py

# Or open in edit mode for defense demo
marimo edit notebooks/walkthrough.py

---

Documentation

---

Academic Context

Remaining Thesis Work

• Cloud deployment — live at acrqa-api-production.up.railway.app (Railway + PostgreSQL + Redis)
• User study protocol — docs/evaluation/USER_STUDY_PROTOCOL.md
• 5-minute demo video (script) ← human task
• YouTube upload (follows demo video) ← human task

---

License

MIT — see LICENSE

---