truf-server/openspec/changes/stabilize-and-widen-scanner-coverage/specs/source-discovery-targeting/spec.md

ADDED Requirements

Requirement: Metadata Discovery Uses High-Signal Queries

Repository, package, and image metadata discovery SHALL prefer provider names, API hosts, framework names, and ecosystem terms over generic secret-related words.

Scenario: Repo metadata query list is reviewed

• WHEN default repository or package metadata queries are configured
• THEN broad terms such as api_key, secret, and token SHALL NOT be added by default unless the source searches content rather than metadata

Scenario: Provider query is configured

• WHEN a provider such as Qwen, DashScope, Groq, or OpenRouter is targeted
• THEN provider names, API hostnames, and framework terms SHALL be eligible for metadata discovery queries

Requirement: Exact Secret Terms Reserved For Content-Oriented Sources

Exact environment variable and API host searches SHALL be used for content-oriented sources such as Postman/API artifacts, code search, and CI artifacts rather than generic metadata searches.

Scenario: Env var search term is added

• WHEN an exact term such as DASHSCOPE_API_KEY is added to discovery
• THEN it SHALL be applied to a source that can inspect file or artifact content

Requirement: Package Git Repository Canonicalization

package_git discovery SHALL canonicalize repository URLs from package metadata before queueing targets.

Scenario: Package metadata contains issue URL

• WHEN package metadata contains a repository-like URL ending in /issues
• THEN package_git discovery SHALL normalize it to the canonical repository URL when possible

Scenario: Package metadata contains repository URL variants

• WHEN package metadata contains .git, branch, tree, or homepage variants for the same repository
• THEN package_git discovery SHALL avoid queueing duplicate normalized repository targets

Requirement: CI Seed Parsing From Existing Data

GitHub Actions and GitLab CI target discovery SHALL parse repository/project seeds from existing scanner DB records, package git candidates, findings, and target scan metadata where possible.

Scenario: Seed record contains package git target JSON

• WHEN a CI source examines a package git candidate or target scan record with repository metadata
• THEN it SHALL derive a GitHub repository or GitLab project seed when the URL provider matches the CI source

Scenario: Seed record cannot identify repository

• WHEN no repository or project can be derived from a seed record
• THEN the CI source SHALL count it as unparseable and continue processing other seeds

Requirement: CI Scan Volume Is Configurable

CI source scan volume SHALL remain controlled by existing per-source configuration values.

Scenario: CI seed limit is raised

• WHEN ci_seed_scan_limit or ci_max_repos_per_cycle is increased in configuration
• THEN the CI source SHALL use the configured value without requiring code changes