> For the complete documentation index, see [llms.txt](https://docs.offensive-ai.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.offensive-ai.org/intro.md).

# What is offensive-ai?

**offensive-ai** is an offensive-security toolkit for authorized red-team engagements. It is a Python library and CLI that combines classic network reconnaissance with modern AI/LLM security testing.

It probes live AI/LLM endpoints for the [OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/), scans and actively attacks [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers for known CVEs, and performs full-stack infrastructure security assessments — all from a single `pip install`.

> **Legal Notice**: Active attack features require the `--i-have-authorization` flag. Only use against systems you own or have explicit written permission to test.

***

## Capability Overview

| Domain                      | What it covers                                                                                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **AI / LLM Security**       | OWASP LLM Top 10 probing, MCP protocol CVEs, A2A agent card analysis, Postman collection fuzzing, OpenClaw gateway attacks                                                                             |
| **Infrastructure Security** | Kubernetes cluster assessment (OWASP K8s Top 10), Auth protocol scanning (OIDC / OAuth 2.0 / SAML), Hybrid Identity / ADFS endpoint discovery, mTLS, certificates, security headers, WAF/CDN detection |
| **Agentic REPL**            | Natural-language interactive shell (`offensive-ai agent`) — an LLM picks and calls the right scanner/attacker tool via native tool-calling, no framework dependency                                    |
| **Reporting**               | PDF, JSON, CSV export with tech-specific remediation advice (Nginx, Apache, IIS, Cloudflare)                                                                                                           |
| **LLM Judge**               | Optional AI-powered triage via Gemini, Anthropic, or OpenAI — enriches findings and generates exploit-chain summaries                                                                                  |

***

## Installation

```bash
# Core toolkit
pip install offensive-ai

# With optional LLM judge (Gemini / Anthropic / OpenAI)
pip install "offensive-ai[ai]"
```

**Requirements**: Python 3.10+

***

## Key Design Principles

* **Authorization-first** — every attacker class raises `AuthorizationRequired` synchronously before any network I/O if `authorized=True` is not passed explicitly.
* **Async throughout** — all scanners and attackers are `async`; use `asyncio.run()` or an existing event loop.
* **LLM provider priority** — Gemini → Anthropic → OpenAI (first key found in environment wins).
* **Rule-based fallback** — all modules work without an LLM API key; the judge is always optional.

***

## Modules at a Glance

| Module                    | CLI command        | Python class              |
| ------------------------- | ------------------ | ------------------------- |
| OWASP LLM Scanner         | `owasp-scan`       | `LLMOwaspScanner`         |
| MCP Scanner               | `mcp-scan`         | `MCPScanner`              |
| MCP Attacker              | `mcp-attack`       | `MCPAttacker`             |
| A2A Scanner               | `a2a-scan`         | `A2AScanner`              |
| A2A Attacker              | `a2a-attack`       | `A2AAttacker`             |
| Postman Scanner           | `postman-scan`     | `PostmanScanner`          |
| Postman Attacker          | `postman-attack`   | `PostmanAttacker`         |
| OpenClaw Scanner          | `openclaw-scan`    | `OpenClawScanner`         |
| OpenClaw Attacker         | `openclaw-attack`  | `OpenClawAttacker`        |
| Kubernetes Scanner        | `k8s-scan`         | `K8sScanner`              |
| Kubernetes Attacker       | `k8s-attack`       | `K8sAttacker`             |
| Auth Protocol Scanner     | `auth-scan`        | `AuthScanner`             |
| Auth Attacker             | `auth-attack`      | `AuthAttacker`            |
| Hybrid Identity Checker   | `hybrid-identity`  | `HybridIdentityChecker`   |
| OWASP Web Scanner         | `owasp-web-scan`   | `OwaspScanner`            |
| Port Scanner              | `port-scan`        | `PortChecker`             |
| Certificate Analyzer      | `cert-analyze`     | `CertificateAnalyzer`     |
| mTLS Checker              | `mtls-check`       | `MTLSChecker`             |
| Security Headers          | `security-headers` | `SecurityHeaderChecker`   |
| L7 Detector               | `l7-detect`        | `L7Detector`              |
| LLM Judge                 | —                  | `LLMJudge`                |
| Guardrail Bench           | `guardrail-bench`  | `GuardrailBench`          |
| LLM Conversation Attacker | `llm-attack`       | `LLMConversationAttacker` |
| Agentic REPL              | `agent`            | `AgentSession`            |

See the [Python API Reference](/api.md) for full typed signatures, parameter tables, and return types. See the [Agentic REPL](/agentic-automation/agent.md) page for the natural-language interactive shell.

***

## Links

* **PyPI**: [pypi.org/project/offensive-ai](https://pypi.org/project/offensive-ai/)
* **GitHub**: [github.com/Htunn/offensive-ai](https://github.com/Htunn/offensive-ai)
* **Docker**: [hub.docker.com/r/htunnthuthu/offensive-ai](https://hub.docker.com/r/htunnthuthu/offensive-ai)
* **Docs**: [docs.offensive-ai.org](https://docs.offensive-ai.org)