@mitre/hdf-schema 3.4.4 → 3.5.0

package/dist/helpers.d.ts

@@ -14,8 +14,19 @@ import type {
   ResultStatus,
   SupportedPlatform,
   RequirementGroup,
+  StatusOverride,
+  Poam,
+  Cvss,
+  Reference,
+  AffectedPackage,
+  Epss,
+  Kev,
+  OverrideType,
 } from '../dist/ts/hdf.js';
 
+/** Minimal identity shape used by amendment appliedBy fields. */
+type Identity = { type: string; identifier: string; description?: string };
+
 export function createMinimalBaseline(
   name: string,
   requirements: EvaluatedRequirement[],
@@ -35,13 +46,27 @@ export function createMinimalBaseline(
 
 export function createRequirement(
   id: string,
-  title: string,
+  title: string | null | undefined,
   descriptions: Description[],
   impact: number,
   results: RequirementResult[],
   options?: {
     sourceLocation?: SourceLocation;
     tags?: Record<string, unknown>;
+    code?: string;
+    // Amendment fields
+    effectiveStatus?: ResultStatus;
+    effectiveImpact?: number;
+    disposition?: OverrideType;
+    statusOverrides?: StatusOverride[];
+    poams?: Poam[];
+    // Vulnerability fields
+    cwe?: string[];
+    cvss?: Cvss[];
+    refs?: Reference[];
+    affectedPackages?: AffectedPackage[];
+    epss?: Epss;
+    kev?: Kev;
   }
 ): EvaluatedRequirement;
 
@@ -56,6 +81,8 @@ export function createResult(
     runTime?: number;
     backtrace?: string[];
     exception?: string;
+    resource?: string;
+    resourceId?: string;
   }
 ): RequirementResult;
 
@@ -68,6 +95,34 @@ export function createSupportedPlatform(
 
 export function createSourceLocation(ref: string, line: number): SourceLocation;
 
+export function createStatusOverride(
+  type: OverrideType | string,
+  options?: {
+    reason?: string;
+    appliedBy?: Identity;
+    appliedAt?: string;
+    expiresAt?: string;
+    status?: ResultStatus;
+    impact?: { value: number };
+  }
+): StatusOverride;
+
+export function createPoam(
+  type: 'remediation' | 'mitigation' | 'riskAcceptance' | 'vendorDependency' | string,
+  options?: {
+    explanation?: string;
+    appliedBy?: Identity;
+    appliedAt?: string;
+    expiresAt?: string;
+    milestones?: Array<Record<string, unknown>>;
+  }
+): Poam;
+
+export function createCvss(
+  version: string,
+  options?: Partial<Omit<Cvss, 'version'>>
+): Cvss;
+
 export function severityToImpact(severity: null): null;
 export function severityToImpact(severity: string): number;
 export function severityToImpact(severity: string | null): number | null;

package/dist/helpers.js

@@ -54,27 +54,43 @@ export function createMinimalBaseline(name, requirements, options = {}) {
 /**
  * Create a minimal valid EvaluatedRequirement
  * @param {string} id - Unique requirement identifier
- * @param {string} title - Human-readable title
+ * @param {string|null|undefined} title - Human-readable title. Pass null/undefined
+ *   to omit it (some controls legitimately have no title).
  * @param {import('../dist/ts/hdf-results.js').Description[]} descriptions - Array of descriptions
  * @param {number} impact - Impact score (0.0 to 1.0)
  * @param {import('../dist/ts/hdf-results.js').RequirementResult[]} results - Array of test results
- * @param {Object} [options] - Optional fields
+ * @param {Object} [options] - Optional fields: sourceLocation, code, tags;
+ *   amendment fields (effectiveStatus, effectiveImpact, disposition, statusOverrides, poams);
+ *   vulnerability fields (cwe, cvss, refs, affectedPackages, epss, kev).
  * @returns {import('../dist/ts/hdf-results.js').EvaluatedRequirement}
  */
 export function createRequirement(id, title, descriptions, impact, results, options = {}) {
   const req = {
     id,
-    title,
     descriptions,
     impact,
     results,
     tags: options.tags || {},
   };
 
-  // Only include sourceLocation if it's provided
-  if (options.sourceLocation) {
-    req.sourceLocation = options.sourceLocation;
-  }
+  if (title != null) req.title = title;
+  if (options.sourceLocation) req.sourceLocation = options.sourceLocation;
+  if (options.code != null) req.code = options.code;
+
+  // Amendment fields
+  if (options.effectiveStatus) req.effectiveStatus = options.effectiveStatus;
+  if (options.effectiveImpact != null) req.effectiveImpact = options.effectiveImpact;
+  if (options.disposition) req.disposition = options.disposition;
+  if (options.statusOverrides) req.statusOverrides = options.statusOverrides;
+  if (options.poams) req.poams = options.poams;
+
+  // Vulnerability fields
+  if (options.cwe) req.cwe = options.cwe;
+  if (options.cvss) req.cvss = options.cvss;
+  if (options.refs) req.refs = options.refs;
+  if (options.affectedPackages) req.affectedPackages = options.affectedPackages;
+  if (options.epss) req.epss = options.epss;
+  if (options.kev) req.kev = options.kev;
 
   return req;
 }
@@ -107,6 +123,8 @@ export function createResult(status, message, options = {}) {
     runTime: options.runTime,
     backtrace: options.backtrace,
     exception: options.exception,
+    ...(options.resource ? { resource: options.resource } : {}),
+    ...(options.resourceId ? { resourceId: options.resourceId } : {}),
   };
 }
 
@@ -144,11 +162,75 @@ export function createSourceLocation(ref, line) {
   return { ref, line };
 }
 
+/**
+ * Create a minimal valid inline Status_Override (requirement.statusOverrides[]).
+ * The schema requires one of status/impact; when neither is supplied this
+ * defaults status to 'notApplicable' so the built override stays valid.
+ * @param {string} type - Override_Type (waiver, attestation, falsePositive, riskAdjustment, ...)
+ * @param {Object} [options] - reason, appliedBy, appliedAt, expiresAt, status, impact
+ * @returns {Object}
+ */
+export function createStatusOverride(type, options = {}) {
+  const override = {
+    type,
+    reason: options.reason || 'Test override',
+    appliedBy: options.appliedBy || { type: 'simple', identifier: 'test' },
+    appliedAt: options.appliedAt || '2025-01-01T00:00:00Z',
+    expiresAt: options.expiresAt || '2099-12-31T00:00:00Z',
+  };
+  if (options.status) override.status = options.status;
+  if (options.impact) override.impact = options.impact;
+  if (!override.status && !override.impact) override.status = 'notApplicable';
+  return override;
+}
+
+/**
+ * Create a minimal valid POA&M (requirement.poams[]). expiresAt is schema-
+ * required (a POA&M is time-boxed) and defaults to a far-future constant.
+ * @param {string} type - remediation | mitigation | riskAcceptance | vendorDependency
+ * @param {Object} [options] - explanation, appliedBy, appliedAt, expiresAt, milestones
+ * @returns {Object}
+ */
+export function createPoam(type, options = {}) {
+  const poam = {
+    type,
+    explanation: options.explanation || 'Remediation planned',
+    appliedBy: options.appliedBy || { type: 'simple', identifier: 'test' },
+    appliedAt: options.appliedAt || '2025-01-01T00:00:00Z',
+    expiresAt: options.expiresAt || '2099-12-31T00:00:00Z',
+  };
+  if (options.milestones) poam.milestones = options.milestones;
+  return poam;
+}
+
+/**
+ * Create a Cvss primitive. Only `version` is schema-required; every other CVSS
+ * field is passed through from options when present.
+ * @param {string} version - CVSS version (e.g. '3.1', '4.0')
+ * @param {Object} [options] - source, baseVector, baseScore, baseSeverity, threatVector,
+ *   threatScore, environmentalVector, environmentalScore, supplementalVector, computedScore, computedSeverity
+ * @returns {Object}
+ */
+export function createCvss(version, options = {}) {
+  const cvss = { version };
+  const fields = [
+    'source', 'baseVector', 'baseScore', 'baseSeverity',
+    'threatVector', 'threatScore', 'environmentalVector', 'environmentalScore',
+    'supplementalVector', 'computedScore', 'computedSeverity',
+  ];
+  for (const f of fields) {
+    if (options[f] != null) cvss[f] = options[f];
+  }
+  return cvss;
+}
+
 // Re-export severity mapping from @mitre/hdf-utilities (canonical location).
 // Kept here for backwards compatibility — consumers importing from
 // @mitre/hdf-schema/helpers still get these functions.
 export { severityToImpact, impactToSeverity } from '@mitre/hdf-utilities';
 
+import { worstStatus } from '@mitre/hdf-utilities';
+
 /**
  * Compute the effective status of a requirement from its results and impact.
  *
@@ -157,10 +239,8 @@ export { severityToImpact, impactToSeverity } from '@mitre/hdf-utilities';
  *   1. effectiveStatus already set → return it
  *   2. impact === 0 → notApplicable
  *   3. No results → notReviewed
- *   4. Any "error" result → error
- *   5. Any "failed" result → failed
- *   6. All "passed" → passed
- *   7. Otherwise → notReviewed
+ *   4. Worst-wins roll-up of results via the canonical shared ordering
+ *      (error > failed > passed > notApplicable > notReviewed)
  *
  * @param {import('../dist/ts/hdf-results.js').EvaluatedRequirement} requirement
  * @returns {import('../dist/ts/hdf-results.js').ResultStatus}
@@ -174,31 +254,11 @@ export function computeEffectiveStatus(requirement) {
     return 'notApplicable';
   }
 
-  const results = requirement.results;
-  if (!results || results.length === 0) {
-    return 'notReviewed';
-  }
-
-  let hasError = false;
-  let hasFailed = false;
-  let hasPassed = false;
-
-  for (const result of results) {
-    switch (result.status) {
-      case 'error':
-        hasError = true;
-        break;
-      case 'failed':
-        hasFailed = true;
-        break;
-      case 'passed':
-        hasPassed = true;
-        break;
-    }
-  }
-
-  if (hasError) return 'error';
-  if (hasFailed) return 'failed';
-  if (hasPassed) return 'passed';
-  return 'notReviewed';
+  // Worst-wins roll-up via the canonical shared ordering (error > failed >
+  // passed > notApplicable > notReviewed); empty results -> notReviewed.
+  // NOTE: unlike the full effective-status computation in @mitre/hdf-utilities,
+  // this helper deliberately honors an already-set effectiveStatus first (its
+  // documented back-compat contract) and does not consult statusOverrides.
+  const results = requirement.results ?? [];
+  return worstStatus(results.map((result) => result.status));
 }

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export declare const hdfBaselineSchema: Readonly<Record<string, unknown>>;
 export declare const hdfComparisonSchema: Readonly<Record<string, unknown>>;
 export declare const hdfEvidencePackageSchema: Readonly<Record<string, unknown>>;
 export declare const hdfPlanSchema: Readonly<Record<string, unknown>>;
+export declare const hdfRequirementChangeEventSchema: Readonly<Record<string, unknown>>;
 export declare const hdfResultsSchema: Readonly<Record<string, unknown>>;
 export declare const hdfSystemSchema: Readonly<Record<string, unknown>>;
 export declare const affectedPackageSchema: Readonly<Record<string, unknown>>;
@@ -22,6 +23,7 @@ export declare const componentSchema: Readonly<Record<string, unknown>>;
 export declare const cvssSchema: Readonly<Record<string, unknown>>;
 export declare const dataFlowSchema: Readonly<Record<string, unknown>>;
 export declare const epssSchema: Readonly<Record<string, unknown>>;
+export declare const eventsSchema: Readonly<Record<string, unknown>>;
 export declare const extensionsSchema: Readonly<Record<string, unknown>>;
 export declare const kevSchema: Readonly<Record<string, unknown>>;
 export declare const parameterSchema: Readonly<Record<string, unknown>>;