127 lines
4.5 KiB
Markdown
127 lines
4.5 KiB
Markdown
# 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
|
|
```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, 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 |