arca-agent 0.5.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 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

# 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

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, 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

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:

just test        # run tests
just lint        # ruff check
just ci          # full CI check
just build       # build wheel

See CONTRIBUTING.md for full development workflow.

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. The LICENSE file is always present at the repository root and in every wheel.