Metadata-Version: 2.4
Name: agent-guardian
Version: 1.0.0rc13
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

<div align="center">

# 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)
<!-- OpenSSF Best Practices badge — PLACEHOLDER.
     Register the project at https://www.bestpractices.dev/ , then replace
     <ID> below with the issued numeric project id and uncomment the line.
     Criteria evidence is mapped in docs/security/openssf-badge-status.md. -->
<!-- [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/<ID>/badge)](https://www.bestpractices.dev/projects/<ID>) -->
[![Docs](https://img.shields.io/badge/docs-docs.agentguardian.io-1f6feb.svg)](https://docs.agentguardian.io)

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

</div>

---

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/swarm-diagrams/agentguardian-security-loop.jpg" alt="AgentGuardian recon, OWASP ASI probe generation, findings, reports, and fix-rerun loop" width="900">
</p>

<p align="center">▶ <b><a href="https://youtu.be/AD-CIIccklA">Watch the demo</a></b> to see how AgentGuardian finds vulnerabilities in a live scan.</p>

## Getting started

**1. Install**

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

or

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

**2. Configure a model provider**

AgentGuardian drives its attacks with an LLM. Export a key for your provider — Gemini, OpenAI, or Anthropic:

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

For every supported provider and the full set of configuration options, see the [configuration guide](https://docs.agentguardian.io/reference/config#provider-api-keys).

**3. Scan an agent**

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 \
  --output pdf --output-path report.pdf
```

To scan **your own** agent instead, swap `--endpoint` for any target — a hosted URL or a `--system-prompt` file (see [What you can scan](#what-you-can-scan)).

**4. Review the findings**

AgentGuardian opens a live dashboard while it runs (`http://127.0.0.1:7474`) and writes an evidence bundle — findings, transcripts, and your PDF report — under `~/.agentguardian/scans/<scan-id>/`.

## What you can scan

### Scan an HTTP agent

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

### Scan a system prompt

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

### Scan an in-process 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.

> **Roadmap — white-box agentic detection.** Today's scans are **black-box**: AgentGuardian drives the agent adversarially and detects compromise from what is observable (the response, returned data, and any tool calls the API exposes) across the full OWASP ASI taxonomy. Framework-native modes (LangGraph, CrewAI, AutoGen, OpenAI Agents, ADK, Strands) and OpenTelemetry trace correlation are in progress — they will read the agent's own tool/sub-agent traces to catch internal tool-misuse a clean reply can hide. Follow [#126](https://github.com/glacien-technologies/agent-guardian/issues/126).

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

## Reports and evidence

Every scan writes a local evidence bundle under `~/.agentguardian/scans/<scan-id>/`:

- `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
- a live local dashboard — browse findings, transcripts, and exports

Generate shareable or CI-ready reports in any format on demand:

```bash
agent-guardian report SCAN_ID --output sarif --output-path scan.sarif   # GitHub Security
agent-guardian report SCAN_ID --output md                                # Markdown
agent-guardian report SCAN_ID --output pdf  --output-path report.pdf      # shareable PDF
```

Formats: `json` · `sarif` · `junit` · `md` · `gitlab` · `pdf`. Stored evidence can be verified with `agent-guardian verify`.

## How it works

Every scan follows the same loop:

```text
Target → surface mapping → adversarial agents → AIVSS-scored findings → evidence bundle
```

For the full workflow, see [how AgentGuardian works](https://docs.agentguardian.io/concepts/target-adapters).

## 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 telemetry status` | Manage opt-in telemetry (`enable` / `disable`) |
| `agent-guardian version` | Print the installed version |

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

## 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) — including the [parallel suites guide](https://docs.agentguardian.io/ci-cd/parallel-suites) for scanning many agents from one file.

## Standards and coverage

AgentGuardian maps its shipped probes to:

- OWASP Top 10 for Agentic Applications
- MITRE ATLAS
- CSA Agentic AI Red Teaming Guide

The exact agents and probes that ran against your target are enumerated in every scan report (`coverage` in `scan.json`). The full probe-to-standard mapping lives in the [OWASP mapping](https://docs.agentguardian.io/reports/owasp-mapping) and the [framework coverage matrix](https://docs.agentguardian.io/reference/framework-coverage-matrix).

## Privacy & telemetry

**Telemetry is opt-in and disabled by default.** Out of the box AgentGuardian sends nothing — no analytics ping, no install ping, no scan counts. Telemetry only activates after you explicitly opt in. Once enabled, it sends anonymous operational counts (agents dispatched, attempts, findings) plus a locally generated, anonymous install id (a random UUID stored at `~/.agentguardian/install_id`, with no link to your identity).

Manage it any time:

```bash
agent-guardian telemetry status     # show current state
agent-guardian telemetry enable      # opt in
agent-guardian telemetry disable     # opt out
```

AgentGuardian never collects prompts, agent responses, target URLs, headers, secrets, API keys, transcripts, reports, evidence files, tool inputs or outputs, or customer data.

## Run from source

To run AgentGuardian from a source checkout instead of the published package:

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

# virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# install the checkout in editable mode
pip install -e ".[dev]"

# run it from source
agent-guardian doctor
agent-guardian scan \
  --endpoint http://localhost:8000/chat \
  --model gemini:gemini-3.5-flash \
  --mode fast
```

For contribution guidelines, see the [contribution guide](https://docs.agentguardian.io/community/contributing).

## 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/h4FRgxvr) for quickstart help, probe design, adapter questions, and roadmap discussion. For longer-form support channels, see the [support guide](https://docs.agentguardian.io/community/support).

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