@mitre/hdf-schema 2.0.0

package/src/schemas/primitives/extensions.schema.json

@@ -0,0 +1,342 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v2.0.0",
+  "title": "HDF Extension Primitives",
+  "description": "Extension types for waivers, attestations, generators, and integrity.",
+  "$defs": {
+    "Status_Override": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "required": [
+        "type",
+        "status",
+        "reason",
+        "appliedBy",
+        "appliedAt",
+        "expiresAt"
+      ],
+      "properties": {
+        "type": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v2.0.0#/$defs/Override_Type",
+          "description": "The type of status override applied to this requirement."
+        },
+        "status": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v2.0.0#/$defs/Result_Status",
+          "description": "The new status this override sets for the requirement. This intentionally changes the compliance status."
+        },
+        "reason": {
+          "type": "string",
+          "description": "Explanation for why this status override was applied."
+        },
+        "appliedBy": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Identity",
+          "description": "Identity of who applied this status override. For simple cases, use type 'simple' with just an identifier."
+        },
+        "appliedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp when this status override was applied. ISO 8601 format."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp when this status override expires and must be reviewed/renewed. REQUIRED - no permanent status overrides allowed. ISO 8601 format."
+        },
+        "signature": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Signature",
+          "description": "Optional digital signature for enhanced trust and non-repudiation. Supports hardware security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other signing methods."
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Evidence"
+          },
+          "description": "Supporting evidence for this status override, such as screenshots demonstrating manual verification for attestations."
+        },
+        "previousChecksum": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Checksum",
+          "description": "SHA-256 checksum of the previous amendment in chronological order. Creates a tamper-evident chain of amendments (similar to blockchain). Null for the first amendment on a requirement."
+        }
+      },
+      "examples": [
+        {
+          "type": "waiver",
+          "status": "notApplicable",
+          "reason": "This control does not apply to containerized environments as the application runs in ephemeral containers without persistent storage",
+          "appliedBy": {
+            "identifier": "security-team@example.com",
+            "type": "email"
+          },
+          "appliedAt": "2025-12-01T10:00:00Z",
+          "expiresAt": "2026-12-01T00:00:00Z"
+        },
+        {
+          "type": "attestation",
+          "status": "passed",
+          "reason": "Manual verification completed: Reviewed firewall rules and confirmed all required ports are properly restricted per security policy",
+          "appliedBy": {
+            "identifier": "john.doe",
+            "type": "username",
+            "description": "Senior Security Engineer"
+          },
+          "appliedAt": "2025-11-30T14:30:00Z",
+          "expiresAt": "2026-05-30T00:00:00Z",
+          "evidence": [
+            {
+              "type": "screenshot",
+              "data": "base64-encoded-screenshot-data-here",
+              "description": "Screenshot showing firewall configuration",
+              "mimeType": "image/png",
+              "encoding": "base64",
+              "capturedAt": "2025-11-30T14:25:00Z",
+              "capturedBy": {
+                "identifier": "john.doe",
+                "type": "username"
+              }
+            }
+          ]
+        }
+      ],
+      "description": "An intentional change to a requirement's compliance status (waiver or attestation). Status overrides change the effectiveStatus of the requirement. All status overrides must have an expiration date to enforce periodic review.",
+      "title": "Status Override"
+    },
+    "POAM": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "required": [
+        "type",
+        "explanation",
+        "appliedBy",
+        "appliedAt"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "remediation",
+            "mitigation",
+            "riskAcceptance"
+          ],
+          "description": "The type of POA&M. 'remediation' fixes root cause. 'mitigation' reduces risk via compensating controls. 'riskAcceptance' documents decision to accept risk."
+        },
+        "explanation": {
+          "type": "string",
+          "description": "Detailed explanation of the plan, including what actions will be taken."
+        },
+        "appliedBy": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Identity",
+          "description": "Identity of who created this POA&M. For simple cases, use type 'simple' with just an identifier."
+        },
+        "appliedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp when this POA&M was created. ISO 8601 format."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Optional expiration date for this POA&M requiring review/renewal. ISO 8601 format."
+        },
+        "milestones": {
+          "type": "array",
+          "items": {
+            "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Milestone"
+          },
+          "description": "Optional array of milestones tracking progress toward completion."
+        },
+        "signature": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Signature",
+          "description": "Optional digital signature for enhanced trust and non-repudiation."
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Evidence"
+          },
+          "description": "Supporting evidence for this POA&M, such as documentation of compensating controls or mitigation implementation."
+        },
+        "previousChecksum": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Checksum",
+          "description": "SHA-256 checksum of the previous amendment in chronological order. Creates a tamper-evident chain of amendments (similar to blockchain). Null for the first amendment on a requirement."
+        }
+      },
+      "examples": [
+        {
+          "type": "remediation",
+          "explanation": "Upgrade OpenSSL to version 3.0.x to address CVE-2024-XXXXX vulnerability. Root cause: outdated dependency version in base image.",
+          "appliedBy": {
+            "identifier": "devops-team@example.com",
+            "type": "email"
+          },
+          "appliedAt": "2025-12-01T09:00:00Z",
+          "milestones": [
+            {
+              "description": "Update base Docker image to use OpenSSL 3.0.x",
+              "estimatedCompletion": "2025-12-15T00:00:00Z",
+              "status": "completed",
+              "completedAt": "2025-12-10T16:30:00Z",
+              "completedBy": {
+                "identifier": "alice.smith",
+                "type": "username"
+              }
+            },
+            {
+              "description": "Deploy updated image to production",
+              "estimatedCompletion": "2025-12-20T00:00:00Z",
+              "status": "inProgress"
+            },
+            {
+              "description": "Verify vulnerability no longer present via security scan",
+              "estimatedCompletion": "2025-12-22T00:00:00Z",
+              "status": "pending"
+            }
+          ]
+        },
+        {
+          "type": "mitigation",
+          "explanation": "Implement network segmentation as compensating control while awaiting vendor patch for database vulnerability. Traffic to vulnerable database server is restricted to internal management VLAN only.",
+          "appliedBy": {
+            "identifier": "security-architect",
+            "type": "system",
+            "description": "Automated POA&M creation from vulnerability scan"
+          },
+          "appliedAt": "2025-11-28T14:00:00Z",
+          "expiresAt": "2026-02-28T00:00:00Z",
+          "milestones": [
+            {
+              "description": "Configure firewall rules to restrict database access to management VLAN",
+              "estimatedCompletion": "2025-12-02T00:00:00Z",
+              "status": "completed",
+              "completedAt": "2025-11-29T11:15:00Z",
+              "completedBy": {
+                "identifier": "network-ops@example.com",
+                "type": "email"
+              }
+            },
+            {
+              "description": "Monitor for vendor security patch release",
+              "estimatedCompletion": "2026-02-28T00:00:00Z",
+              "status": "inProgress"
+            }
+          ],
+          "evidence": [
+            {
+              "type": "code",
+              "data": "# Firewall rule configuration\niptables -A INPUT -s 10.0.1.0/24 -p tcp --dport 5432 -j ACCEPT\niptables -A INPUT -p tcp --dport 5432 -j DROP",
+              "description": "Firewall rules restricting database access",
+              "mimeType": "text/plain"
+            }
+          ]
+        },
+        {
+          "type": "riskAcceptance",
+          "explanation": "Risk accepted for legacy system scheduled for decommissioning in Q1 2026. Cost of remediation ($50K for emergency upgrade) exceeds residual risk given 3-month remaining lifespan. Compensating controls: isolated network segment, enhanced monitoring.",
+          "appliedBy": {
+            "identifier": "ciso@example.com",
+            "type": "email"
+          },
+          "appliedAt": "2025-12-05T10:00:00Z",
+          "expiresAt": "2026-04-01T00:00:00Z",
+          "milestones": [
+            {
+              "description": "Complete migration to replacement system",
+              "estimatedCompletion": "2026-03-15T00:00:00Z",
+              "status": "inProgress"
+            },
+            {
+              "description": "Decommission legacy system",
+              "estimatedCompletion": "2026-03-31T00:00:00Z",
+              "status": "pending"
+            }
+          ]
+        }
+      ],
+      "description": "Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance. POAMs do NOT change the effectiveStatus - the requirement remains in its current state while the POA&M tracks remediation efforts.",
+      "title": "POAM"
+    },
+    "Generator": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the software that produced this HDF file. Example: 'gosec-to-hdf'."
+        },
+        "version": {
+          "type": "string",
+          "description": "The version of the tool. Example: '5.22.3'."
+        }
+      },
+      "description": "Information about the tool that generated this HDF file.",
+      "title": "Generator"
+    },
+    "Tool": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the security tool that produced the data. Examples: 'gosec', 'Semgrep', 'OpenSCAP', 'AWS Config', 'Nessus'. Omit if the tool cannot be identified."
+        },
+        "version": {
+          "type": "string",
+          "description": "Version of the source tool, if available in the tool's output. Example: '5.22.3'."
+        },
+        "format": {
+          "type": "string",
+          "description": "The file format, if it is a recognized named format shared by multiple tools. Examples: 'SARIF', 'XCCDF'. Omit for tool-specific formats where the tool name already implies the format (Nessus XML, gosec JSON)."
+        }
+      },
+      "description": "The security tool that produced the assessment data represented in this HDF file. Aligns with SARIF, OSCAL, and CycloneDX terminology.",
+      "title": "Tool"
+    },
+    "Integrity": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "dependentRequired": {
+        "algorithm": [
+          "checksum"
+        ],
+        "checksum": [
+          "algorithm"
+        ]
+      },
+      "properties": {
+        "algorithm": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Hash_Algorithm",
+          "description": "The hash algorithm used for the checksum."
+        },
+        "checksum": {
+          "type": "string",
+          "description": "The checksum value."
+        },
+        "signature": {
+          "type": "string",
+          "description": "Optional cryptographic signature."
+        },
+        "signedBy": {
+          "type": "string",
+          "description": "Identifier of who signed this file."
+        }
+      },
+      "examples": [
+        {
+          "algorithm": "sha256",
+          "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+        },
+        {
+          "algorithm": "sha512",
+          "checksum": "cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e",
+          "signature": "MEUCIQDx1y2hKl3mN8vP9qRz4tJ2sW5nX6cY8bD9aE3fG4hI5wIgK7mN8oP9qR0zS1tU2vW3xY4zA5bC6dD7eE8fG9hI0jK=",
+          "signedBy": "security-automation@example.com"
+        }
+      ],
+      "description": "Cryptographic integrity information for verifying the HDF file has not been tampered with. If algorithm is provided, checksum must also be provided, and vice versa.",
+      "title": "Integrity"
+    }
+  }
+}

