arca-agent 0.4.0

ARCA — Recursive GNN+RL Autonomous Cyber Agent with Local LLM reflection

ARCA

Autonomous Reinforcement Cyber Agent — local, synthetic & live network security simulation.

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

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	Full user manual — installation, training, auditing, live scanning, API, dashboard, reports
Glossary	Comprehensive terminology reference
CLI Reference	All CLI commands with flags and examples

---

Install

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 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 scan	Scan LAN for reachable Ollama endpoints
arca info	Print version, PyTorch, CUDA, C++ extension status
arca health	Check LLM provider connectivity

Examples

# 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

# Interactive dashboard
arca dashboard --network home.yaml

# Start API
arca serve --port 8000

Python API

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

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.

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
examples/           Runnable example scripts
tests/              Pytest test suite

Development

pip install -e ".[dev]"
pytest
ruff check arca tests

Live Network Module

ARCA can audit real networks (with authorization):

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. See LICENSE if included with your distribution.