Technical Appendix • v2.3.3

Trust Model & Proof

Every claim on this page is backed by source code, passing automated tests, or both. This document is the honest contract between Terminal Guardian and its buyers.

verified-claims.json → | Homepage proof section →

Test evidence summary

Pester full suite

458

passed • 0 failed • Pester v3.4.0

tests/ — Invoke-Pester -Path tests

Fail-closed assertions

passed • 0 failed • deterministic

TerminalGuardian/test-failclosed.ps1

All test results are deterministic and reproducible by running the two commands above from the installed module directory. No network access is required to reproduce these results.

What it is

Terminal Guardian is a Windows-only PowerShell 7+ safety module. It intercepts every command in the PowerShell sessions it governs and evaluates each one against an active policy pack before execution — not after.

Platform

Windows only • PowerShell 7+ (pwsh)

Current release

v2.3.3 — validated & tested

Evaluation model

Deterministic rule-based policy — no ML, no heuristics

Enforcement

Local-first — core enforcement runs on your machine

Four deterministic policy outcomes

The same command evaluated against the same policy always produces the same outcome. No probabilistic scoring, no behavioral drift, no model retraining.

ALLOW

Command clears policy. Execution proceeds with no user-visible interruption.

WARN

Elevated risk flagged. Execution continues with a visible warning written to the audit trail.

CHALLENGE

Explicit confirmation required before execution. Outcome logged regardless of user response.

BLOCK

Command halted. Execution does not proceed. Policy rule name and actor written to audit trail.

Verified

Verified claims table

Every claim below is backed by source code and/or passing tests. The evidence file column names the exact file that can be inspected to confirm the claim.

PowerShell native module

VERIFIED

Native pwsh module with module manifest, selftest command, and profile hook installer.

Evidence: TerminalGuardian.psd1, TerminalGuardian.psm1 • Type: source

Denylist enforcement — 13 shipped rules

VERIFIED

TG-001 through TG-013 cover destructive delete, disk wipe, Format-Volume, recursive remove, and redaction test token.

Evidence: TerminalGuardian/Rules/default-rules.json • Type: source + test (test-failclosed.ps1 Test 2)

JSON-first rule evaluation (denylist before semantic)

VERIFIED

Explicit JSON denylist rules are evaluated before any semantic analysis stage. No command can bypass the denylist via a later stage.

Evidence: Private/RuleEngine.ps1 lines 179-197 • Type: source + test (BrainLane.Integration.Tests.ps1)

Action tiers: block, challenge, warn

VERIFIED

Four deterministic outcomes: block (TG-006, TG-007, TG-012, TG-013), challenge (TG-001–005), warn (TG-008–011), allow (default).

Evidence: Rules/default-rules.json action fields • Type: source + Pester suite (458 passed)

Audit logging — unconditional for blocked and forced events

VERIFIED

Tab-separated log: timestamp, eventType, severity, ruleId, forcedRuleId, description, userChoice, redactedCommandLine. Blocked and forced events logged even when logLevel=off.

Evidence: Private/Logger.ps1 • Type: source

Secret redaction — [REDACTED] before any log write

VERIFIED

Passwords, API keys, and tokens matching known patterns are replaced with [REDACTED] before any log write. Deterministically tested.

Evidence: Private/Redaction.ps1 • Type: source + test (TG-013 redaction test)

Local-first enforcement path

VERIFIED

Command evaluation, policy matching, and enforcement run entirely on the local machine. No command content is sent to a remote server during normal operation.

Evidence: Private/RuleEngine.ps1 (no remote call in evaluation path) • Type: source

Forced bypass always logged — --TG-Force at HIGH severity

VERIFIED

--TG-Force can override a block or challenge, but is itself logged as a forced event at HIGH severity — unconditionally, even when logLevel is off.

Evidence: Private/Logger.ps1 line 33 (forced always-logged) • Type: source

Fail-closed rule load protection

VERIFIED — 15/15 tests pass

