Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
222 lines (158 loc) · 6.15 KB

CONTRIBUTING.md

File metadata and controls

222 lines (158 loc) · 6.15 KB
Raw

Contributing to OWASP GenAI Security Project - AIBOM Generator

Thank you for your interest in contributing to the OWASP AIBOM Generator! This project is part of the OWASP GenAI Security Project and welcomes contributions from the community.

Quick Start

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR_USERNAME/aibom-generator.git
cd aibom-generator

  3. Set up your environment:

    # Local Python setup
pip install -e '.[dev]'

Development Workflow

Branch Naming

Use descriptive branch names following this pattern:

type/issue-number-description

Types:

  • feat - New features
  • fix - Bug fixes
  • docs - Documentation changes
  • refactor - Code refactoring
  • test - Adding or updating tests

Examples:

  • feat/17-schema-validation
  • fix/13-purl-encoding
  • docs/contributing-guide

Pull Request Process

  1. Create a branch from v0.2 (or main for documentation)
  2. Make your changes with clear, focused commits
  3. Push to your fork and open a PR
  4. Link your PR to any related issues
  5. Respond to review feedback

Commit Messages

Use conventional commits:

type(scope): description

[optional body]

Examples:

  • feat(validation): add CycloneDX 1.6 schema validation
  • fix(generator): correct PURL encoding for model IDs

Code Standards

Python Style

  • Python 3.8+ compatibility required
  • Follow existing patterns in the codebase
  • Use type hints for function signatures

Import Organization

# Standard library
import json
import logging

# Third-party
from cyclonedx.model.bom import Bom
from huggingface_hub import HfApi

# Local imports
from .models.service import AIBOMService
from .utils.validation import validate_aibom

Logging Conventions

Use the Python logging module with module-level loggers:

import logging

logger = logging.getLogger(__name__)

# Use lazy formatting (not f-strings)
logger.info("Processing model: %s", model_id)
logger.warning("Schema validation found %d issues", count)
logger.error("Failed to fetch model: %s", error, exc_info=True)

Project Architecture (v0.2)

aibom-generator/
├── src/
│   ├── main.py               # Application entry point
│   ├── cli.py                # Command-line interface
│   ├── config.py             # Configuration settings
│   ├── controllers/
│   │   ├── cli_controller.py # CLI request handling
│   │   └── web_controller.py # Web/API request handling
│   ├── models/
│   │   ├── service.py        # Core AIBOM generation service
│   │   ├── extractor.py      # Metadata extraction
│   │   ├── registry.py       # Field registry management
│   │   ├── scoring.py        # Completeness scoring
│   │   └── schemas.py        # Pydantic models
│   ├── utils/
│   │   ├── validation.py     # CycloneDX 1.6 schema validation
│   │   ├── license_utils.py  # License normalization
│   │   └── analytics.py      # Usage tracking
│   └── templates/            # HTML templates
├── tests/                    # Unit and integration tests
└── requirements.txt
└── pyproject.toml

Key Concepts

  • Service-oriented architecture: Core logic lives in models/service.py
  • Registry-driven fields: Field definitions from models/registry.py
  • CycloneDX Python Library: BOM serialization, schema validation, and SPDX license handling delegate to cyclonedx-python-lib — avoid manual JSON construction for anything the library supports
  • CycloneDX 1.6 compliance: All AIBOMs validate against the schema via the library's built-in JsonValidator
  • Completeness scoring: Quality metrics in models/scoring.py

Running Tests

# Install test dependencies
pip install -e '.[dev]'

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_validation.py -v

Building and Running

Local Development (Recommended)

pip install -e '.[dev]'

# Run API server
python -m uvicorn src.main:app --reload --port 7860

# Or use CLI
python -m src.cli --model_id "microsoft/DialoGPT-medium"

Updating Dependencies

pyproject.toml is the source of truth for all dependencies. requirements.txt is a generated artifact derived from it and must be kept in sync.

After adding or removing a dependency in pyproject.toml, regenerate requirements.txt and sync the lock file:

uv pip compile pyproject.toml -o requirements.txt
uv lock

Commit pyproject.toml, requirements.txt, and uv.lock together.

Areas Welcoming Contributions

We especially welcome contributions in these areas:

  • SPDX 3.1 export - Add support for SPDX AI Profile format
  • Model-specific extractors - Better metadata extraction for specific model types
  • Documentation - Improve guides, examples, and API docs
  • UI/UX enhancements - Improve the web interface
  • Test coverage - Expand unit and integration tests
  • Performance optimization - Faster extraction and generation

Reporting Issues

Before creating an issue:

  1. Search existing issues to avoid duplicates
  2. Use a clear, descriptive title
  3. For bugs, include:
    • Steps to reproduce
    • Expected vs actual behavior
    • Model ID if applicable
    • Error messages

Issue tracker: GitHub Issues

License

This project is licensed under the Apache License 2.0. By contributing, you agree that your contributions will be licensed under the same license.

Community

Thank you for helping make AI transparency practical!