POC Walkthrough — oracledb (npm)

Last updated: 2026-05-24

The oracledb package is the canonical vendor-binary handling walkthrough in the CleanLibrary POC. It demonstrates the WARN verdict with supply-chain caveat — a third state between ALLOW (clean) and DENY (vulnerable). Useful for understanding how CleanLibrary handles packages that bundle native vendor binaries with redistribution-license complexity.

Versions covered

Version	Decision	Severity	Confidence	Composite Score
6.0.0	WARN	Medium	0.68	45
6.5.1	WARN	Medium	0.70	42
6.7.0	WARN	Medium	0.71	40
6.8.0	WARN	Medium	0.72	38
6.10.0	WARN	Medium	0.74	35

All WARN. Confidence rises with version recency; composite_score drops modestly. The WARN doesn't go away with newer versions — the vendor-binary characteristic is inherent to the package, not a version-specific issue.

1. Query a verdict

$ curl -sH "Authorization: Bearer your-poc-key" \
  https://cleanapp.clnstrt.dev/v1/customer/verdicts/npm/oracledb/6.10.0 | jq

{
  "verdict_id": "01KDVDNA00000000000000202K",
  "verdict": "INSUFFICIENT_DATA",
  "source": "INSUFFICIENT_DATA",
  "confidence": 0.74,
  "composite_score": 35,
  "severity": "MEDIUM",
  "reasoning": "oracledb 6.10.0 — bundles native vendor binary (Oracle Instant Client); review supply-chain provenance + license terms before production deploy",
  "evidence_gaps": [
    "vendor-binary signing chain not introspectable from package metadata",
    "Oracle redistribution license terms not auto-validated"
  ],
  "suggested_actions": [
    "Verify Oracle license compliance for redistribution scenario",
    "Pin to specific version; avoid floating updates"
  ],
  ...
}

2. Understanding the WARN

WARN ≠ "stop"; WARN = "informed-acceptance required". The verdict surfaces what CleanLibrary cannot autonomously verify:

Evidence gap	Customer action
Vendor-binary signing chain not introspectable	Verify Oracle Instant Client signing manually; or document acceptance
Oracle redistribution license terms not auto-validated	Legal review of your specific deployment scenario (per-developer vs container vs SaaS)

For oracledb, the WARN is signaling "this package is widely-deployed and works, but the supply-chain story has complexity beyond what we can verify on your behalf."

3. Risk-acceptance flow (Phase 1+)

Phase 1+ will expose cleanlib risk-accept for documented overrides:

$ cleanlib risk-accept --ecosystem npm --package oracledb --version 6.10.0 \
    --reason "Oracle Enterprise License agreement in place; signed off by Legal 2026-Q2"

This creates an audit-trail entry; subsequent verdict-API queries still return WARN, but your organization's policy evaluator can configure WARN-with-risk-acceptance → ALLOW.

4. SDK flow

from cleanlib_sdk import CleanlibClient

client = CleanlibClient(endpoint="https://cleanapp.clnstrt.dev", api_key="your-poc-key")

verdict = client.fetch_verdict("npm", "oracledb", "6.10.0")
print(f"{verdict.decision} (severity {verdict.severity}, conf {verdict.confidence}):")
print(f"  {verdict.reasoning}")
print(f"  Evidence gaps: {verdict.evidence_gaps}")
print(f"  Suggested actions: {verdict.suggested_actions}")
# WARN (severity Medium, conf 0.74):
#   oracledb 6.10.0 — bundles native vendor binary (Oracle Instant Client)...
#   Evidence gaps: ['vendor-binary signing chain not introspectable...', ...]
#   Suggested actions: ['Verify Oracle license compliance...', ...]

5. VS Code flow

CleanLibrary: Fetch verdict for package → npm → oracledb → 6.10.0.

Expected: Yellow warning icon, WARN, reasoning + evidence gaps + suggested actions visible in detail.

6. What this walkthrough validates

Capability	Demonstrated by oracledb
Third-state verdict (not just ALLOW/DENY)	WARN surfaces "needs informed acceptance"
Evidence-gap transparency	Explicit list of what CleanLibrary cannot verify
Vendor-binary handling	Verdict acknowledges native-binary-bundling complexity without auto-DENY
License-aware suggested actions	Acknowledges legal-review necessity for redistribution
Version-pinning recommendation	Suggests pinning to specific version to avoid surprise updates

7. What to look for during evaluation

• Does WARN match your team's posture toward vendor-binary-bundling packages? (Some teams treat WARN as DENY; some as "noted")
• Does the evidence-gap transparency align with what your engineers actually need to know to make a risk decision?
• Does the suggested-actions list reflect your team's actual remediation workflow?
• For Phase 2: would you use cleanlib risk-accept for documented overrides?

Feedback channel: see API Key Onboarding §7.