Metadata-Version: 2.4
Name: opsentry
Version: 1.8.4
Summary: AI agent security guardrails for engineering teams
Author-email: OpSight Intelligence <utku@opsightintel.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/opsight-intelligence/opsentry
Project-URL: Documentation, https://github.com/opsight-intelligence/opsentry#readme
Project-URL: Repository, https://github.com/opsight-intelligence/opsentry
Project-URL: Issues, https://github.com/opsight-intelligence/opsentry/issues
Keywords: security,guardrails,claude-code,ai-agent,devsecops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: Jinja2>=3.1
Dynamic: license-file

# 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](https://github.com/opsight-intelligence).

## Quick Start

```bash
# 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](https://github.com/opsight-intelligence/opsentry/blob/main/docs/red-team-log.md)
- **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](./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, 203 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

```bash
# 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:

```bash
cd ai-guardrails
./update.sh
```

## Verifying Installation

To check that all guardrails are properly installed and unmodified:

```bash
./verify.sh
```

## 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
All git commands are blocked from agent execution. The agent will write git commands as text for the developer to review and run manually.

### 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 `./verify.sh` to check for differences. Run `./install.sh` to reset.

## Questions or Issues

Open an issue on [GitHub](https://github.com/opsight-intelligence/opsentry/issues) 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:

```sh
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`.
