Metadata-Version: 2.4
Name: agsec
Version: 0.2.2
Summary: AI Agent Action Firewall core SDK
Home-page: https://github.com/riyandhiman14/Agent-Sec
Author: Riyandhiman
Author-email: Riyandhiman <noreply@example.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/riyandhiman14/Agent-Sec
Project-URL: Repository, https://github.com/riyandhiman14/Agent-Sec
Project-URL: Documentation, https://github.com/riyandhiman14/Agent-Sec#readme
Keywords: agent,security,policy,sandbox
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Provides-Extra: rich
Requires-Dist: rich>=13.0.0; extra == "rich"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Requires-Dist: langchain-core>=0.2.0; extra == "all"
Requires-Dist: rich>=13.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.17.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# agsec

[![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)

---

**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 / deny / review  →  real world
```

---

## See it in action

### Without agsec — Claude deletes files freely
<p align="center">
  <img src="assets/claude_allowed.gif" alt="Claude deletes files without guardrails" width="720">
</p>

### With agsec — dangerous action blocked
<p align="center">
  <img src="assets/claude_blocked.gif" alt="agsec blocks Claude from deleting files" width="720">
</p>

### agsec analyze — threat analysis
<p align="center">
  <img src="assets/agsec_analyse.gif" alt="agsec analyze command" width="720">
</p>

---

## The problem

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.

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                    # scaffold default policies
agsec install claude-code     # activate the firewall
```

Done. Every tool call is now checked against your policies. Out of the box, the following are blocked:

- `rm`, `rm -rf`, `rmdir` — destructive deletes
- Reads and writes to `.env`, credentials, SSH keys, cloud credentials
- `git push --force`, `git reset --hard` — destructive git
- `DROP TABLE`, `TRUNCATE`, `ALTER DROP` — DDL commands
- `DELETE FROM`, `UPDATE SET`, `INSERT INTO` — DML commands
- `sqlite3 audit.db`, `psql audit.db` — audit database tampering
- `chmod 777`, `mkfs`, `dd`, `shred` — destructive filesystem ops
- Direct push to `main`, `master`, `production` branches

---

## Not ready to block yet? Start in Observe Mode

```bash
agsec init --observe          # log everything, block nothing
agsec audit --stats           # see what would have been blocked
agsec enforce                 # start blocking when ready
```

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. Every action is logged with its actual outcome, so `agsec analyze` accurately shows what got through vs what would have been blocked.

---

## 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"]
```

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. 21 built-in threat patterns for blast radius analysis. Supports 14 condition operators: `==`, `!=`, `>`, `<`, `>=`, `<=`, `in`, `not_in`, `contains`, `starts_with`, `ends_with`, `regex`, `exists`, `not_exists`.

---

## Supported platforms

### 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)
```

Claude Code and Claude Cowork are fully tested. Others are functional — community testing welcome.

### Python frameworks

**LangChain:**

```python
from agsec.integrations.langchain import guard, allow, deny, review, param

agent = create_react_agent(llm, guard(
    allow(search, calculator),
    review(send_email),
    deny(delete_record),
    deny(payment).when(param("amount") > 10000),
))
```

**OpenAI / Anthropic / OpenRouter:**

```python
from agsec.integrations.openai import protect, deny, param

client = protect(OpenAI(),
    deny("delete_user"),
    deny("payment").when(param("amount") > 10000),
)
# Works with OpenRouter, Groq, Together — anything OpenAI-compatible
```

**Any Python function:**

```python
from agsec import guard

@guard("email.send")
def send_email(to, subject, body):
    ...
```

---

## CLI reference

```bash
agsec init [--observe]        # scaffold policies
agsec install <platform>      # activate firewall
agsec uninstall <platform>    # deactivate

agsec policy list             # view all rules
agsec policy add              # add a rule (interactive)
agsec policy remove <sid>     # remove a rule
agsec validate                # check for errors

agsec audit [--stats]         # view action log
agsec analyze [--hours N]     # threat analysis with blast radius
agsec analyze --all           # full activity report (every action)
agsec status                  # firewall status at a glance
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
```

---

## OWASP Agentic Top 10 coverage

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
- [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 workflow
- [OWASP Mapping](docs/owasp-mapping.md) — compliance reference

---

## Contributing

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).
