Metadata-Version: 2.4
Name: agent-guardian
Version: 1.0.0rc8
Summary: Open-source red teaming toolkit for AI agents, RAG systems, MCP servers, and tool-using LLM applications.
Project-URL: Homepage, https://github.com/glacien-technologies/agent-guardian
Project-URL: Documentation, https://github.com/glacien-technologies/agent-guardian/blob/main/docs/index.md
Project-URL: Repository, https://github.com/glacien-technologies/agent-guardian
Project-URL: Issues, https://github.com/glacien-technologies/agent-guardian/issues
Project-URL: Changelog, https://github.com/glacien-technologies/agent-guardian/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/glacien-technologies/agent-guardian
Author-email: "Glacien Pte. Ltd." <opensource@glacien.ai>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,agentic-ai,ai-red-team,ai-safety,ai-security,aivss,cybersecurity,genai-security,jailbreak,llm,llm-security,mitre-atlas,owasp,prompt-injection,red-team,sarif,security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Requires-Dist: cryptography>=43.0
Requires-Dist: exceptiongroup>=1.2; python_version < '3.11'
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.28
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.21
Requires-Dist: pydantic>=2.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.2
Requires-Dist: rich>=13.9
Requires-Dist: structlog>=24.4
Requires-Dist: textual>=0.86
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn[standard]>=0.32
Provides-Extra: agentdojo
Requires-Dist: agentdojo>=0.1; extra == 'agentdojo'
Provides-Extra: aws
Requires-Dist: botocore>=1.34; extra == 'aws'
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: hypothesis>=6.115; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pip-licenses>=5.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20260518; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: examples
Requires-Dist: langchain-core>=0.3; extra == 'examples'
Requires-Dist: langchain-google-genai>=2.0; extra == 'examples'
Requires-Dist: langgraph>=0.2; extra == 'examples'
Requires-Dist: openai-agents>=0.3; extra == 'examples'
Requires-Dist: openai>=1.50; extra == 'examples'
Provides-Extra: examples-crewai
Requires-Dist: crewai>=0.55; extra == 'examples-crewai'
Provides-Extra: full
Requires-Dist: faiss-cpu>=1.9; extra == 'full'
Requires-Dist: presidio-analyzer>=2.2; extra == 'full'
Requires-Dist: sentence-transformers>=3.3; extra == 'full'
Requires-Dist: weasyprint>=63.0; extra == 'full'
Provides-Extra: gcp
Requires-Dist: google-auth>=2.0; extra == 'gcp'
Provides-Extra: grpc
Requires-Dist: grpcio>=1.60; extra == 'grpc'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-semantic-conventions>=0.48b0; extra == 'otel'
Provides-Extra: pdf-fallback
Provides-Extra: ws
Requires-Dist: websockets>=12.0; extra == 'ws'
Description-Content-Type: text/markdown

<div align="center">

# AgentGuardian

**Red-team your AI agents before attackers do.**

Open-source, local-first adversarial security testing for AI agents, RAG systems, MCP servers, and tool-using LLM applications.

