opena2a guard

Configuration file integrity signing, verification, policy enforcement, and real-time monitoring.

Usage

opena2a guard <subcommand> [options]

Subcommands

Subcommand	Description
`sign`	Compute and store SHA-256 hashes for config, SKILL.md, and HEARTBEAT.md files.
`verify`	Check files against stored hashes. Detect and report tampering.
`status`	Show summary of signed, unsigned, and tampered files.
`watch`	Real-time file system monitoring with timestamped tamper alerts.
`diff`	Show changes since the last signing (changed, missing, new files).
`policy init`	Generate a guard policy from currently signed files.
`policy show`	Display active policy settings and heartbeat status.
`hook install`	Install a pre-commit git hook that blocks tampered commits.
`hook uninstall`	Remove the guard pre-commit hook.
`hook status`	Check whether the guard hook is installed.
`resign`	Re-sign files after intentional modifications.
`snapshot create`	Save current signature state as a timestamped snapshot.
`snapshot list`	List all saved snapshots with file counts.
`snapshot restore`	Restore a previous snapshot (current state is backed up first).

Key Concepts

Concept	Details
Signature Store	`.opena2a/guard/signatures.json -- SHA-256 hashes for all guarded files.`
Policy File	`.opena2a/guard/policy.json -- enforcement rules (block unsigned, disable heartbeat on tamper).`
Snapshot Directory	`.opena2a/guard/snapshots/ -- timestamped backups of signature state (max 20, auto-pruned).`
Exit Codes	`0 = clean, 1 = tampered or unsigned files detected, 3 = quarantine (--enforce mode).`
Shield Integration	`opena2a shield status includes ConfigGuard state alongside other tool statuses.`
Skill Signatures	`HTML comment blocks appended to SKILL.md with pinned_hash, signed_at, signed_by.`
Heartbeat Signatures	`HTML comment blocks appended to HEARTBEAT.md with expires_at (7-day default).`

Default Guarded Files

When no --files flag is provided, guard automatically detects and signs these files:

mcp.json, .mcp.json, .claude/settings.json
package.json, package-lock.json
arp.yaml, arp.yml, arp.json
openclaw.json, .openclaw/config.json
.opena2a.yaml, .opena2a.json
tsconfig.json, go.mod, go.sum
pyproject.toml, requirements.txt
Dockerfile, docker-compose.yml

Core Subcommands

guard sign

Compute SHA-256 hashes for all detected (or specified) configuration files and store them in .opena2a/guard/signatures.json. With --skills or --heartbeats, signs the corresponding markdown files by appending an HTML comment signature block.

Flag	Description
`--files <files...>`	Specific files to sign (instead of auto-detection).
`--dir <path>`	Target directory to scan for config files.
`--skills`	Sign SKILL.md files (appends pinned_hash, signed_at, signed_by).
`--heartbeats`	Sign HEARTBEAT.md files (includes expires_at, 7-day default).

# Sign all detected config files

opena2a guard sign

# Sign specific files only

opena2a guard sign --files mcp.json package.json

# Sign SKILL.md files (appends HTML comment signature block)

opena2a guard sign --skills

# Sign HEARTBEAT.md files with 7-day expiry

opena2a guard sign --heartbeats

guard verify

Re-compute hashes and compare against the stored signatures. Reports tampered, unsigned, and missing files. In --enforce mode, tampered files trigger quarantine (exit code 3) and, when a policy is active, heartbeats are automatically disabled on tamper detection. Provides diff information for tampered files, including byte-level change size and key-level changes for JSON files.

Flag	Description
`--enforce`	Enable quarantine mode (exit code 3 on tamper).
`--skills`	Verify SKILL.md signature blocks.
`--heartbeats`	Verify HEARTBEAT.md signature blocks.
`--files <files...>`	Verify specific files only.
`--dir <path>`	Target directory.
`--ci`	CI mode (non-interactive, deterministic output).
`--format <text\|json>`	Output format.

# Verify all signed files

opena2a guard verify

# Verify in CI with JSON output

opena2a guard verify --ci --format json

# Enforce quarantine on tamper detection

opena2a guard verify --enforce

Exit Codes

