Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
257 lines (178 loc) · 10.9 KB

CONTRIBUTING.md

File metadata and controls

257 lines (178 loc) · 10.9 KB

Contributing to agent-bom

agent-bom has 7,000+ monthly installs. Every contribution directly improves security for real AI agent deployments. This guide gets you from zero to merged PR.

The best ways to help:

  • Try the demo and open issues for confusing output, missing context, or weak remediation.
  • Request integrations for MCP clients, coding agents, CI systems, cloud providers, and security workflows you actually use.
  • Pick a good first issue or help wanted task and comment before starting.
  • Improve docs, screenshots, diagrams, and first-run examples when something is unclear.
  • Star, share, or recommend the project when agent-bom gives you useful evidence; community signal helps security teams trust an open tool.

Table of contents

Quick start

git clone https://github.com/msaad00/agent-bom.git
cd agent-bom
uv sync --extra dev-all
uv run pre-commit install                          # wires ruff + ruff-format hooks
uv run pytest tests/ -x -q                         # must be green before you start

That's it. agent-bom agents now runs from your local checkout. Use uv sync --extra dev only for a lighter core workflow; dev-all is the supported full-suite contributor setup.

What to work on

Easiest — good first issues

Browse good first issue on GitHub. No architecture knowledge required.

Typical good-first tasks:

  • Add an MCP client — 5–15 lines in src/agent_bom/discovery/__init__.py. Each entry is a dict with a config path and parser.
  • Add a registry entry — Add a JSON object to mcp_registry.json (schema in config/schemas/).
  • Fix a test — search for # TODO or pytest.mark.skip in tests/.
  • Improve a docstring — Any function in src/agent_bom/ without a clear docstring.

Medium — help wanted

Browse help wanted.

Typical help-wanted tasks:

  • New package ecosystem parsers — Ruby Gemfile.lock, .NET packages.lock.json, Swift Package.resolved
  • Cloud CIS benchmark — GCP or Azure module following the pattern in src/agent_bom/cloud/
  • Dashboard improvements — Next.js components in ui/ (TypeScript, Tailwind)
  • Output format — New --format target (CSV, Markdown table, etc.) in src/agent_bom/output/

Critical — P0 issues

See open issues labeled P0 for the most impactful work. These close core coverage gaps (OS-level scanning, container image analysis, CWE enrichment, IaC misconfiguration, compliance frameworks). Comment on the issue before starting — these require coordination.

Priority — P1 features

See open issues labeled P1 for high-impact work that's well-scoped and ready to pick up.

Development workflow

Start with AGENTS.md when using assistant or agent workflows in this repo. It captures the product, security, verification, and release lenses that should be applied alongside this contributor guide.

# Create a branch
git checkout -b feat/your-feature   # or fix/your-fix

# Make your changes, then run:
uv run ruff check src tests --fix   # lint + autofix
uv run ruff format src tests        # formatting
uv run pytest tests/ -x -q          # full suite must stay green

# Pre-commit hooks do this automatically on commit
git add -p                          # stage intentionally
git commit -m "feat: your message"
gh pr create --base main            # or push + open PR on GitHub

Branch naming: feat/, fix/, docs/, chore/ prefixes. Always branch from and PR to main.

Important PR update rule

Do not use GitHub's Update branch button on active PRs unless the PR is actually non-mergeable and you cannot refresh it locally.

If GitHub only says "This branch is out-of-date with the base branch", that does not automatically mean there is a conflict. In this repo, that banner is informational unless merge protection explicitly blocks on being current with main.

Preferred path:

scripts/refresh-pr-branch.sh your-branch

Why:

  • GitHub's synthetic merge head can leave PRs in a bad check state where expected checks never attach cleanly
  • a real locally pushed head is more reliable for CI, branch protection, and debugging

If a PR ever shows "no checks reported", "expected" checks with no attached run, or obviously stale check-rollup state after an update, replace the branch head with a clean local rebase instead of retrying the GitHub button again.

Manual equivalent:

git fetch origin
git checkout your-branch
git rebase origin/main
git push --force-with-lease origin your-branch

Tests

uv run pytest tests/ -x -q          # all tests, stop on first fail
uv run pytest tests/ -k "scanner" -v
uv run pytest tests/test_core.py -v

