Metadata-Version: 2.4
Name: shadowcat-agent
Version: 2.0.0
Summary: AI-powered autonomous web security scanner with real-time streaming — enterprise DAST platform
Project-URL: Homepage, https://github.com/shadowcat-dast/shadowcat
Project-URL: Repository, https://github.com/shadowcat-dast/shadowcat
Author: ShadowCat Team
License: MIT
License-File: LICENSE.md
Keywords: agent,ai-scanner,cybersecurity,dast,openrouter,pentest,vulnerability-detection,web-security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: <4.0,>=3.12
Requires-Dist: anthropic>=0.40.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: claude-agent-sdk>=0.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.27
Requires-Dist: langfuse>=2.0.0
Requires-Dist: lxml>=5.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.30
Requires-Dist: textual>=0.47.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: headless
Requires-Dist: playwright>=1.60.0; extra == 'headless'
Description-Content-Type: text/markdown

<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
<a name="readme-top"></a>

<!-- PROJECT SHIELDS -->
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![Discord][discord-shield]][discord-url]

<!-- PROJECT LOGO -->
<br />
<div align="center">

<h3 align="center">ShadowCat</h3>

  <p align="center">
    AI-Powered Autonomous Penetration Testing Agent
    <br />
    <strong>National Software Contest 2026 (NSC2026) Entry</strong>
    <br />
    <br />
    <a href="https://shadowcat.com"><strong>Official Website: shadowcat.com »</strong></a>
    <br />
    <br />
    <a href="https://github.com/shadowcat-dast/ShadowCat/issues">Report Bug</a>
    ·
    <a href="https://github.com/shadowcat-dast/ShadowCat/issues">Request Feature</a>
  </p>
</div>

<!-- ABOUT THE PROJECT -->

---

## 🇹🇭 NSC2026 Competition Entry — SecureThai

> **National Software Contest 2026 (NSC2026) submission.**
> An **enterprise-grade, AI-driven DAST platform** that autonomously tests web
> applications for OWASP Top 10 vulnerabilities and **proves every finding with
> deterministic, evidence-grounded verification** — the agent gathers HTTP
> evidence; a separate oracle renders the verdict. No hallucinated findings.

### What makes it competitive

| Capability | Where |
|---|---|
| Autonomous ReAct agent (mode-agnostic, safety-gated tool dispatch) | [`backend/core/orchestrator.py`](backend/core/orchestrator.py) |
| Evidence-grounded verification (agent collects, oracle judges) | [`backend/verification/`](backend/verification/) |
| Concurrent authenticated spider + JS API & subdomain discovery | [`backend/crawler/`](backend/crawler/) |
| WAF fingerprinting + payload evasion | [`backend/waf/`](backend/waf/) |
| Real-time scan streaming (SSE) to the SecureThai dashboard | [`backend/api/routes_scan.py`](backend/api/routes_scan.py) |
| Self-contained HTML/PDF report generation | [`backend/reporting/`](backend/reporting/) |
| Thai PDPA compliance mapping | [`backend/compliance/`](backend/compliance/) |
| Multi-gateway LLM (PSU Blue `sk-user-…` / OpenRouter `sk-or-…`, auto-routed) | [`backend/core/llm_client.py`](backend/core/llm_client.py) |

### Run the competition entry

```bash
# 1. Backend (FastAPI + SSE) — from the repo root
cp .env.example .env          # set OPENROUTER_API_KEY (PSU Blue sk-user-… or OpenRouter sk-or-…)
uv sync
uv run uvicorn backend.api.routes_scan:app --port 8000

# 2. Frontend (SecureThai dashboard) — separate Next.js repo
#    npm install && npm run dev   →   http://localhost:3000
```

### Documentation

- **Architecture & design source of truth:** [`docs/ENTERPRISE_ARCH.md`](docs/ENTERPRISE_ARCH.md)
- **Backend module guide:** [`backend/README.md`](backend/README.md)
- **Build progress / changelog:** [`docs/PROGRESS.md`](docs/PROGRESS.md)

### Repository map

