feat(oci): normalize Docker Hub refs and use tree-sitter for Dockerfile parsing

Normalize Docker Hub image references in PURL generation so all FROM
formats (node:22, docker.io/node:22, docker.io/library/node:22) produce
the same repository_url=docker.io/node qualifier, matching the Hummingbird
hardened image index. Migrate Dockerfile FROM parsing from regex to
tree-sitter-containerfile for robust AST-based extraction. Rename
TRUSTIFY_DA_RECOMMENDATIONS_ENABLED to TRUSTIFY_DA_RECOMMEND and use
getCustom() for consistent env/option lookup. Support suffixed Dockerfile
variants (e.g. Dockerfile.dev).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: a-oren

CONVENTIONS.md

@@ -8,7 +8,8 @@
 - **TypeScript**: Configuration present but code is primarily JavaScript with JSDoc
 - **Node.js**: Requires Node >= 20.0.0, npm >= 11.5.1
 - **CLI**: `yargs` for command-line argument parsing
-- **Parsing Libraries**: `fast-xml-parser`, `fast-toml`, `smol-toml`, `tree-sitter-requirements`
+- **Parsing Libraries**: `fast-xml-parser`, `fast-toml`, `smol-toml`, `web-tree-sitter` with grammar packages (`tree-sitter-requirements`, `tree-sitter-gomod`, `tree-sitter-containerfile`)
+- **Prefer proper parsers over regex**: When parsing structured file formats (e.g., go.mod, requirements.txt, Dockerfile), use tree-sitter grammars rather than hand-written regex. Tree-sitter grammars already exist for several formats and provide a well-defined AST that handles edge cases. Follow the existing pattern: add the grammar package, create a `*_parser.js` module under `src/providers/`, copy the `.wasm` file in `pretest`/`postcompile` scripts, and use queries to extract data from the syntax tree.
 
 ## Code Style
 

README.md

@@ -695,7 +695,7 @@ By default, The API algorithm will use native commands of PIP installer as data
 It's also possible to use the lightweight Python PIP utility [pipdeptree](https://pypi.org/project/pipdeptree/) as data source instead. In order to activate this, you need to set the environment variable/option `TRUSTIFY_DA_PIP_USE_DEP_TREE` to 'true'.
 
 #### Toggle Red Hat Trusted Content recommendations
-Both the HTML-based report and JSON response will by default contain recommendations for migrating to Red Hat-based Trusted Content repositories. This feature can be disabled by setting `TRUSTIFY_DA_RECOMMENDATIONS_ENABLED` to 'false' via environment variables or options.
+Both the HTML-based report and JSON response will by default contain recommendations for migrating to Red Hat-based Trusted Content repositories. This feature can be disabled by setting `TRUSTIFY_DA_RECOMMEND` to 'false' via environment variables or options.
 
 #### Additional CLI arguments
 For some ecosystems we support passing additional CLI arguments to the underlying tools. The following table outlines the supported ecosystems and the environment variable/option that configures this. Note that the arguments are expected to be in the format of a JSON array.

package-lock.json

@@ -40,11 +40,11 @@
 		"test": "c8 npm run tests",
 		"tests": "mocha --config .mocharc.json",
 		"tests:rep": "mocha --reporter-option maxDiffSize=0 --reporter json > unit-tests-result.json",
-		"pretest": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm src/providers/tree-sitter-gomod.wasm",
+		"pretest": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm src/providers/tree-sitter-gomod.wasm && cp node_modules/tree-sitter-containerfile/tree-sitter-containerfile.wasm src/providers/tree-sitter-containerfile.wasm",
 		"precompile": "rm -rf dist",
 		"compile": "tsc -p tsconfig.json",
 		"compile:dev": "tsc -p tsconfig.dev.json",
