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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.offensive-ai.org/intro.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.