Rules:

  • Every new feature needs at least one test.
  • Every bug fix needs a regression test that fails without the fix and passes with it. This is enforced during code review — PRs that fix bugs without a regression test will be asked to add one. Over 90% of historical fix: commits include regression tests.
  • Network tests (hitting real APIs) are marked @pytest.mark.network and skipped in CI. Use mocks for unit tests.
  • The test suite must stay green. Pre-existing failures are bugs, not technical debt.
  • Coverage floor: CI enforces a minimum statement coverage threshold (currently 73%, target 80% per #529). PRs that drop coverage below the floor will fail CI.

Test layout:

Directory What it tests
tests/test_core.py CLI commands, report generation
tests/test_scanner_ecosystems.py OSV ecosystem mapping
tests/test_nvidia_advisory.py NVIDIA CSAF advisory enrichment
tests/test_accuracy_baseline.py Known-vuln packages always detected (network)
tests/test_runtime_*.py Proxy, detectors, patterns
tests/test_api_*.py REST API endpoints

Code style

  • Formatter: ruff format (Black-compatible, line length 120)
  • Linter: ruff check — all rules in pyproject.toml
  • Types: Type hints on all new public functions. mypy is run in CI.
  • No print() — use console.print() (Rich) in CLI code, logging in library code.
  • No stubs or vaporware — only document and claim features that are implemented and tested.
  • Shell scripts: every script must enable strict mode at the top. Bash scripts (#!/usr/bin/env bash or #!/bin/bash) must use set -euo pipefail. POSIX sh scripts (#!/bin/sh) must use set -eu — pipefail is a non-POSIX extension and is intentionally omitted on sh shebangs to keep endpoint installers (Jamf, Kandji, Alpine ash) portable.

Pre-commit hooks enforce ruff on every commit. Install once with pre-commit install.

Dependency updates

Dependency updates are part of the shipped product surface, not background noise.

Review bar

  • Patch and minor updates still need green CI, security scan, and release-surface alignment.
  • Major updates need a short human review of upstream release notes before merge.
  • If an update changes user-visible behavior, contracts, runtime assumptions, or packaging, call that out in the PR body and release notes where applicable.
  • Do not merge “green but unexplained” upgrades. We should be able to say what changed, why it is safe, and what we validated.

For Dependabot and manual upgrade PRs include

  • the package and version change
  • whether it is patch, minor, or major
  • any breaking-change risk or notable upstream release-note items
  • what was validated locally or in CI
  • whether docs, examples, pins, or release-managed files also needed updating

This keeps update history readable for operators and makes package maintenance look intentional rather than accidental.

Submitting a PR

  1. Branch from main and name it feat/, fix/, docs/, or chore/.
  2. All tests pass: uv run pytest tests/ -x -q
  3. Lint clean: uv run ruff check src tests && uv run ruff format --check src tests
  4. PR description: one-sentence summary, what changed, how to test it. If the PR resolves a GitHub issue, include Closes #<issue-number> in the PR body — GitHub will auto-close the issue when the PR merges.
  5. One review required — a maintainer will review within a few days.

By submitting a pull request, you certify that your contribution is made under the terms of the Apache-2.0 license and that you have the right to submit it under those terms (Developer Certificate of Origin).

CI checks that run on every PR:

  • pytest (all tests)
  • ruff check + ruff format --check
  • mypy type check
  • Version alignment (all version strings must match)
  • Docker build

Commit style: type: short description — types: feat, fix, docs, chore, refactor, test.

For dependency PRs, prefer a one-line summary in the body such as:

Upgrade type: minor
Release notes reviewed: yes
Breaking changes expected: no
Validation: CI + targeted local tests

Architecture overview

See docs/ARCHITECTURE.md for system diagrams and the full module map.

5 products, 1 package: agent-bom (BOM + scanning), agent-shield (runtime protection), agent-cloud (cloud posture), agent-iac (IaC security), agent-claw (fleet governance). All share the same core engine.

Pipeline at a glance: discover MCP configs → parse packages → scan via OSV/NVD/GHSA → enrich (EPSS + KEV) → blast radius → compliance tag → output.

Honesty rule

Only document and claim features that are actually implemented and tested. Do not add stubs, placeholders, or roadmap items as shipping features.

Version bump

Use scripts/bump-version.py. It updates the release-managed version surfaces in one go. See docs/PUBLISHING.md for the full release checklist.

Developer Certificate of Origin

All contributions must include a Signed-off-by line (git commit -s). By signing, you certify you have the right to submit the work under the Apache 2.0 license per DCO v1.1.

Security reports

Please do not open a public issue for security vulnerabilities. Use GitHub Security Advisories or email andwgdysaad@gmail.com. We aim to respond within 48 hours.