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

• Periodic vulnerability scanning (configurable schedule)
• Severity classification and reporting
• Integration with vulnerability databases
• Automated alerting for critical vulnerabilities

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
• 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, Ignore Rules (SQLite schema)
• API Layer: FastAPI REST endpoints for frontend communication
• Scanning Engine: Background job system for repository scanning
• GitLab Integration: python-gitlab library for repository and branch access
• Database: SQLite with proper indexing for performance
• Security: Secure handling of GitLab tokens and vulnerability data
• Scalability: Design for scanning hundreds of repositories efficiently