feat: add OSV.dev dependency vulnerability analyzer (--use-osv) (#135)

* fix: recognize current ngrok tunnel domains and add bore.pub/serveo.net/localtunnel.me

ngrok migrated off ngrok.io to ngrok-free.dev / ngrok.app, so exfil to a
current ngrok endpoint slipped past the suspicious-domain checks. Add the
modern ngrok domains plus bore.pub, serveo.net and localtunnel.me to:

- ContextExtractor.SUSPICIOUS_DOMAINS (Python string-literal URL classification)
- tool_chaining_abuse_generic.yara / command_injection_generic.yara exfil dests
- cross_skill_scanner exfil pattern list

Add regression tests for the new domains (YARA true-positives + ContextExtractor).

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(static): flag unpinned dependencies in scanned skill packages

Skill packages are end-user applications, so unpinned dependencies
(requests>=2 or a bare requests) let a later, potentially compromised
release be pulled in at install time -- a supply-chain risk. Only the LLM
prompt mentioned this previously; there was no deterministic check.

Add StaticAnalyzer._check_dependency_pinning() which parses requirements*.txt
files and a manifest metadata "dependencies" list, emitting
SUPPLY_CHAIN_UNPINNED_DEPENDENCY (MEDIUM for open ranges/bare names, LOW for
==x.* wildcard pins). Skips when a lockfile (uv.lock/poetry.lock/...) is
present, since versions are already resolved -- this is why the scanner's own
library pinning policy (ranges in pyproject.toml) is not affected.

Register the rule in the core pack.yaml, document the new pass in the
static-analyzer docs and threat taxonomy, and add unit tests.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(static): classify URLs in config files via shared url_classifier

The suspicious/legitimate domain lists and matching logic previously lived
inside ContextExtractor and only ran over Python AST string literals, so a
tunnel/proxy endpoint hidden in a config value (e.g. base_url in config.yaml)
was never classified.

Refactor (behavior-preserving): extract SUSPICIOUS_DOMAINS/LEGITIMATE_DOMAINS
and the classification into skill_scanner/core/static_analysis/url_classifier.py
(classify_url + extract_urls). ContextExtractor imports from it and keeps the
lists as class attributes for backward compatibility; existing suspicious-URL
behavior is unchanged (covered by refactor-safety tests).

New pass: StaticAnalyzer._scan_config_files() parses config.yaml/.yml/.json,
settings.*, and *.toml (regex fallback on parse failure), runs each URL through
the shared classifier, and emits CONFIG_SUSPICIOUS_URL (HIGH). Registered in
the core pack.yaml.

Docs updated (static-analyzer, behavioral-analyzer). Adds unit tests plus a
labeled config-routed exfil eval sample; benchmark stays at 100% P/R.

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(static): scan config files via raw URL extraction

Collapse the structured YAML/JSON/TOML parse-and-walk in config URL
scanning down to a single raw-text extract_urls() pass. The raw scan is
simpler, drops the json/yaml/tomllib imports and the _iter_string_values
recursion, and additionally catches suspicious URLs hidden in config
comments. classify_url() still only flags known tunnel/exfil domains, so
false-positive risk stays low.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(static): scan more manifest formats for unpinned dependencies

Extend the unpinned-dependency check beyond requirements*.txt and
manifest metadata to also read pyproject.toml ([project] dependencies
and optional-dependencies), setup.cfg ([options] install_requires /
extras), setup.py (install_requires literals via AST), and Pipfile
([packages]/[dev-packages]). All sources are normalized to requirement
strings and run through the existing classifier, so a lockfile still
suppresses findings and pinned specs stay clean.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: add OSV dependency vulnerability analyzer (--use-osv)

Add an opt-in external analyzer that checks a skill's pinned Python
dependencies against the free, open OSV.dev vulnerability database. Follows
the established external-analyzer pattern (like VirusTotal): no API key, and
it fails open so a network error never breaks a scan.

- OSVAnalyzer parses requirements*.txt and manifest metadata dependencies,
  queries only exact (==) pins via OSV querybatch, and emits
  SUPPLY_CHAIN_KNOWN_VULNERABILITY (HIGH) with advisory IDs/links.
- Wire use_osv through analyzer_factory, the CLI (--use-osv), the API router
  (use_osv on JSON + upload endpoints), and the setup wizard.
- Uses httpx (already a dependency): zero new runtime dependencies.

Tests mock all OSV HTTP calls (no live network). Adds a deep-dive doc and
updates the analyzer selection guide, analyzer index, CLI/API references, and
configuration/dependency references.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(osv): collect pinned dependencies from more manifest formats

Extend OSV pin collection beyond requirements*.txt and manifest metadata
to also read pyproject.toml, setup.cfg, setup.py (install_requires via
AST), and Pipfile. Only exact == pins are queried against OSV; ranges are
left to the static unpinned-dependency check.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(llm): allow Vertex AI to use ambient Application Default Credentials

ProviderConfig.validate() required a truthy credential for every provider
except Bedrock and Ollama, and the only credential source it checked for
Vertex was GOOGLE_APPLICATION_CREDENTIALS. This blocked ambient auth via
a GCE/Cloud Run attached service account or Workload Identity, even though
LiteLLM/google-auth already fall back to it automatically when no explicit
credential is passed -- the same pattern already supported for Bedrock's
IAM role. Excludes is_vertex from the check, mirroring the Bedrock/Ollama
precedent, and documents the fallback.

* Bumps to resolve security findings

* fix(llm): don't leak Vertex ADC credential path into GEMINI_API_KEY

- _resolve_api_key() now returns None for Vertex instead of the
  GOOGLE_APPLICATION_CREDENTIALS path, since vertex_ai/gemini-* models
  set both is_vertex and is_gemini, which was causing the file path to
  be written into GEMINI_API_KEY.
- Regenerated configuration-reference.md via generate_reference_docs.py
  instead of hand-editing, and updated the underlying descriptions so
  the doc doesn't drift on next regeneration.

Addresses CodeRabbit review feedbak on #144.

* revert unrelated cli-command-reference.md regeneration

* fix(static): classify suspicious URLs by hostname

* fix(static): tolerate malformed setup.py input

* docs(static): correct analyzer pass count

* fix(static): validate suspicious URL schemes

* docs(vertex): clarify conditional ADC configuration

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: gyrospectre <7224858+gyrospectre@users.noreply.github.com>
Co-authored-by: Vineeth Sai Narajala <vnarajal@cisco.com>

Author: 4 people

docs/architecture/analyzers/index.md

@@ -17,6 +17,7 @@ Analyzers implement independent detection strategies and return normalized `Find
 | Behavioral | Static AST/dataflow | No | 1 | Python source behavior |
 | VirusTotal | External intel | Yes | 1 | Binary hash/file reputation |
 | AI Defense | External service | Yes | 1 | Prompt/content/code threat signal |
+| OSV | External service | No | 1 | Known-vulnerable pinned dependencies |
 | Trigger | Heuristic | No | 1 | Vague or risky trigger descriptions |
 | LLM | Semantic | Usually (not required for Bedrock IAM mode) | 2 | Intent-level threat reasoning |
 | Meta | Semantic post-pass | Usually (not required for Bedrock IAM mode) | 2 | FP filtering and prioritization |
@@ -44,5 +45,6 @@ See [Scanning Pipeline](../scanning-pipeline.md) for the full execution flow.
 - [LLM Analyzer](llm-analyzer.md)
 - [Meta-Analyzer](meta-analyzer.md)
 - [AI Defense Analyzer](aidefense-analyzer.md)
+- [OSV Analyzer](osv-analyzer.md)
 - [Analyzer Selection Guide](meta-and-external-analyzers.md)
 - [Writing Custom Rules](writing-custom-rules.md)

docs/architecture/analyzers/meta-and-external-analyzers.md

@@ -17,6 +17,7 @@ This page helps you choose which optional analyzers to enable for your use case.
 | Cloud-based threat classification | AI Defense | `--use-aidefense` | Requires Cisco AI Defense API access |
 | Catch vague/risky skill descriptions | Trigger | `--use-trigger` | Lightweight; no external dependencies |
 | Python dataflow and cross-file analysis | Behavioral | `--use-behavioral` | CPU-intensive for large codebases |
+| Known-vulnerable dependency detection | OSV | `--use-osv` | Requires network; queries PyPI pins only (no API key) |
 
 ## When to Use Each Analyzer
 
@@ -99,15 +100,28 @@ Skip when: the skill contains no Python source, or you need the fastest possible
 
 See [Behavioral Analyzer deep dive](behavioral-analyzer.md) for detection patterns.
 
+### OSV Analyzer
+
+Best for: skills that declare pinned Python dependencies you want checked against known CVEs/advisories. Queries the free, open [OSV.dev](https://osv.dev) database — no API key required.
+
+```bash
+skill-scanner scan ./my-skill --use-osv
+```
+
+Skip when: scanning air-gapped/offline (it requires network access), or the skill declares no exactly pinned dependencies. It fails open — a network error logs a warning and yields no findings.
+
+See [OSV Analyzer deep dive](osv-analyzer.md) for details.
+
 ## Recommended Combinations
 
 | Scenario | Flags |
 |---|---|
 | Quick CI gate | (defaults -- core analyzers only) |
 | Thorough single-skill review | `--use-llm --use-behavioral --use-trigger --enable-meta` |
 | Binary-heavy skill | `--use-virustotal` |
+| Dependency-heavy skill | `--use-osv` |
 | Enterprise with AI Defense | `--use-aidefense --use-llm --enable-meta` |
-| Maximum coverage | `--use-llm --use-behavioral --use-trigger --use-virustotal --enable-meta` |
+| Maximum coverage | `--use-llm --use-behavioral --use-trigger --use-virustotal --use-osv --enable-meta` |
 
 ## Bytecode Analyzer
 
@@ -128,4 +142,5 @@ skill-scanner scan-all ./skills-dir --check-overlap
 - [LLM Analyzer](llm-analyzer.md)
 - [Meta Analyzer](meta-analyzer.md)
 - [AI Defense Analyzer](aidefense-analyzer.md)
+- [OSV Analyzer](osv-analyzer.md)
 - [Binary Handling](../binary-handling.md)

docs/architecture/analyzers/osv-analyzer.md

@@ -0,0 +1,86 @@
+# OSV Analyzer
+
+## Overview
+
+The OSV Analyzer checks a skill's declared Python dependencies against the
+[OSV.dev](https://osv.dev) vulnerability database — a free, open aggregator of
+security advisories (GHSA, PYSEC, CVE, and more). It is an **opt-in external
+analyzer** (like VirusTotal): it requires network access, needs **no API key**,
+and **fails open** so a network problem never breaks a scan.
+
+## What It Detects
+
+- **Known-vulnerable dependency versions** — a pinned dependency
+  (`package==1.2.3`) that has one or more advisories in OSV is flagged as
+  `SUPPLY_CHAIN_KNOWN_VULNERABILITY` (HIGH), with the advisory IDs and links.
+
+Only dependencies pinned to an **exact** version are queried. An open range
+(`package>=1`) has no single version to look up; that risk is already surfaced
+by the static [unpinned-dependency check](static-analyzer.md).
+
+## Sources Scanned
+
+| Source | Notes |
+|--------|-------|
+| `requirements*.txt` | `requirements.txt`, `requirements-dev.txt`, etc. |
+| `pyproject.toml` | `[project]` dependencies and optional-dependencies (PEP 621) |
+| `setup.cfg` | `[options] install_requires` and `[options.extras_require]` |
+| `setup.py` | String literals inside `install_requires=[...]` (parsed via AST, not executed) |
+| `Pipfile` | `[packages]` and `[dev-packages]` sections |
+| Manifest `metadata.dependencies` | Optional list of requirement strings in SKILL.md frontmatter |
+
+Ecosystem defaults to `PyPI`.
+
+## Usage
+
+### Command Line
+
+```bash
+# Enable OSV dependency scanning (no API key needed)
+skill-scanner scan /path/to/skill --use-osv
+
+# Combine with other analyzers
+skill-scanner scan /path/to/skill --use-osv --use-behavioral
+```
+
+### Python API
+
+```python
+from skill_scanner.core.analyzers.osv_analyzer import OSVAnalyzer
+from skill_scanner.core.loader import SkillLoader
+
+analyzer = OSVAnalyzer(enabled=True)
+skill = SkillLoader().load_skill("/path/to/skill")
+findings = analyzer.analyze(skill)
+```
+
+### API
+
+Set `use_osv: true` on the scan request (see the
+[API Endpoint Reference](../../reference/api-endpoint-reference.md)).
+
+## How It Works
+
+1. **Collect pins** — parse every supported dependency source (see
+   [Sources Scanned](#sources-scanned)), keeping only exact `==` pins as
+   `(name, version)` pairs.
+2. **Batch query** — POST all pins to `https://api.osv.dev/v1/querybatch`
+   (`{"package": {"ecosystem": "PyPI", "name": ...}, "version": ...}`).
+3. **Generate findings** — for each package that returns advisories, emit a
+   `SUPPLY_CHAIN_KNOWN_VULNERABILITY` finding listing the advisory IDs.
+
+## Error Handling
+
+The analyzer fails open. On any network/HTTP error it logs a warning and
+returns no findings, so an offline or air-gapped environment simply skips the
+check rather than failing the scan.
+
+## Dependencies
+
+Uses `httpx`, which is already a scanner dependency — enabling OSV adds **no new
+runtime dependency** and no API key.
+
+## Related Pages
+
+- [Analyzer Selection Guide](meta-and-external-analyzers.md) — when to enable `--use-osv`
+- [Static Analyzer](static-analyzer.md) — the complementary unpinned-dependency check

docs/architecture/analyzers/static-analyzer.md

@@ -3,7 +3,7 @@
 > [!TIP]
 > **TL;DR**
 >
-> The static analyzer runs 14 detection passes per skill covering YAML signatures, YARA rules, Python checks, binary inspection, document analysis, homoglyph detection, and allowed-tools enforcement. It is always-on (core analyzer) and requires no external services.
+> The static analyzer runs 15 detection passes per skill covering YAML signatures, YARA rules, Python checks, binary inspection, document analysis, homoglyph detection, dependency pinning, and allowed-tools enforcement. It is always-on (core analyzer) and requires no external services.
 
 The static analyzer is the primary deterministic detection engine. It combines YAML signature matching, YARA-X rule scanning, Python-based checks, and file inventory analysis to detect security threats without requiring external services.
 

docs/reference/api-endpoint-reference.md

@@ -90,6 +90,7 @@ curl -X POST http://localhost:8000/scan-upload \
 | `use_aidefense` | `bool` |
 | `aidefense_api_url` | `str | None` |
 | `use_trigger` | `bool` |
+| `use_osv` | `bool` |
 | `enable_meta` | `bool` |
 | `llm_consensus_runs` | `int` |
 
@@ -131,6 +132,7 @@ curl -X POST http://localhost:8000/scan-upload \
 | `use_aidefense` | `bool` |
 | `aidefense_api_url` | `str | None` |
 | `use_trigger` | `bool` |
+| `use_osv` | `bool` |
 | `enable_meta` | `bool` |
 | `llm_consensus_runs` | `int` |
 

docs/reference/cli-command-reference.md

@@ -33,6 +33,7 @@ Flags shared by `scan` and `scan-all`:
 | `--use-behavioral` | off | Enable the behavioral analyzer |
 | `--use-virustotal` | off | Enable VirusTotal hash lookups |
 | `--use-aidefense` | off | Enable Cisco AI Defense analyzer |
+| `--use-osv` | off | Enable OSV.dev dependency vulnerability scanning (no API key; requires network) |
 | `--enable-meta` | off | Enable the meta (cross-correlation) analyzer |
 | `--fail-on-findings` | off | Exit non-zero if critical or high findings are reported; equivalent to `--fail-on-severity high` (CI gate) |
 | `--fail-on-severity LEVEL` | off | Exit non-zero if findings at or above LEVEL exist (critical, high, medium, low, info) |
@@ -156,6 +157,8 @@ options:
   --use-aidefense       Enable AI Defense analyzer (requires API key)
   --aidefense-api-key AIDEFENSE_API_KEY
                         AI Defense API key (or set AI_DEFENSE_API_KEY)
+  --use-osv             Enable OSV.dev dependency vulnerability scanning (no
+                        API key; requires network)
   --aidefense-api-url AIDEFENSE_API_URL
                         AI Defense API URL (optional, defaults to US region)
   --llm-provider {anthropic,openai}
@@ -268,6 +271,8 @@ options:
   --use-aidefense       Enable AI Defense analyzer (requires API key)
   --aidefense-api-key AIDEFENSE_API_KEY
                         AI Defense API key (or set AI_DEFENSE_API_KEY)
+  --use-osv             Enable OSV.dev dependency vulnerability scanning (no
+                        API key; requires network)
   --aidefense-api-url AIDEFENSE_API_URL
                         AI Defense API URL (optional, defaults to US region)
   --llm-provider {anthropic,openai}
@@ -384,6 +389,8 @@ options:
   --use-aidefense       Enable AI Defense analyzer (requires API key)
   --aidefense-api-key AIDEFENSE_API_KEY
                         AI Defense API key (or set AI_DEFENSE_API_KEY)
+  --use-osv             Enable OSV.dev dependency vulnerability scanning (no
+                        API key; requires network)
   --aidefense-api-url AIDEFENSE_API_URL
                         AI Defense API URL (optional, defaults to US region)
   --llm-provider {anthropic,openai}

docs/reference/configuration-reference.md

@@ -79,6 +79,10 @@ Enable the Cisco AI Defense cloud analyzer.
 | `AI_DEFENSE_API_KEY` | Cisco AI Defense analyzer API key. | `(your AI Defense key)` |
 | `AI_DEFENSE_API_URL` | Cisco AI Defense endpoint override. | `https://us.api.inspect.aidefense.security.cisco.com/api/v1` |
 
+## OSV Dependency Scanning
+
+The OSV analyzer queries [OSV.dev](https://osv.dev) for known-vulnerable pinned dependencies. It is an external service that requires **no API key**, only outbound network access to `api.osv.dev`. Enable it with `--use-osv` (or `use_osv` on the API). Skip it in air-gapped environments — with no network it fails open and reports nothing.
+
 ## Feature Toggles
 
 Override default analyzer enablement via environment. Values: `true`/`1` or `false`/`0`.

docs/reference/dependencies-and-llm-providers.md

@@ -12,7 +12,7 @@ All versions from [`pyproject.toml`](https://github.com/cisco-ai-defense/skill-s
 | `uvicorn[standard]` | >= 0.29.0 | ASGI server |
 | `pydantic` | >= 2.6.0 | Data validation and serialization |
 | `python-multipart` | >= 0.0.6 | File upload handling |
-| `httpx` | >= 0.28.1 | Async HTTP client |
+| `httpx` | >= 0.28.1 | HTTP client (also used by the VirusTotal, AI Defense, and OSV external analyzers) |
 
 ### CLI and TUI
 

skill_scanner/api/router.py

@@ -206,6 +206,7 @@ class ScanRequest(BaseModel):
     use_aidefense: bool = Field(False, description="Enable AI Defense analyzer")
     aidefense_api_url: str | None = Field(None, description="AI Defense API URL")
     use_trigger: bool = Field(False, description="Enable trigger specificity analysis")
+    use_osv: bool = Field(False, description="Enable OSV.dev dependency vulnerability scanning")
     enable_meta: bool = Field(False, description="Enable meta-analysis for false positive filtering")
     llm_consensus_runs: int = Field(1, description="Number of LLM consensus runs (majority vote)")
 
@@ -251,6 +252,7 @@ class BatchScanRequest(BaseModel):
     use_aidefense: bool = False
     aidefense_api_url: str | None = None
     use_trigger: bool = False
+    use_osv: bool = False
     enable_meta: bool = Field(False, description="Enable meta-analysis")
     llm_consensus_runs: int = Field(1, description="Number of LLM consensus runs (majority vote)")
 
@@ -297,6 +299,7 @@ def _build_analyzers(
     aidefense_api_key: str | None = None,
     aidefense_api_url: str | None = None,
     use_trigger: bool = False,
+    use_osv: bool = False,
     llm_consensus_runs: int = 1,
 ):
     """Build the analyzer list — delegates to the centralized factory."""
@@ -313,6 +316,7 @@ def _build_analyzers(
         aidefense_api_key=aidefense_api_key,
         aidefense_api_url=aidefense_api_url,
         use_trigger=use_trigger,
+        use_osv=use_osv,
         llm_consensus_runs=llm_consensus_runs,
     )
 
@@ -425,6 +429,7 @@ def run_scan():
             aidefense_api_key=aidefense_api_key,
             aidefense_api_url=request.aidefense_api_url,
             use_trigger=request.use_trigger,
+            use_osv=request.use_osv,
             llm_consensus_runs=request.llm_consensus_runs,
         )
         scanner = SkillScanner(analyzers=analyzers, policy=policy)
@@ -505,6 +510,7 @@ async def scan_uploaded_skill(
     aidefense_api_key: str | None = Header(None, alias="X-AIDefense-Key"),
     aidefense_api_url: str | None = Form(None, description="AI Defense API URL"),
     use_trigger: bool = Form(False, description="Enable trigger specificity analysis"),
+    use_osv: bool = Form(False, description="Enable OSV.dev dependency vulnerability scanning"),
     enable_meta: bool = Form(False, description="Enable meta-analysis for FP filtering"),
     llm_consensus_runs: int = Form(1, description="Number of LLM consensus runs"),
 ):
@@ -598,6 +604,7 @@ async def scan_uploaded_skill(
             use_aidefense=use_aidefense,
             aidefense_api_url=aidefense_api_url,
             use_trigger=use_trigger,
+            use_osv=use_osv,
             enable_meta=enable_meta,
             llm_consensus_runs=llm_consensus_runs,
         )
@@ -684,6 +691,7 @@ def run_batch_scan(
             aidefense_api_key=aidefense_api_key,
             aidefense_api_url=request.aidefense_api_url,
             use_trigger=request.use_trigger,
+            use_osv=request.use_osv,
             llm_consensus_runs=request.llm_consensus_runs,
         )
 

skill_scanner/cli/cli.py

@@ -134,6 +134,7 @@ def _build_analyzers(policy: ScanPolicy, args: argparse.Namespace, status: Calla
         aidefense_api_key=getattr(args, "aidefense_api_key", None),
         aidefense_api_url=getattr(args, "aidefense_api_url", None),
         use_trigger=getattr(args, "use_trigger", False),
+        use_osv=getattr(args, "use_osv", False),
         llm_provider=getattr(args, "llm_provider", None),
         llm_consensus_runs=getattr(args, "llm_consensus_runs", 1),
         llm_max_tokens=getattr(args, "llm_max_tokens", None),
@@ -153,6 +154,8 @@ def _build_analyzers(policy: ScanPolicy, args: argparse.Namespace, status: Calla
             status("Using AI Defense analyzer")
         elif name == "trigger":
             status("Using Trigger analyzer (description specificity analysis)")
+        elif name == "osv_analyzer":
+            status("Using OSV dependency vulnerability analyzer")
 
     return analyzers
 
@@ -946,6 +949,11 @@ def _add_common_scan_flags(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--use-aidefense", action="store_true", help="Enable AI Defense analyzer (requires API key)")
     parser.add_argument("--aidefense-api-key", help="AI Defense API key (or set AI_DEFENSE_API_KEY)")
     parser.add_argument("--aidefense-api-url", help="AI Defense API URL (optional, defaults to US region)")
+    parser.add_argument(
+        "--use-osv",
+        action="store_true",
+        help="Enable OSV.dev dependency vulnerability scanning (no API key; requires network)",
+    )
     parser.add_argument(
         "--llm-provider",
         choices=["anthropic", "openai", "openai-compatible"],