A Rust workspace for an authorized-engagement C2 / agent framework. Combines a libp2p-based mesh, an A2A gRPC control plane with mTLS + signed agent cards + a capability matrix + a hash-chained audit log, cross-platform agents with PTY-backed interactive shells, and a Tauri 2 + Leptos desktop operator console.
Use only with explicit authorization. rust-nexus is intended for authorized security testing, red-team engagements, and security research. See the Security Notice below.
v3.8 — in progress. Workspace trimmed from 14 to 9 crates; Linux
cgroup v2 sandbox and /proc observer implemented (WS1.5); GML
telemetry aggregator and adjustment layer foundations laid (WS2);
ATT&CK techniques consolidated into nexus-agent (WS4).
For the per-phase rollup see STATUS.md and
ROADMAP.md.
For the per-phase rollup and what's deferred to v1.4.x / v1.5, see
STATUS.md and ROADMAP.md.
Local single-box demo in ~15 minutes:
git clone <repo>
cd rust-nexus
cargo test --workspace --exclude nexus-console # 276/276 pass
./scripts/gen-certs.sh # dev mTLS certs
./scripts/demo.sh # headless PASS gateFor the full end-to-end walkthrough (server + agent + Tauri console
with interactive shell), see docs/deployment/local-dev.md.
For production rollouts, see
docs/deployment/README.md.
9 workspace members plus a Tauri UI sub-crate (excluded from the
workspace; built by Trunk for wasm32). v3.8 trimmed from 14 crates --
5 archived under archive/.
| Crate | Role |
|---|---|
nexus-common |
NodeIdentity (Ed25519 + X25519), sealed envelopes, OS detection, kernel context types, shared error / message types |
nexus-a2a |
A2A gRPC plane: server / client, signed AgentCards, mTLS, capability matrix, hash-chained audit log, rate limit + 4 MiB message cap, GML adjustment layer, SwarmCoordinator, SituationalAwareness |
nexus-mesh |
libp2p mesh transport (TCP + Noise + Yamux + Gossipsub + Identify + Ping + Kademlia + mDNS), DTN store-and-forward, telemetry aggregator |
nexus-infra |
C2 server runtime -- OperatorRouter, AgentRegistrar, SessionRegistry, RegistryLister, mTLS plumbing. Hosts A2A (:50052) alongside legacy NexusC2 (:50051) |
nexus-agent |
Cross-platform agent -- PTY shell, transports (gRPC / mesh / legacy), Linux cgroup v2 sandbox, /proc observer, consolidated ATT&CK techniques |
nexus-web-comms |
Transport trait abstraction + legacy HTTP / WebSocket transports |
nexus-recon |
Reconnaissance helpers |
nexus-console/src-tauri |
Tauri 2 operator console (Rust backend) -- connect dialog, agent list, shell session, audit viewer |
integration-tests |
Cross-crate integration tests (A2A loopback, mTLS round-trip, agent-side bidi PTY round-trip) |
Archived (v3.8): nexus-webui, nexus-hybrid-exec,
nexus-t1059-command-scripting, nexus-t1547-boot-logon-autostart,
nexus-t1021-006-winrm -- see archive/ for the original source.
ATT&CK techniques are consolidated into nexus-agent/src/techniques/.
| Excluded | Notes |
|---|---|
nexus-console/ui |
Leptos + WASM frontend; built by Trunk for wasm32-unknown-unknown |
+--------------------+ operator-A2A +--------------------+
| nexus-console | <─── mTLS + signed card ──► | nexus-infra |
| Tauri + Leptos | :50052 (Tonic 0.14) | C2 server |
| + xterm.js | | (NodeIdentity, |
+--------------------+ | AgentChannels, |
| capability |
+--------------------+ v1.2 agent-mode | matrix, audit |
| nexus-agent | <─ mTLS + AgentRegister ─► | sink, rate |
| (PTY shell, | :50052 first frame | limiter) |
| OS-aware shell | + per-session task_id | |
| select) | +────┬───────────────+
+--------------------+ │
│ (Tonic 0.10 lane
+--------------------+ legacy task-pull │ unchanged)
| overlay agents | <────────────────────────────────┘
| (Cloudflare DNS, | :50051
| BOF, fiber...) |
+--------------------+
Two gRPC services run on the same nexus-infra server process but on
separate ports: A2A on 50052 (v1.2 mTLS + signed cards + capability
gating + audit log + agent-mode bidi), and the legacy NexusC2 on 50051
(Tonic 0.10, untouched). Overlay agents from the v1.0 era keep
working via the legacy lane; v1.2 agents register on the A2A lane and
support interactive shells.
For the wire reference see
docs/enhancements/agent-swarm-mesh/v1.0/shell-session-protocol.md;
for the v1.2 API surface see
docs/enhancements/agent-swarm-mesh/v1.2/migration-from-v1.1.md.
All deployment operations are handled by scripts in scripts/.
| Script | Purpose |
|---|---|
scripts/gen-certs.sh |
Dev/test CA + certs (localhost only) |
scripts/gen-certs-prod.sh |
Production CA + server/operator/agent certs with correct SANs |
./scripts/gen-certs-prod.sh --domain c2.example.com --ip 1.2.3.4 --out ./certs/prod| Script | Purpose |
|---|---|
scripts/transfer-prep.sh |
Stages the server binary, certs, config, and a one-shot setup script into scripts/transfer/ ready to SCP to a remote host |
scripts/transfer/remote-host-prep.sh |
Generated by transfer-prep.sh. Run as root on the remote host to install everything and start the service |
# Stage + get ready-to-run scp/ssh commands
./scripts/transfer-prep.sh --ip 1.2.3.4 --user ubuntu
# One-liner output by the script:
scp -r scripts/transfer/ ubuntu@1.2.3.4:~/nexus-transfer/ && \
ssh ubuntu@1.2.3.4 'sudo bash ~/nexus-transfer/remote-host-prep.sh'| Script | Purpose |
|---|---|
scripts/build-agent-bundles.sh |
Builds the agent binary, mints per-host client certs, and packages into zip bundles |
scripts/deliverables-prep.sh |
One-command wrapper — builds Linux and/or Windows bundles with configurable counts |
# 3 Linux + 3 Windows bundles, C2 address pre-baked
./scripts/deliverables-prep.sh --lin-count 3 --win-count 3 --ip c2.example.com| Script | Purpose |
|---|---|
scripts/deploy-operator-console.sh |
Builds the Tauri console, wires cert env vars, and launches |
scripts/operator-package.sh |
Packages the console binary + operator certs into a distributable folder (with optional --zip) |
# Build + launch (auto-detects certs/prod/)
NEXUS_SERVER_ADDR=https://c2.example.com:50052 ./scripts/deploy-operator-console.sh
# Package for distribution to an operator workstation
./scripts/operator-package.sh --ip c2.example.com --zip- mTLS via reserved env vars:
NEXUS_CA_CERT,NEXUS_SERVER_CERT,NEXUS_SERVER_KEY,NEXUS_CLIENT_CERT,NEXUS_CLIENT_KEY— seenexus-a2a/src/tls.rs. - Ed25519-signed AgentCards with canonical-JSON encoding — see
nexus-a2a/src/cards.rs. - Per-agent capability matrix (HashMap-backed JSON; nalgebra
MatrixRouter queued for v1.3) — see
nexus-a2a/src/capabilities.rsandconfig/capabilities.example.json. - Hash-chained audit log (
BLAKE3(prev || record)) with anaudit_verifyCLI — seenexus-a2a/src/audit.rsandnexus-a2a/src/bin/audit_verify.rs. - Token-bucket rate limit + 4 MiB message size cap — see
nexus-a2a/src/interceptors.rs. - Agent-side A2A bidi — operator → C2 → agent → PTY → response —
see
nexus-agent/src/a2a_client.rs. - Tauri 2 + Leptos operator console — see
nexus-console/anddocs/deployment/operator-console.md. - CI codesigning for macOS + Windows Tauri bundles — see
.github/workflows/tauri-build.ymlanddocs/enhancements/agent-swarm-mesh/v1.2/codesigning.md.
The complete defense matrix and threat model is at
docs/enhancements/agent-swarm-mesh/v1.2/security-overview.md.
| What you want | Where to look |
|---|---|
| Local-dev quickstart | docs/deployment/local-dev.md |
| Production deployment | docs/deployment/production.md |
| Operator console distribution | docs/deployment/operator-console.md |
| Day-2 operations / runbook | docs/deployment/operations.md |
| Generate production certs | scripts/gen-certs-prod.sh |
| Stage server files for remote host | scripts/transfer-prep.sh |
| Build + package agent bundles | scripts/deliverables-prep.sh |
| Package operator console | scripts/operator-package.sh |
| v1.2 security overview | docs/enhancements/agent-swarm-mesh/v1.2/security-overview.md |
| v1.2 migration notes (from v1.1) | docs/enhancements/agent-swarm-mesh/v1.2/migration-from-v1.1.md |
| Tauri codesigning (CI) | docs/enhancements/agent-swarm-mesh/v1.2/codesigning.md |
| Wire reference (shell-session protocol) | docs/enhancements/agent-swarm-mesh/v1.0/shell-session-protocol.md |
| Project status + version | STATUS.md |
| Roadmap / decisions log | ROADMAP.md |
| Per-PR / development notes | CLAUDE.md, docs/development/ |
# Workspace builds (excludes the Tauri shell — that needs libwebkit2gtk).
cargo check --workspace --exclude nexus-console
cargo test --workspace --exclude nexus-console
cargo clippy --workspace --exclude nexus-console --all-targets -- -D warnings
cargo fmt --all --check
# Tauri UI compiles for wasm32 via trunk:
cd nexus-console/ui && cargo build --target wasm32-unknown-unknown && cd ../..
# Headless PASS gate (integration-tests/A2A loopback):
./scripts/demo.shDevelopment notes live under docs/development/;
the working agreement for AI-assisted contributions is in
CLAUDE.md.
- Mixed Tonic versions are intentional. The new A2A plane uses
Tonic 0.14 (
tonic_14 = { package = "tonic", ... }) while the legacy NexusC2 plane stays on Tonic 0.10. Both compile side-by-side. NEXUS_*_CERTenv var names are reserved. Do not rename. They are referenced from operator docs, CI workflows, and operator consoles built in the field.shared NodeIdentitybetween the mesh (libp2p) and A2A (signed cards). One identity per node — do not introduce a second key.- No AGPL code paths. rust-nexus replicates GhostWire-style mesh primitives directly from MIT/Apache libp2p crates rather than embedding the AGPL-licensed GhostWire crate.
For the full set of decisions (D-V1.0-A through D-V1.2-H, plus the
v2.1.2 series), see ROADMAP.md.
rust-nexus is designed for authorized security testing, red-team engagements, and security research. Users must:
- Ensure compliance with applicable laws and regulations.
- Obtain explicit written authorization before deployment against any system, network, or organization you do not own.
- Follow responsible disclosure for any vulnerabilities discovered using this framework.
- Respect system, network, and organizational boundaries.
The authors are not responsible for misuse of this software.
This project is licensed under the MIT License — see LICENSE.