Codeward Intel

Codeward Intel is the knowledge graph the scanner resolves findings against. It is browsable at intel.codeward.io — packages, vulnerabilities, licences, CWEs and OWASP categories, with no account required.

The scanner ships no vulnerability database of its own. It parses your lockfiles, then asks Intel what it knows about what it found.

What Intel adds

A raw CVE feed tells you a package is affected. Intel also carries:

• EPSS — the probability a vulnerability is exploited in the wild in the next 30 days
• CISA KEV — whether it is on the Known Exploited Vulnerabilities catalogue
• Exploit maturity — whether public exploit code exists
• CVSS v3 severity, score and vector, resolved across advisory sources. CVSS v4 is not carried yet — the scanner has a slot for it and will prefer it once Intel publishes it, but every score you see today is v3 (or v2 for advisories that predate it)
• OWASP Top 10 and CWE mappings
• Licence compatibility — OSADL-derived conflict detection between licences in your tree
• Licence classification — Intel resolves a category and severity for every licence it knows, from the ScanCode LicenseDB category corpus plus choosealicense.com obligations. Licences missing from the scanner's built-in table take Intel's classification; where Intel has no resolved category, its copyleft strength fills in (strong becomes restricted, or forbidden for AGPL-family identifiers whose obligation extends over a network; weak becomes reciprocal; none becomes notice). By default the scanner's own table wins wherever it has a verdict; set CODEWARD_INTEL_CLASSIFICATION=true to make Intel's authoritative instead — see License categories
• Alias resolution — deprecated SPDX identifiers resolve to their canonical form, so a lockfile declaring GPL-3.0 is classified as GPL-3.0-only without the scanner carrying an alias table
• Package health and risk scoring — maintenance signals, deprecation, EOL dates, malicious-package reports, and typo-squat/takeover indicators

Modes

Mode	Data source	Needs a key	Freshness
download	Signed snapshot segments, downloaded and queried locally	No	As fresh as the last snapshot publish
api	Live queries against the Intel API	Yes	Live
local	Snapshot segments already in the cache; no network	No	Whatever you seeded
disabled	None — no vulnerability findings are produced	No	—

You do not have to choose. Leave --intel-mode unset and the scanner picks: api when CODEWARD_INTEL_TOKEN is present, download when it is not.

# Default — signed snapshots, no key needed
scan

# Live API, because a key is set
CODEWARD_INTEL_TOKEN=ck_… scan

# Explicit
scan --intel-mode local

warning

Setting --intel-mode api without a token fails immediately with a clear error. It used to 401 and report a repository with zero vulnerabilities, which is the most dangerous possible outcome for a security gate.

Snapshot mode in practice

In download mode the scanner fetches only the segments matching the ecosystems it actually found — an npm-only project never downloads the Python or Maven data.

Each figure below is core plus that ecosystem's vuln- and pkg- segments, as published in the August 2026 snapshot. They grow as Intel does; treat them as an order of magnitude, not a budget.

Project	Compressed download	On disk after decompression
npm	~87 MB	~1.5 GB
Python	~12 MB	~149 MB
Go	~8 MB	~105 MB
Maven	~7 MB	~78 MB
PHP	~6 MB	~60 MB
Ruby	~3 MB	~42 MB
.NET	~2 MB	~29 MB
Rust	~3 MB	~28 MB
All eight	~120 MB	~2.0 GB

Segments are served zstd-compressed and expanded locally, at roughly 16× on the SQLite files. The decompressed size is what needs disk, and for npm that is an order of magnitude more than the download. Cache the snapshot directory — the GitHub Action does this for you; elsewhere, persist whatever CODEWARD_CACHE_DIR points at. A warm cache fetches only what changed.

Ecosystems without snapshot coverage

Snapshots carry vulnerability data for npm, PyPI, Go, Maven, Cargo, RubyGems, NuGet and Composer only. The scanner parses lockfiles for five more ecosystems — Dart/Flutter (pubspec.lock), Swift (Package.resolved), CocoaPods (Podfile.lock), Elixir (mix.lock) and C/C++ (conan.lock) — and in download or local mode those produce package and licence findings but no vulnerability findings, and no degraded-scan warning, because there is no segment for them to be missing from.

Intel's API does hold advisories for those ecosystems, though coverage is thin. If you depend on them, run api mode with a key rather than the default snapshot path.

