Metadata-Version: 2.4
Name: arca-agent
Version: 0.5.0
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: llama-cpp-python>=0.3.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: 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: 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"
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 — local, synthetic & live network security simulation.**

[![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-0.5.0-blue.svg)](arca/__version__.py)

</div>

ARCA trains and evaluates reinforcement-learning agents against simulated and real computer networks. It supports generated presets, YAML-defined networks, live scanning via nmap, Plotly + Dash visualization, local LLM reflection, and a production-grade FastAPI REST server. Intended for authorized education, research, and defensive simulation only.

---

## Quickstart

```bash
pip install arca-agent[all]
arca init-network --output my_net.yaml --preset office
arca simulate my_net.yaml --mode audit --visualize
arca dashboard --network my_net.yaml
```

## Documentation

| Document | Content |
|----------|---------|
| [Manual](docs/MANUAL.md) | Full user manual — installation, training, auditing, live scanning, API, dashboard, reports |
| [Glossary](docs/GLOSSARY.md) | Comprehensive terminology reference |
| [CLI Reference](docs/cli.md) | All CLI commands with flags and examples |

---

## Install

```bash
pip install arca-agent
pip install "arca-agent[all]"    # Dash, optional C++ extension, SB3, Groq

# From source
git clone https://github.com/DipayanDasgupta/arca.git
cd arca
pip install -e ".[dev,all]"
```

## CLI

Run `arca --help` for the full command reference.

| Command | Purpose |
|---------|---------|
| `arca simulate NETWORK.yaml` | Train, audit, or interact with a custom simulated network |
| `arca train` | Train on a built-in preset or YAML network |
| `arca audit` | Run an evaluation episode and return an audit report |
| `arca live-audit CIDR` | **NEW** Run a live network audit with nmap + fingerprinting + CVE correlation |
| `arca dashboard` | Launch the interactive Dash operations console |
| `arca serve` | Start the FastAPI REST server with OpenAPI docs |
| `arca viz` | Export topology and vulnerability heatmap as HTML |
| `arca init-network` | Generate a YAML network template or run the interactive builder |
| `arca show-cves` | List CVE definitions and reusable vulnerability templates |
| `arca models` | **NEW** Manage saved models (list, save, load, delete) |
| `arca config` | **NEW** Manage ARCA configuration (show, set, init) |
| `arca replay` | **NEW** Replay saved episodes step by step |
| `arca repl` | **NEW** Open interactive Python shell with ARCA pre-loaded |
| `arca scan` | Scan LAN for reachable Ollama endpoints |
| `arca info` | Print version, PyTorch, CUDA, C++ extension status |
| `arca health` | Check LLM provider connectivity |

### Examples

```bash
# Create a network and simulate
arca init-network --output home.yaml --preset home
arca simulate home.yaml --mode audit --langgraph --visualize

# Train and save a model
arca train --preset enterprise --timesteps 100000 --save models/agent

# Audit with pre-trained model
arca audit --network home.yaml --model models/agent.zip --langgraph

# Live network audit
arca live-audit 192.168.1.0/24 --fingerprints --nessus
arca live-audit 192.168.1.0/24 --dry-run  # discovery only, safe preview

# Manage models
arca models list
arca models save production-agent

# Interactive dashboard
arca dashboard --network home.yaml

# Start API
arca serve --port 8000

# Replay an episode
arca replay latest

# Interactive Python shell
arca repl

# Manage config
arca config show
```

## Python API

```python
from arca import ARCAAgent, NetworkEnv, ARCAConfig

# Load a network and train
env = NetworkEnv.from_yaml("my_network.yaml")
agent = ARCAAgent(env=env)
agent.train(timesteps=50_000)

# Run an audit
ep = agent.run_episode()
print(ep.summary())

# Generate a report
from arca.reporting import ARCAReportGenerator
gen = ARCAReportGenerator()
gen.add_episode_buffer(agent.memory_buffer)
gen.save_html()
```

## REST API

```bash
arca serve
# Docs at http://127.0.0.1:8000/docs
```

Key endpoints: `GET /healthz`, `GET /readyz`, `POST /train` (async), `POST /train/cancel`, `POST /audit`, `POST /reflect`, `POST /visualizations/topology`, `POST /visualizations/vulnerability-heatmap`, `POST /live/audit`, `GET /cves`, `GET /cves/templates`, `GET /presets/{name}`, `GET /live/sessions`.

Production configuration via env vars: `ARCA_API_KEY`, `ARCA_CORS_ORIGINS`, `ARCA_RATE_LIMIT`.

## Project layout

```
arca/               Python package
  core/             Agent, configuration, PPO trainer, GNN policy
  sim/              Gymnasium simulation, YAML network builder, episode tracking
  memory/           Persistent episode buffer, vector memory (RAG)
  agents/           LangGraph multi-agent orchestrator
  graph/            LLM red-team audit workflow
  llm/              Local LLM, Ollama, Groq, OpenAI providers
  training/         Curriculum scheduler, self-play evaluator, offline RL
  api/              FastAPI server (async, rate-limited, auth)
  cli/              Typer commands
  viz/              Plotly figures, Dash dashboard
  reporting/        Markdown + HTML report generator
  live/             Live network scanning (nmap, NSE, credential testing)
  targets/          LLM target connectors
  utils/            JSON helpers, smoothing, structured logging, timer
  cpp_ext/          C++ simulation engine (pybind11, optional)
docs/               User manual, glossary, CLI reference, architecture, FAQ, roadmap
examples/           Runnable example scripts
tests/              Pytest test suite
Dockerfile          Multi-stage Docker build
docker-compose.yml  Docker Compose configuration
```

## Development

```bash
pip install -e ".[dev]"
make test          # run tests
make lint          # ruff check
make format        # ruff format + fix
make typecheck     # mypy
make test-cov      # coverage report
```

Or with `just`:
```bash
just test        # run tests
just lint        # ruff check
just ci          # full CI check
just build       # build wheel
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for full development workflow.

## Live Network Module

ARCA can audit real networks (with authorization):

```python
from arca.live import RulesOfEngagement, LiveNetworkEnv

roe = RulesOfEngagement(["192.168.1.0/24"])
env = LiveNetworkEnv(cidr="192.168.1.0/24", roe=roe)
agent = ARCAAgent(env=env)
agent.load("models/agent")
agent.run_episode()
```

**Warning:** Only scan networks you own or have explicit written permission to test.

## Safety

ARCA models networks and does not authorize scanning, exploitation, or access to systems without explicit permission. Use it only in environments you own or are authorized to assess.

## License

MIT. The `LICENSE` file is always present at the repository root and in every wheel.
