@mitre/hdf-converters 3.0.0 → 3.1.0-rc.1

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

@@ -1,12 +1,73 @@
 # @mitre/hdf-converters
 
-Converters for transforming security tool outputs and HDF format versions.
-
-## Overview
-
-This library provides converters for:
-- **HDF v1.0 → v2.0**: Transform legacy HDF format to current version
-- **Security Tools** (future): 30+ security tool output converters (Nessus, SCAP, etc.)
+Convert security tool outputs to and from Heimdall Data Format (HDF). Part of the [hdf-libs](https://github.com/mitre/hdf-libs) monorepo.
+
+Every converter is implemented in both TypeScript and Go. The TypeScript library is published as an npm package; the Go implementations are used by the [`hdf` CLI](https://github.com/mitre/hdf-libs/tree/main/hdf-cli).
+
+All converter output conforms to the [HDF JSON Schema](https://mitre.github.io/hdf-libs/schemas/).
+
+## Supported Converters
+
+### Security Tool to HDF
+
+| Source Format | Function | Input |
+|---|---|---|
+| AWS Config | `convertAwsConfigToHdf` | JSON |
+| BurpSuite | `convertBurpsuiteToHdf` | XML |
+| Conveyor | `convertConveyorToHdf` | JSON |
+| CycloneDX (SBOM/VEX) | `convertCyclonedxToHdf` | JSON |
+| DBProtect | `convertDbprotectToHdf` | XML |
+| Dependency-Track | `convertDeptrackToHdf` | JSON |
+| Fortify | `convertFortifyToHdf` | XML |
+| GitLab Security Report | `convertGitlabToHdf` | JSON |
+| Gosec | `convertGosecToHdf` | JSON |
+| Grype | `convertGrypeToHdf` | JSON |
+| Ion Channel | `convertIonchannelToHdf` | JSON |
+| JFrog Xray | `convertJfrogXrayToHdf` | JSON |
+| JUnit | `convertJunitToHdf` | XML |
+| MSFT Defender for Cloud | `convertMsftDefenderCloudToHdf` | JSON |
+| MSFT Defender for DevOps | `convertMsftDefenderDevopsToHdf` | JSON |
+| MSFT Defender for Endpoint | `convertMsftDefenderEndpointToHdf` | JSON |
+| MSFT Secure Score | `convertMsftSecureScoreToHdf` | JSON |
+| Nessus | `convertNessusToHdf` | XML |
+| Netsparker / Invicti | `convertNetsparkerToHdf` | XML |
+| NeuVector | `convertNeuvectorToHdf` | JSON |
+| Nikto | `convertNiktoToHdf` | JSON |
+| OSCAL Catalog | `convertOscalCatalogToHdf` | JSON |
+| OSCAL Component Definition | `convertOscalComponentToHdf` | JSON |
+| OSCAL POA&M | `convertOscalPoamToHdf` | JSON |
+| OSCAL Profile | `convertOscalProfileToHdf` | JSON |
+| OSCAL SAP | `convertOscalSapToHdf` | JSON |
+| OSCAL SAR | `convertOscalSarToHdf` | JSON |
+| OSCAL SSP | `convertOscalSspToHdf` | JSON |
+| OWASP ZAP | `convertZapToHdf` | JSON |
+| Prisma Cloud | `convertPrismaToHdf` | JSON |
+| SARIF | `convertSarifToHdf` | JSON |
+| ScoutSuite | `convertScoutsuiteToHdf` | JSON |
+| Snyk | `convertSnykToHdf` | JSON |
+| SonarQube | `convertSonarqubeToHdf` | JSON |
+| Splunk | `convertSplunkToHdf` | JSON |
+| TruffleHog | `convertTrufflehogToHdf` | JSON |
+| Twistlock | `convertTwistlockToHdf` | JSON |
+| Veracode | `convertVeracodeToHdf` | JSON |
+| XCCDF Results | `convertXccdfResultsToHdf` | XML |
+
+### HDF to Other Formats
+
+| Target Format | Function |
+|---|---|
+| CSV | `convertHdfToCsv` |
+| XML | `convertHdfToXml` |
+| XCCDF | `convertHdfToXccdf` |
+| OSCAL SAR | `convertHdfToOscalSar` |
+| OSCAL POA&M | `convertHdfToOscalPoam` |
+
+### Format Migration
+
+| Conversion | Function |
+|---|---|
+| Legacy HDF (InSpec exec-json format) to current HDF | `convertV1ToV2` |
+| Detect legacy HDF format | `isHDFV1` |
 
 ## Installation
 
@@ -14,126 +75,103 @@ This library provides converters for:
 npm install @mitre/hdf-converters
 ```
 
-## Usage
+Requires Node.js >= 22.
 
-### HDF v1.0 to v2.0 Conversion
+## TypeScript Usage
 
-```typescript
-import { convertV1ToV2, isHDFV1 } from '@mitre/hdf-converters';
+All exports use ESM (`"type": "module"`).
 
-// Check if data is v1.0 format
-const data = JSON.parse(fileContent);
-if (isHDFV1(data)) {
-  const v2Data = convertV1ToV2(data);
-  console.log('Converted to v2.0:', v2Data);
-}
-```
+### Convert a security tool report
 
-### Key Changes in v2.0
+```typescript
+import { convertGrypeToHdf } from '@mitre/hdf-converters';
 
-- `version` field removed (implicit in schema)
-- `profiles` → `baselines`
-- `platform` (single object) → `targets` (array, supports multiple targets)
-- Extension fields moved to `extensions` object
+const grypeJson = fs.readFileSync('grype-report.json', 'utf-8');
+const hdfResults = convertGrypeToHdf(grypeJson, 'grype-report.json');
+```
 
-## Auto-Detection (Fingerprint Registry)
+### Auto-detect input format
 
-Automatically detect which converter to use for a given input:
+The `@mitre/hdf-converters/detect` sub-path provides lightweight format detection without importing any converter code.
 
 ```typescript
 import { registerAllFingerprints, detectConverter } from '@mitre/hdf-converters/detect';
 
 registerAllFingerprints();
 const result = detectConverter(rawInput);
-// result.fingerprint.id === 'gosec-to-hdf'
-// result.confidence === 1.0
+// result.fingerprint.id  -> e.g. 'grype-to-hdf'
+// result.confidence       -> 0.0 to 1.0
+// result.version          -> detected format version (if available)
 ```
 
-Each converter self-registers a lightweight structural fingerprint.
-Detection is cheap (~2KB, no converter imports). Conversion is lazy-loaded.
+### Upgrade legacy HDF
 
-Fingerprints can optionally detect the **format version** (e.g. SARIF 2.1.0,
-CycloneDX 1.5) via the `detectVersion` field on `ConverterFingerprint`. The
-detected version is returned in `DetectionResult.version`.
-
-See **[Fingerprint Registry Guide](../docs/guides/converter-fingerprint-registry.md)**
-for full documentation, usage examples, and how to add fingerprints for new converters.
+```typescript
+import { convertV1ToV2, isHDFV1 } from '@mitre/hdf-converters';
 
-## Version Specifiers
+const data = JSON.parse(fileContent);
+if (isHDFV1(data)) {
+  const currentHdf = convertV1ToV2(data);
+}
+```
 
-Converters support `format@version` syntax to specify input or output format versions:
+## Go Usage
 
-```bash
-# Explicit input version
-hdf convert --from sarif@2.0 scan.sarif
+Go converters live under `converters/<name>/go/` and follow the same function signature:
 
-# HDF schema version transforms
-hdf convert --from hdf@1 --to hdf@2 legacy.json     # Upgrade v1 → v2
-hdf convert --from hdf@1 --to hdf legacy.json        # Same (v2 is default)
+```go
+import grype "github.com/mitre/hdf-libs/hdf-converters/converters/grype-to-hdf/go"
 
-# Post-process any converter output to v1
-hdf convert --from grype --to hdf@1 scan.json         # Grype → HDF v2 → HDF v1
+results, err := grype.ConvertGrypeToHdf(input, "grype-report.json")
 ```
 
-### Version Defaulting
-
-- No `@version`: converter uses its latest supported version
-- `--to hdf` (no version): produces latest HDF version (currently v2)
-- `--to hdf@1`: downgrades output to HDF v1 (lossy — prints warning)
-- `--from legacyhdf` is an alias for `--from hdf@1 --to hdf@2`
+For CLI usage, install the `hdf` binary from [hdf-cli](https://github.com/mitre/hdf-libs/tree/main/hdf-cli):
 
-### Multi-Version Converters (VersionedConverter)
-
-Converters that handle multiple input versions implement `VersionedConverter`:
-
-```go
-type VersionedConverter interface {
-    Converter
-    SetInputVersion(version string)
-    SupportedVersions() []string
-}
+```bash
+hdf convert grype-report.json -o results.json          # auto-detect format
+hdf convert --from grype grype-report.json -o results.json  # explicit format
 ```
 
-When `SetInputVersion("")` is called (or not called at all), the converter
-defaults to its latest supported version. `SupportedVersions()` returns
-versions in order, latest first.
-
-### HDF Version Transforms
+## Package Exports
 
-The `hdfversion` package provides a registry-based router for HDF schema
-version transforms:
+| Import path | Contents |
+|---|---|
+| `@mitre/hdf-converters` | All converter functions and types |
+| `@mitre/hdf-converters/detect` | Auto-detection (fingerprints, `detectConverter`) |
+| `@mitre/hdf-converters/registry` | Fingerprint registry primitives |
 
-```go
-import "github.com/mitre/hdf-converters/shared/go/hdfversion"
+## Project Structure
 
-output, err := hdfversion.TransformHDF(input, "1", "2")  // upgrade
-output, err := hdfversion.TransformHDF(input, "2", "1")  // downgrade (lossy)
-ver, err := hdfversion.DetectHDFVersion(input)            // "1" or "2"
 ```
-
-```typescript
-import { transformHDF, detectHDFVersion } from '@mitre/hdf-converters/shared/typescript/hdf-version.js';
-
-const v2 = transformHDF(v1Input, '1', '2');
-const ver = detectHDFVersion(input); // '1' or '2'
+hdf-converters/
+  converters/<name>/
+    typescript/converter.ts       # TS implementation
+    typescript/converter.test.ts  # TS tests
+    go/converter.go               # Go implementation
+    go/converter_test.go          # Go tests
+    fixtures/input/               # Real tool output
+    fixtures/expected/            # Schema-validated expected HDF
+  shared/
+    typescript/                   # Shared TS helpers
+    go/                           # Shared Go helpers
+  src/
+    index.ts                      # Barrel export (all converters)
+    detect.ts                     # Auto-detection sub-path entry
 ```
 
-## Adding New Converters
-
-This package maintains **dual implementations** (TypeScript and Go) for all converters:
-- TypeScript for npm package (web apps, Node.js tools)
-- Go for `hdf-cli` (standalone binary, better security)
+Each converter has shared test fixtures and differential tests that verify TypeScript and Go produce identical output.
 
-See **[CONVERTER_GUIDE.md](./CONVERTER_GUIDE.md)** for complete implementation instructions.
+## Adding a New Converter
 
-**Quick start**:
-1. Implement TypeScript converter in `converters/{tool}/typescript/`
-2. Add test fixtures in `converters/{tool}/fixtures/`
-3. Port to Go in `converters/{tool}/go/`
-4. Differential tests ensure both produce identical output
+See [CONVERTER_GUIDE.md](https://github.com/mitre/hdf-libs/blob/main/hdf-converters/CONVERTER_GUIDE.md) for implementation instructions.
 
-**Architecture decision**: [ADR-001](../docs/architecture/ADR-001-dual-converter-implementations.md)
+Summary:
+1. Add real tool output fixtures in `converters/<name>/fixtures/input/`
+2. Write tests first (TDD) in both TypeScript and Go
+3. Implement the converter in `converters/<name>/typescript/` and `converters/<name>/go/`
+4. Register a fingerprint for auto-detection
+5. Add a CLI wrapper in `hdf-cli/cmd/hdf/cmd/`
 
 ## License
 
-Apache-2.0 © MITRE Corporation
+Apache-2.0 -- MITRE Corporation

package/dist/detect.d.ts

@@ -0,0 +1,28 @@
+import { ConverterDirection, ConverterFingerprint, InputFamily, OutputType, getFingerprint, getFingerprints, getIngestFingerprints, registerFingerprint } from "./registry.js";
+
+//#region shared/typescript/fingerprint.d.ts
+interface DetectionResult {
+  fingerprint: ConverterFingerprint;
+  confidence: number;
+  /** Detected format version (e.g. "2.1.0" for SARIF). Empty when not available. */
+  version: string;
+}
+declare function detectConverter(input: string): DetectionResult | undefined;
+declare function detectConverterAll(input: string): DetectionResult[];
+declare function detectFamily(input: string): InputFamily | undefined;
+//#endregion
+//#region shared/typescript/register-all.d.ts
+/**
+ * Explicit fingerprint registration for all converters.
+ *
+ * Consumers call registerAllFingerprints() once at startup.
+ * This avoids side-effect imports that bundlers tree-shake away.
+ */
+/**
+ * Register all known converter fingerprints.
+ * Idempotent — safe to call multiple times or after _resetRegistry().
+ */
+declare function registerAllFingerprints(): void;
+//#endregion
+export { type ConverterDirection, type ConverterFingerprint, type DetectionResult, type InputFamily, type OutputType, detectConverter, detectConverterAll, detectFamily, getFingerprint, getFingerprints, getIngestFingerprints, registerAllFingerprints, registerFingerprint };
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","names":[],"sources":["../shared/typescript/fingerprint.ts","../shared/typescript/register-all.ts"],"mappings":";;;UASiB,eAAA;EACf,WAAA,EAAa,oBAAA;EACb,UAAA;EAEA;EAAA,OAAA;AAAA;AAAA,iBAMc,eAAA,CAAgB,KAAA,WAAgB,eAAA;AAAA,iBAgBhC,kBAAA,CAAmB,KAAA,WAAgB,eAAA;AAAA,iBAoCnC,YAAA,CAAa,KAAA,WAAgB,WAAA;;;;;;AA9D7C;;;;;;;iBCwGgB,uBAAA,CAAA"}

package/dist/detect.js

@@ -0,0 +1,3 @@
+import { getFingerprint, getFingerprints, getIngestFingerprints, registerFingerprint } from "./registry.js";
+import { i as detectFamily, n as detectConverter, r as detectConverterAll, t as registerAllFingerprints } from "./register-all-DaYHszLd.js";
+export { detectConverter, detectConverterAll, detectFamily, getFingerprint, getFingerprints, getIngestFingerprints, registerAllFingerprints, registerFingerprint };