secureCodeBox · J12934 · Sep 4, 2025 · Sep 3, 2025
diff --git a/.templates/new-scanner/parser/parser.test.js b/.templates/new-scanner/parser/parser.test.js
@@ -11,22 +11,22 @@ test("should properly parse new-scanner json file", async () => {
   const fileContent = JSON.parse(
     await readFile(import.meta.dirname + "/__testFiles__/example.com.json", {
       encoding: "utf8",
-    })
+    }),
   );
   const findings = await parse(fileContent);
   // validate findings
-  await expect(validateParser(findings)).resolves.toBeUndefined();
+  expect(validateParser(findings)).toBeUndefined();
   expect(findings).toMatchInlineSnapshot();
 });
 
 test("should properly parse empty json file", async () => {
   const fileContent = JSON.parse(
     await readFile(import.meta.dirname + "/__testFiles__/empty.json", {
       encoding: "utf8",
-    })
+    }),
   );
   const findings = await parse(fileContent);
   // validate findings
-  await expect(validateParser(findings)).resolves.toBeUndefined();
+  expect(validateParser(findings)).toBeUndefined();
   expect(findings).toMatchInlineSnapshot();
 });
diff --git a/documentation/docs/contributing/integrating-a-scanner/parser-dir.md b/documentation/docs/contributing/integrating-a-scanner/parser-dir.md
@@ -28,7 +28,7 @@ COPY --from=build --chown=root:root --chmod=755 /home/app/node_modules/ ./node_m
 COPY --chown=root:root --chmod=755 ./parser.js ./parser.js
 ```
 
-If your parser does not require any external dependencies, A multi-stage build is not needed.  
+If your parser does not require any external dependencies, A multi-stage build is not needed.
 Instead, a simpler Dockerfile can be used.
 
 ```dockerfile
@@ -94,7 +94,7 @@ Please provide some tests for your parser in the `parser.test.js` file. To make
 import { validateParser } from "@securecodebox/parser-sdk-nodejs/parser-utils";
 
 const findings = await parse(fileContent);
-await expect(validateParser(findings)).resolves.toBeUndefined();
+expect(validateParser(findings)).toBeUndefined();
 ```
 
 If you need additional files for your test please save these in the `__testFiles__` directory. Please take a look at [Integration Tests | secureCodeBox](/docs/contributing/integrating-a-scanner/integration-tests) for more information.

diff --git a/documentation/docs/contributing/test-concept/scanner-test.md b/documentation/docs/contributing/test-concept/scanner-test.md
@@ -12,7 +12,7 @@ We employ two types of tests: Unit tests for the parser and integration-tests. B
 
 ### Unit Tests for Parser
 
-Each scanner has a parser and each parser has a unit test file. The unit test file is named parser.test.js. This file contains different test scenarios. In each test, the results from parser.js and the folder `_snapshots_` are compared. If they are the same, the unit test is successful. 
+Each scanner has a parser and each parser has a unit test file. The unit test file is named parser.test.js. This file contains different test scenarios. In each test, the results from parser.js and the folder `_snapshots_` are compared. If they are the same, the unit test is successful.
 A unit test can look like this:
 
 ```js
@@ -24,7 +24,7 @@ test("parser parses large json result without vulnerable extensions successfully
     }
   );
   const findings = await parse(JSON.parse(fileContent));
-  await expect(validateParser(findings)).resolves.toBeUndefined();
+  expect(validateParser(findings)).toBeUndefined();
   expect(findings).toMatchSnapshot();
 });
 

diff --git a/parser-sdk/nodejs/Dockerfile b/parser-sdk/nodejs/Dockerfile
@@ -6,15 +6,14 @@ FROM oven/bun:1.2 AS build
 WORKDIR /home/app/
 COPY package.json package-lock.json ./
 RUN bun install --ignore-scripts
-COPY *.js ./
+COPY *.ts findings-schema.json  ./
 RUN bun run build
 
 FROM node:22-alpine
 ARG NODE_ENV
 RUN addgroup --system --gid 1001 app && adduser app --system --uid 1001 --ingroup app
 WORKDIR /home/app/parser-wrapper/
 COPY --chown=root:root --chmod=755 ./package.json ./package-lock.json ./
-COPY --chown=root:root --chmod=755 ./findings-schema.json ./findings-schema.json
 COPY --from=build --chown=root:root --chmod=755 /home/app/build/ ./
 USER 1001
 ENV NODE_ENV=${NODE_ENV:-production}

