OpSight OpSentry

Three layers of defense for AI coding agents — detect, prevent, and make dangerous actions architecturally impossible.

Competitors match patterns and lose the arms race. OpSentry makes entire attack classes impossible.

Built by OpSight Intelligence.

Quick Start

# pip (recommended)
pip install opsentry && opsentry install

# Homebrew
brew tap opsight-intelligence/opsentry && brew install opsentry && opsentry install

# Git clone
git clone https://github.com/opsight-intelligence/opsentry.git && cd opsentry && ./install.sh

# GitHub Action (CI/CD)
# uses: opsight-intelligence/opsentry-action@v1

Restart Claude Code after installation.

New in v1.8

• 168 tests (101 functional + 67 adversarial red-team) — up from 155 in v1.7. red team log
• Precision path matching — block-scope-escape.sh rewritten with word-boundary regex and realpath symlink resolution. Project-local .claude/ directories, ~/Library/ on macOS, /var/folders/ (macOS temp), and filenames like foo.bashrc.bak are no longer over-blocked. Attack 3 protection is preserved and now also catches symlink-based bypass attempts against $HOME/.claude/.
• Configuration baseline integrity — install.sh writes a SHA-256 manifest of the guardrail-controlled subset of CLAUDE.md and settings.json to ~/.claude/.opsentry-baseline.json, locked with filesystem immutability. opsentry patrol re-verifies on every run and flags drift as a FAIL finding. User customizations (custom deny rules, custom hook matchers) are preserved — only the guardrail subset is hashed.
• Block log pattern analysis — opsentry patrol now scans ~/.claude/guardrail-blocks.log for five attack signatures beyond simple counts: repeat offender (same hook 5+/1h), rapid burst (5+ blocks in any 30s window), multi-hook coverage (3+ distinct hooks in 1h), exfiltration cluster (block-sensitive-files + block-data-exfiltration within 5 minutes), and self-modification attempts (Attack 3 active exploitation signal).
• Patrol bug fixes — no longer aborts mid-execution when drift is detected (fixed set -euo pipefail interaction with verify.sh failures); no longer crashes on macOS due to the GNU-only grep -oP flag in the block log section.

v1.7 highlights (still current)

• Protection levels — strict / balanced / permissive in guardrails.yaml
• Filesystem immutability — chflags uchg (macOS) / chattr +i (Linux) locks guardrail files
• Compliance Patrol — opsentry patrol with schedulable daily audits
• pip install — pip install opsentry ships the CLI, deployment scripts, and config generator
• Red-team hardening — all 8 hooks hardened against adversarial bypass vectors (67 red-team test cases)

Full release history: CHANGELOG.md

What Gets Installed

File	Location	Purpose
CLAUDE.md	~/.claude/CLAUDE.md	Behavioral rules Claude Code follows every session
settings.json	~/.claude/settings.json	Hard deny rules for sensitive file access and dangerous commands
block-sensitive-files.sh	~/.claude/hooks/	Blocks reading .env, credentials, secrets, certificates
block-dangerous-commands.sh	~/.claude/hooks/	Blocks rm -rf, sudo, chmod 777, DROP TABLE, etc.
block-git-commands.sh	~/.claude/hooks/	Blocks all git command execution
block-data-exfiltration.sh	~/.claude/hooks/	Blocks curl/wget uploads, base64 of secrets, /tmp writes, netcat
block-package-install.sh	~/.claude/hooks/	Blocks pip/npm/gem installs from untrusted sources
block-scope-escape.sh	~/.claude/hooks/	Blocks self-modification of ~/.claude/ and system paths
block-environment-escape.sh	~/.claude/hooks/	Blocks ssh, docker run/exec, terraform apply/destroy, kubectl
block-pii-leakage.sh	~/.claude/hooks/	Blocks writing SSNs, credit card numbers, Korean RRNs into code

How OpSentry Defends Your Environment

Layer 1 — Runtime Guardrails (Detect)

Pre-execution pattern matching blocks known attack vectors before they run. 8 hook scripts, 168 hook tests, battle-tested against 8 red team attacks.

• CLAUDE.md — behavioral rules Claude reads at session start (18 mandatory security sections)
• settings.json — hard deny rules in Claude Code's permission system
• Hook scripts — deterministic bash enforcement that inspects every tool call

Layer 2 — CI/CD Analysis (Prevent)

Cross-file AST composition analysis catches exfiltration patterns that span multiple files at PR time. Import-graph-aware — detects when file-read, network-send, and sensitive-path references are assembled across imports.

• SEC-012 — cross-file exfiltration composition analysis (42 tests)
• SEC-013 — network exposure scanning (23 dangerous ports)
• Auto-fix — eval() → ast.literal_eval(), bare except: → specific exceptions
• Merge gating — critical/high findings block PR merge