If rule files are missing, unreadable, or malformed, all commands are blocked — not silently allowed. A CRITICAL audit event is written unconditionally.

Evidence: Private/RuleEngine.ps1 lines 43-116 & 165-177 • Type: source + test-failclosed.ps1 (15/15)

SHA-256 checksum + integrity manifest

VERIFIED

Every release ZIP has a published SHA-256 checksum. tg selftest computes local file hashes and compares them against the remote integrity manifest.

Evidence: docs/CHECKSUMS.txt, Get-TGRemoteIntegrityManifest.ps1 • Type: source + build artifact

Semantic pipeline error fail-closed

VERIFIED

If the AST semantic analysis pipeline throws an unexpected error, the policy decision is block — not allow. All pipeline failures default to the safe outcome (TgCode=TG-SEM-ERR).

Evidence: Private/RuleEngine.ps1 lines 200-221 (try/catch → block) • Type: source

Clean automated test suite — 458 + 15 passing

VERIFIED

Pester full suite: 458 passed, 0 failed. Fail-closed assertions: 15 passed, 0 failed. Deterministic and reproducible.

Evidence: tests/ (Pester v3.4.0) + TerminalGuardian/test-failclosed.ps1 • Type: automated test suite

Safety Invariant

Fail-closed enforcement — technical detail

A security tool that silently allows everything when it breaks is not a security tool. Terminal Guardian defaults to block — not allow — when any rules loading error occurs.

Trigger conditions (any one causes fail-closed):

■ Default rules file (Rules/default-rules.json) does not exist
■ Default rules file exists but cannot be read (permissions, locked)
■ Default rules file contains invalid or malformed JSON
■ User rules file (~/.terminal-guardian/rules.json) exists but cannot be read or parsed

Policy on failure:

■ onRuleLoadError=block-all (default): all commands blocked with RuleId=FAIL-CLOSED
■ onRuleLoadError=allow: old behavior preserved (not recommended; audit event still emitted)

Audit event on failure (always written, ignores logLevel):

<ISO8601-timestamp> critical CRITICAL RULES_LOAD_FAILURE - ENTERING FAIL-CLOSED MODE <reason>

Recovery:

Run Update-TerminalGuardianRules after fixing the rules file. If rules now load cleanly, fail-closed state clears automatically.

Test evidence

test-failclosed.ps1: 15 assertions, 0 failed. Tests cover: valid rules allow, denylist challenge, missing rules block-all, corrupt rules block-all, CRITICAL audit event written, and recovery after reload.

Source: Private/RuleEngine.ps1 lines 43-116 (Get-TerminalGuardianRules) and 165-177 (Get-TerminalGuardianAction)

Audit logging — technical detail

Every enforcement event is written to a local tab-separated log file. Blocked and forced events are written unconditionally — even when logLevel=off. Critical events (rules load failure) are also always written.

Log file location:

~/.terminal-guardian/logs/guardian_YYYY-MM-DD.log

Log entry format (tab-separated fields):

Field	Values
timestamp	ISO 8601 datetime
eventType	blocked, warned, allowed, forced, critical
severity	LOW, MEDIUM, HIGH, CRITICAL
ruleId	TG-001…TG-013, FAIL-CLOSED, TG-SEM-ERR, etc.
forcedRuleId	Rule overridden by --TG-Force, if applicable
description	Human-readable event description
userChoice	User response to challenge, if applicable
redactedCommandLine	Command with secrets replaced by [REDACTED]

Always-logged event types: blocked, forced, critical — regardless of logLevel setting. This ensures a bypass or failure can never be silently omitted from the audit record.

Secret redaction — technical detail

Before any command line is written to the audit log, it passes through the redaction layer. Recognized secret patterns are replaced with [REDACTED] — the raw value never reaches the log file.

Pattern types detected and redacted:

Passwords and passphrases passed as command arguments
API keys and bearer tokens
Connection strings containing credentials
TG_REDACTION_TEST_SECRET pattern (used for deterministic test verification)

Source: Private/Redaction.ps1 • Verified by: TG-013 rule + redaction deterministic test

