Usage Guide¶

This guide describes how to run and configure the G.U.A.R.D. compliance gate locally and within continuous integration (CI) environments.

Local Setup¶

The G.U.A.R.D. audit gate tool is implemented in TypeScript and runs under Node.js.

Prerequisites¶

Node.js (v18 or higher)
Git (configured on your path)

Installation¶

To install dependencies for the CLI tool, navigate to the guard-audit-gate directory and run:

cd guard-audit-gate
npm install

Running the Tool¶

To build the TypeScript files and run a compliance audit against the default configuration:

npm run audit

You can also run the test suite to verify the code:

npm test

Docker Hub Deployment¶

For external projects or pipelines, the preferred way to run G.U.A.R.D. is by pulling the official image hosted on Docker Hub: benv01/guard-audit-gate:latest.

Using the Docker image avoids having to install Node.js and compile TypeScript files in your local workspace or CI runner.

Running with Docker¶

Mount your current repository directory into the container and execute the compliance check with optional HTML dashboard and audit receipt generation:

docker run --rm -v "$(pwd):/repo" benv01/guard-audit-gate:latest \
  --registry /repo/compliance-registry.yaml \
  --repo-root /repo \
  --base-sha HEAD~1 \
  --html-report /repo/guard-audit-dashboard.html \
  --receipt-out /repo/guard-audit-receipt.json \
  --project-name "EPR Core Service"

CLI Reference¶

The audit CLI can be configured using command-line arguments or environment variables.

Options¶

guard-audit-gate [options]

--registry <PATH>: The path to your compliance-registry.yaml file.
Default: ${repo-root}/mock-epr/compliance-registry.yaml
Env Variable: CHECKER_REGISTRY
--repo-root <PATH>: The root directory of the git repository to analyze.
Default: Current working directory (process.cwd())
Env Variable: CHECKER_REPO_ROOT
--base-sha <SHA>: The git commit SHA used as the baseline for change detection. If omitted, the tool automatically resolves the base commit.
Default: Auto-resolved (e.g. origin/main or the parent commit)
Env Variable: CHECKER_BASE_SHA
--html-report <PATH>: Path where the interactive standalone HTML dashboard will be saved.
Env Variable: CHECKER_HTML_REPORT_PATH
--receipt-out <PATH>: Path where the tamper-evident JSON audit receipt will be written.
Env Variable: CHECKER_RECEIPT_OUT_PATH
--history-dir <PATH>: Directory to persist and aggregate historical JSON audit receipts for long-term governance.
Env Variable: CHECKER_HISTORY_DIR
--project-name <NAME>: Human-readable name of the project shown in dashboard headers and receipts.
Env Variable: CHECKER_PROJECT_NAME / CI_PROJECT_NAME
--pipeline-url <URL>: Direct link to the CI/CD pipeline or build execution.
Env Variable: CHECKER_PIPELINE_URL / CI_PIPELINE_URL
--actor <NAME>: Identity of the user or system triggering the audit.
Env Variable: CHECKER_ACTOR / GITLAB_USER_NAME
--approver <NAME>: Identity of the compliance stakeholder approving detected drift.
Env Variable: CHECKER_APPROVER

CI/CD Pipeline Integration¶

G.U.A.R.D. is designed to run as a pull/merge request check in CI/CD pipelines to block non-compliant code changes from being merged while publishing management-ready audit artifacts.

GitLab CI Example¶

Add the following job to your .gitlab-ci.yml file:

stages:
  - test
  - compliance

guard_audit:
  stage: compliance
  image:
    name: benv01/guard-audit-gate:latest
    entrypoint: [""]
  variables:
    CHECKER_JUNIT_PATH: "$CI_PROJECT_DIR/guard-audit-report.xml"
    CHECKER_HTML_REPORT_PATH: "$CI_PROJECT_DIR/guard-audit-dashboard.html"
    CHECKER_RECEIPT_OUT_PATH: "$CI_PROJECT_DIR/guard-audit-receipt.json"
    CHECKER_PIPELINE_OUT_PATH: "$CI_PROJECT_DIR/audit-pipeline.yml"
  script:
    - node /app/dist/src/cli.js --registry ./compliance-registry.yaml --repo-root .
  artifacts:
    when: always
    paths:
      - audit-pipeline.yml
      - guard-audit-dashboard.html
      - guard-audit-receipt.json
    reports:
      junit: guard-audit-report.xml

Demonstration Projects (Mock EPR)¶

The workspace includes two demonstration Electronic Patient Record (EPR) projects showing G.U.A.R.D. verifying compliance mapping:

1. TypeScript Mock EPR (`mock-epr/`)¶

Located at mock-epr/, this is a Node/TypeScript web app.

To run it:

cd mock-epr
npm install
npm run dev

The compliance mappings are defined in mock-epr/compliance-registry.yaml and reference anchors inside mock-epr/src/main.ts.

2. Python Mock EPR (`mock-epr-python/`)¶

Located at mock-epr-python/, this is a Python-based web app.