```
backend/      NSC2026 entry — enterprise AI DAST (FastAPI + SSE)
agent/        Agentic TUI package (CTF/HTB) — `shadowcat-agent` CLI
docs/         Architecture, progress notes, demo media
tests/        Test suite
scripts/      Container + helper scripts
archive/      Superseded code (old api/ DAG-RAG attempt, legacy v0.15)
benchmark/    XBOW validation benchmarks (submodule)
```

---

## Demo

### Installation
[![Installation Demo](https://asciinema.org/a/761661.svg)](https://asciinema.org/a/761661)

[Watch on YouTube](https://www.youtube.com/watch?v=RUNmoXqBwVg)

### ShadowCat in Action
[![ShadowCat Demo](https://asciinema.org/a/761663.svg)](https://asciinema.org/a/761663)

[Watch on YouTube](https://www.youtube.com/watch?v=cWi3Yb7RmZA)

---

## What's New in v1.0 (Agentic Upgrade)

- **Autonomous Agent** - Agentic pipeline for intelligent, autonomous penetration testing
- **Session Persistence** - Save and resume penetration testing sessions
- **Docker-First** - Isolated, reproducible environment with security tools pre-installed

> **In Progress**: Multi-model support for OpenAI, Gemini, and other LLM providers

---

## Features

- **AI-Powered Challenge Solver** - Leverages LLM advanced reasoning to perform penetration testing and CTFs
- **Live Walkthrough** - Tracks steps in real-time as the agent works through challenges
- **Multi-Category Support** - Web, Crypto, Reversing, Forensics, PWN, Privilege Escalation
- **Real-Time Feedback** - Watch the AI work with live activity updates
- **Extensible Architecture** - Clean, modular design ready for future enhancements

---

## Quick Start

### Prerequisites

- **Docker** (required) - [Install Docker](https://docs.docker.com/get-docker/)
- **LLM Provider** (choose one):
  - Anthropic API Key from [console.anthropic.com](https://console.anthropic.com/)
  - Claude OAuth Login (requires Claude subscription)
  - OpenRouter for alternative models at [openrouter.ai](https://openrouter.ai/keys)
  - [Tutorial: Using Local Models with Claude Code](https://docs.google.com/document/d/1ixK7x-wlr5t5TYZJdfm75UME5KnPCpS46boLkUXKg1w/edit?usp=sharing)


### Installation

```bash
# Clone and build
git clone --recurse-submodules https://github.com/shadowcat-dast/ShadowCat.git
cd ShadowCat
make install

# Configure authentication (first time only)
make config

# Connect to container
make connect
```

> **Note**: The `--recurse-submodules` flag downloads the benchmark suite. If you already cloned without it, run: `git submodule update --init --recursive`

### Try a Benchmark

```bash
cd benchmark/standalone-xbow-benchmark-runner
python3 run_benchmarks.py --range 1-1 --pattern-flag
```

See [Benchmark Documentation](benchmark/README.md) for detailed usage.

### Commands Reference

| Command | Description |
|---------|-------------|
| `make install` | Build the Docker image |
| `make config` | Configure API key (first-time setup) |
| `make connect` | Connect to container (main entry point) |
| `make stop` | Stop container (config persists) |
| `make clean-docker` | Remove everything including config |


---

## Usage

```bash
# Interactive TUI mode (default)
shadowcat --target 10.10.11.234

# Non-interactive mode
shadowcat --target 10.10.11.100 --non-interactive

# With challenge context
shadowcat --target 10.10.11.50 --instruction "WordPress site, focus on plugin vulnerabilities"
```

**Keyboard Shortcuts:** `F1` Help | `Ctrl+P` Pause/Resume | `Ctrl+Q` Quit

---

## Using Local LLMs

ShadowCat supports routing requests to local LLM servers (LM Studio, Ollama, text-generation-webui, etc.) running on your host machine.

### Prerequisites

- Local LLM server with an OpenAI-compatible API endpoint
  - **LM Studio**: Enable server mode (default port 1234)
  - **Ollama**: Run `ollama serve` (default port 11434)

### Setup

```bash
# Configure ShadowCat for local LLM
make config
# Select option 4: Local LLM

# Start your local LLM server on the host machine
# Then connect to the container
make connect
```

### Customizing Models

Edit `scripts/ccr-config-template.json` to customize:

- **`localLLM.api_base_url`**: Your LLM server URL (default: `host.docker.internal:1234`)
- **`localLLM.models`**: Available model names on your server
- **Router section**: Which models handle which operations

| Route | Purpose | Default Model |
|-------|---------|---------------|
| `default` | General tasks | openai/gpt-oss-20b |
| `background` | Background operations | openai/gpt-oss-20b |
| `think` | Reasoning-heavy tasks | qwen/qwen3-coder-30b |
| `longContext` | Large context handling | qwen/qwen3-coder-30b |
| `webSearch` | Web search operations | openai/gpt-oss-20b |

### Troubleshooting

- **Connection refused**: Ensure your LLM server is running and listening on the configured port
- **Docker networking**: Use `host.docker.internal` (not `localhost`) to access host services from Docker
- **Check CCR logs**: Inside the container, run `cat /tmp/ccr.log`

---

## Telemetry

ShadowCat collects anonymous usage data to help improve the tool. This data is sent to our [Langfuse](https://langfuse.com) project and includes:
- Session metadata (target type, duration, completion status)
- Tool execution patterns (which tools are used, not the actual commands)
- Flag detection events (that a flag was found, not the flag content)

**No sensitive data is collected** - command outputs, credentials, or actual flag values are never transmitted.

### Opting Out

```bash
# Via command line flag
shadowcat --target 10.10.11.234 --no-telemetry

# Via environment variable
export LANGFUSE_ENABLED=false
```

---

## Benchmarks

ShadowCat includes 104 XBOW validation benchmarks for comprehensive testing and evaluation.

```bash
cd benchmark/standalone-xbow-benchmark-runner

python3 run_benchmarks.py --range 1-10 --pattern-flag   # Run benchmarks 1-10
python3 run_benchmarks.py --all --pattern-flag          # Run all 104 benchmarks
python3 run_benchmarks.py --retry-failed                # Retry failed benchmarks
python3 run_benchmarks.py --dry-run --range 1-5         # Preview without executing
```

### Performance Highlights

ShadowCat achieved an **86.5% success rate** (90/104 benchmarks) on the XBOW validation suite:

- **Cost**: Average $1.11, Median $0.42 per successful benchmark
- **Time**: Average 6.1 minutes, Median 3.3 minutes per successful benchmark
- **Success rates by difficulty**:
  - Level 1: 91.1%
  - Level 2: 74.5%
  - Level 3: 62.5%

For detailed benchmark results, analysis, and automated testing instructions, see the **[Benchmark Documentation](benchmark/README.md)**.

---

## Legacy Version

The previous multi-LLM version (v0.15) supporting OpenAI, Gemini, Deepseek, and Ollama is archived in [`legacy/`](legacy/):

```bash
cd legacy && pip install -e . && shadowcat --reasoning gpt-4o
```

---

## License

Distributed under the MIT License. See `LICENSE.md` for more information.

**Disclaimer**: This tool is for educational purposes and authorized security testing only. The authors do not condone any illegal use. Use at your own risk.

---

## Acknowledgments

- Developed by the ShadowCat Team for the National Software Contest 2026 (NSC2026).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- MARKDOWN LINKS & IMAGES -->
[contributors-shield]: https://img.shields.io/github/contributors/shadowcat-dast/ShadowCat.svg?style=for-the-badge
[contributors-url]: https://github.com/shadowcat-dast/ShadowCat/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/shadowcat-dast/ShadowCat.svg?style=for-the-badge
[forks-url]: https://github.com/shadowcat-dast/ShadowCat/network/members
[stars-shield]: https://img.shields.io/github/stars/shadowcat-dast/ShadowCat.svg?style=for-the-badge
[stars-url]: https://github.com/shadowcat-dast/ShadowCat/stargazers
[issues-shield]: https://img.shields.io/github/issues/shadowcat-dast/ShadowCat.svg?style=for-the-badge
[issues-url]: https://github.com/shadowcat-dast/ShadowCat/issues
[license-shield]: https://img.shields.io/github/license/shadowcat-dast/ShadowCat.svg?style=for-the-badge
[license-url]: https://github.com/shadowcat-dast/ShadowCat/blob/master/LICENSE.md
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