Integrity

Every snapshot manifest is signed with an Ed25519 key, and the public key is compiled into the scanner binary. Verification is on by default:

• The manifest signature is checked before any segment is trusted.
• Each segment's SHA-256 is verified after download, and the compressed archive's checksum is verified before it is decompressed.
• A bad or missing signature is a hard failure, not a warning. "No signature" is treated exactly like "wrong signature" — otherwise removing one field from a manifest would bypass the whole scheme.

CODEWARD_INTEL_PUBKEY overrides the built-in key for self-hosted Intel. The literal value none disables verification; do not use it against the public service.

Mirrors

Snapshots are served from an ordered list of mirrors, tried until one produces a manifest that verifies:

1. Intel itself
2. github.com/codeward-io/intel-db release assets

If a mirror serves something that fails verification, the scanner moves to the next one rather than failing the scan. Override the list for internal or air-gapped mirrors:

CODEWARD_INTEL_MIRRORS=https://mirror.internal/codeward,https://intel.codeward.io/api/v1/db

Your Intel API token is only ever sent to Intel, never to a mirror.

Extra segments

A scan downloads the smallest set of segments that answers it: core plus a vuln-<eco> and pkg-<eco> pair for every ecosystem it detected. Intel publishes more than that, and CODEWARD_INTEL_SEGMENTS selects the rest by group:

CODEWARD_INTEL_SEGMENTS=cwes            # CWE reference data
CODEWARD_INTEL_SEGMENTS=cwes,enrichments
CODEWARD_INTEL_SEGMENTS=all

Group	Segments	Adds
cwes	cwes	Names, descriptions, mitigations and OWASP mappings for the CWE IDs on an advisory (~370 KB compressed, 969 CWEs)
enrichments	vuln-enrichments, pkg-enrichments, license-enrichments	AI enrichment claims — currently empty, see below
rules	code_rules	Validated Codeward code scanning rules — currently empty, see below

Extras are best-effort. One that a mirror does not carry, or that fails to download, is logged and skipped rather than failing the scan — the scan is answerable without it.

Two of the three groups are empty today

cwes is the only group that currently carries data.

enrichments selects segments built from enrichments of type ai_enrichment, and Intel publishes none — all three databases ship as empty tables of a few hundred bytes. The resolved package intelligence (health and risk scores, category, alternatives, malicious and takeover signals) is carried on the pkg-<eco> segments regardless, so nothing is lost by leaving this off.

rules downloads rules that nothing executes yet: the scanner has no rule evaluator, and Intel publishes only rules with validation_status='passed', of which there are currently none. Both groups exist so the segments are reachable when that changes.

Freshness and staleness

Snapshots are generated by Intel and republished to the GitHub Releases mirror every six hours.

The run summary prints the snapshot's generated_at watermark and its age. A snapshot older than 7 days marks the scan degraded and puts a warning in the PR comment — a silently stale mirror produces the same false all-clear as an outage. Set CODEWARD_INTEL_MAX_AGE_DAYS to change that threshold, or 0 to suppress the staleness warning entirely — useful when you knowingly run an old air-gapped snapshot, or when byte-for-byte report comparisons must not change with wall-clock time.

In api mode the data is live; /api/v1/data-version exposes the current watermark.

When there is no data

If the scanner cannot obtain vulnerability data at all — outage, expired key, blocked egress, empty air-gapped cache — it fails the scan rather than reporting a clean repository:

Scan produced no vulnerability data
reason: Vulnerability data unavailable — results are incomplete: …
exit_code: 1

Set CODEWARD_INTEL_REQUIRED=false if a partial scan is genuinely preferable to a red build. The PR comment and run summary carry the warning either way.

Getting an API key

api mode needs a key with the query:batch scope. Keys are issued by hand while the service finds its footing — email [email protected] with the org and the rough scan volume you expect.

You do not need a key to:

• browse intel.codeward.io
• use the read API (/api/v1/packages/*, /vulnerabilities/*, /licenses/*, /cwes/*, …)
• run the scanner in download, local or disabled mode
• run the MCP server

Rate limits

Anonymous read endpoints are rate-limited per IP. Batch lookups accept up to 50 ids anonymously; above that a key is required. The bulk scanner query endpoint always requires a key.

The scanner retries 429 and 5xx responses with exponential backoff, honouring Retry-After.