codeminder

Codeminder is a hybrid LLM-based SAST (Static Application Security Testing) tool. It combines the speed and precision of traditional pattern-based scanning with the deep, semantic understanding of Large Language Models to provide a comprehensive and actionable security analysis. This vibecoded app won 3rd place at Gemini Vibe Code Hackathon – London.

Workflow

graph TD
    subgraph "Input"
        A[/"Project Folder"/]
    end

    subgraph "Phase 1: Parallel Static Analysis"
        direction LR
        A --> B(Scan code with Semgrep<br/>OWASP Top 10);
        A --> B1(Scan dependencies & IaC with Trivy);
        A --> C(Parse code with tree-sitter);
    end

    subgraph "Phase 2: Context Building"
        D(Build Dependency Graph);
        C --> D;
    end
    
    subgraph "Phase 3: AI-Powered Deep Analysis"
        I{"LLM Analysis Engine<br/>(Gemini 2.5 Pro)"}
    end

    subgraph "Phase 4: Reporting"
        J[Aggregate & Filter Findings];
        K[Generate Report];
        L[Actionable Insights];
    end

    B -- Semgrep Code Findings --> I;
    B1 -- Trivy Infra/Dependency Findings --> I;
    C -- Code Snippets --> I;
    D -- Dependency Context --> I;
    I --> J --> K --> L;

Loading

Prerequisites

Before running Codeminder, you must have the Trivy binary installed on your system.

macOS (using Homebrew):

brew install aquasecurity/trivy/trivy

For other operating systems, please refer to the official Trivy installation documentation.

The Analysis Process in Detail

1. Parallel Scanning: The project is scanned by three tools in parallel:

   • Semgrep: Scans the source code for OWASP Top 10 and other common vulnerability patterns.
   • Trivy: Scans for known CVEs in third-party dependencies and misconfigurations in Infrastructure as Code (IaC) files.
   • tree-sitter: Parses the source code into Abstract Syntax Trees (ASTs).

2. Context Building: The ASTs from tree-sitter are used to build a dependency graph of the entire application. This graph maps the relationships between functions, classes, and modules.

3. Contextual Code Slicing & LLM Analysis: This is the core of Codeminder. For each potential vulnerability found by Semgrep or Trivy, the tool performs the following:

   • It uses the dependency graph to trace the data flow related to the finding.
   • It extracts only the relevant functions and lines of code along that data path (the "slice").
   • It sends this small, highly-relevant slice of code, along with the initial finding, to the Gemini LLM for deep analysis. The LLM is prompted to verify the vulnerability, check for sanitization, and eliminate false positives.

4. Reporting: The verified, high-confidence findings from the LLM are aggregated, filtered, and presented in a clear, actionable report.

How to Use

Command-Line Interface (CLI)

You can run Codeminder directly from the command line to scan a local directory.

1. Install Dependencies:

   pip install -r requirements.txt

2. Set Up Environment Variables: Copy the env.example to .env and add your GEMINI_API_KEY.

   cp env.example .env
   # Now edit .env and add your API key

3. Run a Scan:

   python runner.py /path/to/your/project

   The report will be saved as a JSON file in the localdata/reports/ directory.

Web API (for programmatic access)

Codeminder provides a FastAPI-powered web server for integration with other tools.

1. Start the Server:

   For development with auto-reload:

   uvicorn api:app --reload --port 18735

   For production, it is recommended to use a process manager like Gunicorn:

   gunicorn -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:18735 api:app

   This command starts 4 worker processes. The API will be available at http://127.0.0.1:18735.

2. API Endpoints:

   The API has a single endpoint: POST /scan. You can use it in two ways:

   a) Scan a public GitHub repository:

   Send a POST request with the repo_url.

   curl -X POST -F "repo_url=https://github.com/user/repository.git" http://127.0.0.1:18735/scan

   b) Scan a zipped project folder:

   Send a POST request with the .zip file.

   curl -X POST -F "file=@/path/to/your/project.zip" http://127.0.0.1:18735/scan

   The API will return the full JSON report in the response.

Technologies

• Language: Python 3.12
• LLM: Google Gemini 2.5 Pro
• LLM Interaction: google-genai
• Code Scanning: semgrep (for OWASP Top 10)
• Dependency & IaC Scanning: trivy (by Aqua Security)
• AST Parsing: tree-sitter (for multi-language support)
• Dependency Graph: networkx
• CLI: argparse (Python standard library)
• API: FastAPI, uvicorn