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:

docker run --rm -v "$(pwd):/repo" benv01/guard-audit-gate:latest \
  --registry /repo/compliance-registry.yaml \
  --repo-root /repo \
  --base-sha HEAD~1

CLI Reference¶

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

Options¶

guard-audit-gate [--registry PATH] [--repo-root PATH] [--base-sha SHA]

--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

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.

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: [""]
  script:
    # Run the compliance engine inside the container
    - node /app/dist/src/cli.js --registry ./compliance-registry.yaml --repo-root .

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.