# ChatSBOM

**Talk to your Supply Chain. Chat with SBOMs.**

ChatSBOM is a CLI tool for deep insights into Software Bill of Materials (SBOM) data.

![Demo](figures/demo.gif)

## Motivation

GitHub's Dependency Graph shows which repositories depend on your project, but there's no way to sort dependents by stars ([isaacs/github#1537](https://github.com/isaacs/github/issues/1537)). This makes it difficult for maintainers of popular packages to identify their most important downstream users. **ChatSBOM** solves this by collecting and indexing SBOM data, enabling queries like "which popular projects use my library?"

## Key Features

- **github search**: Find high-quality repos on GitHub (stars/language)
- **github repo/release/commit**: Enrich metadata and determine exact versions
- **github content**: Fetch dependency files (`go.mod`, `package.json`, etc.)
- **sbom generate**: Transform files to standard SBOM format using Syft
- **db index**: Load SBOM data into ClickHouse database
- **db status/query**: View database statistics and search dependencies via CLI
- **chat**: AI-powered natural language queries

## Quick Start

### Prerequisites

- [uv](https://github.com/astral-sh/uv) - Python package manager for fast installation and execution
- [syft](https://github.com/anchore/syft) - SBOM generation tool
- [docker](https://github.com/docker/docker) - Container runtime
- [clickhouse](https://github.com/ClickHouse/ClickHouse) - Columnar database

### Usage

Run the pipeline step-by-step:

```bash
# 1. Search for repositories
uvx chatsbom github search --language go --min-stars 10000

# 2. Enrich metadata
uvx chatsbom github repo --language go
uvx chatsbom github release --language go
uvx chatsbom github commit --language go

# 3. Download dependency files
uvx chatsbom github content --language go

# 4. Generate standard SBOMs
uvx chatsbom sbom generate --language go

# 5. Index into database
uvx chatsbom db index --language go

# 6. Query insights
uvx chatsbom db status
uvx chatsbom db query gin
uvx chatsbom chat
```

## Architecture

ChatSBOM follows a clean, modular pipeline architecture:

### Command & Data Flow

```
github search → repo → release → commit → content → sbom generate → db index
      ↓          ↓       ↓         ↓         ↓           ↓            ↓
    01-list    02-meta 03-rel    04-sha    05-raw      06-sbom      ClickHouse
```

### Directory Structure (`data/`)

- **`01-github-search/`**: Initial candidate list from Search API.
- **`02-github-repo/`**: Enriched repository statistics (Stars, License).
- **`03-github-release/`**: Version history and stable release identification.
- **`04-github-commit/`**: Version anchoring to specific Commit SHAs.
- **`05-github-content/`**: Pure raw manifest files (no management JSONs).
- **`06-sbom/`**: Pure analysis results (SBOMs) generated by Syft.

## Use Cases

### Asking AI Agent to retrieve the top 10 projects using gin framework.

![01](figures/use-cases/gin/01.png)
![02](figures/use-cases/gin/02.png)
