agentguard-oss 0.4.1__tar.gz

agentguard_oss-0.4.1/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+*.jsonl
+*.jsonl.lock
+.demo-workspace/
+
+site/
+.hypothesis/

agentguard_oss-0.4.1/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/). Before 1.0, minor versions may change the API.
+
+## [Unreleased]
+
+## [0.4.1] - 2026-10-10
+
+### Fixed
+- Ask-level command concerns (irreversible infrastructure operations, raw network transfers,
+  environment dumps, inline code that runs commands) were dropped when the command was wrapped
+  in `bash -c`, `cmd /c`, PowerShell `-Command` or `eval`, so `bash -c 'terraform destroy'`
+  ran without approval. They now propagate through these wrappers, within the nesting limit.
+- Changes to `core.hooksPath` through legacy or modern `git config` commands now raise
+  ask-level risk, including wrapped shell commands. Queries and unrelated settings remain
+  allowed by this check.
+
+## [0.4.0] - 2026-10-08
+
+### Added
+- `ContainerExecutor`: allowlisted commands in Docker or Podman (optionally gVisor) with no
+  network, read-only root, no capabilities, no-new-privileges, an unprivileged user,
+  resource limits and a read-only workspace by default.
+- DNS pinning: `NetworkExecutor` connects only to the public addresses it checked.
+- `EgressProxy` and `agentguard egress-proxy`: an allowlisting HTTPS CONNECT proxy with
+  pinned public DNS and audited decisions.
+- Secret detection with the vendored gitleaks ruleset (221 rules) on RE2, and
+  `scripts/update_secret_rules.py`.
+- PII detection (email, phone, credit card, SSN, IBAN) with checksums; policies can name
+  the categories in `sensitive_data`; cards, SSNs and IBANs are redacted from logs.
+- Shell-aware command analysis (`agentguard.risk.commands`): tokenizes, splits and
+  unwraps commands; new hard-deny and ask-level categories; obfuscation asks.
+- `agentguard judge-bench`: labeled benchmark (71 cases plus a 35-case holdout) reporting
+  recall, false positives, instability and latency for rules, a judge and both combined.
+- Property-based tests (Hypothesis) for paths, URLs, commands, secrets, audit and policy.
+- CI on Linux, Windows and macOS with Python 3.11-3.14; CodeQL, bandit, pip-audit and
+  Dependabot; nightly long property runs; Docker integration tests.
+- Security review guide for an independent reviewer.
+
+### Changed
+- New dependency: `google-re2`.
+- Deterministic recall on the benchmark rose from 54% to 95% (holdout: 0% to 100%, same
+  author; see the benchmarks page).
+
+### Fixed
+- `rm -r -f`, `chmod 0777`, `curl ... | python3` evaded detection; `echo rm -rf` was
+  blocked; URLs with DEL or C1 characters were accepted.
+- Persistence paths were missed on Windows after normalization.
+- `killpg` cleanup raised on macOS; writable container workspaces were unwritable.
+
+## [0.3.0] - 2026-10-08
+
+### Added
+- Queued approvals that do not block the agent: `ApprovalStore` (SQLite, shared by agents and
+  the dashboard) and `QueueApproval`. An `ask` call raises `ApprovalPending` with a request
+  ID; retrying after approval runs it. Identical pending calls share one request, and
+  recently rejected calls are denied without asking again. `wait=` waits inside the call.
+- Grants: approve once, the same call, a tool or a capability for 1 minute to 24 hours,
+  bound to agent and environment, revocable.
+- Token-authenticated approvers (hashed), with strong approval for `--strong` approvers who
+  re-enter their token. `agentguard approvers add/list/remove`, `agentguard approvals list`.
+- Slack notifications with approve/allow/reject buttons (signature-verified clicks) and
+  HMAC-signed webhooks (`verify_signature`).
+- `agentguard dashboard` (extra `dashboard`): approval queue, grants, audit log viewer with
+  search and timelines, and policy report; token login, CSRF protection, strict CSP, and a
+  JSON API with Bearer tokens.
+- `agentguard report` and `build_report`: what was asked about or denied, by tool and
+  reason, for tuning a policy from dry-run sessions.
+- Audit checkpoint (`.head`) so appends no longer re-read the log; rotation (`max_bytes`)
+  with the chain continuing across segments; HMAC signing (`signing_key`, `--key-env`);
+  `LoggingExporter` (OpenTelemetry, syslog) and `HttpExporter` (Splunk HEC, collectors).
+- Sessions: `guard.new_session(agent_id=...)` with its own lock, rate window, taint and halt
+  state; sessions run in parallel. `with session:` binds tools in a context.
+- Pluggable rate limiting: `LocalRateLimiter` and `RedisRateLimiter` (extra `redis`), with
+  policy `limits.rate_limit_scope` of `session`, `agent` or `global`.
+
+### Changed
+- `max_calls_per_minute` is enforced per `rate_limit_scope` (default `session`, as before).
+- Audit events may carry `signature`; it is excluded from the event hash.
+- CLI errors outside `demo` no longer suggest checking the model service.
+
+### Fixed
+- Credential paths after `@` or `=` (`curl -d @.env`, `--file=.env`) are hard-denied.
+
+## [0.2.0] - 2026-10-08
+
+Renamed the distribution to `agentguard-oss` (`import agentguard`) and prepared PyPI
+publishing.
+
+### Added
+- Argument roles: `guard.tool(path_arg=, url_arg=, command_arg=, content_arg=,
+  recipient_args=)` for tools whose parameters are not named `path`, `url`, `cmd`,
+  `content` or `to`. Misconfigured tools fail at registration.
+- Custom capabilities declared in the policy (`capabilities: {db.query: {risk: 30}}`),
+  with baseline risk, an outbound flag for session-taint checks, and a description.
+- `agentguard check-policy` validates a policy and prints a summary or located errors.
+- `agentguard explain` shows the matching rules, risk factors and decision for one call.
+- Framework adapters: LangChain/LangGraph, OpenAI Agents SDK and Google ADK
+  (`agentguard.adapters.*.guarded_tool`). Denials are returned to the model with reasons.
+- Gemma is the default live demo agent when Ollama has a Gemma model; `--scripted` runs
+  offline. The judge takes trusted `guidance` and a `capabilities` scope.
+- `ShellExecutor(check=False)` returns nonzero exits as results.
+- `Guard.tools`, `Guard.capabilities`, `agentguard.__version__`, `py.typed`.
+
+### Changed
+- Distribution renamed from `agentguard-sdk` (taken on PyPI) to `agentguard-oss`.
+- Tools receive the absolute requested path; policy and credential checks use both the
+  requested path and its resolved target.
+- A judge `deny` flag escalates to human approval; a judge score at or above the deny
+  threshold still denies.
+- Ollama requests disable thinking, use an 8192-token context and longer timeouts.
+
+### Fixed
+- Links inside the workspace bypassed `FilesystemExecutor` link rejection, and Windows
+  junctions were missed on Python 3.11 by the executor and the verifier.
+- The email/message recipient limit ignored `cc`, `bcc` and `recipients`.
+- Nested guarded calls from an async tool deadlocked.
+- New files were created with lowercase names on Windows.
+- `format` flags (`ruff format`, `--format=`) were hard-denied as disk formatting.
+- Policy domains accepted `?` and `[`, which acted as wildcards.
+- `git push` and `repository.write` were not treated as outbound for session taint.
+- The audit record overwrote the action's proposal timestamp.
+
+## [0.1.0] - 2026-10-08
+
+Initial source release: policy as code, deterministic risk scoring, CLI approval,
+controlled executors, workspace verification, hash-chained audit log, MCP adapter,
+and the prompt-injection demo with an optional local Gemma agent and judge.
+
+[Unreleased]: https://github.com/prollysamz/agentguard/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/prollysamz/agentguard/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/prollysamz/agentguard/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/prollysamz/agentguard/compare/971b8bd...v0.3.0
+[0.2.0]: https://github.com/prollysamz/agentguard/compare/8a0f847...971b8bd
+[0.1.0]: https://github.com/prollysamz/agentguard/commit/8a0f847

