ASPHALES (ἀσφαλής)

AI-Powered Autonomous Code Review & Vulnerability Verification Agent

ASPHALES bridges deterministic SAST security tooling with high-reasoning NVIDIA-hosted AI models (NVIDIA NIM). It inspects codebases, identifies security vulnerabilities and dependency flaws, synthesizes minimal surgical patches, and autonomously re-tests the codebase in an isolated sandbox to verify that findings are cleared without regressions.

---

Architecture Overview

GitHub / Local Repository
          │
          ▼
   [ Workspace Isolator ] ── (Shallow clone & temp sandbox)
          │
          ▼
   [ Ecosystem & Manifest Detector ] ── (Discovers Python, Node, manifests, tests)
          │
          ├───────────────────────────────────────────┐
          ▼                                           ▼
[ Static & Secret Analyzers ]               [ Dependency & SCA Checkers ]
- Bandit (Python AST)                       - pip-audit (Python CVEs)
- Semgrep (Universal SAST)                  - npm audit (Node Advisories)
- Gitleaks (Hardcoded Credentials)
- Ruff (Linter & Code Quality)
          │                                           │
          └─────────────────────┬─────────────────────┘
                                │
                                ▼
                   [ Test Runner Tool (Pytest / npm test) ]
                                │
                                ▼
                   [ Evidence Aggregator & Secret Redactor ]
                                │
                                ▼
                   [ NVIDIA NIM AI Reasoning Layer ]
                   (meta/llama-3.3-70b-instruct / deepseek-r1)
                   - Attack Vector Modeling
                   - False Positive Filtering
                                │
                                ▼
                   [ Interactive Remediation Engine ]
                   - Surgical Unified Diff Generation
                                │
                                ▼
                   [ Closed-Loop Verification ]
                   - Re-executes triggering tool (Bandit / Semgrep / Ruff)
                   - Re-executes test suite (Pytest / npm test)
                   - Reports verified fix status
                                │
                                ▼
                   [ Next.js Real-Time Telemetry Dashboard ]

---

Quickstart Guide

1. Configure NVIDIA NIM API Key (Optional)

Create a .env file in the root directory:

NVIDIA_API_KEY=nvapi-your-key-here
NVIDIA_MODEL=meta/llama-3.3-70b-instruct

Note: If no key is set, ASPHALES automatically falls back to its built-in offline mock provider so demos and evaluations remain functional offline.

2. Start the FastAPI Backend Engine

python -m uvicorn apps.api.main:app --host 0.0.0.0 --port 8000 --reload

Backend runs on http://localhost:8000. API docs available at http://localhost:8000/docs.

3. Start the Next.js Frontend Dashboard

cd apps/web
npm run dev

Frontend runs on http://localhost:3000.

4. Optional GitHub Remediation Push

After a fix is verified in the isolated workspace, ASPHALES can prepare a sanitized diff and, only after explicit confirmation, create a dedicated asphales/fix/... branch and commit through the GitHub API. It never pushes directly to the default branch.

Configure a token with repository contents and pull-request permissions:

GITHUB_TOKEN=github_pat_your_token_here

The token is used only by the backend, never sent to the frontend, AI prompts, diffs, logs, or scanner processes. Without a token, local benchmark workflows show clearly labeled DEMO/SIMULATED branch, commit, and Pull Request results.

---

Built-In Benchmark Repositories for Demos

For zero-latency testing during live presentations:

1. Python Benchmark (samples/vulnerable-python):
   • Real SQL Injection via f-string formatting (Bandit B608)
   • Hardcoded AWS credential (Gitleaks / Secret Leak)
   • Dangerous eval() call (Bandit B307)
   • Pinned vulnerable dependency (pip-audit)
   • Pytest unit tests for regression verification
2. Node.js Benchmark (samples/vulnerable-node):
   • Prototype pollution in object merge
   • Leaked GitHub Personal Access Token
   • Vulnerable Lodash dependency (npm audit)