Metadata-Version: 2.4
Name: arca-agent
Version: 1.9.4
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 — 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-1.5.0-blue.svg)](arca/__version__.py)
[![PyPI](https://img.shields.io/pypi/v/arca-agent.svg)](https://pypi.org/project/arca-agent/)

</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.

---

## Installation

```bash
# CPU-only (recommended default — most users do not need CUDA):
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install arca-agent

# With CUDA GPU support (requires NVIDIA drivers + CUDA toolkit):
pip install arca-agent[all]

# Minimal install (core simulation + API only, no extras):
pip install arca-agent

# Add specific features as needed
pip install arca-agent[live]       # live nmap scanning + paramiko
pip install arca-agent[llm-local]  # local LLM via llama-cpp
pip install arca-agent[gpu]        # stable-baselines3 for GPU RL training
pip install arca-agent[viz]        # Dash dashboard
pip install arca-agent[tui]        # Textual terminal UI
pip install arca-agent[pdf]        # PDF report export

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

### Resource Requirements (measured on Linux x86_64, CPU-only build)

| Operation | Peak RSS | Notes |
|-----------|----------|-------|
| `import arca` | ~14 MB | Lazy imports — torch NOT loaded yet |
| `ARCAAgent()` first instantiation | ~620 MB | Pulls in torch + torch_geometric |
| Minimal training (3 hosts, 200 steps) | ~680 MB | Full pipeline: train + run_episode |
| Realistic training (enterprise, 50k steps) | Not yet measured | Please report if you run this — open an issue/PR |
| Production API server (idle) | ~620 MB | Same as ARCAAgent() footprint |

These are measured peak RSS via `resource.getrusage(RUSAGE_SELF).ru_maxrss`.
Plan container/VM sizing with at least 1 GB for evaluation, 2 GB+ for production training.

### Known Environment Notes

- **WSL2 / Docker Desktop**: Windows Subsystem for Linux 2 caps memory at ~50% of host
  RAM by default. If you see OOM kills during training, create a `.wslconfig` file in
  your Windows `%USERPROFILE%` directory with `[wsl2] memory=8GB` (or your desired
  limit) and restart WSL (`wsl --shutdown`).
- **Docker**: Our images default to plain `torch` from PyPI which pulls CPU-only on
  arm64 and CUDA on amd64. For CPU-only Docker builds, use the included
  `Dockerfile.cpu` or set `--build-arg TORCH_INDEX=https://download.pytorch.org/whl/cpu`.
- **CI/GitHub Actions**: The 7 GB default runner memory is sufficient for the
  test suite (excluding `tests/test_arca.py` which needs ~1.5 GB for training tests).

## Quickstart

```bash
# Minimal smoke-test (~680 MB peak RSS, finishes in <60s on CPU):
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install arca-agent
arca train --preset small_office --timesteps 200
```

```bash
# Full example:
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 — training, auditing, live scanning, observability, security, API |
| [Glossary](docs/GLOSSARY.md) | Comprehensive terminology reference |
| [CLI Reference](docs/cli.md) | All CLI commands with flags and examples |
| [Architecture](docs/ARCHITECTURE.md) | System design, component details, data flow |
| [Benchmarks](docs/BENCHMARKS.md) | Performance benchmarks (C++, API, LLM) |
| [FAQ](docs/FAQ.md) | Frequently asked questions |
| [Comparison](docs/COMPARISON.md) | ARCA vs Caldera, Metasploit, Infection Monkey |

---

## CLI Commands (v1.5.0)

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 custom YAML network |
| `arca audit` | Run an evaluation episode and return a security audit report |
| `arca live-audit CIDR` | Run a live network audit with nmap + fingerprinting + CVE correlation |
| `arca dashboard` | Launch the interactive Dash operations console (v2 with themes) |
| `arca serve` | Start the FastAPI REST server (WebSocket, Prometheus, SSE) |
| `arca viz` | Export topology and vulnerability heatmap as HTML |
| `arca init-network` | Generate a YAML network template or run the interactive wizard |
| `arca show-cves` | List CVE definitions and reusable vulnerability templates |
| `arca cves update` | Fetch latest CVEs from NVD and update local cache |
| `arca cves search QUERY` | Search the 79-entry CVE database |
| `arca cves stats` | Show CVE database statistics |
| `arca models` | Manage saved models (list, save, load, delete) |
| `arca config` | Manage ARCA configuration (show, set, init) |
| `arca replay EPISODE_ID` | Replay saved episodes step by step |
| `arca repl` | 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 |
| `arca tui` | Launch the Textual-based terminal UI |

### 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, multi-format reports
# Note: GNN training saves .pt; .zip is also accepted (load() normalizes the extension).
arca audit --network home.yaml --model models/agent.zip --langgraph --format all

# Live network audit with SARIF + STIX export
arca live-audit 192.168.1.0/24 --fingerprints --format all

# CVE database management
arca cves stats
arca cves search log4shell
arca cves update --pages 5

# Interactive dashboard with theme support
arca dashboard --network home.yaml

# Terminal UI (Textual-based)
arca tui

# Start API with observability endpoints
arca serve --port 8000

# Manage models and config
arca models list
arca config show
arca config set rl.learning_rate 0.0005
```

## 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 with SARIF + STIX
from arca.reporting import ARCAReportGenerator
gen = ARCAReportGenerator()
gen.add_episode_buffer(agent.memory_buffer)
gen.save_html()

# Production observability
from arca.observability import get_logger, HealthMonitor, BackupManager
logger = get_logger("my-app")
monitor = HealthMonitor()
bm = BackupManager(); bm.create("daily")

# Security hardening
from arca.security import RBACManager, MFAManager, PolicyEngine
rbac = RBACManager(); rbac.create_user("admin", role="admin")
mfa = MFAManager(); secret = mfa.generate_secret()

# Multi-agent collaboration
from arca.integrations.advanced import MultiAgentOrchestrator, JiraConnector
orch = MultiAgentOrchestrator()
jira = JiraConnector(); ticket = jira.create_from_finding("CVE-2021-44228", 10.0, "10.0.0.1", "...")
```

## REST API

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

Key endpoints: `GET /`, `GET /health`, `GET /healthz`, `GET /readyz`, `GET /status`, `POST /train` (async), `POST /train/cancel`, `POST /audit`, `POST /reflect`, `POST /live/audit`, `POST /live/audit/stream` (SSE), `WS /ws/training`, `GET /metrics` (Prometheus), `GET /presets`, `GET /presets/{name}`, `GET /capabilities`, `GET /cves`, `GET /cves/templates`, `POST /visualizations/topology`, `POST /visualizations/vulnerability-heatmap`, `GET /live/sessions`, `POST /api/v1/keys/rotate`, `POST /api/v1/keys/revoke`, `GET /api/v1/keys`, `POST /reports/pdf`, `POST /api/v1/agents/register`, `GET /api/v1/agents`, `POST /api/v1/agents/{agent_id}/heartbeat`, `GET /api/v1/agents/{agent_id}/tasks`, `GET /api/v1/agents/{agent_id}/telemetry`, `POST /api/v1/telemetry`.

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

### Multi-instance / Containerized Deployments

ARCA stores two per-host secret files in `~/.arca/`:

| File | Purpose | Created |
|------|---------|---------|
| `~/.arca/key_pepper` | Per-deployment HMAC pepper for API key hashing | Auto-generated on first boot if `ARCA_KEY_PEPPER` is unset |
| `~/.arca/api_key` | Auto-generated API key (when `ARCA_API_KEY` is unset) | Auto-generated on first boot |

**Critical:** In multi-instance or ephemeral-filesystem deployments (Docker,
Kubernetes, any redeploy that doesn't persist `$HOME`), every instance or
redeploy silently regenerates both files, which:

- Invalidates all previously issued API keys deployment-wide
- Makes keys hashed on instance A fail validation on instance B

**To avoid this, do one of:**

1. **Mount a shared persistent volume** at `~/.arca/` across all instances, or
2. **Set both env vars explicitly and identically** on every instance:
   ```bash
   export ARCA_API_KEY="arca_<your-32-char-token>"
   export ARCA_KEY_PEPPER="<your-64-char-hex-pepper>"
   ```
   When both are set, `~/.arca/` files are not created or read.

## Project Layout (v1.5.0)

```
arca/                  Python package
  core/                Agent, configuration, PPO trainer, GNN policy, recurrent policy
  sim/                 Gymnasium env, CVE DB (79 entries), schema v2, YAML builder
  memory/              Persistent episode buffer, vector memory (RAG)
  agents/              LangGraph multi-agent orchestrator (8 nodes)
  graph/               LLM red-team audit workflow
  llm/                 Local LLM, Ollama, Groq, OpenAI providers
  training/            Curriculum, self-play, blue-team RL, Optuna tuning, VecEnv
  api/                 FastAPI server (WebSocket, Prometheus, SSE, rate-limited, auth)
  cli/                 Typer CLI (20+ commands)
  viz/                 Plotly figures, Dash dashboard v2, topology editor
  reporting/           Report generator, SARIF 2.1.0, STIX 2.1, comparison/i18n
  live/                Live network scanning (nmap, fingerprints, reporter)
  observability/       Structured logging, health monitor, alerting, audit agg, backup
  security/            RBAC (5 roles), MFA (TOTP), secrets mgmt, dep scanner, CIS
  integrations/        SIEM, Jira/ServiceNow ticketing, MISP, vuln scanner import
  client/              ARCAClient (sync + async) for REST API
  plugins/             Plugin system with entry-point discovery
  safety.py            Safety briefing, hash-chain audit, kill switch, canary detect
  benchmarks.py        Performance benchmark suite
  examples.py          8 ready-to-run examples
  migration.py         Version upgrade and compatibility tools
  tui.py               Textual-based terminal UI
docs/                  User manual, glossary, CLI reference, architecture, benchmarks, FAQ
examples/              Runnable example scripts
packaging/             Debian/RPM/Homebrew packaging specs
tests/                 Pytest test suite
Dockerfile             Multi-stage multi-arch Docker build
docker-compose.yml     Docker Compose configuration
```

## Key Features (v1.5.0)

### Observability
- Structured JSON logging with rotation, correlation/trace IDs, secret redaction
- Health monitoring (CPU, memory, disk, GPU) with Kubernetes probes
- Alerting engine with rules, deduplication, and escalation policies
- Centralized audit aggregation with search, stats, and CSV/JSON export
- Automated compressed backups with checksum verification and restore

### Integrations
- A2A multi-agent collaboration with task delegation and dependency resolution
- Jira and ServiceNow ticketing from CVE findings
- Vulnerability scanner import (Nessus, Qualys, OpenVAS, Burp) with deduplication
- MISP threat intelligence event creation and sharing
- SIEM connectors (Splunk, CrowdStrike, SentinelOne, FortiSOAR)

### Security Hardening
- Role-based access control (5 roles, 18 permissions)
- TOTP-based multi-factor authentication (Google Authenticator compatible)
- Multi-backend secrets management (Vault, AWS, GCP, Azure, file)
- Dependency vulnerability scanning (pip-audit integration)
- CIS benchmarks (Docker 8 controls, Kubernetes 6, Python 8)
- Security policy engine with compliance scoring

### Dashboard v2
- Interactive topology editor (drag-and-drop, YAML/JSON export)
- Report builder with custom sections, reorder, and toggle
- 4 color themes (dark, light, cyberpunk, solarized)
- Persistent user preferences

### Advanced Training
- Blue-team RL agent with Q-learning defense policy
- Multi-agent self-play training loop
- Optuna hyperparameter tuning with median pruner
- Weights & Biases experiment tracking
- Parallel VecEnv execution
- Checkpointing with early stopping
- Multi-agent debate reflection

### Network Schema v2
- 15+ host roles (router, switch, server, database, domain controller, PLC)
- Unidirectional weighted connections
- Network zones and VLANs
- NAT rules and static routes
- Credential store per host
- Time-to-compromise and detection probability
- MITRE ATT&CK mapping per action/CVE

## 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.

## Development

```bash
pip install -e ".[dev]"
# Fast tests (no RL training, ~15s):
pytest tests/ --ignore=tests/test_arca.py -q
# Full suite including RL training tests (~2 min, needs ~3 GB free RAM):
pytest tests/ -q
# RL tests in separate process (recommended for CI):
pytest tests/test_arca.py -q && pytest tests/ --ignore=tests/test_arca.py -q
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.

## Safety

ARCA models networks and does not authorize scanning, exploitation, or access to systems without explicit permission. The tool includes:
- Mandatory safety briefing on first run
- Tamper-evident hash-chain audit logging
- Kill switch (`ARCA_KILL_SWITCH_FILE`)
- Canary host detection
- Geographic IP blocking
- Usage telemetry (opt-in only)

Use ARCA 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.
