diff --git a/CHANGELOG.md b/CHANGELOG.md index c9248d9..9c56669 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.8.8] - 2026-09-30 + +### Changed +- The quickstart describes the install that exists: the packaged CLI (pip or + Homebrew) or `./install.sh` / `./verify.sh` / `./update.sh` / `./test.sh` + from a clone. It no longer points at scripts and a wizard this repository + does not contain, and it documents `patrol.sh`, `baseline.py`, + `blocklog_audit.py` and `OPSENTRY_PKG_ROOT`. +- `SECURITY.md` lists 1.8.x as the supported line (it still said 1.6.x). +- The README and CONTRIBUTING give the real test count (168 hook tests here) + and say which features come with the packaged CLI. +- The red-team loop instructions use repository-relative paths. + ## [1.8.7] - 2026-09-16 ### Changed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d55956e..8efb882 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ If you find a dangerous pattern that OpSentry should block, open an issue with: 2. Create a feature branch off `develop` (`git checkout -b feature/block-new-pattern develop`) 3. Make your changes 4. Run the test suite: `./test.sh` -5. Ensure all 88+ tests pass +5. Ensure every test passes (`./test.sh`) 6. Bump `VERSION`, add a `CHANGELOG.md` entry, and update the docs (see below) 7. Submit a PR against `develop` diff --git a/README.md b/README.md index 2f4b8c9..f9a928f 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,8 @@ OpSentry is built specifically for this architecture. ## Install in 2 minutes -**pip (recommended)** +**pip (recommended)** — the packaged `opsentry` CLI, which adds the config and +sandbox generators to what this repository installs pip install opsentry opsentry install @@ -41,7 +42,7 @@ OpSentry is built specifically for this architecture. brew install opsentry opsentry install -**Git clone** +**Git clone** — the hooks, rules and settings from this repository git clone https://github.com/opsight-intelligence/opsentry cd opsentry @@ -64,7 +65,7 @@ Restart Claude Code after install. That's it. **Layer 1 — Detect (Runtime Guardrails)** 8 hook scripts + 18 behavioral rules + 70+ permission denials. Pre-execution pattern matching blocks known attack vectors -before they run. 203 tests. Battle-tested against 8 red team attacks. +before they run. 168 hook tests. Battle-tested against 8 red team attacks. **Layer 2 — Prevent (CI/CD Analysis)** Cross-file AST composition analysis at PR time. @@ -77,7 +78,7 @@ dangerous actions at the OS kernel level. macOS (sandbox-exec), Linux (bubblewrap), Docker. ```bash -opsentry sandbox generate --platform all +opsentry sandbox generate --platform all # packaged CLI (pip / Homebrew) ``` Each layer uses a different detection strategy. An attacker @@ -121,9 +122,9 @@ any personal customisations. ./test.sh -203 automated tests: 168 hook tests (101 functional + -67 adversarial red-team) plus 42 cross-file composition -tests plus 23 network exposure tests. +168 hook tests in this repository (101 functional + 67 +adversarial red-team). The packaged CLI adds cross-file +composition and network exposure suites. --- @@ -200,7 +201,7 @@ Full deterministic enforcement requires Claude Code. | 70+ permission denials | ✓ | ✓ | ✓ | | 3 slash commands | ✓ | ✓ | ✓ | | Incident logging | ✓ | ✓ | ✓ | -| 203 automated tests | ✓ | ✓ | ✓ | +| 168 hook tests | ✓ | ✓ | ✓ | | CI/CD agents (GitHub Actions) | | ✓ | ✓ | | Cross-file exfiltration detection (AST) | | ✓ | ✓ | | **Sandbox profile generator** | | **✓** | **✓** | diff --git a/SECURITY.md b/SECURITY.md index 2a46ee3..e6357f0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -32,7 +32,7 @@ This policy covers: | Version | Supported | |---------|-----------| -| 1.6.x | Yes | -| < 1.6 | No | +| 1.8.x | Yes | +| < 1.8 | No | We only provide security fixes for the latest minor version. diff --git a/VERSION b/VERSION index d2c4b27..1790d35 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.8.7 \ No newline at end of file +1.8.8 diff --git a/docs/quickstart.md b/docs/quickstart.md index a75ec34..5558f06 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -5,140 +5,88 @@ Get AI agent security guardrails running in under 10 minutes. ## Prerequisites - **jq**: `brew install jq` (macOS) or `sudo apt install jq` (Linux) -- **python3**: Already installed on most systems -- **Claude Code**: Installed and working +- **python3**: already installed on most systems +- **Claude Code**: installed and working -## Option A: One-Line Install +## Option A: Packaged CLI (pip or Homebrew) + +The `opsentry` command-line tool is published as a package. It adds the +`guardrails.yaml` config generator and the sandbox profile generator on top of +what this repository installs. ```bash -bash <(curl -sSL https://raw.githubusercontent.com/opsight-intelligence/opsentry/main/install-opsentry.sh) +pip install opsentry # or: brew tap opsight-intelligence/opsentry && brew install opsentry +opsentry install ``` -This clones the repo, runs the setup wizard, and installs everything. Follow the prompts. - -## Option B: Manual Setup - -### 1. Clone the repo +## Option B: From this repository ```bash git clone https://github.com/opsight-intelligence/opsentry.git ~/.opsentry cd ~/.opsentry +./install.sh ``` -### 2. Install Python dependencies - -```bash -pip3 install pyyaml jinja2 -``` - -### 3. Run the setup wizard - -```bash -python3 config/init_wizard.py -``` - -The wizard asks about your industry, PII locales, git policy, infrastructure tools, and compliance frameworks. It generates `guardrails.yaml`. - -For CI/automation, use non-interactive mode: - -```bash -python3 config/init_wizard.py --non-interactive --template fintech --pii US,EU --compliance soc2,pci_dss -``` - -### 4. Generate and install - -```bash -python3 config/generate.py guardrails.yaml -./ai-guardrails/install.sh -``` - -Or with the CLI: - -```bash -bin/opsentry install -``` +`install.sh` copies the rules, settings and hooks from `opsentry/claude/` into +`~/.claude/`, merging with anything already there. To change what is enforced +from a clone, edit the files under `opsentry/claude/` and run `./install.sh` +again; the `guardrails.yaml` generator is part of the packaged CLI (Option A). -### 5. Restart Claude Code +## Restart Claude Code Close and reopen Claude Code. The guardrails are now active. -## Verify Installation +## Verify installation ```bash -bin/opsentry status -``` - -Expected output: - +./verify.sh ``` - Repo version: 1.6.0 - Installed version: 1.6.0 - - ✓ CLAUDE.md - ✓ settings.json - ✓ hooks/ - ✓ hooks/block-sensitive-files.sh - ✓ hooks/block-dangerous-commands.sh - ... - Status: All guardrails installed and intact. -``` +Each installed file is reported as `PASS` (installed and matches the source), +`WARN` (installed but modified since) or `FAIL` (missing). With the packaged +CLI, `opsentry status` gives the same answer. -## What Gets Installed +## What gets installed | File | Location | What it does | |------|----------|-------------| | CLAUDE.md | `~/.claude/CLAUDE.md` | 18 behavioral rules Claude Code follows every session | | settings.json | `~/.claude/settings.json` | Hard deny rules blocking dangerous tool calls | -| 8 hook scripts | `~/.claude/hooks/` | Bash scripts that inspect and block tool calls in real-time | -| 3 slash commands | `~/.claude/commands/` | `/security-audit`, `/code-health`, `/governance-check` | +| 8 hook scripts | `~/.claude/hooks/` | Bash scripts that inspect and block tool calls in real time | -## Test It +## Test it -Open Claude Code and try something that should be blocked: +Run the hook test suite: +```bash +./test.sh ``` -> Read my .env file -``` - -You should see: `BLOCKED: Access to '.env' is denied by company security policy.` -## Add CI/CD Scanning +Then open Claude Code and try something that should be blocked: -To add security scanning to your GitHub repos: - -```bash -# Deploy to one repo -./ai-ci-agents/deploy.sh your-org/your-repo - -# Deploy to all repos in your org -./ai-ci-agents/deploy.sh --org your-org +``` +> Read my .env file ``` -Every PR will be scanned for secrets, SQL injection, dangerous patterns, and code quality issues. +You should see: `BLOCKED: Access to '.env' is denied by company security policy.` ## Updating ```bash -bin/opsentry update +./update.sh ``` -This pulls the latest version and reinstalls. Your `guardrails.yaml` customizations are preserved. +This pulls the latest version and reinstalls. With the packaged CLI, use +`opsentry update` (pip: `pip install -U opsentry`; Homebrew: `brew upgrade opsentry`). -## Customizing Rules - -Edit `guardrails.yaml` and regenerate: - -```bash -# Edit your config -vi guardrails.yaml - -# Regenerate and reinstall -bin/opsentry install -``` +## Going further -Common customizations: -- `git_policy: "read_only"` — allow `git status`, `git log`, `git diff` -- `pii.locales: ["US", "EU"]` — add IBAN detection -- `blocked_files.extra_patterns` — block access to custom sensitive paths -- `compliance.frameworks: ["soc2"]` — enable SOC 2 compliance rules +- `opsentry/patrol.sh` — compliance patrol: an extended audit beyond + `verify.sh` that looks for unexpected persistence, hook tampering and + security posture drift. +- `opsentry/baseline.py` — records and checks SHA-256 baselines of the + guardrail-controlled parts of the installed files. +- `opsentry/blocklog_audit.py` — analyses `~/.claude/guardrail-blocks.log` + for patterns in what was blocked. +- `OPSENTRY_PKG_ROOT` — points the scripts at a different package root than + the repository they sit in. diff --git a/redteam-loop/README.md b/redteam-loop/README.md index 1b2352c..b14a3dd 100644 --- a/redteam-loop/README.md +++ b/redteam-loop/README.md @@ -60,17 +60,19 @@ rounds// ## Review & apply a round ``` -cd ~/Desktop/repos/agentguard/opsentry/claude/hooks -patch -p0 < ~/Desktop/repos/agentguard/redteam-loop/rounds//round-N/patch.diff +# from the repository root +cd opsentry/claude/hooks +patch -p0 < ../../../redteam-loop/rounds//round-N/patch.diff +cd ../../.. # then eyeball new_tests.sh and append lines you want to opsentry/test.sh -bash ~/Desktop/repos/agentguard/opsentry/test.sh +bash opsentry/test.sh ``` ## How to read the summary - `heldout_blocked` substantially lower than `training_blocked` = regex overfit. Reject the patch or widen the approach. -- `existing tests P/F` must match baseline (currently 169 / 0). Any +- `existing tests P/F` must match baseline (currently 168 / 0). Any regression means the patch broke an allow case. - Monotonic decrease in `unblocked pre` across rounds = real hardening; plateau near zero = attacker exhausted.