dependencyiq 2.0.0 → 2.2.0

package/README.md

@@ -0,0 +1,374 @@
+# DependencyIQ
+
+**A multi-language dependency-vulnerability agent for GitLab — built on GitLab Orbit and the GitLab Duo Agent Platform.**
+
+DependencyIQ does not just tell you a package is vulnerable. It tells you whether that vulnerability is *real risk for your code*, what breaks if you upgrade, whether the dependency is dead weight that should be deleted, and — when you ask it to — it applies the fix and opens the merge request itself. The intelligence is grounded in GitLab Orbit's import graph, not in guesses.
+
+---
+
+## Table of contents
+
+- [What it is](#what-it-is)
+- [The problem it solves](#the-problem-it-solves)
+- [How it works end to end](#how-it-works-end-to-end)
+- [Architecture](#architecture)
+- [The engine (`src/`)](#the-engine-src)
+- [Risk scoring](#risk-scoring)
+- [Orbit blast-radius analysis](#orbit-blast-radius-analysis)
+- [Remediation logic](#remediation-logic)
+- [The GitLab Duo integration](#the-gitlab-duo-integration)
+- [Distribution: the `dependencyiq` npm package](#distribution-the-dependencyiq-npm-package)
+- [CI/CD pipeline](#cicd-pipeline)
+- [The live dashboard](#the-live-dashboard)
+- [Configuration (`AGENTS.md`)](#configuration-agentsmd)
+- [Using it in your own project](#using-it-in-your-own-project)
+- [CLI reference](#cli-reference)
+- [Key design decisions and why](#key-design-decisions-and-why)
+- [Testing](#testing)
+- [Requirements](#requirements)
+- [License](#license)
+
+---
+
+## What it is
+
+DependencyIQ is one tested engine exposed through several surfaces:
+
+- A **command-line engine** (`dependencyiq`, published to npm) that scans, scores, plans, fixes, and reports.
+- **Custom Chat Agents** on the GitLab Duo Agent Platform — an interactive control surface for triage and remediation.
+- An **ambient Custom Flow** — an autonomous, event-triggered pipeline that runs the engine in CI/CD and opens a remediation merge request.
+- An **Agent Skill** — a slash-command / natural-language entry point in Duo Chat.
+- A **live dashboard** published to GitLab Pages.
+
+Every surface calls the same engine. The logic exists once.
+
+## The problem it solves
+
+Every scanner can say "this package has a CVE." Almost none can answer what actually matters next:
+
+- **Is this real risk?** A high CVSS score on a package that only your test fixtures import is not the same as one your public API depends on.
+- **What breaks if we upgrade?** One file, or forty, with a breaking change baked into a major version bump?
+- **Can we just delete it?** If nothing in your codebase actually imports a package, patching its CVE is wasted effort — removing it is the fix.
+- **Across every language at once.** A single repository can mix npm, PyPI, Go, Maven, and more; each needs its own toolchain.
+
+Answering these by hand means grepping the codebase, reading changelogs, and writing the fix yourself, for every vulnerable package, in every ecosystem. DependencyIQ does it instead, grounded in real import-graph evidence.
+
+## How it works end to end
+
+```
+Scan ─► Score ─► Plan ─► Fix ─► Verify ─► Track ─► Report
+ │       │        │       │       │         │         │
+ OSV-    Orbit    impact  per-    tests    GitLab    summary
+ Scanner blast    report  eco     run      issues/   + clean
+ (any    radius   + migra system  +        MR notes  comment
+ eco)    + risk   -tion   fixers  pipeline + plans
+         score    plan            tools
+```
+
+1. **Scan** — OSV-Scanner reads every manifest/lockfile present and reports known vulnerabilities across all ecosystems in one pass.
+2. **Score** — each finding is combined with real Orbit exposure data and a usage count, minus a test-coverage discount, into a 0–100 risk score.
+3. **Plan** — for the top finding, an Upgrade Impact Report estimates affected files, semver distance, breaking-change risk, and effort, and produces an ordered migration plan.
+4. **Fix** — the appropriate per-ecosystem fixer edits the manifest (version bump, transitive override, or removal) and commits the change.
+5. **Verify** — the test suite runs; failures are surfaced and the remediation is marked blocked if anything breaks.
+6. **Track** — the work becomes visible GitLab artifacts: a tracking issue, MR notes carrying the evidence, and a task plan for follow-ups.
+7. **Report** — a concise, honest summary is posted where the run was triggered.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        Entry points                          │
+│   Chat Agents      Ambient Flow      Agent Skill      CLI     │
+│   (interactive)    (autonomous CI)   (Duo Chat)    (terminal) │
+└───────────────┬──────────────┬─────────────┬──────────────┬──┘
+                └──────────────┴─────────────┴──────────────┘
+                                  │
+                                  ▼
+              ┌───────────────────────────────────────┐
+              │   The engine — `dependencyiq` CLI     │
+              │   (src/agent.js + modules)            │
+              └───────────────────┬───────────────────┘
+                                  │
+        ┌──────────────┬──────────┴───────────┬───────────────┐
+        ▼              ▼                       ▼               ▼
+   OSV-Scanner   GitLab Orbit            GitLab REST     Package
+   (scan)        (import graph)          (commits, MRs,  registries
+                                          issues, vulns)  (freshness)
+```
+
+Directory map:
+
+```
+src/                                # the engine
+├── agent.js                        # CLI entry point and orchestrator
+├── scanners/
+│   ├── osvScanner.js               # multi-ecosystem vulnerability scan
+│   ├── cvss.js                     # CVSS v3 base score from a vector string
+│   ├── manifestParser.js           # lists every direct dependency
+│   ├── dependencyTreeBuilder.js    # direct-vs-transitive resolution
+│   ├── ecosystemFixers.js          # per-ecosystem bump / override / remove
+│   └── supplyChainTrustSignals.js  # maintainer-compromise signals
+├── orbitClient.js                  # REST client for the Orbit API
+├── blastRadius.js                  # single-project exposure analysis
+├── riskCalculator.js               # the 0–100 risk score + dead-dep detection
+├── impactReport.js                 # affected files + semver + effort estimate
+├── upgradeImpactSimulator.js       # three remediation strategies
+├── strategyGenerator.js            # markdown templates (plans, MR descriptions)
+├── freshnessChecker.js             # registry lookups + stability-aware version
+├── freshnessPolicy.js              # enforces AGENTS.md freshness thresholds
+├── configLoader.js                 # parses the AGENTS.md config block
+├── prGenerator.js                  # commits the fix + opens the merge request
+├── remoteFixer.js                  # patch a manifest via the API (no checkout)
+├── crossProjectFanOut.js           # group-wide emergency response
+├── mrReviewer.js                   # safety-review incoming dependency MRs
+├── executiveSummary.js             # leadership-facing roll-up
+├── dashboardGenerator.js           # static HTML dashboard
+├── fleet*.js                       # cross-project aggregation
+├── activityFetcher.js              # live "agent activity" feed
+├── gitlabAuth.js                   # token resolution (GITLAB_TOKEN / CI_JOB_TOKEN)
+└── httpRetry.js                    # shared retry/backoff for HTTP calls
+
+.gitlab/duo/
+├── agent-config.yml                # flow execution environment
+├── mcp.json                        # connects the Orbit MCP server
+├── agents/                         # the Custom Chat Agent definitions
+└── flows/                          # the ambient Custom Flow definition
+
+skills/dependency-analysis/SKILL.md # the Agent Skill
+scripts/validate-config.js          # CI guard for the Duo agent/flow YAML
+.gitlab-ci.yml                      # the pipeline
+docs/                               # per-capability deep dives
+```
+
+## The engine (`src/`)
+
+The engine is a Node.js application with a [Commander](https://github.com/tj/commander.js)-based CLI. It is **pure logic where it can be** — the content transforms (version bumps, removals, overrides), the risk math, the dependency-tree resolution, and the report templates are all deterministic, side-effect-free functions wrapped by thin I/O layers. That is what makes the behaviour testable and reproducible.
+
+The orchestration lives in `agent.js::analyzeRepository()`: detect ecosystems → scan → per-vulnerability Orbit exposure → risk score → rank → (optionally) choose a target version, apply the fix, and open the MR. Every other module is a single responsibility called from there.
+
+## Risk scoring
+
+The score is a plain weighted sum minus a discount — **no hidden multipliers** — so the per-finding breakdown shown on the dashboard always adds up to the final number.
+
+```
+score = (cvss / 10 × 0.45)      # raw severity
+      + (exposure  × 0.35)      # how exposed the affected files are
+      + (usage     × 0.10)      # how many files import the package
+      − (testCoverage × 0.10)   # discount when usage is test-only
+```
+
+Scaled to 0–100, then bucketed: **URGENT ≥ 80, HIGH ≥ 50, MEDIUM ≥ 20, LOW < 20** (thresholds are configurable in `AGENTS.md`).
+
+- `cvss` is the real CVSS base score when OSV provides one; otherwise it is **computed from the CVSS v3 vector string** (`src/scanners/cvss.js`); only as a last resort does it fall back to a coarse severity-bucket midpoint.
+- `exposure` comes from a real Orbit query. **When Orbit is unavailable it contributes exactly 0** — the score becomes purely CVSS-driven rather than carrying a fabricated baseline. Which case applied is reported as `exposureDataSource`.
+- File classification (public-API / internal / test) honours `public_api_paths` / `test_paths` from `AGENTS.md`, falling back to built-in heuristics.
+
+**Decision — why a transparent linear model.** A black-box score that a developer cannot reconstruct is a score they will not trust. Every contribution is shown on the dashboard and in the prefilled issue description, and the parts always sum to the total. Severity is a *signal*, not the answer; exposure is what turns a CVE into a priority.
+
+## Orbit blast-radius analysis
+
+The differentiator is `src/blastRadius.js` over `src/orbitClient.js`: it asks GitLab Orbit's knowledge graph which files actually import a vulnerable package (`ImportedSymbol → File` relationships) and whether that code is public-API, internal, or test-only. This is what separates "vulnerable" from "vulnerable *and reachable from your public surface*."
+
+- If Orbit confirms **zero importers anywhere**, the recommendation flips from "patch" to **remove** — you do not upgrade a dependency nothing uses; you delete it.
+- The Orbit query DSL is shape-sensitive: single-node lookups use `query_type: "search"` with a singular `node`; joins between entities use `query_type: "traversal"` with `nodes` and `relationships`. The client enforces the correct shape.
+- **Honest degradation:** every Orbit interaction can fail (graph not yet indexed, transient error). When it does, the analysis says so explicitly and proceeds with `exposure = 0` rather than inventing importers. The same rule applies everywhere in the engine — see [Key design decisions](#key-design-decisions-and-why).
+
+For chat sessions, the Orbit MCP server is connected through `.gitlab/duo/mcp.json` so the agents can query the graph directly.
+
+## Remediation logic
+
+`src/scanners/ecosystemFixers.js` chooses one of three actions per finding, then `src/prGenerator.js` commits it and opens the MR. The fixers never regenerate lockfiles themselves — they print the exact follow-up command (`npm install`, `go mod tidy`, …) which CI runs before the commit.
+
+| Situation | Action | Mechanism |
+|---|---|---|
+| Direct dependency with a fixed version | **Bump** the manifest line | per-ecosystem text transform |
+| **Transitive** npm dependency (no direct line to change) | **Override** | adds an `overrides` pin forcing `>= floor` |
+| Orbit confirms the package is unused | **Remove** | deletes the dependency entry |
+
+**Decision — transitive vulnerabilities must still produce a fix.** A vulnerable package you do not declare directly is the most common and most ignored case. The fixer first tries a direct bump; if there is no direct line to change, it **falls back to an npm `overrides` pin** rather than giving up with no change. That guarantees a transitive vulnerability still yields a real, committable diff and therefore a real merge request — not a dead end.
+
+**Decision — choose the least-disruptive secure version.** For an upgrade, the engine does not blindly take OSV's minimum fixed version. It picks the least-disruptive *settled* version at or above that floor, preferring to stay within the current major where possible, and flags explicitly when a fix is forced to cross a major boundary.
+
+**Safety:** the engine applies fixes and opens MRs **only when asked** (`--fix --create-pr`), and it never merges. The merge request is the human approval gate.
+
+## The GitLab Duo integration
+
+The engine is exposed to the GitLab Duo Agent Platform through four artifact types under `.gitlab/duo/`.
+
+### Execution environment — `agent-config.yml`
+
+Read by GitLab from the project's default branch, this defines the environment every flow runs in:
+
+- **`image: node:20`** — the Duo runtime CLI requires Node ≥ 20.17.
+- **`setup_script`** installs the engine as a global CLI (`npm install -g dependencyiq`) and downloads the OSV-Scanner binary. Because the engine is *installed* rather than read from the checked-out repository, the flow scans whatever project it runs in.
+- **`network_policy`** allow-lists the registries the engine needs.
+
+### The Custom Flow (ambient) — `flows/vulnerability-analysis-flow.yaml`
+
+`components` are nodes, `routers` are edges, `flow.entry_point` is the start. It runs `environment: ambient` — a real CI job — so unlike a chat session it can execute the tested engine.
+
+The entry component is a **triage router**. It inspects the trigger and answers with a single word, and a **conditional router** (`condition.input` + `routes`, the flow-registry mechanism for branching) maps that word to one of three routes:
+
+```
+triage_router ─┬─ analyze   → discover_assess → plan → remediate → verify → track → report → end
+               ├─ guardian  → guardian_review ───────────────────────────────────────────────→ end
+               └─ freshness → freshness_check ───────────────────────────────────────────────→ end
+```
+
+- **`analyze`** runs the full six-stage remediation pipeline. Each stage runs an exact `dependencyiq …` command and is instructed to *report only command output and never invent findings*. The analyze route also accepts a **target branch**: if the trigger names one, stage 1 checks it out (`git fetch && git checkout`) before scanning, and degrades safely to the current branch if the checkout fails.
+- **`guardian_review`** runs `dependencyiq review-mr --post` to safety-review an incoming dependency MR.
+- **`freshness_check`** runs `dependencyiq freshness` for a tech-debt policy report.
+- The final **report** stage posts one clean, professional summary comment on the triggering issue (not just the run log), constrained to the actual findings of this run.
+
+There is deliberately **no human-approval node**: an ambient flow cannot pause for chat, so the MR that the analyze route opens (but never merges) is the approval gate. `scripts/validate-config.js` graph-checks the flow on every CI run — orphan components, dangling router targets, prompt/component mismatches, and that the pipeline reaches `end`.
+
+**Decision — one router, many intents.** Rather than a separate flow per task, a single ambient flow routes by the triggering context. This keeps one trigger surface (the flow's service account) serving analyse, MR review, and freshness, while the routes themselves remain independent.
+
+### The Custom Chat Agents — `agents/*.yaml`
+
+Interactive, conversational surfaces. Each defines a `name`, `description`, `public` visibility, a staged `system_prompt`, and a `tools` list:
+
+- **DependencyIQ** — single-repository triage. Follows a staged operator protocol: check Orbit health, get the vulnerability signal, read manifests, run the blast-radius query, show the decision-trail math, then stop at an explicit approval gate before committing a simple version-pin fix.
+- **DependencyIQ Emergency Response** — organisation-wide incident triage. Given a compromised package, it queries Orbit's group graph for every project that imports it and classifies exposure. (Kept as a chat agent rather than an ambient route because it is high-stakes and parameterised — it should be run deliberately, not autonomously.)
+- **DependencyIQ Freshness** — read-only. It explains what the `AGENTS.md` freshness policy will enforce and which declared versions are pinned, then hands off to the CLI/flow for the registry-backed answer.
+- **DependencyIQ Guardian** — interactive safety review of an incoming dependency merge request, mirroring the `mr_safety_review` CI logic before the pipeline has even run.
+
+**Decision — what a chat agent may and may not do.** Web-UI chat cannot run shell commands, so the chat agents never claim to have run a scanner; they query Orbit and read manifests, and can commit a *simple* version-pin edit because the Commits API can create a branch atomically. Anything heavier — deterministic per-ecosystem fixers, high-volume runs — is the flow's or CLI's job. Each agent's prompt states this boundary as a hard rule.
+
+### The Agent Skill — `skills/dependency-analysis/SKILL.md`
+
+Registers `/dependency-analysis` plus natural-language trigger keywords in Duo Chat.
+
+### Orbit connection — `mcp.json`
+
+Registers the Orbit MCP server so chat sessions get the Orbit graph tools.
+
+## Distribution: the `dependencyiq` npm package
+
+The engine is published to npm as `dependencyiq`, with a `bin` entry exposing the `dependencyiq` command.
+
+**Decision — install the engine, do not vendor it.** Earlier the flow invoked `node src/agent.js`, which required the engine's source to live inside the target repository. That couples the tool to one repo. Publishing the engine as a package and installing it in `setup_script` decouples them: any project can run the flow without carrying the engine's source. For a security tool this is also the *correct* trust model — the engine runs inside the customer's own CI, so their dependency data never leaves their environment. The package ships only `src/` (no tests, no tooling).
+
+## CI/CD pipeline
+
+`.gitlab-ci.yml` both dog-foods the engine on this repository and ships the dashboard.
+
+| Stage | Job | Purpose |
+|---|---|---|
+| validate | `validate_config` | graph-checks the Duo agent/flow YAML and the `AGENTS.md` block |
+| lint | `lint` | ESLint (non-blocking) |
+| test | `test` | Jest with coverage |
+| security | `npm_audit` | npm advisory database, a second signal alongside OSV |
+| security | `mr_safety_review` | on MRs touching `package.json`, posts an approve/review/block verdict |
+| analyze | `analyze_vulnerabilities` | full scan + Orbit risk scoring, uploads a report artifact |
+| analyze | `freshness_check` | tech-debt drift report (non-blocking) |
+| remediate | `remediate_top_vulnerability` | manual-gate job that applies the top fix and opens an MR |
+| deploy | `pages` | publishes the dashboard to GitLab Pages on the default branch |
+| publish | `catalog_publish` | on a semver tag, publishes the agents/flow to the AI Catalog |
+
+**Decision — tokens.** Same-project read calls fall back to the automatic `CI_JOB_TOKEN`, so the common path needs zero manual setup. A broader-scoped `GITLAB_TOKEN` is required only where it genuinely is: opening real merge requests and any cross-project work. The `catalog_publish` job is gated to semver tags only, so branch and merge-request pipelines are never affected by it.
+
+## The live dashboard
+
+The `pages` job runs `dependencyiq dashboard` and publishes a self-contained, interactive HTML report (no backend) to GitLab Pages:
+
+- A **decision trail** per finding — the weighted score breakdown, the real evidence files grouped by exposure (public-API / internal / test), and that finding's share of the project's total flagged risk.
+- **Direct-vs-transitive badges** with the resolved dependency chain, from a real BFS over the lockfile.
+- An **executive summary** — remediation engineer-hours, how many findings are urgent/high, how many are likely-breaking major bumps, how many unused dependencies can be removed.
+- One-click "create issue" links and a copy-paste fix command per row.
+
+## Configuration (`AGENTS.md`)
+
+`AGENTS.md` carries a fenced `yaml` block parsed by `src/configLoader.js` and merged over defaults. It is real configuration, not documentation:
+
+```yaml
+risk_thresholds:        # the URGENT/HIGH/MEDIUM/LOW cut-offs for the 0–100 score
+  urgent: 80
+  high: 50
+  medium: 20
+  low: 0
+excluded_packages:      # reported, but never proposed for auto-fix
+  - "aws-sdk"
+public_api_paths:       # files weighted as public-facing exposure
+  - "src/api/**"
+test_paths:             # files that count toward the test-coverage discount
+  - "test/**"
+freshness_policy:       # tech-debt thresholds, applied to every direct dependency
+  max_minor_versions_behind: 2
+  max_days_behind: 180
+  stability_window_days: 14
+```
+
+**Decision — configuration is data the code reads live.** Thresholds and path hints change behaviour on the next run with no code change, and the freshness policy is enforced separately from CVE urgency so tech-debt drift is visible even for packages with no known vulnerability.
+
+## Using it in your own project
+
+Because the engine is a published package, adopting DependencyIQ does not require copying its source.
+
+1. Enable **GitLab Duo** and **GitLab Orbit** on your group, with hosted runners available.
+2. Add `.gitlab/duo/agent-config.yml` to your repository:
+   ```yaml
+   image: node:20
+   network_policy:
+     include_recommended_allowed: true
+     allowed_domains: [registry.npmjs.org, github.com, objects.githubusercontent.com, api.github.com]
+   setup_script:
+     - npm install -g dependencyiq
+     - curl -fsSL -o /usr/local/bin/osv-scanner "https://github.com/google/osv-scanner/releases/download/v1.9.2/osv-scanner_linux_amd64"
+     - chmod +x /usr/local/bin/osv-scanner
+   ```
+3. Register the flow (and any agents) from the AI Catalog and enable its triggers.
+4. Optionally add an `AGENTS.md` config block to tune thresholds and path hints.
+
+The flow then scans and remediates **your** repository — the engine installs itself.
+
+## CLI reference
+
+```bash
+npm install -g dependencyiq
+
+dependencyiq analyze   .  --fix --create-pr     # scan, score, fix, open an MR
+dependencyiq analyze   .  --impact              # Upgrade Impact Report + migration plan
+dependencyiq review-mr .  --post                # safety-review an incoming dependency MR
+dependencyiq freshness .                         # tech-debt freshness policy check
+dependencyiq dashboard .                         # static HTML report → public/index.html
+dependencyiq emergency <group> <package> --dry-run   # org-wide incident triage
+```
+
+When run via the flow or chat agents, GitLab injects the project id and tokens under composite identity; no manual token setup is needed there. For a local run, set `GITLAB_TOKEN` (api scope) and `GITLAB_PROJECT_ID`.
+
+## Key design decisions and why
+
+A consolidated list of the choices that shape everything else.
+
+1. **One engine, many surfaces.** The CLI, chat agents, flow, and skill are different entry points into one tested codebase, never copies of the logic. New surfaces add reach, not duplication.
+2. **Never fabricate.** Every feature degrades honestly. If Orbit is unavailable, exposure contributes 0 and the report says so; if a CVSS score is missing, it is computed from the vector or marked coarse; the report stage may only restate this run's real findings. A plausible-looking invented number is worse than an honest gap.
+3. **Run the tested engine, do not approximate it.** The flow executes `dependencyiq …` via `run_command`; the flow's behaviour *is* the engine's behaviour. The agents do not re-derive scanning logic from prose.
+4. **Exposure over severity.** Risk is driven by what your code actually imports (Orbit), not raw CVSS. A critical CVE in a test-only dependency outranks nothing.
+5. **Transparent scoring.** A plain weighted sum with no hidden multipliers, shown in full on the dashboard, so the score is auditable and therefore trusted.
+6. **Transitive vulnerabilities still get a fix.** The fixer falls back to an `overrides` pin when there is no direct line to change, so the most-ignored class of vulnerability still produces a real MR.
+7. **Remove dead weight instead of patching it.** Zero Orbit importers flips the recommendation from upgrade to removal.
+8. **Never merge.** The engine opens MRs but never merges; the MR is the human gate. The ambient flow has no approval node by design.
+9. **One ambient flow, routed by intent.** A triage router dispatches to analyze / guardian / freshness, keeping one trigger surface for several jobs.
+10. **Install the engine, don't vendor it.** Publishing `dependencyiq` to npm decouples the tool from any one repository and keeps analysis inside the customer's own CI.
+11. **Configuration is live data.** Thresholds, path hints, and the freshness policy are read from `AGENTS.md` on every run.
+
+## Testing
+
+```bash
+npm test       # Jest with coverage
+npm run lint   # ESLint
+```
+
+The pure transforms, the risk math, the dependency-tree resolution, the CVSS computation, the supply-chain signals, the MR-review verdicts, and the dashboard generation are all covered by unit tests.
+
+## Requirements
+
+- GitLab Premium/Ultimate with **GitLab Orbit** and the **Duo Agent Platform** enabled.
+- **OSV-Scanner** on `PATH` (or set `OSV_SCANNER_PATH`).
+- For local API operations: a `GITLAB_TOKEN` with `api` scope.
+- No external AI API key — reasoning inside the agents and flow uses GitLab's managed model.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependencyiq",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Multi-language dependency vulnerability agent: OSV-Scanner + GitLab Orbit blast-radius analysis + automated MRs",
   "main": "src/agent.js",
   "bin": {

package/src/agent.js

@@ -72,7 +72,7 @@ async function analyzeRepository(repoPath, projectId, options = {}) {
 
     console.log('\n📊 Analyzing blast radius with GitLab Orbit...');
     for (const vuln of vulnerabilities) {
-      const exposure = await analyzeExposure(projectId, vuln.package, pathHints);
+      const exposure = await analyzeExposure(projectId, vuln.package, vuln.ecosystem, pathHints);
 
       vuln.riskScore = calculateRiskScore(vuln, {
         affectedFilesCount: exposure.affectedFilesCount,
@@ -86,7 +86,7 @@ async function analyzeRepository(repoPath, projectId, options = {}) {
       vuln.affectedFiles = exposure.affectedFiles;
       vuln.exposure = exposure;
       vuln.recommendation = vuln.riskScore.recommendation;
-      vuln.dependencyChain = resolveDependencyChain(repoPath, vuln.ecosystem, vuln.package);
+      vuln.dependencyChain = resolveDependencyChain(repoPath, vuln.ecosystem, vuln.package, vuln.currentVersion);
     }
 
     console.log('\n🎯 Ranking by actual risk...');

package/src/blastRadius.js

@@ -7,6 +7,7 @@
  */
 
 const orbitClient = require('./orbitClient');
+const { hasAnyToken } = require('./gitlabAuth');
 
 // Built-in heuristic defaults, used when AGENTS.md doesn't specify
 // public_api_paths / test_paths. A project with a non-standard layout
@@ -39,7 +40,12 @@ let orbitReachable = null; // cached per-process: null = unknown, true/false onc
 
 async function isOrbitReachable() {
   if (orbitReachable !== null) return orbitReachable;
-  if (!process.env.GITLAB_TOKEN) {
+  // CI_JOB_TOKEN (auto-present in every CI job) is sufficient for this
+  // same-project read call — see gitlabAuth.js's getAuthHeaders, which
+  // already falls back to it. Requiring GITLAB_TOKEN specifically here
+  // reported Orbit as unavailable in every normal CI/Flow run that never
+  // set that CI/CD variable, even when Orbit was actually healthy.
+  if (!hasAnyToken()) {
     orbitReachable = false;
     return false;
   }
@@ -85,10 +91,46 @@ function classifyFiles(files, hints = {}) {
  * @returns {Promise<Object>} exposure analysis with a `source` field
  *   ('orbit' | 'unavailable') so callers know how much to trust it.
  */
-async function analyzeExposure(projectId, packageName, hints = {}) {
+// OSV-Scanner ecosystem -> the `language` Orbit tags File nodes with. Used
+// only to check whether Orbit indexed source in this package's language for
+// the project (see below). An unmapped ecosystem falls back to "any file".
+const ECOSYSTEM_LANGUAGE = {
+  PyPI: 'python',
+  npm: 'javascript',
+  Maven: 'java',
+  Go: 'go',
+  RubyGems: 'ruby',
+  'crates.io': 'rust',
+  NuGet: 'c#',
+  Packagist: 'php',
+};
+
+async function analyzeExposure(projectId, packageName, ecosystem, hints = {}) {
   if (projectId && await isOrbitReachable()) {
     try {
       const files = await orbitClient.findPackageImporters(projectId, packageName);
+
+      // Zero importers is ambiguous. It means "safe to remove" ONLY if Orbit
+      // actually indexed this project's source IN THIS PACKAGE'S LANGUAGE.
+      // Orbit indexes the default branch only, so scanning a Python feature
+      // branch of a project whose default branch is JavaScript returns zero
+      // Python importers even though the index is "present" — that is
+      // unknown, not unused. The language-scoped check below avoids the trap
+      // where a JS default branch makes a Python package look falsely unused.
+      const language = ECOSYSTEM_LANGUAGE[ecosystem];
+      if (files.length === 0 && !(await orbitClient.isProjectIndexed(projectId, language))) {
+        return {
+          source: 'unavailable',
+          affectedFiles: [],
+          affectedFilesCount: 0,
+          isInPublicAPI: false,
+          isInTests: false,
+          languages: [],
+          recommendation: 'upgrade',
+          warning: 'GitLab Orbit is reachable but has not indexed this branch (Orbit indexes the default branch only), so blast radius is unknown here — defaulted to upgrade rather than guessing the dependency is unused. Scan the default branch for real importer data.',
+        };
+      }
+
       const { isInPublicAPI, isInTests } = classifyFiles(files, hints);
       const categorizedFiles = files.map(f => ({ ...f, category: categorizeFile(f.path, hints) }));
       return {