Metadata-Version: 2.4
Name: arca-agent
Version: 1.9.6
Summary: ARCA — Recursive GNN+RL Autonomous Cyber Agent with Local LLM reflection
Home-page: https://github.com/DipayanDasgupta/arca
Author: Dipayan Dasgupta
Author-email: Dipayan Dasgupta <deep.dasgupta2006@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/DipayanDasgupta/arca
Project-URL: Repository, https://github.com/DipayanDasgupta/arca
Keywords: reinforcement-learning,cybersecurity,pentesting,langgraph,agentic-ai,graph-neural-network,pybind11,autonomous-agent,local-llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: gymnasium>=1.0
Requires-Dist: networkx>=3.3
Requires-Dist: torch>=2.3.0
Requires-Dist: torch-geometric>=2.5.0
Requires-Dist: langgraph>=0.2
Requires-Dist: langchain-core>=0.3
Requires-Dist: langchain>=0.3
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Requires-Dist: matplotlib>=3.8
Requires-Dist: plotly>=5.20
Requires-Dist: pandas>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tensorboard>=2.17
Requires-Dist: httpx>=0.27
Requires-Dist: ollama>=0.2
Provides-Extra: gpu
Requires-Dist: stable-baselines3>=2.3; extra == "gpu"
Provides-Extra: sb3
Requires-Dist: stable-baselines3>=2.3; extra == "sb3"
Provides-Extra: cpp
Requires-Dist: pybind11>=2.11; extra == "cpp"
Provides-Extra: viz
Requires-Dist: dash>=2.16; extra == "viz"
Requires-Dist: dash-bootstrap-components>=1.5; extra == "viz"
Provides-Extra: live
Requires-Dist: python-nmap>=0.7; extra == "live"
Requires-Dist: paramiko>=3.0; extra == "live"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: wandb
Requires-Dist: wandb>=0.15; extra == "wandb"
Provides-Extra: tune
Requires-Dist: optuna>=3.0; extra == "tune"
Provides-Extra: pdf
Requires-Dist: weasyprint>=60; extra == "pdf"
Provides-Extra: otel
Requires-Dist: opentelemetry-api; extra == "otel"
Requires-Dist: opentelemetry-sdk; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-fastapi; extra == "otel"
Provides-Extra: tui
Requires-Dist: textual>=0.40; extra == "tui"
Provides-Extra: llm-local
Requires-Dist: llama-cpp-python>=0.3.0; extra == "llm-local"
Provides-Extra: all
Requires-Dist: stable-baselines3>=2.3; extra == "all"
Requires-Dist: pybind11>=2.11; extra == "all"
Requires-Dist: dash>=2.16; extra == "all"
Requires-Dist: dash-bootstrap-components>=1.5; extra == "all"
Requires-Dist: groq>=0.5; extra == "all"
Requires-Dist: python-nmap>=0.7; extra == "all"
Requires-Dist: paramiko>=3.0; extra == "all"
Requires-Dist: weasyprint>=60; extra == "all"
Requires-Dist: textual>=0.40; extra == "all"
Requires-Dist: optuna>=3.0; extra == "all"
Dynamic: author
Dynamic: classifier
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<div align="center">

<img src="logo.png" alt="ARCA logo" width="260">

# ARCA — Autonomous Reinforcement Cyber Agent

**Public Demo — RL-powered network attack simulation with real CVEs, local & Kaggle GPU execution.**

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.9.5-blue.svg)](arca/__version__.py)
[![PyPI](https://img.shields.io/pypi/v/arca-agent.svg)](https://pypi.org/project/arca-agent/)

**Live Demo:** [https://arca.dpdns.org](https://arca.dpdns.org) — sign in with Google, no waitlist.

</div>

ARCA trains reinforcement-learning agents to find attack paths through simulated networks. It uses real CVEs from a 79-entry database, supports both local CPU and Kaggle GPU backends, and exports results as PDF/JSON/SARIF/STIX reports. The agent learns by trial and error — exactly how a real attacker would — and shows the exact chain of exploits it would use.

---

## Quick Start

```bash
pip install arca-agent
arca serve              # starts API at http://localhost:8000
```

Or run the full web app with the Next.js frontend:

```bash
git clone https://github.com/DipayanDasgupta/arca.git
cd arca/frontend && npm install && npm run dev  # frontend at :3000
cd arca && pip install -e ".[dev]" && arca serve  # backend at :8000
```

---

## Features

| Feature | Status |
|---------|--------|
| 5 built-in network presets (micro → enterprise, 4–25 hosts) | Stable |
| Custom YAML network upload | Stable |
| PPO RL training with GNN policy (CleanRL) | Stable |
| Structured attack traces with real CVEs (79 in database) | Stable |
| Local CPU execution | Stable |
| Kaggle GPU offload (push/poll/retrieve) | Stable |
| Per-user Kaggle credential upload | Stable |
| Canonical SimulationResult schema (shared Local/Kaggle) | Stable |
| 10-stage job state machine with timeout detection | Stable |
| PDF / JSON / SARIF 2.1 / STIX 2.1 report export | Stable |
| Interactive Plotly network topology + vulnerability heatmap | Stable |
| CVE database browser (search, filter by OS/severity) | Stable |
| Security audit with LLM reflection (Groq/Ollama) | Stable |
| Attack graph visualization (host→host chain with CVE table) | Stable |
| Cancel training button | Stable |
| Light/dark mode | Stable |
| Training modes (Curriculum, Self-Play, Offline RL) | UI ready, backend partial |
| Live network scanning (nmap + fingerprint) | Backend ready, UI deferred |
| MITRE ATT&CK + CTEM compliance reporting | Backend ready, UI deferred |

---

## Architecture

```
┌─────────────────────────────────────────────────┐
│                  Frontend (Next.js 16)            │
│  9 dashboard pages · Tailwind · ReactFlow ·     │
│  Plotly · Framer Motion · NextAuth (Google)     │
├─────────────────────────────────────────────────┤
│               API Proxy (Next.js)                 │
│        → FastAPI Backend (Uvicorn :8000)         │
├─────────────────────────────────────────────────┤
│                ARCA Core (Python)                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ ARCA Agent│ │ Network  │ │ Training Module   │ │
│  │ (GNN+PPO) │ │  Env     │ │ (Curriculum, SP,  │ │
│  │           │ │ (Gym)    │ │  Offline RL, BT)  │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ CVE DB v5│ │ Reporting│ │ Live Scanner     │ │
│  │ (79 CVEs)│ │ (4 formats)│ │ (nmap, SSH)     │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
├─────────────────────────────────────────────────┤
│          Execution Backends                      │
│     Local CPU (in-process) · Kaggle GPU (push)  │
├─────────────────────────────────────────────────┤
│              Storage                             │
│     SQLite (frontend) · In-memory (backend)     │
└─────────────────────────────────────────────────┘
```

---

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/train` | Start async training (local or kaggle) |
| GET | `/train/status/{id}` | Poll job status with stage/error tracking |
| POST | `/train/cancel` | Cancel in-progress training |
| GET | `/presets` | List built-in network presets |
| GET | `/presets/{name}` | Get preset details (hosts, subnets, etc.) |
| GET | `/cves` | Paginated CVE database with OS/severity filters |
| POST | `/visualizations/topology` | Network topology graph (Plotly JSON) |
| POST | `/visualizations/vulnerability-heatmap` | Host vulnerability heatmap |
| POST | `/audit` | Run security audit episode |
| POST | `/reflect` | LLM reflection on network state |
| POST | `/reports/pdf` | Generate PDF security report |
| WS | `/ws/training` | WebSocket training progress stream |