-		"postcompile": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm dist/src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm dist/src/providers/tree-sitter-gomod.wasm"
+		"postcompile": "cp node_modules/tree-sitter-requirements/tree-sitter-requirements.wasm dist/src/providers/tree-sitter-requirements.wasm && cp node_modules/tree-sitter-gomod/tree-sitter-gomod.wasm dist/src/providers/tree-sitter-gomod.wasm && cp node_modules/tree-sitter-containerfile/tree-sitter-containerfile.wasm dist/src/providers/tree-sitter-containerfile.wasm"
 	},
 	"dependencies": {
 		"@babel/core": "^7.23.2",
@@ -61,25 +61,26 @@
 		"p-limit": "^7.3.0",
 		"packageurl-js": "~1.0.2",
 		"smol-toml": "^1.6.0",
+		"tree-sitter-containerfile": "^0.8.1",
 		"tree-sitter-gomod": "github:strum355/tree-sitter-go-mod#56326f2ad478892ace58ff247a97d492a3cbcdda",
 		"tree-sitter-requirements": "github:Strum355/tree-sitter-requirements#d0261ee76b84253997fe70d7d397e78c006c3801",
 		"web-tree-sitter": "^0.26.7",
 		"yargs": "^18.0.0"
 	},
 	"devDependencies": {
 		"@babel/core": "^7.23.2",
+		"@eslint/js": "^10.0.0",
 		"@trustify-da/trustify-da-api-model": "^2.0.9",
 		"@types/node": "^25.9.1",
 		"@types/which": "^3.0.4",
 		"babel-plugin-rewire": "^1.2.0",
 		"c8": "^11.0.0",
 		"chai": "^6.2.2",
-		"@eslint/js": "^10.0.0",
 		"eslint": "^10.4.1",
 		"eslint-import-resolver-typescript": "^4.4.4",
 		"eslint-plugin-import-x": "^4.16.2",
-		"globals": "^17.6.0",
 		"esmock": "^2.6.2",
+		"globals": "^17.6.0",
 		"mocha": "^11.7.6",
 		"msw": "^2.12.7",
 		"sinon": "^22.0.0",

package.json

@@ -44,7 +44,7 @@ async function requestStack(provider, manifest, url, html = false, opts = {}) {
 	}, opts);
 
 	const finalUrl = new URL(`${url}/api/v5/analysis`);
-	if (opts['TRUSTIFY_DA_RECOMMENDATIONS_ENABLED'] === 'false') {
+	if (getCustom('TRUSTIFY_DA_RECOMMEND', 'true', opts) === 'false') {
 		finalUrl.searchParams.append('recommend', 'false');
 	}
 
@@ -106,7 +106,7 @@ async function requestComponent(provider, manifest, url, opts = {}) {
 	}, opts);
 
 	const finalUrl = new URL(`${url}/api/v5/analysis`);