diff --git a/parser-sdk/nodejs/package-lock.json b/parser-sdk/nodejs/package-lock.json
diff --git a/parser-sdk/nodejs/package.json b/parser-sdk/nodejs/package.json
@@ -17,5 +17,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpointer": "^5.0.1"
   },
-  "devDependencies": {}
+  "devDependencies": {
+    "@types/node": "^22.18.0"
+  }
 }
diff --git a/parser-sdk/nodejs/parser-utils.js b/parser-sdk/nodejs/parser-utils.js
diff --git a/parser-sdk/nodejs/parser-utils.ts b/parser-sdk/nodejs/parser-utils.ts
@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: the secureCodeBox authors
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import { randomUUID } from "node:crypto";
+
+import addFormats from "ajv-formats";
+import { get } from "jsonpointer";
+import Ajv, { type ErrorObject } from "ajv-draft-04";
+import findingsSchema from "./findings-schema.json" with { type: "json" };
+
+const ajv = new Ajv();
+addFormats(ajv);
+
+export type Severity = "INFORMATIONAL" | "LOW" | "MEDIUM" | "HIGH";
+
+export interface Reference {
+  type: string;
+  value: string;
+}
+
+export interface ScanSummary {
+  created_at: string; // ISO8601 date-time
+  name: string;
+  namespace: string;
+  scan_type: string;
+}
+
+// parsers do not need to set all fields as fields like the ID are set by the parser-sdk
+export interface FindingFromParser {
+  identified_at?: string | null; // ISO8601 date-time
+  name: string;
+  description?: string | null;
+  category: string;
+  severity: Severity;
+  mitigation?: string | null;
+  references?: Reference[] | null;
+  attributes?: Record<string, unknown>;
+  location?: string | null;
+}
+
+export interface FindingWithIdsAndDates extends FindingFromParser {
+  id: string; // UUID v4
+  parsed_at: string; // ISO8601 date-time
+}
+
+export interface Finding extends FindingWithIdsAndDates {
+  scan: ScanSummary;
+}
+
+export interface Scan {
+  metadata: {
+    name: string;
+    namespace: string;
+    creationTimestamp: string;
+  };
+  spec: {
+    scanType: string;
+  };
+  status: {
+    rawResultType: string;
+  };
+}
+
+export function validate(findings: unknown): asserts findings is Finding[] {
+  const validator = ajv.compile(findingsSchema);
+  const valid = validator(findings);
+  if (!valid && validator.errors) {
+    const errorMessage = generateErrorMessage(validator.errors, findings);
+    throw new Error(errorMessage);
+  } else if (!valid) {
+    throw new Error("Validation of findings failed for unknown reasons.");
+  }
+}
+
+export function addScanMetadata(
+  findings: FindingWithIdsAndDates[],
+  scan: Scan,
+): Finding[] {
+  const scanMetadata = {
+    created_at: scan.metadata.creationTimestamp,
+    name: scan.metadata.name,
+    namespace: scan.metadata.namespace,
+        scan_type: scan.spec.scanType,
+  };
+
+  return findings.map((finding) => ({
+    ...finding,
+    scan: scanMetadata,
+  }));
+}
+
+export function addIdsAndDates(
+  findings: FindingFromParser[],
+): FindingWithIdsAndDates[] {
+  return findings.map((finding) => {
+    return {
+      ...finding,
+      id: randomUUID(),
+      parsed_at: new Date().toISOString(),
+    };
+  });
+}
+
+// used for tests to validate if the parser sets all required fields correctly. Adds sample IDs and Dates to the findings which would normally be set by the parser-sdk.
+export function validateParser(findings: FindingFromParser[]) {
+  const sampleScan: Scan = {
+    metadata: {
+      creationTimestamp: new Date().toISOString(),
+      name: "sample-scan-name",
+      namespace: "sample-namespace",
+    },
+    spec: {
+      scanType: "sample-scan-type",
+    },
+    status: {
+      rawResultType: "example-results",
+    },
+  };
+  // add sample IDs and Dates only if the findings Array is not empty
+  const extendedData = addScanMetadata(addIdsAndDates(findings), sampleScan);
+  return validate(extendedData);
+}
+
+function generateErrorMessage(errors: ErrorObject[], findings: Finding[]) {
+  return JSON.stringify(
+    errors.map((error) => {
+      return {
+        ...error,
+        invalidValue: get(findings, error.instancePath),
+      };
+    }),
+    null,
+    2,
+  );
+}