Skip to content

compatibility.md

Latest commit

 

History

History
138 lines (112 loc) · 7.11 KB

compatibility.md

File metadata and controls

138 lines (112 loc) · 7.11 KB
Raw

Compatibility and Stability

Stability Tiers

Tirith subcommands fall into two stability tiers:

  • Stable — flags, exit codes, and output format will not change in a backwards-incompatible way within a major version.
  • Experimental — surface may change without notice while the command and its schema are still being shaped.

Per-Command Stability Matrix

This table reflects the current state of each subcommand. It is descriptive, not a promise of future classification — see "Graduation criteria" below for what an experimental command must satisfy to move to stable.

Command Stability Notes
check Stable Analyze a command before execution. Integration-critical (shell hooks, MCP).
paste Stable Analyze pasted content.
score Stable Risk-score a URL (--explain shows the deterministic factor breakdown).
diff Stable Compare a URL against known-good patterns.
why Stable Explain the last triggered rule.
receipt Stable Manage execution receipts.
init Stable Initialize shell hooks.
scan Experimental File/directory scanning for hidden content and config poisoning. Integration-critical (CI, MCP).
doctor Experimental Installation and configuration diagnostics. Integration-critical.
run Experimental Safe script download/execute (Unix only).
fetch Experimental Server-side cloaking detection (Unix only).
checkpoint Experimental File checkpoint and rollback.
gateway Experimental MCP gateway proxy for AI-agent security.
setup Experimental Configure tirith for AI coding tools.
policy Experimental Policy init / validate / test / tune.
trust Experimental Manage trusted patterns: add / list / explain / diff / remove / gc. Narrow scope and a 30-day TTL by default; scope visualization, per-entry explain, and a diff trail.
warnings Experimental Show accumulated session warnings.
threat-db Experimental Threat-DB update / status / explain / sources / health / diff.
daemon Experimental Background daemon (Unix only).
audit Experimental Audit log export, stats, and compliance reports.
activate Experimental License key activation.
license Experimental License status and management.
mcp-server Experimental MCP server mode (JSON-RPC over stdio).
lab Experimental Adversarial training corpus runner. Offline. --filter narrows by tag; --score adds a 0-100 risk score per scenario.
completions Experimental Shell completion generation (hidden).
manpage Experimental Man page generation (hidden).

The MCP tools exposed by mcp-server (tirith_check_command, tirith_check_url, tirith_check_paste, tirith_scan_file, tirith_scan_directory, tirith_verify_mcp_config, tirith_fetch_cloaking) are also treated as an integration-critical surface for graduation purposes.

Graduation Criteria

An experimental command graduates to stable only once it satisfies all of the following:

  • Stable JSON schema — the --format json output has a fixed, documented schema. schema_version is emitted, and existing fields are not removed or retyped within a major version.
  • Golden snapshot tests — representative inputs are covered by golden snapshot tests so output drift is caught in CI.
  • Versioned config/policy migration — any config or policy keys the command reads have a defined migration path; format changes are versioned, not silent.
  • Exit-code compatibility promise — the command's exit codes are documented and committed to (see "Exit Codes" below).
  • --format json consistency — the JSON output is consistent with the shared output conventions used by the already-stable commands.
  • Backward-compatible MCP tool schemas — for commands exposed through the MCP server, the corresponding tool input/output schemas evolve only in a backward-compatible way.
  • CLI deprecation policy — flags and behaviors are removed only through a documented deprecation cycle, never abruptly.

These criteria are prioritised for the experimental integration-critical surface — scan, doctor, and the MCP tools — because CI pipelines and AI agents depend on them most directly. (check is already Stable; the already-stable commands are held to these same guarantees as maintenance invariants.) Other experimental commands graduate after that surface is locked down.

Exit Codes

Exit codes are stable:

Code Meaning
0 Allow (no issues found)
1 Block (high/critical severity findings)
2 Warn (medium/low severity findings)
3 WarnAck — acknowledgement required (warn-ack hook protocol)

Exit code 3 is the warn-ack hook protocol path used by shell hooks under strict warn mode, not the normal direct-CLI contract. Non-hook callers should not normally see exit code 3.

JSON Output

  • schema_version is emitted in all JSON output (currently version 3)
  • Version 3 changes: added Info severity level (maps to Allow action), added httpie_pipe_shell and xh_pipe_shell rule IDs
  • JSON fields are additive only: new fields may appear in any release
  • Existing fields will not be removed or change type within a major version
  • The findings array structure is stable
  • Evidence types may be extended (e.g., homoglyph_analysis with detailed character info)

Rule IDs

  • Rule IDs (e.g., curl_pipe_shell, punycode_domain) are stable identifiers
  • Rule wording (title, description) may change
  • New rules may be added in any release
  • Rules will not be removed within a major version (they may be deprecated)

Policy Format

  • Both policy.yaml and policy.yml extensions are accepted (.yaml preferred)
  • Policy format is additive: new keys may appear
  • Existing keys will not change semantics within a major version

PowerShell parity

The following detection rules apply when --shell powershell is passed to tirith check or when the shell hook detects a PowerShell session:

Rule ID Behavior detected
base64_decode_execute powershell -EncodedCommand <base64> and -enc / -ec aliases
pipe_to_interpreter iwr url | iex, irm url | iex, and full Invoke-WebRequest / Invoke-RestMethod forms
ps_set_execution_policy_bypass Set-ExecutionPolicy Bypass, powershell -ExecutionPolicy Bypass, and the -ep short alias
ps_defender_exclusion Add-MpPreference -ExclusionPath, -ExclusionProcess, or -ExclusionExtension
ps_inline_download_execute iex (iwr https://…) — inline download-execute form where iex is the leading command

tirith run and tirith fetch are Unix-only and do not apply to PowerShell workflows. tirith check, tirith paste, tirith score, and the shell hook work on Windows with pwsh.

tirith doctor --compat reports PowerShell hook health when pwsh (PowerShell 7+) or powershell (Windows PowerShell 5.1) is found on PATH: PSReadLine availability and the current TIRITH_STATUS value exported by the hook.