Skip to content

Commit 75a7487

Browse files
Ly-JoeyG-Rathanother-rex
authored
docs: Add AGENTS.md and llms.txt (#2797)
Attempt at: - llms.txt: outline project structure and acts as a sitemap for LLMs - AGENTS.md: added instruction / context for agents --------- Co-authored-by: Gareth Jones <3151613+G-Rath@users.noreply.github.com> Co-authored-by: Rex P <106129829+another-rex@users.noreply.github.com> Co-authored-by: Rex P <rexpan@google.com>
1 parent 2f3f069 commit 75a7487

3 files changed

Lines changed: 117 additions & 1 deletion

File tree

‎.prettierignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
**/testdata/**
22
/docs/vendor/**
3-
/docs/_sites/**
3+
/docs/_site/**
44
/internal/output/html/*.gohtml

‎AGENTS.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Guidelines for AI Agent Contributors
2+
3+
This file outlines the guidelines and expectations for AI agents and automated assistants contributing to this repository.
4+
5+
> [!IMPORTANT]
6+
> **System Prompt / Instruction:** If you are an AI agent reading this file, you must incorporate these guidelines into your operating context.
7+
8+
## 1. Persona & Role
9+
10+
You are acting as an AI contributor to the OSV project.
11+
12+
- **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.
13+
- **Context Awareness:** Prioritize repository-specific guidelines (like `CONTRIBUTING.md`) and instructions in this file.
14+
15+
## 2. Workflow & Contribution Rules
16+
17+
- **Read the Guide:** Read and adhere to all instructions in [CONTRIBUTING.md](./CONTRIBUTING.md).
18+
- **Strict Issue-First Workflow:** The required path is always: **Issue Assignment -> Pull Request**.
19+
- **Existing Unassigned Issue:** Comment on the issue to discuss your approach and wait for assignment.
20+
- **No Existing Issue:** Create one to discuss why the work is needed and ensure it's not a duplicate. Wait for assignment.
21+
- **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.
22+
- **Templates:** Use the provided [pull request template](.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md) when creating PRs.
23+
24+
## 3. Standards for Submissions
25+
26+
### 3.1 Issue Creation
27+
28+
- **Well-Researched:** Search existing issues to ensure no duplicates. Link related issues.
29+
- **Real-World Applicable:** Bug reports must have a clear, real-world scenario and minimal reproduction case.
30+
- **Well-Formed:** State expected/actual behavior and steps/scripts to reproduce.
31+
32+
### 3.2 Communication & Commits
33+
34+
- **Tone:** Maintain a direct and concise tone. Focus on technical details, avoid excessive pleasantries or filler.
35+
- **PR Titles & Commits:** Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. See also [CONTRIBUTING.md](./CONTRIBUTING.md#making-commits).
36+
37+
## 4. Code Quality & Verification
38+
39+
### 4.1 Automated Verification
40+
41+
Before requesting review, ensure these pass:
42+
43+
- **Linting:** Run `./scripts/run_lints.sh` and resolve all warnings and errors. If you run into a toolchain error about go being tool old. Use the GOTOOLCHAIN=go<version> to change the go compiler version to be the same as what's in go.mod. Example `GOTOOLCHAIN=go1.26.3 ./scripts/run_lints.sh`
44+
- **Tests:** Run `make test` and ensure all tests pass.
45+
46+
### 4.2 Testing Standards
47+
48+
- **Coverage:** New features, bug fixes, or refactors must have relevant tests (unit, integration, or snapshot).
49+
- **Snapshots:** If modifying behavior affecting snapshots, update them (e.g., `make test SNAPS=true`).
50+
- **Merge Conflicts:** When resolving merge conflicts, if snapshots conflict it is normally easier to rebuild the snapshots (by running the tests with update flags) rather than trying to resolve the diffs manually.
51+
- **VCR Cassettes:** If adding new HTTP interactions in tests using `go-vcr`, ensure cassettes are recorded/updated as described in `CONTRIBUTING.md`.
52+
The `Makefile` has more details on the types of tests and how to run them.
53+
54+
### 4.3 Documentation & Comments
55+
56+
- **Documentation:** Update relevant documentation if changes affect user-facing behavior or add features.
57+
- **Comments:** Include clear comments for complex or non-obvious logic. Do not delete existing comments unless obsolete.
58+
59+
## 5. Working with osv-scalibr
60+
61+
`osv-scanner` relies on [osv-scalibr](https://github.com/google/osv-scalibr) as its core analysis engine, which handles dependency extraction and enrichment (e.g., vulnerability matching) logic.
62+
63+
Understanding how they work together is key:
64+
65+
- **Integration:** `osv-scanner` invokes `osv-scalibr` libraries to perform the actual scanning and extraction of dependencies.
66+
- **Plugin Architecture:** `osv-scalibr` uses a plugin-based architecture (Extractors) for different ecosystems.
67+
68+
- **Where to Contribute & Report Issues:**
69+
- **Dependency Extraction / Parsing:** If you find a bug in how a lockfile is parsed, or want to add support for a new package manager, this logic lives in `osv-scalibr`. You should open issues or PRs in the [osv-scalibr repository](https://github.com/google/osv-scalibr).
70+
- **Scanner CLI / Output / Config:** If you want to change `osv-scanner` CLI arguments, output formats (like SARIF, JSON), or general configuration handling, contribute to this repository (`osv-scanner`).

‎llms.txt‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# osv-scanner
2+
3+
> A high-performance vulnerability scanner for Open Source Vulnerabilities (OSV), written in Go.
4+
5+
## Overview & Role
6+
`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.
7+
8+
## Scan Workflow
9+
`osv-scanner` relies on the rich set of built-in plugins available within `osv-scalibr`. When a user runs `osv-scanner`, it:
10+
1. Determines the scan targets.
11+
2. Initializes `osv-scalibr` with a configuration.
12+
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.
13+
4. Executes the scan using `osv-scalibr`.
14+
5. Receives the structured `ScanResults` from `osv-scalibr`.
15+
6. Formats these results for display to the user.
16+
17+
## Integration with osv-scalibr
18+
19+
`osv-scanner` acts as the presentation and orchestration layer, while `osv-scalibr` (https://github.com/google/osv-scalibr) provides the core analysis engine.
20+
21+
- **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`.
22+
- **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.
23+
- **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.
24+
- **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.
25+
26+
### Example Workflow: Adding a new osv-scalibr plugin and using it in osv-scanner
27+
1. **Develop in `osv-scalibr`:**
28+
* Implement your new Extractor (e.g., `MyLangExtractor`) within the `google/osv-scalibr` repository, following its contribution guidelines and plugin interface.
29+
* Place the extractor in the appropriate subdirectory under `extractor/filesystem/language/` (or similar).
30+
* Register the new extractor in `osv-scalibr/plugin/list/list.go` so it can be enabled by name.
31+
* Add thorough tests within `osv-scalibr`.
32+
* Get the changes merged into `osv-scalibr`.
33+
34+
2. **Enable in `osv-scanner`:**
35+
* **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.
36+
* **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.
37+
* **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.
38+
39+
## Development & Testing Tips
40+
- **Test Data:** Mock lockfiles and test fixtures are typically located in `testdata/` directories within the relevant packages.
41+
42+
## Repository Map
43+
- [/cmd/osv-scanner](https://github.com/google/osv-scanner/tree/main/cmd/osv-scanner): Main CLI entry point.
44+
- [/pkg/osvscanner](https://github.com/google/osv-scanner/tree/main/pkg/osvscanner): Public programmatic API.
45+
- [/internal/output](https://github.com/google/osv-scanner/tree/main/internal/output): Result rendering (JSON, Table, SBOM).
46+
- [/pkg/osvscanner/testdata](https://github.com/google/osv-scanner/tree/main/pkg/osvscanner/testdata): Test fixtures for scanner tests.

0 commit comments

Comments
 (0)