From b54036609f12507fbb1bf98cab35d1782ba45eb7 Mon Sep 17 00:00:00 2001 From: Riyan Dhiman Date: Sun, 29 Mar 2026 02:52:00 +0530 Subject: [PATCH] version bump and fixes --- README.md | 185 +++++++++++++++++++++++++-------------- future_security_items.md | 53 ----------- pyproject.toml | 2 +- release.sh | 2 +- setup.py | 2 +- 5 files changed, 120 insertions(+), 124 deletions(-) delete mode 100644 future_security_items.md diff --git a/README.md b/README.md index 91a6536..5369578 100644 --- a/README.md +++ b/README.md @@ -3,55 +3,115 @@ [![PyPI version](https://badge.fury.io/py/agsec.svg)](https://pypi.org/project/agsec/) [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![OWASP Agentic Top 10](https://img.shields.io/badge/OWASP%20Agentic%20Top%2010-7%2F10%20covered-orange)](docs/owasp-mapping.md) -**Action firewall for AI agents.** Before an agent can do anything, it passes through agsec. +--- + +**Your AI agent has shell access. File access. Network access. Git access.** + +**There are no guardrails by default.** + +AgSec is a policy engine for AI agents - like AWS IAM, but for what agents can do on your machine. Write declarative YAML policies. Every action gets checked at runtime before it executes. Deny always wins. ``` -Agent wants to act --> agsec evaluates policy --> allow / block / review --> real world +agent wants to act → agsec evaluates policy → allow / deny / review → real world ``` -## Why +--- + +## The problem -AI agents get real access to real systems. agsec gives you one policy layer across all of them — declarative YAML policies, runtime enforcement, full audit trail. Like AWS IAM, but for what agents can do. Addresses [7 of 10 OWASP Agentic Top 10](docs/owasp-mapping.md) risks. +You give Claude Code, Cursor, or Codex access to your terminal. It tries to be helpful. Sometimes it runs `rm -rf`. Writes to `.env`. Force-pushes to main. Makes an API call you didn't expect. -## Quick Start +It's not malicious. It's just that agents have no blast radius limit unless you give them one. + +agsec is that limit. + +--- + +## 3-command setup ```bash pip install agsec -agsec init # create default policies -agsec install claude-code # activate firewall +agsec init # scaffold default policies +agsec install claude-code # activate the firewall ``` -Done. Every tool call is now checked. `rm -rf` blocked, `.env` writes blocked, force push blocked — out of the box. +Done. Every tool call is now checked against your policies. Out of the box, the following are blocked: + +- `rm`, `rm -rf`, `rmdir` — destructive deletes +- Writes to `.env`, `.env.*`, secrets files +- `git push --force` — force pushes +- `DROP TABLE`, `DELETE FROM` without WHERE — destructive SQL +- Reads of `~/.ssh`, `~/.aws`, `~/.gnupg` — credential directories -### Start in Observe Mode +--- -Not ready to block? Audit everything first, block nothing: +## Not ready to block yet? Start in Observe Mode ```bash -agsec init --observe # log only, no blocking -agsec audit --stats # see what would be blocked -agsec enforce # start blocking when ready +agsec init --observe # log everything, block nothing +agsec audit --stats # see what would have been blocked +agsec enforce # start blocking when ready ``` -## Supported Platforms +Observe mode gives you a full audit trail of every action your agent attempted — with zero disruption to your workflow. See the blast radius before you enforce it. -### System Agents (hook-based enforcement) +--- -```bash -agsec install claude-code # Claude Code + Claude Cowork (tested) -agsec install codex # OpenAI Codex -agsec install cursor # Cursor -agsec install windsurf # Windsurf (Codeium) -agsec install cline # Cline -agsec install copilot # GitHub Copilot (project + user level) +## Write your own policies + +```yaml +version: "1.0" +default: deny + +statements: + - sid: "AllowReadOps" + effect: allow + actions: ["file.read", "file.glob", "file.grep"] + + - sid: "BlockDeletes" + effect: deny + actions: ["bash.execute"] + conditions: + params.command: + op: "regex" + value: "\\brm\\s" + reason: "Agents should not delete files" + + - sid: "ReviewLargePayments" + effect: review # pause and ask a human + actions: ["payment.create"] + conditions: + params.amount: + op: "gt" + value: 10000 + + - sid: "AllowBash" + effect: allow + actions: ["bash.execute"] ``` -Claude Code and Claude Cowork are fully tested. Codex, Cursor, Windsurf, and Cline are functional but need community testing. VS Code Copilot also works with `agsec install claude-code` since it reads `.claude/settings.json`. Please report issues. +Three effects: `allow`, `deny`, `review` (human-in-the-loop pause). Deny always wins — same evaluation logic as AWS IAM. Layered policy evaluation (project + agent layers) where each layer is a gate. Supports 14 condition operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `in`, `not_in`, `contains`, `starts_with`, `ends_with`, `regex`, `exists`, `not_exists`. + +--- + +## Supported platforms + +### System agents — hook-based enforcement -### Python SDKs (client wrapper) +```bash +agsec install claude-code # Claude Code + Claude Cowork ✓ tested +agsec install codex # OpenAI Codex +agsec install cursor # Cursor +agsec install windsurf # Windsurf (Codeium) +agsec install cline # Cline +agsec install copilot # GitHub Copilot (project + user level) +``` -### Frameworks (tool wrapper) +Claude Code and Claude Cowork are fully tested. Others are functional — community testing welcome. + +### Python frameworks **LangChain:** @@ -88,63 +148,52 @@ def send_email(to, subject, body): ... ``` -## Policy Example - -```yaml -version: "1.0" -default: deny +--- -statements: - - sid: "AllowReadOps" - effect: allow - actions: ["file.read", "file.glob", "file.grep"] +## CLI reference - - sid: "BlockFileDelete" - effect: deny - actions: ["bash.execute"] - conditions: - params.command: - op: "regex" - value: "\\brm\\s" - reason: "Agents should not delete files" - - - sid: "AllowBash" - effect: allow - actions: ["bash.execute"] +```bash +agsec init [--observe] # scaffold policies +agsec install # activate firewall +agsec uninstall # deactivate + +agsec policy list # view all rules +agsec policy add # add a rule (interactive) +agsec policy remove # remove a rule +agsec validate # check for errors + +agsec audit [--stats] # view action log +agsec analyze [--hours N] # threat analysis with blast radius +agsec observe # switch to observe mode +agsec enforce # switch to enforce mode + +agsec halt # kill switch: block ALL actions immediately +agsec resume # restore from halt ``` -Deny always wins. Same evaluation order as AWS IAM. +--- -## CLI +## OWASP Agentic Top 10 coverage -```bash -agsec init [--observe] # scaffold policies -agsec install # activate (claude-code, codex, cursor, windsurf, cline, copilot) -agsec uninstall # deactivate -agsec policy list # see all rules -agsec policy add # add a rule (interactive) -agsec policy remove # remove a rule -agsec validate # check for errors -agsec audit [--stats] # view logs -agsec observe # switch to observe mode -agsec enforce # switch to enforce mode -agsec halt # kill switch: block ALL actions immediately -agsec resume # restore from halt -``` +agsec addresses 7 of the 10 OWASP Agentic Top 10 risks out of the box. See the [full mapping](docs/owasp-mapping.md). + +--- ## Documentation - [Policy Format](docs/policies.md) — schema, operators, conditions, examples -- [CLI Reference](docs/cli.md) — all commands in detail -- [Integrations](docs/integrations.md) — Claude Code/Cowork, Codex, Cursor, Windsurf, Cline, Copilot, LangChain, OpenAI, Anthropic +- [CLI Reference](docs/cli.md) — all commands +- [Integrations](docs/integrations.md) — Claude Code, Codex, Cursor, Windsurf, Cline, Copilot, LangChain, OpenAI, Anthropic - [SDK Usage](docs/sdk.md) — programmatic Python API -- [Observe Mode](docs/observe-mode.md) — audit first, enforce later -- [OWASP Mapping](docs/owasp-mapping.md) — compliance with OWASP Agentic Top 10 +- [Observe Mode](docs/observe-mode.md) — audit-first workflow +- [OWASP Mapping](docs/owasp-mapping.md) — compliance reference + +--- ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines. +See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome — especially platform testing reports for Codex, Cursor, Windsurf, and Cline. ## License -Apache 2.0 — see [LICENSE](LICENSE). +Apache 2.0 — see [LICENSE](LICENSE). \ No newline at end of file diff --git a/future_security_items.md b/future_security_items.md deleted file mode 100644 index 4a7369f..0000000 --- a/future_security_items.md +++ /dev/null @@ -1,53 +0,0 @@ -# Future Security Items - -## 1. Input Normalization Before Policy Evaluation - -**Found during:** Internal testing (developer bypassed global hook using base64 encoding) - -**Problem:** Policy conditions use pattern matching (regex, contains, etc.) on raw input strings. If inputs are encoded, obfuscated, or use unicode escapes, patterns won't match. - -**Bypass examples:** -- Base64: `echo "cm0gLXJmIC8=" | base64 -d | sh` — the command string doesn't contain `rm` -- Unicode escapes in JSON: `D\u0052OP TABLE` (decoded by JSON parser, but other encodings may not be) -- String concatenation: `"r" + "m" + " -rf /"` -- Hex encoding, URL encoding, etc. - -**Who's affected:** -- CLI hooks (Claude Code/Codex): Lower risk — the runtime sends tool arguments as-is, agent can't control encoding -- SDK integrations (OpenAI/Anthropic protect()): Higher risk — LLM could generate obfuscated tool arguments -- Generic @guard decorator: Medium risk — depends on caller - -**Current mitigation:** None. Same limitation as WAFs, SAST tools, and every pattern-based security tool. - -**Future fix options:** -- Normalize inputs before evaluation (decode common encodings, collapse whitespace, lowercase) -- Add a normalization step in PolicyEngine.evaluate() before condition matching -- For bash commands specifically: parse the command into AST instead of regex matching -- For SQL: use a SQL parser instead of string matching -- Add a `normalize: true` flag on policy statements - -**Priority:** Medium — this is a known limitation of pattern-based security. Defense-in-depth (multiple layers) is the standard approach. But we should fix it before enterprise customers rely on it. - -## 2. Hook Bypass via Settings File Modification - -**Problem:** If an agent has file write access, it could modify `.claude/settings.json` to remove the agsec hook. - -**Current mitigation:** The hook blocks file writes to sensitive paths, but `.claude/settings.json` is not in the blocked list. - -**Future fix:** Add `.claude/settings.json` and `.codex/hooks.json` to the default deny list in `03_files.yaml`. - -## 3. Policy File Tampering - -**Problem:** If an agent can write to the `policies/` directory, it could modify or delete policy files to weaken enforcement. - -**Current mitigation:** None. - -**Future fix:** Add `policies/*.yaml` and `.agsec.yaml` to the default deny list. Consider integrity hashing of policy files. - -## 4. Streaming Response Bypass - -**Problem:** `protect()` for OpenAI/Anthropic raises `NotImplementedError` for streaming. If a developer catches and ignores this, streaming calls bypass all checks. - -**Current mitigation:** Explicit error rather than silent pass-through. - -**Future fix:** Implement streaming response interception — wrap the stream generator and check tool calls as they appear in chunks. diff --git a/pyproject.toml b/pyproject.toml index 963df9a..aac8767 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "agsec" -version = "0.2.0" +version = "0.2.1" description = "AI Agent Action Firewall core SDK" readme = "README.md" requires-python = ">=3.8" diff --git a/release.sh b/release.sh index 04cbe09..926da8f 100755 --- a/release.sh +++ b/release.sh @@ -7,6 +7,6 @@ python3 -m build echo "Uploading to PyPI (requires PYPI_API_TOKEN in env)..." python3 -m twine upload dist/* --verbose -rm -dr dist/ +# rm -dr dist/ echo "Release complete." diff --git a/setup.py b/setup.py index ae2a50b..714a8de 100644 --- a/setup.py +++ b/setup.py @@ -5,7 +5,7 @@ setup( name="agsec", - version="0.2.0", + version="0.2.1", author="Riyandhiman", author_email="noreply@example.com", description="AI Agent Action Firewall core SDK",