Metadata-Version: 2.4
Name: cyberai
Version: 1.0.0
Summary: CyberAI — AI-native multi-agent pentest platform
Project-URL: Homepage, https://github.com/evkir/CyberAI
Project-URL: Repository, https://github.com/evkir/CyberAI
Project-URL: Issues, https://github.com/evkir/CyberAI/issues
Author: evkir
License-Expression: MIT
License-File: LICENSE
Keywords: ai,multi-agent,offensive-security,pentest,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: anthropic<1,>=0.28.0
Requires-Dist: click<9,>=8.1.7
Requires-Dist: colorama<1,>=0.4.6
Requires-Dist: dnspython<3,>=2.6.1
Requires-Dist: fastapi<1,>=0.110
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: jinja2<4,>=3.1.2
Requires-Dist: mcp<2,>=1.0
Requires-Dist: networkx<4,>=3.2.1
Requires-Dist: openai<3,>=2.0
Requires-Dist: pydantic<3,>=2.7.0
Requires-Dist: python-dotenv<2,>=1.0.0
Requires-Dist: python-whois<1,>=0.9.4
Requires-Dist: requests<3,>=2.31.0
Requires-Dist: rich<14,>=13.7.0
Requires-Dist: uvicorn<1,>=0.29
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest>=7.4.3; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">

![CI](https://github.com/evkir/CyberAI/actions/workflows/ci.yml/badge.svg)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-v0.5.0-orange)
![LLM](https://img.shields.io/badge/LLM-OpenAI%20%7C%20Anthropic-blueviolet)

# 🤖 CyberAI

**OOB-driven, agent-trust-aware AI pentest platform**

> Built by someone who red-teams AI, not just with it.

</div>

---

## What is CyberAI?

CyberAI is a multi-agent orchestration layer for offensive security. Five
specialized agents — **Recon, Intel, Exploit, Report, Web3** — run a typed,
auditable pipeline that turns a target into actionable attack paths and a
validated report.

Two things set it apart from "LLM wrapper over nmap":

- **OOB-driven exploitation.** Blind vulns (SSRF, XXE, blind injection) are
  confirmed through out-of-band callbacks captured by
  [phantom-grid](https://github.com/evkir/phantom-grid), not guessed from
  response diffs.
- **Agent-trust-aware design.** Every banner and tool output is treated as
  untrusted input: sanitized, injection-scanned, and parsed before it ever
  reaches the LLM context. Adversarial thinking is a design input, not a
  disclaimer.

Reach beyond the network: the **Web3 agent** runs Slither static analysis and
maps detectors to Immunefi severity tiers for smart-contract audits.

---

## Architecture                                                                            +------------------+                                                                       target -----------> |   Orchestrator   |  typed pipeline, dry-run, budget

+--------+---------+  injection-scan at phase boundaries

|

+-----------+----------+-----------+------------+

v           v          v           v            v

+------+   +------+   +--------+  +--------+   +------+

|Recon |-->|Intel |-->|Exploit |->|Report  |   | Web3 | (standalone)

+------+   +------+   +---+----+  +--------+   +--+---+

DNS       NVD/CVE     OOB |  PoC  judge         | Slither

nmap      EPSS        nuclei H1-export          | Immunefi

subdom    prioritize      |                     | severity

v

+-------------+

| phantom-grid|  OOB callback capture

+-------------+
Observability:  SQLite audit log . session export/import . cyberai replay

Interfaces:     CLI . FastAPI dashboard (SSE) . MCP server (Claude Desktop)                ### Agents

| Agent | Input | Output | Key tools |
|-------|-------|--------|-----------|
| **Recon** | target | open ports, DNS, WHOIS, subdomains | nmap (flag-whitelisted), async DNS, subdomain enum |
| **Intel** | recon kb | ranked CVEs | NVD client, EPSS enrichment, risk prioritizer |
| **Exploit** | intel kb | attack paths, OOB findings | nuclei, searchsploit, OOB/SSRF/XXE workflows |
| **Report** | session kb | structured Markdown / H1 export | LLM summary + LLM-as-judge validation |
| **Web3** | .sol path / address | severity-tiered findings | Slither, Etherscan, Immunefi classifier |

---

## Security design

- **Agent trust boundaries** — each agent runs with minimal permissions.
- **Untrusted input handling** — banners sanitized, length-capped, marked
  `UNTRUSTED` before LLM context.
- **Prompt-injection detection** — 33-pattern detector at every phase boundary;
  hits become MEDIUM findings, visible in the report.
- **Scope enforcement** — wildcard + `!`-exclusion matching honors HackerOne /
  Bugcrowd briefs (`cyberai scope import`).
- **Audit trail** — every agent action logged (JSONL or SQLite) with full
  inputs/outputs; sessions are replayable.

---

## Quick start

```bash
git clone https://github.com/evkir/CyberAI.git
cd CyberAI
pip install -e .
```

```bash
cp config.example.yml config.yml
cp .env.example .env
# Edit .env — add OPENAI_API_KEY or ANTHROPIC_API_KEY (not needed for --dry-run)
```

```bash
# Dry-run: walks all 4 phases, no network, no API key
python -m cyberai scan example.com --dry-run

# Real scan, scope-restricted
python -m cyberai scan target.htb --scope '*.target.htb'

# Replay a saved session deterministically
python -m cyberai replay <session_id>

# Import a bug-bounty scope
python -m cyberai scope import h1 --program acme

# Status / config
python -m cyberai status
```

### Web dashboard

```bash
uvicorn cyberai.web.app:app --reload
# http://127.0.0.1:8000  — session list, live SSE progress, report view
```

### MCP server (Claude Desktop / Cursor)

```bash
python -m cyberai.mcp.server
```

Exposes recon/intel tools (`nmap_scan`, `dns_enum`, `cve_search`,
`epss_score`, …) over the Model Context Protocol. See
[docs/mcp/integration.md](docs/mcp/integration.md).

---

## Configuration

```yaml
# config.yml
llm:
  provider: openai        # openai | anthropic
  model: gpt-4o
  max_tokens: 4096
  temperature: 0.2

phantom:
  grid_url: http://127.0.0.1:9090

output_dir: reports/
max_cost_usd: 0.0         # 0 = disabled; set to enforce a budget
```

Optional feature flags (default off, no-regression):
`use_native_tools`, `use_nuclei`, `use_llm_summary`, `use_judge`.

---

## Documentation

| Doc | What |
|-----|------|
| [docs/api/agents.md](docs/api/agents.md) | Agent API reference |
| [docs/exploit/oob-exploitation-workflow.md](docs/exploit/oob-exploitation-workflow.md) | OOB / SSRF walkthrough |
| [docs/web3/web3-audit.md](docs/web3/web3-audit.md) | Smart-contract audit for Immunefi |
| [docs/mcp/integration.md](docs/mcp/integration.md) | MCP server setup |

---

## Related tools

| Tool | Role |
|------|------|
| [phantom-grid](https://github.com/evkir/phantom-grid) | OOB interaction capture |
| [phantom-intel](https://github.com/evkir/phantom-intel) | CVE intelligence feed |
| [reality-probe](https://github.com/evkir/reality-probe) | TLS analysis & config auditing |

---

## Requirements

- Python 3.11+
- OpenAI **or** Anthropic API key (not required for `--dry-run`)
- Optional: phantom-grid (OOB), nuclei, slither, NVD API key

---

## License

MIT — see [LICENSE](LICENSE)

<div align="center">
<sub>Part of the <a href="https://github.com/evkir">evkir</a> security toolchain.</sub>
</div>
