cwe-api-client

TypeScript client for the MITRE CWE REST API. Works in Node.js and the browser (isomorphic). Fully typed, zero runtime dependencies.

---

Installation

npm install cwe-api-client

---

Quick start

import { CweClient } from 'cwe-api-client';

const cwe = new CweClient();

// Custom API base URL (e.g. a mirror)
const cwe = new CweClient({ baseUrl: 'https://my-mirror.example.com/api/v1' });

---

API reference

Version metadata

const version = await cwe.version();

console.log(version.ContentVersion);  // '4.19.1'
console.log(version.ContentDate);     // '2026-01-21'
console.log(version.TotalWeaknesses); // 969
console.log(version.TotalCategories); // 420
console.log(version.TotalViews);      // 58

Multi-ID lookup

Look up multiple CWE entries by their numeric IDs in a single request:

const entries = await cwe.lookup([74, 79]);

entries.forEach(e => console.log(`CWE-${e.ID} (${e.Type})`));
// CWE-74 (class_weakness)
// CWE-79 (base_weakness)

Weakness details

// Await directly
const weakness = await cwe.weakness(79);

// Or call .get() explicitly
const weakness = await cwe.weakness(79).get();

console.log(weakness.Name);                 // 'Improper Neutralization of Input...'
console.log(weakness.Abstraction);          // 'Base'
console.log(weakness.Status);              // 'Stable'
console.log(weakness.LikelihoodOfExploit); // 'High'
console.log(weakness.Description);

Category details

const category = await cwe.category(189);

console.log(category.Name);    // 'Numeric Errors'
console.log(category.Status);  // 'Draft'
console.log(category.Summary);
console.log(category.Relationships?.length); // number of member weaknesses

View details

const view = await cwe.view(1425);

console.log(view.Name);    // 'Weaknesses in the 2023 CWE Top 25...'
console.log(view.Type);    // 'Graph'
console.log(view.Status);  // 'Draft'
console.log(view.Members?.length); // 25

Hierarchy navigation

All hierarchy methods accept an optional viewId to scope the results to a specific CWE view (e.g. 1000 for Research Concepts):

// Direct parents
const parents = await cwe.weakness(74).parents(1000);
parents.forEach(p => console.log(`CWE-${p.ID}`, p.Primary_Parent ? '[primary]' : ''));

// Direct children
const children = await cwe.weakness(74).children(1000);
children.forEach(c => console.log(`CWE-${c.ID} (${c.Type})`));

// Full ancestor tree (recursive, up to the view root)
const ancestors = await cwe.weakness(74).ancestors(1000);
// ancestors[0].Data        → this node
// ancestors[0].Parents     → parent nodes (recursive)

// Full descendant tree (recursive, down to leaf entries)
const descendants = await cwe.weakness(74).descendants(1000);
// descendants[0].Data      → this node
// descendants[0].Children  → child nodes (recursive)

---

Chainable resource pattern

Every resource implements PromiseLike, so it can be awaited directly or chained to sub-methods:

// Await directly → fetches the full weakness
const weakness = await cwe.weakness(79);

// Chain → fetches hierarchy
const parents     = await cwe.weakness(74).parents(1000);
const descendants = await cwe.weakness(74).descendants(1000);

---

Request events

Subscribe to every HTTP request for logging, monitoring, or debugging:

cwe.on('request', (event) => {
  console.log(`[${event.method}] ${event.url} → ${event.statusCode} (${event.durationMs}ms)`);
  if (event.error) {
    console.error('Request failed:', event.error.message);
  }
});

The event object contains:

Field	Type	Description
url	string	Full URL that was requested
method	'GET'	HTTP method used
startedAt	Date	When the request started
finishedAt	Date	When the request finished
durationMs	number	Duration in milliseconds
statusCode	number | undefined	HTTP status code, if a response was received
error	Error | undefined	Present only if the request failed

Multiple listeners can be registered. The event is always emitted after the request completes, whether it succeeded or failed.

---

Error handling

Non-2xx responses throw a CweApiError with the HTTP status code and status text:

import { CweApiError } from 'cwe-api-client';

try {
  await cwe.weakness(99999).get();
} catch (err) {
  if (err instanceof CweApiError) {
    console.log(err.status);     // 404
    console.log(err.statusText); // 'Not Found'
    console.log(err.message);    // 'CWE API error: 404 Not Found'
    console.log(err.stack);      // full stack trace
  }
}

---

TypeScript types

All domain types are exported:

import type {
  // Client
  CweClientOptions, RequestEvent, CweClientEvents,
  // Version
  CweVersion,
  // Multi-ID lookup
  CweEntry, CweEntryType,
  // Weakness
  CweWeakness, CweRelatedWeakness, CweWeaknessOrdinality,
  CweApplicablePlatform, CweAlternateTerm,
  // Category
  CweCategory, CweTaxonomyMapping, CweCategoryRelationship, CweCategoryReference,
  // View
  CweView, CweViewAudience, CweViewMember,
  // Relations / hierarchy
  CweRelationEntry, CweAncestorNode, CweDescendantNode,
} from 'cwe-api-client';

---

Contributing

See CONTRIBUTING.md.

---

License

MIT