package/src/schemas/primitives/parameter.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v2.0.0",
+  "title": "HDF Parameter Primitives",
+  "description": "Input/parameter type definitions for typed, traceable configuration values that bridge governance prose and scanner automation.",
+  "$defs": {
+    "Input_Type": {
+      "type": "string",
+      "enum": [
+        "String",
+        "Numeric",
+        "Boolean",
+        "Array",
+        "Hash",
+        "Regexp"
+      ],
+      "description": "The data type of the input value. Aligns with InSpec input types.",
+      "title": "Input Type"
+    },
+    "Comparison_Operator": {
+      "type": "string",
+      "enum": [
+        "eq",
+        "ne",
+        "lt",
+        "le",
+        "gt",
+        "ge",
+        "contains",
+        "matches",
+        "in",
+        "notIn"
+      ],
+      "description": "Comparison operator for evaluating the input value against observed values. Numeric: eq/ne/lt/le/gt/ge. String: eq/ne/contains/matches. Collection: in/notIn.",
+      "title": "Comparison Operator"
+    },
+    "Input_Constraints": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "properties": {
+        "min": {
+          "type": "number",
+          "description": "Minimum allowed value (for Numeric inputs)."
+        },
+        "max": {
+          "type": "number",
+          "description": "Maximum allowed value (for Numeric inputs)."
+        },
+        "pattern": {
+          "type": "string",
+          "description": "Regular expression pattern the value must match (for String inputs)."
+        },
+        "allowedValues": {
+          "type": "array",
+          "description": "Enumeration of permitted values."
+        }
+      },
+      "description": "Validation constraints for an input value.",
+      "title": "Input Constraints"
+    },
+    "Input": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The input name. Must be unique within a baseline or results document. Example: 'max_concurrent_sessions'."
+        },
+        "type": {
+          "$ref": "#/$defs/Input_Type",
+          "description": "The data type of this input."
+        },
+        "value": {
+          "description": "The input value. Type should match the declared type field. Accepts any JSON value."
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of what this input controls."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether this input must be provided. Defaults to false if omitted."
+        },
+        "sensitive": {
+          "type": "boolean",
+          "description": "Whether this input contains sensitive data (passwords, keys). Sensitive values should be redacted in output. Defaults to false if omitted."
+        },
+        "operator": {
+          "$ref": "#/$defs/Comparison_Operator",
+          "description": "The comparison operator used when evaluating this input against observed values."
+        },
+        "constraints": {
+          "$ref": "#/$defs/Input_Constraints",
+          "description": "Validation constraints for the input value."
+        }
+      },
+      "examples": [
+        {
+          "name": "max_concurrent_sessions",
+          "type": "Numeric",
+          "value": 3,
+          "description": "Maximum concurrent sessions per user",
+          "required": true,
+          "sensitive": false,
+          "operator": "le",
+          "constraints": { "min": 1, "max": 100 }
+        },
+        {
+          "name": "allowed_ciphers",
+          "type": "String",
+          "value": "AES256-GCM",
+          "description": "Permitted TLS cipher suite",
+          "constraints": { "pattern": "^AES" }
+        },
+        {
+          "name": "db_password",
+          "type": "String",
+          "sensitive": true
+        }
+      ],
+      "description": "A typed input parameter that bridges governance requirements and scanner automation. Inputs carry expected configuration values with type information, comparison operators, and validation constraints, enabling traceability from policy through to scan results.",
+      "title": "Input"
+    }
+  }
+}

