Metadata-Version: 2.4
Name: agent-guardian
Version: 1.0.0rc17
Summary: Open-source red teaming toolkit for AI agents, RAG systems, MCP servers, and tool-using LLM applications.
Project-URL: Homepage, https://agentguardian.io
Project-URL: Documentation, https://docs.agentguardian.io
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: azure
Requires-Dist: azure-identity>=1.15; extra == 'azure'
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

# AgentGuardian

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

[![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://docs.agentguardian.io) · [Quickstart](https://docs.agentguardian.io/quickstart) · [Try the demo agent](https://docs.agentguardian.io/start-here/try-the-demo-agent) · [Attack library](https://docs.agentguardian.io/attacks/overview) · [CI/CD](https://docs.agentguardian.io/ci-cd/overview) · [Sample report](./docs/_assets/sample-report.pdf)

---

AgentGuardian is an open-source red-teaming toolkit for AI agents. It scans your agent, maps the attack surface, runs the relevant adversarial agents, and generates evidence-backed findings for you to review — and fix the vulnerabilities before they reach production.

<p align="center">
  <img src="./docs/images/agentguardian-demo.gif" alt="AgentGuardian finding vulnerabilities in a live scan" width="800">
</p>

<p align="center">
  <img src="./docs/images/swarm-diagrams/agentguardian-security-loop.jpg" alt="AgentGuardian recon, OWASP ASI probe generation, findings, reports, and fix-rerun loop" width="900">
</p>

## Quickstart

Requires Python 3.11–3.13.

**1. Install**

```bash
pip install agent-guardian
```

or

```bash
uv tool install agent-guardian
```

**2. Add a model key**

AgentGuardian drives its attacks with an LLM — Gemini, OpenAI, or Anthropic:

```bash
export GEMINI_API_KEY=...        # or OPENAI_API_KEY / ANTHROPIC_API_KEY
```

See the [configuration guide](https://docs.agentguardian.io/reference/config#provider-api-keys) for all providers and options.

**3. Check your setup**

```bash
agent-guardian doctor
```

**4. Run your first scan**

No agent of your own yet? Point it at the hosted demo target — a deliberately vulnerable "finbot" banking agent:

```bash
agent-guardian scan \
  --endpoint https://agent-guardian-testbench-u6tm6gzysq-uc.a.run.app/finbot/chat \
  --model gemini:gemini-3.5-flash \
  --mode fast
```

To scan your own agent, swap `--endpoint` for your target — local, staging, or production, any environment works as long as the endpoint is reachable.

**5. Review the findings**

AgentGuardian opens a live dashboard at `http://127.0.0.1:7474` — watch findings land in real time, browse transcripts and evidence, and export reports.

<p align="center">
  <a href="./docs/images/dashboard.png"><img src="./docs/images/dashboard.png" alt="AgentGuardian live findings dashboard" width="900"></a>
</p>

## Scan targets

### HTTP agent

```bash
agent-guardian scan \
  --endpoint http://localhost:8000/chat \
  --model gemini:gemini-3.5-flash \
  --mode smart
```

### System prompt

```bash
agent-guardian scan \
  --system-prompt ./prompts/customer-support-agent.txt \
  --model gemini:gemini-3.5-flash \
  --mode fast
```

### In-process Python agent

```bash
agent-guardian scan my_app.agent:agent \
  --model gemini:gemini-3.5-flash \
  --mode smart
```

Point AgentGuardian at any importable Python callable or agent object (`module:attr`) and it runs in-process — useful for pre-deploy and CI, with nothing to host.

## What AgentGuardian catches

AgentGuardian tests agentic risks that normal prompt scanners miss:

- Prompt injection and goal hijack
- Unsafe tool calls and tool chaining
- Privilege abuse
- RAG poisoning and indirect prompt injection
- Memory and context poisoning
- Sensitive data leakage
- Agent-to-agent manipulation
- Cascading failures
- Trust exploitation and unsafe outputs
- Goal drift and untraceable behavior

Every probe maps to OWASP Top 10 for Agentic Applications, MITRE ATLAS, and the CSA Agentic AI Red Teaming Guide — full per-ASI breakdown in the [framework-coverage-matrix](https://docs.agentguardian.io/reference/framework-coverage-matrix).

## Reports & evidence

Every scan writes a signed, verifiable evidence bundle to `~/.agentguardian/scans/<scan-id>/`:

| Artifact                 | What it is                                                |
| ------------------------ | --------------------------------------------------------- |
| `scan.json`              | Machine-readable findings, signed (HMAC-SHA256 + Ed25519) |
| `events.jsonl`           | The scan timeline                                         |
| `probe/`                 | Per-probe requests, responses, verdicts, and evidence     |
| `forensic_manifest.json` | Integrity manifest for the bundle                         |

Export in any format, any time:

```bash
agent-guardian report SCAN_ID --output pdf --output-path report.pdf
```

Formats: `json` · `sarif` · `junit` · `md` · `gitlab` · `pdf` — see the [sample report](./docs/_assets/sample-report.pdf). Verify stored evidence with `agent-guardian verify`.

## Scan modes

- `fast` — quick local feedback
- `smart` — broader coverage for development and pull requests
- `full` — release gates and audit evidence

Use `full` when you need AIVSS-scored findings for CI/CD gates.

## Commands

| Command                                   | What it does                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------ |
| `agent-guardian scan`                     | Run an adversarial swarm scan against a target                                       |
| `agent-guardian report <id> --output FMT` | Regenerate a report — `json` · `sarif` · `junit` · `md` · `gitlab` · `pdf` · `badge` |
| `agent-guardian gate <id> --fail-under N` | Apply pass/fail thresholds to a stored scan (CI exit codes)                          |
| `agent-guardian serve`                    | Start the local dashboard                                                            |
| `agent-guardian scans list` / `delete`    | List or delete stored scans (`delete --older-than 30d` for bulk cleanup)             |
| `agent-guardian config show` / `init`     | Inspect the effective config / scaffold a config file                                |
| `agent-guardian verify <report>`          | Verify the HMAC-SHA256 + Ed25519 signatures on a report                              |
| `agent-guardian last-score`               | Print the AIVSS of the most recent scan                                              |
| `agent-guardian doctor`                   | Verify the install, provider keys, and prerequisites                                 |
| `agent-guardian version`                  | Print the installed version                                                          |

Run any command with `--help`, or see the [CLI reference](https://docs.agentguardian.io/reference/cli).

## Run with Docker

```bash
docker build -t agent-guardian .

docker run --rm \
  -e GEMINI_API_KEY \
  -v "$HOME/.agentguardian:/root/.agentguardian" \
  -p 7474:7474 \
  agent-guardian scan \
    --endpoint https://agent-guardian-testbench-u6tm6gzysq-uc.a.run.app/finbot/chat \
    --model gemini:gemini-3.5-flash \
    --mode fast
```

## CI/CD with GitHub Actions

The shipped composite action runs a scan, uploads SARIF to GitHub Code Scanning, and (optionally) posts a summary comment on the pull request:

```yaml
name: AgentGuardian

on:
  pull_request:
  push:
    branches: [main]

jobs:
  red-team:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # upload SARIF to Code Scanning
      pull-requests: write     # post the summary comment
    steps:
      - uses: actions/checkout@v4

      - uses: glacien-technologies/agent-guardian/.github/actions/agentguardian-scan@v1
        with:
          endpoint: http://localhost:8000/chat
          model: gemini:gemini-3.5-flash
          mode: full
          fail-under: "80"
          max-critical: "0"
          comment: "true"
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
```

The job fails when the gate (`fail-under` / `max-critical`) is breached. For GitLab, Bitbucket, raw-CLI, and fleet/nightly setups, see the [CI/CD guides](https://docs.agentguardian.io/ci-cd/overview).

## Run from source

```bash
git clone https://github.com/glacien-technologies/agent-guardian.git
cd agent-guardian

python3.11 -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"

agent-guardian doctor
```

## Contributing

We welcome new probes, new adapters, and new attacker logic. Start with the [contribution guide](https://docs.agentguardian.io/community/contributing) 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 the [ethics policy](https://docs.agentguardian.io/community/ethics). AgentGuardian is for testing systems you own or are explicitly authorised to test.

## Community

Join us on [Discord](https://discord.gg/X6UFKYXdBJ) for quickstart help, probe design, adapter questions, and roadmap discussion.

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