Built by Maven

ai-build-integrity:verify-hashes

Full name:

com.intsof:ai-build-integrity-maven-plugin:0.9.1-SNAPSHOT:verify-hashes

Description:

Verifies that AI instruction resource files have not been modified since their hashes were generated.

This mojo finds all companion hash sidecar files under the base directory using NIO Files.walkFileTree, recomputes the hash of the corresponding source file, and compares the two. If any mismatch is detected, the build fails with a org.apache.maven.plugin.MojoExecutionException.

Security rationale: AI agent instructions must not change once a build has begun or after the artifact is shipped. This verification step ensures that no instruction file has been tampered with between the generate phase and the verification phase.

Performance: Uses Files.walkFileTree for a single-pass directory traversal with directory pruning. Handles both single-module projects and large multi-module projects efficiently.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is not marked as thread-safe and thus does not support parallel builds.
  • Binds by default to the lifecycle phase: test.

Optional Parameters

Name Type Since Description
<algorithmBits> int - Hash algorithm bit width. Must match what was used during generation.
Default: 256
User Property: ai.integrity.algorithm.bits
<baseDir> String - Base directory to scan; defaults to ${project.basedir}.
Default: ${project.basedir}
User Property: ai.integrity.baseDir
<centralHashFile> String - Explicit path to the central hash ledger file. When set, overrides the default target/ai-integrity.<ext> location and enables child modules in a multi-module project to verify against the root module's single shared ledger. Example: ${maven.multiModuleProjectDirectory/target/ai-integrity.sha256}
User Property: ai.integrity.centralHashFile
<centralReportFile> String - Explicit path to the central audit report file. When set, overrides the default target/ai-integrity-report.json location.
User Property: ai.integrity.centralReportFile
<executionRootOnly> boolean - If true, the mojo will only execute in the reactor's execution root project.
Default: false
User Property: ai.integrity.executionRootOnly
<failOnError> boolean - If false, validation failures will only log errors and will not break the build.
Default: true
User Property: ai.integrity.failOnError
<forceIncludes> String - Comma-separated glob patterns for files that MUST be processed, bypassing .gitignore rules.
User Property: ai.integrity.forceIncludes
<generateAuditReport> boolean - If true, generates a machine-readable JSON bill of materials for SIEM systems.
Default: true
User Property: ai.integrity.generateAuditReport
<gitignoreAutoExclude> boolean - If true, natively parse .gitignore files during traversal to auto-exclude paths.
Default: false
User Property: ai.integrity.gitignoreAutoExclude
<hashFileMode> HashFileMode - Strategy for storing generated hashes (SIDECAR or CENTRAL).
Default: SIDECAR
User Property: ai.integrity.hashFileMode
<hideHashFiles> boolean - If true, natively hides the generated hash sidecar files across all operating systems.
Default: true
User Property: ai.integrity.hideHashFiles
<normalizeLineEndings> boolean - If true, Normalizes CRLF to LF in memory before hashing, enabling cross-OS git hashes.
Default: false
User Property: ai.integrity.normalizeLineEndings
<outputExtension> String - Output extension for hash sidecar files. When set to "auto" (the default), the extension is derived from algorithmBits (e.g. .sha256).
Default: auto
User Property: ai.integrity.outputExtension
<skip> boolean - If true, skips the execution of the mojo. Accepts both -Dai.integrity.skip=true and the Maven-conventional -Dskip.ai.integrity=true.
Default: false
User Property: ai.integrity.skip
<skipAlt> boolean - Alternate Maven-conventional skip flag (e.g. -Dskip.ai.integrity=true).
Default: false
User Property: skip.ai.integrity
<skipDirs> String - Comma-separated directory names to skip during traversal.
Default: target,.git,node_modules,.tmp
User Property: ai.integrity.skipDirs

Parameter Details

<algorithmBits>

Hash algorithm bit width. Must match what was used during generation.
  • Type: int
  • Required: No
  • User Property: ai.integrity.algorithm.bits
  • Default: 256

<baseDir>

Base directory to scan; defaults to ${project.basedir}.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.baseDir
  • Default: ${project.basedir}

<centralHashFile>

Explicit path to the central hash ledger file. When set, overrides the default target/ai-integrity.<ext> location and enables child modules in a multi-module project to verify against the root module's single shared ledger. Example: ${maven.multiModuleProjectDirectory/target/ai-integrity.sha256}
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.centralHashFile

<centralReportFile>

Explicit path to the central audit report file. When set, overrides the default target/ai-integrity-report.json location.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.centralReportFile

<executionRootOnly>

If true, the mojo will only execute in the reactor's execution root project.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.executionRootOnly
  • Default: false

<failOnError>

If false, validation failures will only log errors and will not break the build.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.failOnError
  • Default: true

<forceIncludes>

Comma-separated glob patterns for files that MUST be processed, bypassing .gitignore rules.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.forceIncludes

<generateAuditReport>

If true, generates a machine-readable JSON bill of materials for SIEM systems.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.generateAuditReport
  • Default: true

<gitignoreAutoExclude>

If true, natively parse .gitignore files during traversal to auto-exclude paths.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.gitignoreAutoExclude
  • Default: false

<hashFileMode>

Strategy for storing generated hashes (SIDECAR or CENTRAL).
  • Type: com.intsof.ai.build.integrity.HashFileMode
  • Required: No
  • User Property: ai.integrity.hashFileMode
  • Default: SIDECAR

<hideHashFiles>

If true, natively hides the generated hash sidecar files across all operating systems.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.hideHashFiles
  • Default: true

<normalizeLineEndings>

If true, Normalizes CRLF to LF in memory before hashing, enabling cross-OS git hashes.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.normalizeLineEndings
  • Default: false

<outputExtension>

Output extension for hash sidecar files. When set to "auto" (the default), the extension is derived from algorithmBits (e.g. .sha256).
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.outputExtension
  • Default: auto

<skip>

If true, skips the execution of the mojo. Accepts both -Dai.integrity.skip=true and the Maven-conventional -Dskip.ai.integrity=true.
  • Type: boolean
  • Required: No
  • User Property: ai.integrity.skip
  • Default: false

<skipAlt>

Alternate Maven-conventional skip flag (e.g. -Dskip.ai.integrity=true).
  • Type: boolean
  • Required: No
  • User Property: skip.ai.integrity
  • Default: false

<skipDirs>

Comma-separated directory names to skip during traversal.
  • Type: java.lang.String
  • Required: No
  • User Property: ai.integrity.skipDirs
  • Default: target,.git,node_modules,.tmp