package/src/schemas/primitives/plan.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/plan/v2.0.0",
+  "title": "HDF Plan Primitives",
+  "description": "Types for defining assessment plans — what to scan, how to configure it, and when to run.",
+  "$defs": {
+    "Plan_Type": {
+      "type": "string",
+      "enum": [
+        "automated",
+        "manual",
+        "hybrid"
+      ],
+      "description": "The type of assessment. 'automated' for scanner-driven, 'manual' for human-performed, 'hybrid' for both.",
+      "title": "Plan Type"
+    },
+    "Runner_Config": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Name of the assessment runner. Example: 'cinc-auditor', 'inspec', 'openscap'."
+        },
+        "version": {
+          "type": "string",
+          "description": "Version of the runner."
+        }
+      },
+      "description": "Configuration for the assessment runner/scanner.",
+      "title": "Runner Config"
+    },
+    "Assessment": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "required": [
+        "baselineRef"
+      ],
+      "properties": {
+        "baselineRef": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "Reference to the baseline to evaluate. May be a baseline name (e.g. 'RHEL9-STIG'), a relative path to an HDF Baseline document (e.g. 'rhel9-stig.hdf-baseline.json'), or an absolute URI."
+        },
+        "componentRef": {
+          "type": "string",
+          "format": "uuid",
+          "description": "componentId of the system component this assessment targets. Use for direct component binding. Alternative to targetSelector."
+        },
+        "targetSelector": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v2.0.0#/$defs/Target_Selector",
+          "description": "Label selector to match targets for this assessment. Overrides the system component's targetSelector if provided."
+        },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Resolved input values for this assessment. Keys are input names, values are the final resolved values (after baseline defaults + system overrides)."
+        },
+        "runner": {
+          "$ref": "#/$defs/Runner_Config",
+          "description": "Runner/scanner configuration for this assessment."
+        },
+        "description": {
+          "type": "string",
+          "description": "Description of this assessment's purpose."
+        }
+      },
+      "examples": [
+        {
+          "baselineRef": "RHEL9-STIG",
+          "targetSelector": { "labels.component": "WebTier" },
+          "inputs": {
+            "max_concurrent_sessions": 5,
+            "password_min_length": 15
+          },
+          "runner": {
+            "name": "cinc-auditor",
+            "version": "6.8.1"
+          }
+        }
+      ],
+      "description": "A single assessment within a plan — defines which baseline to run against which targets with what configuration.",
+      "title": "Assessment"
+    },
+    "Schedule": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "properties": {
+        "cron": {
+          "type": "string",
+          "description": "Cron expression for recurring assessments. Example: '0 2 1 * *' (2 AM on the 1st of each month)."
+        },
+        "startDate": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Earliest date to begin assessments. ISO 8601 format."
+        },
+        "endDate": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Date after which assessments should no longer run. ISO 8601 format."
+        },
+        "notifyOnRegression": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Email addresses or notification endpoints to alert when regressions are detected."
+        },
+        "notifyOnCompletion": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Email addresses or notification endpoints to alert when assessments complete."
+        }
+      },
+      "examples": [
+        {
+          "cron": "0 2 1 * *",
+          "notifyOnRegression": ["security-team@agency.gov"]
+        }
+      ],
+      "description": "Scheduling configuration for recurring assessments.",
+      "title": "Schedule"
+    }
+  }
+}

package/src/schemas/primitives/platform.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/platform/v2.0.0",
+  "title": "HDF Platform Primitive",
+  "description": "Legacy platform information for backward compatibility with existing HDF documents.",
+  "$defs": {
+    "Platform": {
+      "type": "object",
+      "unevaluatedProperties": false,
+      "required": [
+        "name",
+        "release"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the platform this was run on."
+        },
+        "release": {
+          "type": "string",
+          "description": "The version of the platform this was run on."
+        },
+        "targetId": {
+          "type": "string",
+          "description": "The id of the target. Example: the name and version of the operating system were not sufficient to identify the platform so a release identifier can additionally be provided like '21H2' for the release version of MS Windows 10."
+        }
+      },
+      "description": "Platform information such as its name. This is the legacy target representation; see Target for the new polymorphic target system.",
+      "title": "Platform"
+    }
+  }
+}