Layer 3 — Sandbox Profiles (Make Impossible)

Generated platform-specific sandbox configs that make dangerous actions impossible at the OS level. Not pattern matching — capability removal.

• macOS — sandbox-exec SBPL profiles that deny read/write at the kernel level
• Linux — bubblewrap wrapper scripts that shadow sensitive directories with empty mounts
• Docker — Dockerfile + Compose with cap_drop: ALL, read-only root, network isolation

# Generate sandbox profiles from your guardrails.yaml
opsentry sandbox generate --platform all --output-dir ./sandbox-profiles/

Attack Class	How the Sandbox Defeats It
Credential file read (.env, ~/.aws/)	Denied at kernel level, regardless of command syntax
Guardrail self-destruction (~/.claude/)	Outside the sandbox namespace — invisible
Data exfiltration via network	Network denied by default or allowlisted
Persistence (cron, launchd, systemd)	Write access to persistence dirs denied
Fork bombs / resource exhaustion	Process and memory limits enforced

You own the sandbox runtime — OpSentry provides the security intelligence. No vendor lock-in.

Updating

When rules are updated in this repo, every developer should pull and re-run:

cd ai-guardrails
./update.sh

Verifying Installation

To check that all guardrails are properly installed and unmodified:

opsentry verify                 # packaged CLI
./ai-guardrails/verify.sh       # from a clone of this repository

Prerequisites

• jq is required by the hook scripts. Install with:
  • macOS: brew install jq
  • Ubuntu/Debian: sudo apt install jq
  • Windows (WSL): sudo apt install jq

What Is Blocked

Sensitive Files

All .env files, credential configs, SSL certificates, SSH keys, cloud provider configs, database connection files, and anything in secrets/, credentials/, private/, or keys/ directories.

Dangerous Commands

rm -rf, sudo, chmod 777, kill -9, disk operations (mkfs, dd, fdisk), pipe-to-shell (curl | bash), and database destruction commands (DROP TABLE, TRUNCATE, DELETE without WHERE).

Git Commands

By default all git commands are blocked from agent execution, and the agent writes them as text for the developer to run. git_policy: "read_only" in guardrails.yaml allows the read-only ones (git status, git log, git diff).

Data Exfiltration

Curl/wget file uploads, base64 encoding of sensitive files, writes to /tmp or /dev/shm, clipboard exfiltration of secrets, and netcat outbound channels.

Package Installs from Untrusted Sources

pip/npm/gem/go installs from git URLs, custom registries, or direct download links. Standard registry installs are allowed.

Scope and Environment Escape

Self-modification of ~/.claude/, writes to system paths (/etc, /usr, shell configs), ssh/scp to remote hosts, docker run/exec/build, destructive terraform/kubectl commands.

PII in Source Code

US Social Security Numbers, credit card numbers (Visa, Mastercard, Amex, Discover), and Korean Resident Registration Numbers are blocked from being written into code. Synthetic test values (000-00-0000, 555-55-5555) are allowed.

Client Data

The CLAUDE.md includes strict rules against including client confidential data (company names, internal identifiers, business metrics) in any outputs.

Customisation

• To add new file patterns to block, edit claude/hooks/block-sensitive-files.sh and claude/settings.json
• To add new dangerous commands, edit claude/hooks/block-dangerous-commands.sh
• To add new PII patterns, edit claude/hooks/block-pii-leakage.sh
• To add new exfiltration vectors, edit claude/hooks/block-data-exfiltration.sh
• To change behavioral rules, edit claude/CLAUDE.md
• After changes, run ./ai-guardrails/test.sh to validate, then ./ai-guardrails/install.sh to deploy locally

Troubleshooting

Hooks not firing? Run /hooks inside Claude Code to check if hooks are registered. Verify scripts are executable: ls -la ~/.claude/hooks/

"jq: command not found" errors? Install jq — see Prerequisites above.

Developer modified their settings.json? Run opsentry verify (or ./ai-guardrails/verify.sh) to check for differences, and opsentry install (or ./ai-guardrails/install.sh) to reset.

Questions or Issues

Open an issue on GitHub or reach out to the OpSight team.

Branch guard (pre-push hook)

This repo's main/develop are protected by a client-side pre-push hook (the org is on GitHub Free, which has no server-side branch protection on private repos). The hook lives in .git/hooks/, so it is not version-controlled — re-run the installer in every fresh clone, from your opsight-company checkout:

bash scripts/git-hooks/install-hooks.sh /path/to/this-repo

It only guards opsight-intelligence remotes. For an intentional release push, override with OPSIGHT_ALLOW_PROTECTED_PUSH=1 git push .... All changes go through a feature//bugfix/ branch → PR into develop.