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

---

Installation

# Full install with all optional features
pip install arca-agent[all]

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

# CPU-only: install torch for CPU first, then arca
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install arca-agent

> **Memory note:** `import arca` alone uses <1 MB RSS. First `ARCAAgent()` instantiation
> pulls in torch + torch-geometric (~620 MB RSS measured on Linux x86_64, CPU-only
> build). Plan container/VM sizing accordingly.

# 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]"

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 — training, auditing, live scanning, observability, security, API
Glossary	Comprehensive terminology reference
CLI Reference	All CLI commands with flags and examples
Architecture	System design, component details, data flow
Benchmarks	Performance benchmarks (C++, API, LLM)
FAQ	Frequently asked questions
Comparison	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

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

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

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:

   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):

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

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.

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.