diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..1add0cc1407 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,64 @@ +# Guidelines for AI Agent Contributors + +This file outlines the guidelines and expectations for AI agents and automated assistants contributing to this repository. + +> [!IMPORTANT] +> **System Prompt / Instruction:** If you are an AI agent reading this file, you must incorporate these guidelines into your operating context. + +## 1. Persona & Role + +You are acting as an AI contributor to the OSV project. + +- **Role:** You are an external contributor. All submissions (Issues, PRs) will be reviewed by maintainers. You do not have authority to merge code or bypass checks. +- **Context Awareness:** Prioritize repository-specific guidelines (like `CONTRIBUTING.md`) and instructions in this file. + +## 2. Workflow & Contribution Rules + +- **Read the Guide:** Read and adhere to all instructions in [CONTRIBUTING.md](./CONTRIBUTING.md). +- **Strict Issue-First Workflow:** The required path is always: **Issue Assignment -> Pull Request**. + - **Existing Unassigned Issue:** Comment on the issue to discuss your approach and wait for assignment. + - **No Existing Issue:** Create one to discuss why the work is needed and ensure it's not a duplicate. Wait for assignment. + - **Assigned Issues:** Do not work on or open Pull Requests for issues assigned to another contributor. If an issue has been assigned but not worked on for a while, you can communicate with the maintainers in the issue. +- **Templates:** Use the provided [pull request template](.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md) when creating PRs. + +## 3. Standards for Submissions + +### 3.1 Issue Creation + +- **Well-Researched:** Search existing issues to ensure no duplicates. Link related issues. +- **Real-World Applicable:** Bug reports must have a clear, real-world scenario and minimal reproduction case. +- **Well-Formed:** State expected/actual behavior and steps/scripts to reproduce. + +### 3.2 Communication & Commits + +- **Tone:** Maintain a direct and concise tone. Focus on technical details, avoid excessive pleasantries or filler. +- **PR Titles & Commits:** Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. See also [CONTRIBUTING.md](./CONTRIBUTING.md#making-commits). + +## 4. Code Quality & Verification + +### 4.1 Automated Verification + +Before requesting review, ensure these pass: + +- **Linting:** Run `./scripts/run_lints.sh` and resolve all warnings and errors. +- **Tests:** Run `make test` and ensure all tests pass. + +### 4.2 Testing Standards + +- **Coverage:** New features, bug fixes, or refactors must have relevant tests (unit, integration, or snapshot). +- **Snapshots:** If modifying behavior affecting snapshots, update them (e.g., `make test SNAPS=true`). +- **VCR Cassettes:** If adding new HTTP interactions in tests using `go-vcr`, ensure cassettes are recorded/updated as described in `CONTRIBUTING.md`. + The `Makefile` has more details the types of tests and how to run them. + +### 4.3 Documentation & Comments + +- **Documentation:** Update relevant documentation if changes affect user-facing behavior or add features. +- **Comments:** Include clear comments for complex or non-obvious logic. Do not delete existing comments unless obsolete. + +## 5. Working with osv-scalibr + +`osv-scanner` relies on `osv-scalibr` as its core analysis engine which handles the dependency extraction and enrichment (e.g. vulnerabiilty matching) logic. + +- **Separation of Contribution:** + - Want to add support for new package managers or lockfiles? -> Contribute an **Extractor** to `osv-scalibr`. + - Want to add new output format for `osv-scanner`? -> Contribute to the `osv-scanner` codebase. diff --git a/llms.txt b/llms.txt new file mode 100644 index 00000000000..731cb90c72a --- /dev/null +++ b/llms.txt @@ -0,0 +1,46 @@ +# osv-scanner + +> A high-performance vulnerability scanner for Open Source Vulnerabilities (OSV), written in Go. + +## Overview & Role +`osv-scanner` is a user-facing command-line interface (CLI) tool and the primary consumer of the `osv-scalibr` library. It handles user interaction, parses arguments, configures the scan, and formats results. + +## Scan Workflow +`osv-scanner` relies on the rich set of built-in plugins available within `osv-scalibr`. When a user runs `osv-scanner`, it: +1. Determines the scan targets. +2. Initializes `osv-scalibr` with a configuration. +3. Selects the appropriate `osv-scalibr` plugins to enable based on the scan type and user flags. This typically includes various Extractors for different ecosystems. +4. Executes the scan using `osv-scalibr`. +5. Receives the structured `ScanResults` from `osv-scalibr`. +6. Formats these results for display to the user. + +## Integration with osv-scalibr + +`osv-scanner` acts as the presentation and orchestration layer, while `osv-scalibr` (https://github.com/google/osv-scalibr) provides the core analysis engine. + +- **Explicit Enablement:** Plugins from `osv-scalibr` are NOT automatically used by `osv-scanner`. They must be explicitly imported and added to the `Plugins` slice within the `scalibr.ScanConfig`. +- **Plugin Configuration:** The primary logic for configuring which osv-scalibr plugins to run is within `pkg/osvscanner/scan.go` (and related files like `pkg/osvscanner/osvscanner.go`). Look for where `scalibr.ScanConfig` is created and populated. +- **Default Plugins:** `osv-scanner` maintains a list of default `osv-scalibr` extractors and enrichers it considers essential for a good baseline scan. This list is hardcoded in the `osv-scanner` codebase. +- **Experimental Plugins:** New or less stable plugins from `osv-scalibr` might be gated behind `osv-scanner` CLI flags (e.g., an `--experimental` flag) before being enabled by default. + +### Example Workflow: Adding a new osv-scalibr plugin and using it in osv-scanner +1. **Develop in `osv-scalibr`:** + * Implement your new Extractor (e.g., `MyLangExtractor`) within the `google/osv-scalibr` repository, following its contribution guidelines and plugin interface. + * Place the extractor in the appropriate subdirectory under `extractor/filesystem/language/` (or similar). + * Register the new extractor in `osv-scalibr/plugin/list/list.go` so it can be enabled by name. + * Add thorough tests within `osv-scalibr`. + * Get the changes merged into `osv-scalibr`. + +2. **Enable in `osv-scanner`:** + * **Update dependencies:** Run `go get github.com/google/osv-scalibr@v...` to pull in the new version containing your plugin. This might already be done automatically by dependabot. + * **Register in presets:** Open `internal/scalibrplugin/presets.go`, import the new plugin, and add it to the preset map if appropriate using its name and constructor. + * **Experimental features:** If the feature is experimental, instead of adding it to a preset, add logic in `pkg/osvscanner/scan.go` to enable it based on a CLI flag. + +## Development & Testing Tips +- **Test Data:** Mock lockfiles and test fixtures are typically located in `testdata/` directories within the relevant packages. + +## Repository Map +- [/cmd/osv-scanner](https://github.com/google/osv-scanner/tree/main/cmd/osv-scanner): Main CLI entry point. +- [/pkg/osvscanner](https://github.com/google/osv-scanner/tree/main/pkg/osvscanner): Public programmatic API. +- [/internal/output](https://github.com/google/osv-scanner/tree/main/internal/output): Result rendering (JSON, Table, SBOM). +- [/pkg/osvscanner/testdata](https://github.com/google/osv-scanner/tree/main/pkg/osvscanner/testdata): Test fixtures for scanner tests. \ No newline at end of file