[![PyPI](https://img.shields.io/pypi/v/agent-guardian.svg)](https://pypi.org/project/agent-guardian/)
[![Python](https://img.shields.io/pypi/pyversions/agent-guardian.svg)](https://pypi.org/project/agent-guardian/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![CI](https://github.com/glacien-technologies/agent-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/glacien-technologies/agent-guardian/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/glacien-technologies/agent-guardian/badge)](https://api.securityscorecards.dev/projects/github.com/glacien-technologies/agent-guardian)
[![Docs](https://img.shields.io/badge/docs-agentguardian.io-1f6feb.svg)](https://agentguardian.io)

[Docs](https://agentguardian.io) · [Quickstart](./docs/quickstart.mdx) · [Try the demo agent](./docs/start-here/try-the-demo-agent.mdx) · [Attack library](./docs/attacks/overview.mdx) · [CI/CD](./docs/ci-cd/overview.mdx) · [Sample report](./docs/_assets/sample-report.html)

</div>

---

AgentGuardian points a swarm of adversarial probes at your target and gives you reproducible evidence you can use in engineering, security review, and CI: AIVSS scoring, signed JSON, SARIF, Markdown, JUnit, PDF, and per-probe transcripts.

- Built for agentic systems, not just single-prompt chatbot evals.
- Finds prompt injection, tool misuse, privilege abuse, memory poisoning, code-exec paths, trust exploits, and goal drift.
- Runs locally, in CI, or offline in deterministic `--model stub` mode.

## Demo

```bash
pip install agent-guardian
echo 'You are a helpful customer-support agent for ACME Bank.' > prompt.txt
agent-guardian scan --system-prompt prompt.txt --mode fast --model stub
```

That gives you:

- a live local dashboard during interactive scans
- a stored scan artifact under `~/.agentguardian/scans/<scan_id>/`
- exportable reports via `agent-guardian report SCAN_ID --output sarif --output-path scan.sarif`
- a static reference rendering: [`docs/_assets/sample-report.html`](./docs/_assets/sample-report.html)

`--model stub` requires no API key and no network. Swap in a real model such as `gemini:gemini-2.5-flash` or `openai:gpt-4o` when you want an authoritative judge.

## Install

```bash
# pip
pip install agent-guardian

# pipx
pipx install agent-guardian

# uv
uv add agent-guardian
# or
uv tool install agent-guardian
```

Python `3.11`–`3.13` are supported. Linux and macOS are first-class; Windows is community-supported.

> **Heads up:** current macOS often defaults `python3` to `3.14`, which AgentGuardian does not yet target. If `pip install agent-guardian` fails with `No matching distribution found`, use Python `3.13` instead:
>
> ```bash
> python3.13 -m venv .venv
> source .venv/bin/activate
> pip install agent-guardian
> ```
>
> Docker and the GitHub Action path are insulated from this. See [`docs/installation.mdx`](./docs/installation.mdx) for the full install matrix.

## 60-second quickstart

```bash
# 1. Sanity-check the install
agent-guardian doctor

# 2. See the shipped probe corpus
agent-guardian list-probes

# 3. Run an offline scan
echo 'You are a helpful customer-support agent for ACME Bank.' > prompt.txt
agent-guardian scan --system-prompt prompt.txt --mode fast --model stub

# 4. Export a machine-readable report once you have a scan id
agent-guardian report SCAN_ID --output sarif --output-path scan.sarif
```

Interactive scans auto-serve a local dashboard. You can also browse results later with:

```bash
agent-guardian serve
# → http://127.0.0.1:7474
```

## What you can scan

- **Prompt-only targets** via `--system-prompt PATH`
- **Hosted HTTP agents** via `--endpoint URL`
- **Framework-native objects** via `--framework KIND --framework-ref MODULE:ATTR`
- **Custom Python entrypoints** via the positional `target` argument (`my_agent:run`, `path/to/app.py:graph`)
- **Advanced contract-driven targets** including MCP / OpenAPI / browser / WebSocket flows via the contract path documented in [`docs/concepts/target-adapters.mdx`](./docs/concepts/target-adapters.mdx)

Built-in framework kinds:

- `langgraph`
- `crewai`
- `openai_agents`
- `autogen`
- `adk`
- `strands`

## What it catches

AgentGuardian ships **96 attack probes** covering all ten OWASP Top 10 for Agentic Applications 2026 categories:

- **ASI01** — prompt injection / goal hijack
- **ASI02** — tool misuse
- **ASI03** — privilege compromise
- **ASI04** — supply chain / resource overload
- **ASI05** — code execution
- **ASI06** — memory poisoning
- **ASI07** — agent-to-agent compromise
- **ASI08** — cascading failures
- **ASI09** — trust exploitation / unsafe output handling
- **ASI10** — untraceability / goal drift

The corpus is also mapped to MITRE ATLAS v5.4.0 and the CSA Agentic AI Red Teaming Guide. See the exact set in [`docs/reference/framework-coverage-matrix.md`](./docs/reference/framework-coverage-matrix.md).

## What you get

- **Signed JSON evidence** — `scan.json` ships with HMAC-SHA256 + Ed25519 signatures verifiable with `agent-guardian verify`
- **Exportable reports** — `json`, `sarif`, `junit`, `md`, `gitlab`, and `pdf`
- **Per-probe transcripts** — prompts, responses, verdicts, and evidence trails
- **AIVSS scoring** — publishable in `--mode full`; trend-tracking in `fast` and `smart`
- **Local dashboard** — browse historical scans, findings, and evidence bundles

To verify a stored report:

```bash
agent-guardian verify ~/.agentguardian/scans/SCAN_ID/scan.json
```

## Why AgentGuardian

- **Agent-first** — built for tool-using, stateful, multi-step systems rather than single-turn prompt checks
- **Recon before attack** — fingerprints the target surface and then runs only the relevant specialists
- **Evidence over vibes** — reports are grounded in transcripts, structured findings, and signed artifacts
- **Local-first** — no telemetry, no phone-home, and a fully offline stub-mode path
- **CI-ready** — non-zero exit codes, SARIF export, and reusable GitHub Action patterns

For a deeper competitive breakdown, see [`docs/concepts/agent-guardian-vs.mdx`](./docs/concepts/agent-guardian-vs.mdx).

## How it works

Every scan follows the same narrative:

1. **Plan** — resolve the target type, budgets, models, and output format
2. **Recon** — black-box fingerprint the target: tools, memory, PII exposure, multi-agent handoffs, reachable systems
3. **Red Teaming** — dispatch ASI-aligned specialists against the observed surface
4. **Findings** — judge outcomes, compute AIVSS, and write signed reports

The recon fingerprint is the key difference: AgentGuardian decides which attacks matter *for this target* before it spends budget on them.

## Scan a real target

```bash
# Hosted HTTP endpoint
agent-guardian scan \
  --endpoint http://localhost:8000/chat \
  --model gemini:gemini-2.5-flash \
  --mode smart

# LangGraph app
agent-guardian scan \
  --framework langgraph \
  --framework-ref my_app.graph:graph \
  --model gemini:gemini-2.5-flash

# Custom Python entrypoint
agent-guardian scan \
  my_agent:run \
  --model gemini:gemini-2.5-flash
```

Worked examples live under [`examples/`](./examples/) and the `Try AgentGuardian` guides under [`docs/try/`](./docs/try/).

## Scan modes

| Mode | Typical use | Notes |
| --- | --- | --- |
| `fast` | Dev loop, smoke checks, pre-push | Lowest cost and quickest feedback |
| `smart` | PR iteration, broader nightly coverage | Better signal than `fast`, still non-authoritative |
| `full` | Release gates, CI on `main`, audit evidence | Authoritative mode for AIVSS and `--fail-under` |

Only `--mode full` produces an authoritative AIVSS suitable for hard release gating.

## CI integration

```yaml
name: AgentGuardian
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install agent-guardian
      - name: Red-team the agent
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          agent-guardian scan \
            --endpoint http://localhost:8000/chat \
            --model gemini:gemini-2.5-flash \
            --mode full \
            --output sarif \
            --output-path agentguardian.sarif \
            --fail-under 80
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: agentguardian.sarif
```

See [`docs/ci-cd/overview.mdx`](./docs/ci-cd/overview.mdx) and [`docs/ci-cd/github-actions.mdx`](./docs/ci-cd/github-actions.mdx) for the fuller setup, thresholds, and composite-action path.

## Standards and coverage

Enumerate the corpus locally:

```bash
agent-guardian list-probes
agent-guardian list-probes --by-standard owasp-asi
agent-guardian list-probes --by-standard mitre-atlas
agent-guardian list-probes --by-standard csa-agentic-rt
```

Coverage today:

- **OWASP ASI 2026** — all 10 categories covered
- **MITRE ATLAS v5.4.0** — mapped where black-box agent testing can observe the technique at the target I/O surface
- **CSA Agentic AI Red Teaming Guide** — mapped across the shipped corpus

The exact probe-to-standard mapping lives in [`docs/reports/owasp-mapping.mdx`](./docs/reports/owasp-mapping.mdx) and [`docs/reference/framework-coverage-matrix.md`](./docs/reference/framework-coverage-matrix.md).

## Privacy & telemetry

**No telemetry is collected.** There is no analytics ping, install tracker, or phone-home path. Stub mode additionally works offline with no LLM key.

## Docs

- [Docs home](https://agentguardian.io)
- [`docs/quickstart.mdx`](./docs/quickstart.mdx)
- [`docs/attacks/overview.mdx`](./docs/attacks/overview.mdx)
- [`docs/concepts/target-adapters.mdx`](./docs/concepts/target-adapters.mdx)
- [`docs/reference/cli.mdx`](./docs/reference/cli.mdx)

## Project status

AgentGuardian `1.0.0` is the first stable release. Semantic versioning applies to the public Python API, CLI surface, report schemas, and probe IDs. Probe content and scoring may evolve within a minor release as coverage improves.

See [`ROADMAP.md`](./ROADMAP.md), [`CHANGELOG.md`](./CHANGELOG.md), and [`governance.md`](./governance.md).

## Contributing

We welcome new probes, new adapters, and new attacker logic. Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md) and the [`good first issue`](https://github.com/glacien-technologies/agent-guardian/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label.

All commits must be DCO-signed:

```bash
git commit -s
```

By participating you agree to [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) and [`ETHICS.md`](./ETHICS.md). AgentGuardian is for testing systems you own or are explicitly authorised to test.

## Community

Join us on [Discord](https://discord.gg/h4FRgxvr) for probe design, adapter questions, and roadmap discussion. For longer-form support channels, see [`docs/community/support.mdx`](./docs/community/support.mdx).

## Security

To report a vulnerability, see [`SECURITY.md`](./SECURITY.md). Do **not** open public issues for security reports.

## License

Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).

`AgentGuardian` is a trademark of Glacien Technologies. See [`TRADEMARKS.md`](./TRADEMARKS.md) for usage guidelines.