SHA-256 checksum & integrity manifest

Every Terminal Guardian release ZIP ships with a published SHA-256 checksum. The tg selftest command computes local SHA-256 hashes of module files and compares them against the remote integrity manifest.

v2.3.3 release checksum:

14b4d6da1d8a888500463c66b592f63c9b95ea1c22620229f372a9411905205e TerminalGuardian_Windows_PowerShell_v2.3.3.zip

Verify locally:

Get-FileHash -Algorithm SHA256 -LiteralPath .\TerminalGuardian_Windows_PowerShell_v2.3.3.zip

Evidence files: docs/CHECKSUMS.txt (published hash), TerminalGuardian/Private/Get-TGRemoteIntegrityManifest.ps1 (selftest integrity check implementation), docs/RELEASE_MANIFEST.json (v2.3.3 build metadata).

Non-claims — read before purchasing

Explicit do-not-use claims

The following claims are NOT made and must NOT appear in any Terminal Guardian marketing, sales, or documentation. Each entry explains why the claim is excluded and, where available, a safe alternative.

Code signing / Authenticode signing / signed release artifact

DO NOT USE

The module is not Authenticode-signed. Release ZIPs are not digitally signed artifacts.

Safe alternative: SHA-256 release checksum published in docs/CHECKSUMS.txt

Tamper-evident audit log chaining

DO NOT USE

Logs are plain text files. There is no cryptographic chaining between entries.

Safe alternative: Local audit log with unconditional write for blocked and forced events

Central / remote policy enforcement

DO NOT USE

Rules are loaded locally only. There is no remote rules server, central policy push, or MDM integration.

Safe alternative: Local-first enforcement — JSON rules evaluated entirely on the local machine

Microsoft certified

DO NOT USE

Terminal Guardian is not a Microsoft product and has not been submitted to any Microsoft certification program.

Safe alternative: None — do not substitute a similar claim.

Compliance approved / certified compliant

DO NOT USE

Terminal Guardian has not been submitted to or approved by any compliance body (SOC 2, FedRAMP, ISO 27001, etc.).

Safe alternative: None — do not substitute a domain-level compliance claim not supported by evidence.

Cloud behavioral telemetry (commands sent to cloud)

DO NOT USE

No command content is sent to any remote service during normal operation. Do not claim this as a product feature.

Safe alternative: Local-only enforcement — no command data leaves the machine during normal operation

What it does

Evaluates every PowerShell command before execution

Every command — typed, pasted, scripted, or AI-generated — is evaluated against the active policy pack before the shell runs it.
Maintains a local per-command audit trail

Every evaluation is logged with outcome, matched policy rule, and actor context. The log stays on your machine.
Redacts secrets before logging

Tokens, passwords, and API keys passed inline in commands are redacted from log output before storage.
Verifies policy manifest integrity via SHA-256

The active policy pack is verified against a SHA-256 manifest. If the policy has been modified outside of sanctioned change, the integrity check detects it.
Runs local-first — no cloud required for enforcement

Core policy evaluation happens entirely on your machine. tg selftest optionally performs a cloud integrity check — the only network call, and it is user-initiated.
Defaults to block — not allow — on any error

Fail-closed rule load protection and semantic pipeline error handling both default to the safe outcome.

Non-scope — read this before purchasing

What it is not

Not antivirus or EDR

Does not scan files, detect malware, monitor running processes, or replace endpoint security tools.
Not a replacement for backups or change review

Blocking a command is not a substitute for having backups. Terminal Guardian does not recover deleted files.
Does not govern other shells

cmd.exe, bash, WSL, and non-PowerShell processes are outside scope. Only commands routed through a protected pwsh session are evaluated.
Does not stop a determined local actor

Terminal Guardian is a guardrail for workflow safety — not a hard security boundary for hostile actors with local machine access.
Windows PowerShell 5.1 is not supported

Requires PowerShell 7+ (pwsh). Not compatible with the legacy Windows PowerShell engine.