-	if (opts['TRUSTIFY_DA_RECOMMENDATIONS_ENABLED'] === 'false') {
+	if (getCustom('TRUSTIFY_DA_RECOMMEND', 'true', opts) === 'false') {
 		finalUrl.searchParams.append('recommend', 'false');
 	}
 
@@ -150,7 +150,7 @@ async function requestComponent(provider, manifest, url, opts = {}) {
  */
 async function requestStackBatch(sbomByPurl, url, html = false, opts = {}) {
 	const finalUrl = new URL(`${url}/api/v5/batch-analysis`)
-	if (opts['TRUSTIFY_DA_RECOMMENDATIONS_ENABLED'] === 'false') {
+	if (getCustom('TRUSTIFY_DA_RECOMMEND', 'true', opts) === 'false') {
 		finalUrl.searchParams.append('recommend', 'false')
 	}
 
@@ -203,7 +203,7 @@ async function requestImages(imageRefs, url, html = false, opts = {}) {
 	}
 
 	const finalUrl = new URL(`${url}/api/v5/batch-analysis`);
-	if (opts['TRUSTIFY_DA_RECOMMENDATIONS_ENABLED'] === 'false') {
+	if (getCustom('TRUSTIFY_DA_RECOMMEND', 'true', opts) === 'false') {
 		finalUrl.searchParams.append('recommend', 'false');
 	}
 

src/analysis.js

@@ -61,7 +61,7 @@ export {
  * TRUSTIFY_DA_PYTHON_PATH?: string | undefined,
  * TRUSTIFY_DA_PYTHON_VIRTUAL_ENV?: string | undefined,
  * TRUSTIFY_DA_PYTHON3_PATH?: string | undefined,
- * TRUSTIFY_DA_RECOMMENDATIONS_ENABLED?: string | undefined,
+ * TRUSTIFY_DA_RECOMMEND?: string | undefined,
  * TRUSTIFY_DA_SKOPEO_CONFIG_PATH?: string | undefined,
  * TRUSTIFY_DA_SKOPEO_PATH?: string | undefined,
  * TRUSTIFY_DA_SYFT_CONFIG_PATH?: string | undefined,

src/index.js

@@ -266,9 +266,23 @@ export class ImageRef {
 	getPackageURL() {
 		/** @type {Object.<string, string>} */
 		const qualifiers = {};
-		const repositoryUrl = this.image.getNameWithoutTag();
+		let repositoryUrl = this.image.getNameWithoutTag();
 		const simpleName = this.image.getSimpleName();
 
+		// Normalize Docker Hub image references so all forms produce the same PURL:
+		//   node         → docker.io/node
+		//   docker.io/library/node → docker.io/node
+		if (repositoryUrl != null) {
+			const lower = repositoryUrl.toLowerCase();
+			if (lower === simpleName.toLowerCase()) {
+				// Bare name (e.g. "node") — default to docker.io
+				repositoryUrl = `docker.io/${simpleName}`;
+			} else if (lower.startsWith('docker.io/library/')) {
+				// Official image with library/ prefix — strip it
+				repositoryUrl = `docker.io/${lower.substring('docker.io/library/'.length)}`;
+			}
+		}
+
 		if (repositoryUrl != null && repositoryUrl.toLowerCase() !== simpleName.toLowerCase()) {
 			qualifiers[ImageRef.REPOSITORY_QUALIFIER] = repositoryUrl.toLowerCase();
 		}

src/oci_image/images.js

@@ -0,0 +1,21 @@
+import { readFile } from 'node:fs/promises';
+
+import { Language, Parser, Query } from 'web-tree-sitter';
+
+const wasmUrl = new URL('./tree-sitter-containerfile.wasm', import.meta.url);
+
+async function init() {
+	await Parser.init();
+	const wasmBytes = new Uint8Array(await readFile(wasmUrl));
+	return await Language.load(wasmBytes);
+}
+
+export async function getParser() {
+	const language = await init();
+	return new Parser().setLanguage(language);
+}
+
+export async function getFromQuery() {
+	const language = await init();
+	return new Query(language, '(from_instruction (image_spec) @image)');
+}

src/providers/containerfile_parser.js

@@ -2,6 +2,8 @@ import fs from 'node:fs'
 
 import { generateImageSBOM, parseImageRef } from '../oci_image/utils.js'
 
+import { getFromQuery, getParser } from './containerfile_parser.js'
+
 export default { isSupported, validateLockFile, provideComponent, provideStack, readLicenseFromManifest, packageManagerName() { return 'oci' } }
 
 /** @typedef {import('../provider').Provider} */
@@ -16,11 +18,12 @@ const ecosystem = 'oci'
 
 /**
  * Check if the given manifest name is a Dockerfile or Containerfile.
+ * Supports suffixed variants such as Dockerfile.dev or Containerfile.prod.
  * @param {string} manifestName the manifest file name to check
  * @returns {boolean} true if the manifest is a Dockerfile or Containerfile
  */
 function isSupported(manifestName) {
-	return manifestName === 'Dockerfile' || manifestName === 'Containerfile'
+	return manifestName.startsWith('Dockerfile') || manifestName.startsWith('Containerfile')
 }
 
 /**
@@ -30,47 +33,55 @@ function isSupported(manifestName) {
 function validateLockFile() { return true; }
 
 /**
- * Parse the last FROM line from a Dockerfile to extract the base image reference.
- * In multi-stage builds, the last FROM represents the final stage.
- * @param {string} manifestContent the content of the Dockerfile
- * @returns {string} the image reference from the last FROM line
- * @throws {Error} when no FROM line is found in the Dockerfile
+ * Check whether a syntax node contains any expansion (variable substitution) children.
+ * @param {import('web-tree-sitter').SyntaxNode} node
+ * @returns {boolean}
+ * @private
  */
-export function parseFromImage(manifestContent) {
-	const lines = manifestContent.split(/\r?\n/)
-	let lastFrom = null
-	for (const line of lines) {
-		const trimmed = line.trim()
-		if (/^FROM\s+/i.test(trimmed)) {
-			// Extract image ref: FROM [--flag=val ...] image [AS name]
-			const tokens = trimmed.replace(/^FROM\s+/i, '').split(/\s+/)
-			// Skip all leading --flag tokens (e.g. --platform=linux/amd64)
-			let i = 0
-			while (i < tokens.length && tokens[i].startsWith('--')) {
-				i++
-			}
-			lastFrom = tokens[i] || null
+function containsExpansion(node) {
+	if (node.type === 'expansion') {
+		return true
+	}
+	for (let i = 0; i < node.childCount; i++) {
+		if (containsExpansion(node.child(i))) {
+			return true
 		}
 	}
-	if (!lastFrom) {
+	return false
+}
+
+/**
+ * Parse the last FROM instruction from a Dockerfile using tree-sitter to extract the base image reference.
+ * In multi-stage builds, the last FROM represents the final stage.
+ * @param {string} manifestContent the content of the Dockerfile
+ * @returns {Promise<string>} the image reference from the last FROM instruction
+ * @throws {Error} when no FROM instruction is found or when ARG substitution is used
+ */
+export async function parseFromImage(manifestContent) {
+	const [parser, fromQuery] = await Promise.all([getParser(), getFromQuery()])
+	const tree = parser.parse(manifestContent)
+	const matches = fromQuery.matches(tree.rootNode)
+	if (matches.length === 0) {
 		throw new Error('No FROM line found in Dockerfile')
 	}
-	if (lastFrom.includes('${')) {
+	const lastMatch = matches[matches.length - 1]
+	const imageSpec = lastMatch.captures.find(c => c.name === 'image').node
+	if (containsExpansion(imageSpec)) {
 		throw new Error('Dockerfile uses ARG substitution in FROM line — cannot resolve variable references')
 	}
-	return lastFrom
+	return imageSpec.text
 }
 
 /**
  * Generate an image SBOM from a Dockerfile manifest using syft.
  * @param {string} manifest path to the Dockerfile
  * @param {{}} [opts={}] optional various options to pass along the application
- * @returns {{ecosystem: string, content: string, contentType: string}}
+ * @returns {Promise<{ecosystem: string, content: string, contentType: string}>}
  * @private
  */
-function getImageSBOM(manifest, opts = {}) {
+async function getImageSBOM(manifest, opts = {}) {
 	const manifestContent = fs.readFileSync(manifest, 'utf-8')
-	const image = parseFromImage(manifestContent)
+	const image = await parseFromImage(manifestContent)
 	const imageRef = parseImageRef(image, opts)
 	const sbom = generateImageSBOM(imageRef, opts)
 	return {
@@ -84,19 +95,19 @@ function getImageSBOM(manifest, opts = {}) {
  * Provide content and content type for Dockerfile component analysis.
  * @param {string} manifest path to the Dockerfile
  * @param {{}} [opts={}] optional various options to pass along the application
- * @returns {Provided}
+ * @returns {Promise<Provided>}
  */
-function provideComponent(manifest, opts = {}) {
+async function provideComponent(manifest, opts = {}) {
 	return getImageSBOM(manifest, opts)
 }
 
 /**
  * Provide content and content type for Dockerfile stack analysis.
  * @param {string} manifest path to the Dockerfile
  * @param {{}} [opts={}] optional various options to pass along the application
- * @returns {Provided}
+ * @returns {Promise<Provided>}
  */
-function provideStack(manifest, opts = {}) {
+async function provideStack(manifest, opts = {}) {
 	return getImageSBOM(manifest, opts)
 }