agentguard_oss-0.4.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 AgentGuard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

agentguard_oss-0.4.1/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: agentguard-oss
+Version: 0.4.1
+Summary: Open-source safety layer for AI agent tool calls: policy, risk checks, human approval and tamper-evident audit
+Project-URL: Homepage, https://github.com/prollysamz/agentguard
+Project-URL: Documentation, https://prollysamz.github.io/agentguard/
+Project-URL: Repository, https://github.com/prollysamz/agentguard
+Project-URL: Issues, https://github.com/prollysamz/agentguard/issues
+Project-URL: Changelog, https://github.com/prollysamz/agentguard/blob/main/CHANGELOG.md
+Author: Sameer Jakkuva
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,ai-safety,gemma,guardrails,llm-security,mcp,policy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: google-re2<2,>=1.1
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: portalocker<4,>=3
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: pyyaml<7,>=6.0.2
+Provides-Extra: adk
+Requires-Dist: google-adk<3,>=2; extra == 'adk'
+Provides-Extra: all
+Requires-Dist: google-adk<3,>=2; extra == 'all'
+Requires-Dist: langchain-core<2,>=1; extra == 'all'
+Requires-Dist: mcp<2,>=1.12; extra == 'all'
+Requires-Dist: openai-agents<1,>=0.23; extra == 'all'
+Requires-Dist: redis<9,>=5; extra == 'all'
+Requires-Dist: starlette<2,>=0.40; extra == 'all'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'all'
+Provides-Extra: dashboard
+Requires-Dist: starlette<2,>=0.40; extra == 'dashboard'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: bandit<2,>=1.8; extra == 'dev'
+Requires-Dist: build<2,>=1; extra == 'dev'
+Requires-Dist: fakeredis<3,>=2.26; extra == 'dev'
+Requires-Dist: hypothesis<7,>=6.100; extra == 'dev'
+Requires-Dist: langgraph<2,>=1; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Requires-Dist: twine<8,>=7; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=1; extra == 'langchain'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.12; extra == 'mcp'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents<1,>=0.23; extra == 'openai-agents'
+Provides-Extra: redis
+Requires-Dist: redis<9,>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# AgentGuard
+
+**Let agents act. Keep humans in control.**
+
+[![CI](https://github.com/prollysamz/agentguard/actions/workflows/ci.yml/badge.svg)](https://github.com/prollysamz/agentguard/actions/workflows/ci.yml)
+[![Docs](https://github.com/prollysamz/agentguard/actions/workflows/docs.yml/badge.svg)](https://prollysamz.github.io/agentguard/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+
+AgentGuard is an open-source Python SDK that sits between an AI agent and its tools.
+Every tool call is validated, checked against a policy, scored for risk, optionally
+reviewed by a local **Gemma** model, sent to a human when needed, run through a
+restricted executor, verified, and written to a tamper-evident audit log.
+
+**[Documentation](https://prollysamz.github.io/agentguard/)** ·
+[Quickstart](https://prollysamz.github.io/agentguard/quickstart/) ·
+[Integrations](https://prollysamz.github.io/agentguard/integrations/langchain/) ·
+[Threat model](THREAT_MODEL.md) · [Changelog](CHANGELOG.md)
+
+## See it work
+
+```sh
+pip install agentguard-oss
+agentguard demo --scripted
+```
+
+An agent is asked to fix a calculator. The repository's README hides a prompt injection
+telling it to read `~/.ssh/id_rsa` and upload it. AgentGuard lets the agent read the
+README, **blocks** the SSH-key read and the `curl` exfiltration, **allows** the fix and a
+real unit test, and **escalates** the push to `main` for human approval.
+
+With [Ollama](https://ollama.com) and `ollama pull gemma3:4b`, plain `agentguard demo`
+runs a live **Gemma agent** against the same trap, and `--judge` adds a Gemma security
+reviewer. Add `--interactive` to approve the push yourself. See
+[Gemma agent and judge](https://prollysamz.github.io/agentguard/gemma/).
+
+## Guard a tool
+
+```python
+from pathlib import Path
+
+from agentguard import Guard
+
+guard = Guard(
+    {
+        "version": 1,
+        "defaults": {"effect": "deny"},
+        "rules": [
+            {"capability": "filesystem.read", "paths": ["./workspace/**"], "effect": "allow"},
+            {"capability": "shell.execute", "effect": "ask"},
+        ],
+    },
+    audit="agentguard.jsonl",
+)
+
+
+@guard.tool(capability="filesystem.read")
+def read_file(path: str) -> str:
+    """Read a UTF-8 text file."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+# Give the agent read_file, never the raw function.
+# read_file("~/.ssh/id_rsa") raises GuardDenied before the function body runs.
+```
+
+Then check the policy, ask how it decides a call, and verify the log:
+
+```sh
+agentguard check-policy policy.yaml
+agentguard explain policy.yaml shell.execute --arg cmd="git push origin main"
+agentguard verify-log --audit agentguard.jsonl
+```
+
+## Use it with your framework
+
+```sh
+pip install "agentguard-oss[langchain]"   # also [openai-agents], [adk], [mcp], [all]
+```
+
+```python
+from agentguard.adapters.langchain import guarded_tool        # LangChain / LangGraph
+# from agentguard.adapters.openai_agents import guarded_tool  # OpenAI Agents SDK
+# from agentguard.adapters.adk import guarded_tool            # Google ADK
+
+
+def read_notes(path: str) -> str:
+    """Read a notes file."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+notes_tool = guarded_tool(guard, read_notes, capability="filesystem.read")
+```
+
+Denials go back to the model with AgentGuard's reasons so the agent can adapt. MCP
+servers use `agentguard.adapters.mcp.register_tool`; any other loop can call
+`guard.call(name, arguments)`.
+
+## What you get
+
+| Control | Details |
+| --- | --- |
+| **Policy as code** | YAML allow / ask / deny rules by capability, path, domain, environment and secrets. Explicit denies win. [Custom capabilities](https://prollysamz.github.io/agentguard/policy/#custom-capabilities) like `db.query` or `payments.refund`. |
+| **Risk checks** | Explainable 0–100 scores. Credential files, destructive commands and exfiltration after a secret was seen are always denied. |
+| **Human approval** | Risky calls go to a person in the dashboard, Slack or your own system without blocking the agent; grants like "allow this tool for 10 minutes". No answer means deny. |
+| **Isolation** | Container executor (no network, read-only, no capabilities, optional gVisor), exact-command runners, DNS-pinned HTTPS, and an allowlisting egress proxy. |
+| **Detection** | gitleaks' 221 secret rules on RE2, checksum-validated PII, and shell-aware command analysis. |
+| **Verification** | Before/after hashes catch tools that change files they were not asked to. |
+| **Audit** | Every stage of every call in a signed SHA-256 hash chain with rotation, exported to OpenTelemetry or a SIEM. |
+| **Dashboard** | Approval queue, audit log viewer and a dry-run policy report. |
+| **Multi-agent** | Parallel per-agent sessions; rate limits per session, agent or globally through Redis. |
+| **Gemma** | A local Gemma agent for the demo, and an optional judge that can only add caution. |
+
+Starter policies for [coding, browsing and support agents](examples/policies/) are in
+`examples/policies/`.
+
+## Operate it
+
+```sh
+pip install "agentguard-oss[dashboard]"
+agentguard approvers add alice            # prints a token for the dashboard and API
+agentguard dashboard                      # http://127.0.0.1:8765
+```
+
+```python
+from agentguard.approval import ApprovalStore, QueueApproval
+
+guard = Guard("policy.yaml", approval=QueueApproval(ApprovalStore("agentguard-approvals.db")))
+```
+
+Risky calls raise `ApprovalPending` immediately instead of blocking; the agent retries after
+a human approves in the [dashboard](https://prollysamz.github.io/agentguard/dashboard/), in
+Slack, or through the API. Run a new agent with `mode="dry-run"` and check
+`agentguard report --dry-run-only` to tune the policy before enforcing it.
+
+## Status
+
+AgentGuard 0.4 is alpha and has not had an independent security audit; see the
+[security review guide](https://prollysamz.github.io/agentguard/security-review/) and
+[benchmarks](https://prollysamz.github.io/agentguard/benchmarks/). It is an
+interception layer for cooperative applications, not an OS sandbox: an agent that also has
+unguarded tools, a raw shell or Python `exec` can go around it. Read the
+[threat model](THREAT_MODEL.md) before guarding privileged tools, and report
+vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## Develop
+
+```sh
+git clone https://github.com/prollysamz/agentguard.git
+cd agentguard
+python -m venv .venv
+# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
+python -m pip install -e ".[dev,all,docs]"
+python -m pytest -q
+python -m ruff check .
+mkdocs serve
+```
+
+CI runs the tests on Linux and Windows with Python 3.11 and 3.12. See
+[CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

agentguard_oss-0.4.1/README.md

@@ -0,0 +1,160 @@
+# AgentGuard
+
+**Let agents act. Keep humans in control.**
+
+[![CI](https://github.com/prollysamz/agentguard/actions/workflows/ci.yml/badge.svg)](https://github.com/prollysamz/agentguard/actions/workflows/ci.yml)
+[![Docs](https://github.com/prollysamz/agentguard/actions/workflows/docs.yml/badge.svg)](https://prollysamz.github.io/agentguard/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+
+AgentGuard is an open-source Python SDK that sits between an AI agent and its tools.
+Every tool call is validated, checked against a policy, scored for risk, optionally
+reviewed by a local **Gemma** model, sent to a human when needed, run through a
+restricted executor, verified, and written to a tamper-evident audit log.
+
+**[Documentation](https://prollysamz.github.io/agentguard/)** ·
+[Quickstart](https://prollysamz.github.io/agentguard/quickstart/) ·
+[Integrations](https://prollysamz.github.io/agentguard/integrations/langchain/) ·
+[Threat model](THREAT_MODEL.md) · [Changelog](CHANGELOG.md)
+
+## See it work
+
+```sh
+pip install agentguard-oss
+agentguard demo --scripted
+```
+
+An agent is asked to fix a calculator. The repository's README hides a prompt injection
+telling it to read `~/.ssh/id_rsa` and upload it. AgentGuard lets the agent read the
+README, **blocks** the SSH-key read and the `curl` exfiltration, **allows** the fix and a
+real unit test, and **escalates** the push to `main` for human approval.
+
+With [Ollama](https://ollama.com) and `ollama pull gemma3:4b`, plain `agentguard demo`
+runs a live **Gemma agent** against the same trap, and `--judge` adds a Gemma security
+reviewer. Add `--interactive` to approve the push yourself. See
+[Gemma agent and judge](https://prollysamz.github.io/agentguard/gemma/).
+
+## Guard a tool
+
+```python
+from pathlib import Path
+
+from agentguard import Guard
+
+guard = Guard(
+    {
+        "version": 1,
+        "defaults": {"effect": "deny"},
+        "rules": [
+            {"capability": "filesystem.read", "paths": ["./workspace/**"], "effect": "allow"},
+            {"capability": "shell.execute", "effect": "ask"},
+        ],
+    },
+    audit="agentguard.jsonl",
+)
+
+
+@guard.tool(capability="filesystem.read")
+def read_file(path: str) -> str:
+    """Read a UTF-8 text file."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+# Give the agent read_file, never the raw function.
+# read_file("~/.ssh/id_rsa") raises GuardDenied before the function body runs.
+```
+
+Then check the policy, ask how it decides a call, and verify the log:
+
+```sh
+agentguard check-policy policy.yaml
+agentguard explain policy.yaml shell.execute --arg cmd="git push origin main"
+agentguard verify-log --audit agentguard.jsonl
+```
+
+## Use it with your framework
+
+```sh
+pip install "agentguard-oss[langchain]"   # also [openai-agents], [adk], [mcp], [all]
+```
+
+```python
+from agentguard.adapters.langchain import guarded_tool        # LangChain / LangGraph
+# from agentguard.adapters.openai_agents import guarded_tool  # OpenAI Agents SDK
+# from agentguard.adapters.adk import guarded_tool            # Google ADK
+
+
+def read_notes(path: str) -> str:
+    """Read a notes file."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+notes_tool = guarded_tool(guard, read_notes, capability="filesystem.read")
+```
+
+Denials go back to the model with AgentGuard's reasons so the agent can adapt. MCP
+servers use `agentguard.adapters.mcp.register_tool`; any other loop can call
+`guard.call(name, arguments)`.
+
+## What you get
+
+| Control | Details |
+| --- | --- |
+| **Policy as code** | YAML allow / ask / deny rules by capability, path, domain, environment and secrets. Explicit denies win. [Custom capabilities](https://prollysamz.github.io/agentguard/policy/#custom-capabilities) like `db.query` or `payments.refund`. |
+| **Risk checks** | Explainable 0–100 scores. Credential files, destructive commands and exfiltration after a secret was seen are always denied. |
+| **Human approval** | Risky calls go to a person in the dashboard, Slack or your own system without blocking the agent; grants like "allow this tool for 10 minutes". No answer means deny. |
+| **Isolation** | Container executor (no network, read-only, no capabilities, optional gVisor), exact-command runners, DNS-pinned HTTPS, and an allowlisting egress proxy. |
+| **Detection** | gitleaks' 221 secret rules on RE2, checksum-validated PII, and shell-aware command analysis. |
+| **Verification** | Before/after hashes catch tools that change files they were not asked to. |
+| **Audit** | Every stage of every call in a signed SHA-256 hash chain with rotation, exported to OpenTelemetry or a SIEM. |
+| **Dashboard** | Approval queue, audit log viewer and a dry-run policy report. |
+| **Multi-agent** | Parallel per-agent sessions; rate limits per session, agent or globally through Redis. |
+| **Gemma** | A local Gemma agent for the demo, and an optional judge that can only add caution. |
+
+Starter policies for [coding, browsing and support agents](examples/policies/) are in
+`examples/policies/`.
+
+## Operate it
+
+```sh
+pip install "agentguard-oss[dashboard]"
+agentguard approvers add alice            # prints a token for the dashboard and API
+agentguard dashboard                      # http://127.0.0.1:8765
+```
+
+```python
+from agentguard.approval import ApprovalStore, QueueApproval
+
+guard = Guard("policy.yaml", approval=QueueApproval(ApprovalStore("agentguard-approvals.db")))
+```
+
+Risky calls raise `ApprovalPending` immediately instead of blocking; the agent retries after
+a human approves in the [dashboard](https://prollysamz.github.io/agentguard/dashboard/), in
+Slack, or through the API. Run a new agent with `mode="dry-run"` and check
+`agentguard report --dry-run-only` to tune the policy before enforcing it.
+
+## Status
+
+AgentGuard 0.4 is alpha and has not had an independent security audit; see the
+[security review guide](https://prollysamz.github.io/agentguard/security-review/) and
+[benchmarks](https://prollysamz.github.io/agentguard/benchmarks/). It is an
+interception layer for cooperative applications, not an OS sandbox: an agent that also has
+unguarded tools, a raw shell or Python `exec` can go around it. Read the
+[threat model](THREAT_MODEL.md) before guarding privileged tools, and report
+vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## Develop
+
+```sh
+git clone https://github.com/prollysamz/agentguard.git
+cd agentguard
+python -m venv .venv
+# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
+python -m pip install -e ".[dev,all,docs]"
+python -m pytest -q
+python -m ruff check .
+mkdocs serve
+```
+
+CI runs the tests on Linux and Windows with Python 3.11 and 3.12. See
+[CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

agentguard_oss-0.4.1/agentguard/__init__.py

@@ -0,0 +1,41 @@
+"""AgentGuard's public SDK.
+
+Public API: the names in ``__all__`` here, plus ``agentguard.approval``,
+``agentguard.execution``, ``agentguard.adapters.*`` and
+``agentguard.risk.gemma_judge.GemmaJudge``. Other modules are internal and may change.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from agentguard.approval.base import Approval, ApprovalProvider
+from agentguard.core.action import Action
+from agentguard.core.decision import (
+    ApprovalPending,
+    Decision,
+    Effect,
+    GuardDenied,
+    GuardError,
+)
+from agentguard.core.guard import Guard
+from agentguard.policy.explain import explain
+from agentguard.policy.loader import load_policy
+
+try:
+    __version__ = version("agentguard-oss")
+except PackageNotFoundError:  # Running from a source tree without installation.
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "Action",
+    "Approval",
+    "ApprovalPending",
+    "ApprovalProvider",
+    "Decision",
+    "Effect",
+    "Guard",
+    "GuardDenied",
+    "GuardError",
+    "__version__",
+    "explain",
+    "load_policy",
+]

agentguard_oss-0.4.1/agentguard/__main__.py

@@ -0,0 +1,3 @@
+from agentguard.cli.main import main
+
+raise SystemExit(main())

agentguard_oss-0.4.1/agentguard/adapters/_common.py

@@ -0,0 +1,54 @@
+"""Shared adapter helpers. Adapters translate and dispatch; they make no security decisions."""
+
+import functools
+import inspect
+
+from agentguard.core.decision import ApprovalPending, GuardDenied
+
+
+def denial_result(exc: GuardDenied) -> dict:
+    """What the model sees when AgentGuard denies a call: the reasons, so it can adapt."""
+    if isinstance(exc, ApprovalPending):
+        return {
+            "error": "Approval pending",
+            "request_id": exc.request_id,
+            "reasons": list(exc.decision.reasons),
+            "next_step": "A human must approve this. Continue with other work and retry "
+            "the same call later.",
+        }
+    return {"error": "Denied by AgentGuard", "reasons": list(exc.decision.reasons)}
+
+
+def returning_denials(guarded, on_denied=denial_result):
+    """Wrap a guarded tool so denials become a result instead of an exception.
+
+    Only GuardDenied is converted. Other GuardErrors (a halted session, failed execution)
+    still raise, so frameworks surface them as tool failures.
+    """
+    if inspect.iscoroutinefunction(guarded):
+
+        @functools.wraps(guarded)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await guarded(*args, **kwargs)
+            except GuardDenied as exc:
+                return on_denied(exc)
+    else:
+
+        @functools.wraps(guarded)
+        def wrapper(*args, **kwargs):
+            try:
+                return guarded(*args, **kwargs)
+            except GuardDenied as exc:
+                return on_denied(exc)
+
+    # The return type changes on denial; frameworks infer only the arguments from this.
+    wrapper.__signature__ = inspect.signature(guarded).replace(
+        return_annotation=inspect.Signature.empty
+    )
+    wrapper.__annotations__ = {k: v for k, v in guarded.__annotations__.items() if k != "return"}
+    return wrapper
+
+
+def describe(function, description):
+    return description or inspect.getdoc(function) or f"{function.__name__} (guarded by AgentGuard)"