Code	Meaning
`0`	All files match their stored signatures (clean).
`1`	One or more files are tampered or unsigned.
`3`	Quarantine triggered (--enforce mode only).

guard status

Display a summary of all guarded files, grouped by state: signed, unsigned, and tampered. Supports both text and JSON output formats.

# Show guard status

opena2a guard status

# JSON output for scripting

opena2a guard status --format json

guard watch

Start real-time file system monitoring for all signed config files. Uses fs.watch with debouncing to detect modifications as they happen. Prints timestamped alerts in the format HH:MM:SS TAMPERED filename (+Nb). Press Ctrl+C to stop.

# Start real-time monitoring

opena2a guard watch

# Example output

14:23:07  TAMPERED  mcp.json (+42b)
14:23:12  TAMPERED  package.json (+8b)

guard diff

Show all changes since the last signing. Reports files in three categories: CHANGED (hash mismatch with byte-level size difference), MISSING (signed file no longer exists), and NEW (file exists but was never signed). Supports --files to filter to specific paths.

# Show all changes since last signing

opena2a guard diff

# Filter to specific files

opena2a guard diff --files mcp.json

# Example output

CHANGED  mcp.json (+42 bytes)
MISSING  arp.yaml
NEW      docker-compose.yml

guard resign

Re-sign files after intentional modifications. Displays which files have been modified with byte-level diffs, creates a safety snapshot of the current signature state before re-signing, and prompts for confirmation. In CI mode, confirmation is automatic.

# Re-sign after intentional config changes

opena2a guard resign

# Re-sign in CI (auto-confirm)

opena2a guard resign --ci

Policy Subcommands

guard policy init

Generate a guard policy file at .opena2a/guard/policy.json from the currently signed files. The default policy sets blockOnUnsigned: true, disableHeartbeatOnTamper: true, and autoRemediate: false.

# Initialize guard policy from current signatures

opena2a guard policy init

# Generated policy structure

{
  "requiredFiles": ["mcp.json", "package.json", "..."],
  "blockOnUnsigned": true,
  "disableHeartbeatOnTamper": true,
  "autoRemediate": false
}

guard policy show

Display the current policy configuration, including required files, enforcement flags, and heartbeat status (active or DISABLED).

# Display current policy

opena2a guard policy show

Hook Subcommands

guard hook install | uninstall | status

Manage a pre-commit git hook that runs npx opena2a guard verify --ci --format textbefore each commit. The hook is installed as a bash script at .git/hooks/pre-commitand appends to any existing hook content without overwriting it. When config files are tampered, the commit is blocked.

For emergency situations, set SKIP_GUARD_VERIFY=1 to bypass the hook.

Action	Description
`install`	Install the pre-commit hook (appends to existing hooks).
`uninstall`	Remove the guard section from the pre-commit hook.
`status`	Check whether the guard hook is currently installed.

# Install pre-commit hook

opena2a guard hook install

# Check hook status

opena2a guard hook status

# Remove the hook

opena2a guard hook uninstall

# Emergency bypass (set environment variable)

SKIP_GUARD_VERIFY=1 git commit -m "emergency fix"

Snapshot Subcommands

guard snapshot create | list | restore <timestamp>

Manage timestamped snapshots of the signature store. Snapshots are saved in .opena2a/guard/snapshots/ with a maximum of 20 entries. Older snapshots are automatically pruned when the limit is reached.

Action	Description
`create`	Save current signatures.json as a timestamped snapshot.
`list`	List all snapshots with timestamps and file counts.
`restore <timestamp>`	Restore a snapshot. Current state is saved as a backup first.

# Create a snapshot of current signature state

opena2a guard snapshot create

# List all saved snapshots

opena2a guard snapshot list

# Restore a specific snapshot

opena2a guard snapshot restore 2026-03-02T14-30-00

CI/CD Integration

ConfigGuard integrates into CI/CD pipelines through exit codes and machine-readable output. A typical pipeline step verifies integrity and fails the build on tampering:

# GitHub Actions step

- name: Verify config integrity
  run: npx opena2a guard verify --ci --format json --enforce

# Full workflow: sign, install hook, verify

opena2a guard sign
opena2a guard policy init
opena2a guard hook install
opena2a guard verify --enforce

Related Commands

shield verify protect runtime