# 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
```bash
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
```bash
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