Comprehensive documentation of getit's security architecture, threat model, and mitigation strategies.

1. Threat Model
2. Defense Layers
3. Man-in-the-Loop Gate
4. Secret Scrubbing
5. Path Policy Engine
6. Input Sanitization
7. Environment Isolation
8. Fail-Closed Execution
9. Workspace Security
10. Security Profiles
11. Reporting Vulnerabilities

getit operates in a high-risk environment: an AI model proposes shell commands and file mutations on a user's live system. The primary threats are:

Every LLM-proposed action passes through three sequential safety layers:

┌────────────────────────────────────────────────────────┐
│               LLM Output (Tool Call JSON)              │
└───────────────────────────┬────────────────────────────┘
                            ▼
┌────────────────────────────────────────────────────────┐
│  LAYER 1: Static Analysis & Policy Enforcement         │
│                                                        │
│  • Input sanitizer detects cascades, redirects,        │
│    subshells                                           │
│  • Path policy validates against .getitignore,         │
│    hardcoded bans, global policy.json                  │
│  • Workspace boundary enforcement                      │
└───────────────────────────┬────────────────────────────┘
                            ▼
┌────────────────────────────────────────────────────────┐
│  LAYER 2: Secret Scrubbing                             │
│                                                        │
│  • Known-secret registry (exact match)                 │
│  • Pattern matching (sk-*, ghp_*, AKIA*, Bearer, PEM)  │
│  • Shannon entropy analysis (heuristic catch-all)      │
│  • StreamScrubber for real-time token output            │
└───────────────────────────┬────────────────────────────┘
                            ▼
┌────────────────────────────────────────────────────────┐
│  LAYER 3: Human Approval (MITL Gate)                   │
│                                                        │
│  • ANSI-rendered approval card with full payload        │
│  • Security warnings displayed prominently              │
│  • [Y/n/e/c] interaction with edit and clarify modes    │
│  • Fail-closed: no action without explicit approval     │
└────────────────────────────────────────────────────────┘

The MITL gate is the final and most important safety barrier. No action executes without explicit human approval.

1. The LLM requests a tool call (execute_bash or manage_file)
2. The tool dispatcher constructs a human-readable payload
3. For file patches, a colored unified diff is generated
4. The payload is scrubbed to mask any secrets before display
5. An ANSI-bordered card is rendered showing:
   • The action type (BASH, FILE CREATE, FILE PATCH)
   • The full payload (scrubbed)
   • Any security warnings detected by the input sanitizer
6. The user responds with one of:

• The MITL gate cannot be bypassed by the LLM
• The only bypass mechanism is GETIT_TEST_MODE=true (for automated testing)
• Edit mode uses rl.write() to pre-fill the payload, so users can modify a single flag without retyping
• Clarify mode preserves the full conversation context

At startup, all API keys loaded from .getitrc and environment variables are registered via registerKnownSecret(). These are masked via exact string match before any other analysis.

Regular expressions catch well-known secret formats:

For tokens ≥33 characters that don't match known patterns, Shannon entropy determines if the string is likely a secret:

False-positive prevention (v1.5 improvements):

• Standard git SHAs (40/64-char hex) are whitelisted before entropy analysis
• URLs (http://, https://) are excluded
• npm integrity hashes (sha512-...) are not redacted
• JWT header segments are preserved
• Package version references pass through

All masked values are replaced with stable placeholders: [REDACTED_1], [REDACTED_2], etc. The same secret always maps to the same placeholder within a session, ensuring consistency.

The StreamScrubber class handles real-time token-by-token scrubbing during LLM output streaming. It buffers partial tokens to prevent secrets from being split across chunks.

The following paths are always blocked, regardless of profile or policy:

Works like .gitignore — place it in your project root or any parent directory:

# Block private keys
*.pem
*.key

# Block environment files
.env*

# Block secrets directory
/secrets/*

Resolution order:

1. Patterns are collected hierarchically from $PWD up to the filesystem root
2. Each directory's .getitignore is merged into the pattern set
3. Global patterns from ~/.config/getit/policy.json are added
4. Hardcoded bans are applied last (cannot be overridden)

All file operations resolve paths to their absolute, real form before any policy check:

• ~ is expanded to the home directory
• Symlinks are resolved to their targets
• Relative paths are resolved against the current working directory
• .. traversals are normalized

This prevents bypass attempts using symlinks or relative paths.

When a workspace manifest is active, the policy engine injects an additional rule that blocks writes outside the workspace root — unless the target is an explicitly allowlisted global path (e.g., ~/.config/, ~/.bashrc).

The input sanitizer scans bash commands for dangerous patterns before they reach the MITL gate:

Detected patterns generate warnings that are displayed prominently on the MITL approval card. The command is not blocked — the user sees the warnings and makes an informed decision.

Before spawning any child process, getSafeEnv() creates a clean environment:

const safeEnv = { ...process.env };
delete safeEnv.OPENROUTER_API_KEY;
delete safeEnv.OPENAI_API_KEY;
delete safeEnv.ANTHROPIC_API_KEY;
delete safeEnv.GITHUB_TOKEN;
delete safeEnv.GETIT_API_KEY;
// ... all known sensitive keys

This prevents credential exfiltration via env, printenv, or malicious scripts that read environment variables.

The LLM communicates exclusively through typed JSON tool schemas:

• execute_bash receives a single command string
• manage_file receives structured parameters

Raw, unparsed shell string execution is architecturally impossible. The command is always passed to spawn('/bin/bash', ['-c', command]) after full policy and sanitization checks.

Every safety mechanism defaults to denial:

When a command fails:

1. The agent loop halts immediately
2. The deterministic healer scans stderr for known failure patterns
3. If a match is found, a fix command is proposed through the MITL gate
4. The healer never auto-executes — the user must approve
5. If no match is found, control returns to the user

The shadow tracking repo at ~/.local/state/getit/tracking/ stores only scrubbed file content:

• Files pass through scrubContentGeneric() before staging
• High-entropy strings and known secrets are replaced with placeholders
• The live operational files remain untouched
• getit inspect lets you verify what's tracked before any commit

The rollback system includes multiple safety checks:

• Commit hashes are validated (7-40 hex characters)
• Target paths are checked against the workspace boundary
• Each file restoration goes through the MITL gate
• Atomic writes prevent partial-restore corruption

getit export produces scrubbed copies of all tracked files. The export directory contains zero raw secrets by design.

Select a profile at startup:

getit --profile strict

Or switch within the REPL:

/profile strict

If you discover a security vulnerability in getit, please report it responsibly:

📬 redstarapps@proton.me

Please include:

• Description of the vulnerability
• Steps to reproduce
• Potential impact assessment
• Suggested fix (if any)

We will respond within 48 hours and work with you to address the issue before any public disclosure.

This document reflects the security model of getit v1.5.0.