gdit-claude/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a GitLab Docker Images Tracker project designed to monitor, track, and manage Docker images across multiple GitLab repositories with automated vulnerability scanning and lifecycle management.

Project Purpose

This tool addresses the challenge of managing Docker images across numerous GitLab projects by:

1. Discovery & Tracking: Automatically discovers Docker images referenced in:

   • docker-compose*.yml files
   • Dockerfile* files
   • .gitlab-ci*.yml files
   • Across main branches (main, master, develop)

2. Lifecycle Management: Tracks image usage over time to identify:

   • Images currently in use across projects
   • Images that have been removed from files, branches, or projects
   • Images that are no longer referenced anywhere

3. Vulnerability Scanning: Provides periodic vulnerability scanning (configurable intervals) with severity classification:

   • Critical vulnerabilities
   • High severity vulnerabilities
   • Medium severity vulnerabilities
   • Low severity vulnerabilities
   • Unspecified severity vulnerabilities

4. Ignore Management: Offers granular control to exclude from scanning:

   • Specific Docker images
   • Entire files (ignoring all images within)
   • Entire projects (ignoring all files and images within)

5. Reporting: Generates actionable reports showing which images need updates and where they are being used across the GitLab infrastructure.

Core Features

Image Discovery

• Scan GitLab repositories for Docker images in configuration files
• Parse docker-compose*.yml, Dockerfile*, and .gitlab-ci*.yml files
• Track images across main branches (main, master, develop)
• Maintain historical data on image usage patterns

Vulnerability Management

• Real-time vulnerability scanning with Trivy integration
• Vulnerability-to-scan job traceability for complete audit trail
• Severity classification and reporting (Critical, High, Medium, Low, Unspecified)
• Integration with vulnerability databases (NVD API fallback)
• WebSocket-based real-time scan status notifications

Ignore System

• Image-level ignoring: Exclude specific Docker images from scanning
• File-level ignoring: Exclude entire files from image discovery
• Project-level ignoring: Exclude entire projects from scanning
• Maintain ignore lists with reasoning and timestamps

Reporting & Analytics

• Current image inventory across all projects
• Vulnerability status dashboard
• Image lifecycle tracking (active, deprecated, removed)
• Project-specific image usage reports

Project Structure

This is a full-stack application with separated backend and frontend:

├── backend/          # Python backend with FastAPI
│   ├── main.py       # FastAPI application entry point
│   ├── pyproject.toml # Python dependencies and configuration
│   └── README.md     # Backend documentation
└── frontend/         # React + TypeScript frontend
    ├── src/          # React components and application code
    ├── package.json  # Node.js dependencies and scripts
    └── vite.config.ts # Vite build configuration

Technology Stack

• Backend: Python 3.12+ with FastAPI, SQLite database, and python-gitlab
• Frontend: React 19 + TypeScript + Vite + React Router + Tailwind CSS + shadcn/ui
• Database: SQLite for local storage of image inventory, scan results, and configuration
• Real-time Communication: WebSocket integration with Socket.IO for live scan updates
• Vulnerability Scanning: Trivy integration for comprehensive security analysis
• Build Tools: Vite for frontend, Python packaging for backend
• Package Management: uv/pip for Python, Bun for Node.js

Commands

Backend Commands

cd backend
# Install dependencies
uv sync
# Run tests
uv run pytest
# Format code
uv run black .
# Lint code
uv run ruff check .
# Run development server (runs on port 5000)
uv run python main.py

Frontend Commands

cd frontend
# Install dependencies
bun install
# Start development server (runs on port 3000)
bun dev
# Build for production
bun build
# Lint code
bun lint
# Preview production build
bun preview

Architecture Considerations

• Data Models: Projects, Files, Images, Vulnerabilities, ScanJobs, FileImageUsage, IgnoreRules (SQLite schema)
• API Layer: FastAPI REST endpoints with WebSocket support for real-time communication
• Scanning Engine: Asynchronous background job system with concurrent scan prevention
• GitLab Integration: python-gitlab library with group-based filtering for large instances
• Database: SQLite with proper indexing and many-to-many relationships for performance
• Security: Secure handling of GitLab tokens and vulnerability data
• Real-time Updates: WebSocket notifications with persistent connections across page navigation
• Scalability: Design for scanning hundreds of repositories efficiently with group filtering

Key Features Implemented

Real-time Scan Management

• Asynchronous scanning: Non-blocking scans that allow app usage during execution
• Concurrent scan prevention: Only one scan can run at a time to prevent resource conflicts
• WebSocket notifications: Real-time updates with toast notifications using Sonner
• Persistent connection: WebSocket connection maintained across all pages
• Existing scan detection: New users immediately see ongoing scan status

Database Schema

• Many-to-many relationships: FileImageUsage table linking files and images
• Scan job traceability: Vulnerabilities linked to the scan job that detected them
• Full project paths: Projects include complete GitLab path (e.g., utils/services/checkmk)
• Audit trail: Complete tracking of when and how vulnerabilities were discovered

Group-based Filtering

• Environment variable: GITLAB_GROUPS for limiting scans to specific groups
• Large instance support: Essential for GitLab instances with hundreds of projects
• Development-friendly: Allows focusing on relevant projects during development

User Interface

• Real-time status indicators: Connection status and running scan indicators in sidebar
• Toast notifications: Bottom-right positioned for better UX
• Responsive design: Works across different screen sizes with proper layout
• Event-driven updates: Scan jobs page refreshes only when scan events occur