@mitre/hdf-schema 2.0.0

package/LICENSE.md

@@ -0,0 +1,55 @@
+# License
+
+Copyright © 2025 The MITRE Corporation.
+
+Approved for Public Release; Distribution Unlimited. Case Number 18-3678.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain a
+copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+
+## Redistribution Terms
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+- Redistributions of source code must retain the above copyright/digital
+  rights legend, this list of conditions and the following Notice.
+- Redistributions in binary form must reproduce the above
+  copyright/digital rights legend, this list of conditions and the
+  following Notice in the documentation and/or other materials provided
+  with the distribution.
+- Neither the name of The MITRE Corporation nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+## Notice
+
+The MITRE Corporation grants permission to reproduce, distribute, modify, and
+otherwise use this software to the extent permitted by the licensed terms
+provided in the LICENSE file included with this project.
+
+This software was produced by The MITRE Corporation for the U.S. Government
+under contract. As such the U.S. Government has certain use and data
+rights in this software. No use other than those granted to the U.S.
+Government, or to those acting on behalf of the U.S. Government, under
+these contract arrangements is authorized without the express written
+permission of The MITRE Corporation.
+
+Some files in this codebase were generated by generative AI, under the
+direction and review of The MITRE Corporation employees, for the purpose of
+development efficiency. All AI-generated code functionality was validated
+by standard quality and assurance testing.
+
+For further information, please contact The MITRE Corporation,
+Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539,
+(703) 983-6000.

package/README.md

@@ -0,0 +1,143 @@
+# @mitre/hdf-schema
+
+JSON schemas and multi-language type definitions for **Heimdall Data Format (HDF)**.
+
+## Overview
+
+HDF is a standardized format for representing security assessment results. This package provides:
+
+- **JSON Schemas** for validating HDF documents
+- **Generated types** for TypeScript, Go, and Python
+
+## Installation
+
+```bash
+npm install @mitre/hdf-schema
+```
+
+## Schema Types
+
+### HDF Results
+
+Assessment results from running security checks against target systems. Contains:
+
+- Target system information (hosts, containers, cloud accounts, etc.)
+- Evaluated baselines with requirement results
+- Pass/fail status for each check
+- Statistics and timing data
+
+### HDF Baseline
+
+Security requirement definitions without results. Contains:
+
+- Requirement metadata (title, description, severity)
+- Check and fix instructions
+- Framework mappings (NIST, CIS, etc.)
+- Dependencies between requirements
+
+## Usage
+
+### Validating Documents (TypeScript/JavaScript)
+
+```typescript
+import Ajv from 'ajv';
+import hdfResultsSchema from '@mitre/hdf-schema/schemas/hdf-results.schema.json';
+
+const ajv = new Ajv({ strict: false });
+const validate = ajv.compile(hdfResultsSchema);
+
+const isValid = validate(myDocument);
+if (!isValid) {
+  console.error(validate.errors);
+}
+```
+
+### Using Generated Types (TypeScript)
+
+```typescript
+import type { HdfResults, HdfBaseline } from '@mitre/hdf-schema';
+
+function processResults(results: HdfResults) {
+  for (const baseline of results.profiles) {
+    for (const requirement of baseline.controls) {
+      console.log(`${requirement.id}: ${requirement.results[0]?.status}`);
+    }
+  }
+}
+```
+
+### Using Generated Types (Go)
+
+```go
+import "github.com/mitre/hdf-libs/hdf-schema/dist/go/hdf"
+
+func main() {
+    data := []byte(`{"platform": {...}, "profiles": [...]}`)
+    results, err := hdf.UnmarshalHdfResults(data)
+    if err != nil {
+        panic(err)
+    }
+    fmt.Println(results.Version)
+}
+```
+
+### Using Generated Types (Python)
+
+```python
+from hdf_results import HdfResults
+import json
+
+with open('results.json') as f:
+    data = json.load(f)
+    results = HdfResults.from_dict(data)
+    print(results.version)
+```
+
+## Schema Files
+
+| File | Description |
+|------|-------------|
+| `src/schemas/hdf-results.schema.json` | Results schema (modular, uses $ref) |
+| `src/schemas/hdf-baseline.schema.json` | Baseline schema (modular, uses $ref) |
+| `src/schemas/primitives/*.schema.json` | Shared type definitions |
+| `dist/schemas/hdf-results.schema.json` | Bundled results schema (self-contained) |
+| `dist/schemas/hdf-baseline.schema.json` | Bundled baseline schema (self-contained) |
+
+### Modular vs Bundled Schemas
+
+**Modular schemas** (`src/schemas/`) use `$ref` to reference shared definitions from primitive files. Use these if your validator supports `$ref` resolution.
+
+**Bundled schemas** (`dist/schemas/`) have all references inlined. Use these for tools that don't support `$ref` or for simpler integration.
+
+## Generated Types
+
+After building, types are available in:
+
+| Language | Location |
+|----------|----------|
+| TypeScript | `dist/ts/hdf-results.ts`, `dist/ts/hdf-baseline.ts` |
+| Go | `dist/go/hdf_results.go`, `dist/go/hdf_baseline.go` |
+| Python | `dist/python/hdf_results.py`, `dist/python/hdf_baseline.py` |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Build everything (schemas + types)
+pnpm build
+
+# Build only bundled schemas
+pnpm build:schemas
+
+# Build only generated types
+pnpm build:types
+```
+
+## Schema Version
+
+This package uses **JSON Schema draft/2020-12**.

package/dist/go/go.mod

@@ -0,0 +1,4 @@
+// Code generated by hdf-schema build. DO NOT EDIT.
+module github.com/mitre/hdf-schema
+
+go 1.23