Deployment Path — Pick One
The Connector Node ships for three environments. Pick by where the targets live:
On-premises networks — Active Directory, physical or virtualised internal segments, Microsoft or Linux servers, workstations. Use the VM deployment. Continue to Step 1 below.
Cloud workloads on GCP or AWS. Use the corresponding cloud VM image. See Advanced Deployment.
Kubernetes clusters, especially production-adjacent workloads under compliance-heavy governance. Use the Kubernetes deployment — the only mode with AEGIS runtime protection. See Deployment Recommendation immediately below.
All three modes pair identically with the SpartanX platform and share the same scope firewall. Only the Kubernetes deployment carries AEGIS.
Deployment Recommendation
Kubernetes deployment is strongly recommended when it applies
Rationale for the Kubernetes recommendation, for customers whose environments include cloud or Kubernetes workloads. On-premises AD customers should follow the VM path above and skip to the topology section.
Deployment mode | Scope firewall (Phalanx) | AEGIS runtime protection | Recommended for |
VM (on-prem) | Yes | No | Lab, small internal segments, non-regulated engagements |
Cloud VM (GCE / AMI) | Yes | No | Cloud-hosted internal PoPs, non-regulated engagements |
Kubernetes | Yes | Yes | Regulated engagements, production-adjacent targets, compliance-heavy verticals |
Why AEGIS Matters
AEGIS is the destructive-action guardrail. It sits between the sandbox and every outbound HTTP request, inspects the target and the method, and blocks known-destructive operations (DELETE, DROP, purge, cleanup verbs) against endpoints outside an approved envelope. Without AEGIS, the only egress control is the scope firewall — allow/deny by host and port. That prevents traffic to unauthorised targets; it does not prevent a destructive operation against an authorised target.
For engagements against production-adjacent systems, financial infrastructure, healthcare workloads, or any target where an unintended write operation carries material business risk, AEGIS is the control that satisfies the governance requirement "the platform cannot destructively modify the target". VM and cloud VM deployments do not carry this control today.
If deployment mode is a choice, deploy on Kubernetes.
The VM and cloud VM guides below remain fully supported and are appropriate for lab work, small internal segments, and engagements without compliance-driven governance. The Kubernetes guide follows in the Cloud & Kubernetes section.
Architecture
Deployment topology — how the Connector Node fits your network
The Connector Node is a single scanning pivot placed inside the customer network. It is not an agent per host and not a routing gateway.
What it is
A dedicated VM (or pod) placed inside a network segment that reaches the targets in scope.
Runs the SpartanX agent, transparent proxy, and a local Jupyter kernel gateway.
Holds a single outbound tunnel to the SpartanX platform (WSS on 443).
Executes enumeration, discovery, and attack paths against internal targets on operator command from the platform.
What it is not
Not per-host software. No installer runs on Windows workstations, Windows servers, Linux servers, or domain controllers. Those assets receive no SpartanX code.
Not an in-line gateway. The Connector Node does not sit in the path of production traffic. It does not route, proxy, or intercept traffic that other assets originate. Removing it does not affect any production flow.
Not a domain member. The node never joins Active Directory. It operates from outside the authenticated identity boundary, and takes credentials only when the operator supplies them for a specific engagement (see On-premises Active Directory below).
Traffic model
Two independent flows:
Outbound tunnel to SpartanX — one persistent connection on 443 to relay.spartanx.ai, plus periodic control-plane traffic to api.spartanx.ai and nodes.spartanx.ai. This is the only link between the customer network and the SpartanX platform. All operator commands and result telemetry flow through it.
Inbound scanning inside the customer network — the node originates connections to targets in scope (RPC, LDAP, SMB, HTTP, RDP, WinRM, whatever the engagement requires). Everything the node can reach at the network layer defines the maximum footprint the operator can exercise.
The mental model is a pentest pivot: one endpoint inside the network, remotely operated by the SpartanX platform, executing traffic that a physical attacker on that segment would generate. Nothing else is installed anywhere.
On-Premises Deployment Context
Active Directory environments — placement, access, permissions
For internal engagements against Active Directory, Microsoft servers, Linux servers, and Windows workstations, the Connector Node is the correct deployment. This section covers the network and access decisions the customer's infrastructure team owns.
Network placement
Place the Connector Node on a segment that has direct Layer 3 reachability to the assets in scope — domain controllers, DNS resolvers, file servers, workstation subnets, and any other target the engagement requires. A flat internal LAN is fine; a segmented internal network is also fine as long as firewall rules permit the node to originate connections to the target segments on the ports below.
Avoid placing the node behind NAT, an SSL-terminating proxy, or a corporate web gateway relative to its targets. Those devices distort the fidelity of the pentest — the operator needs the same reachability a real attacker on that segment would have.
Typical target ports on Active Directory
The operator will exercise these depending on the engagement scope. Firewall rules from the node to the target subnets must permit the ports relevant to what the customer wants tested:
53 DNS · 88 Kerberos · 135 RPC endpoint mapper · 139 NetBIOS session · 389 LDAP · 445 SMB · 464 Kerberos password · 636 LDAPS · 3268 / 3269 Global Catalog · 3389 RDP · 5985 / 5986 WinRM · 49152–65535 RPC dynamic range.
Additional ports for application-specific tests (custom services, database endpoints) as declared in scope.
AD membership and identity boundary
The Connector Node does not join the Active Directory domain. It operates outside the identity boundary. The operator selects the identity posture for each engagement:
Unauthenticated — anonymous LDAP, SMB null sessions, network scanning, reachability enumeration. Default.
Authenticated low-privilege user — a standard domain account supplied by the customer, used to simulate an internal attacker with basic credentials (phished user, insider). Credentials are uploaded to the SpartanX platform and consumed by the node in-flight during the engagement.
Authenticated privileged user — used only for path verification, if the engagement scope explicitly authorises it.
The customer decides which posture applies per engagement. The node does not persist credentials to disk.
Setup permissions (customer side)
Virtualisation team — access to import the image into the hypervisor (VirtualBox / VMware / ESXi / Hyper-V / KVM / Proxmox) and assign an IP on the target segment. This is the only privileged action required to bring the node online.
Network team — firewall rules for outbound access to api.spartanx.ai, nodes.spartanx.ai, relay.spartanx.ai on 443, and internal reachability from the node to the target subnets.
Active Directory team — no involvement in setup. Only involved if the engagement scope requires domain credentials for authenticated testing (see above).
Setup does not require Domain Admin, Enterprise Admin, or any privileged Active Directory role. Bringing the Connector Node online is the same infrastructure action as importing any other virtual machine — hypervisor access plus a network IP.
AD credentials are only relevant if a specific engagement is scoped to include authenticated testing, and even then they are supplied per engagement through the SpartanX platform, not embedded in the node.
Credential handling for tested engagements
When an engagement requires AD credentials — for privilege escalation paths, lateral movement, Kerberoasting simulation, or any authenticated attack chain — the credentials are:
Uploaded to the SpartanX platform by the customer operator through the encrypted engagement panel.
Held encrypted at rest under the customer's tenant.
Delivered to the Connector Node in-memory over the mTLS tunnel for the duration of the engagement.
Never written to disk on the node, never logged, and scoped to the engagement that requested them.
Credentials are the customer's decision to supply and the customer's decision to revoke. Revocation invalidates any in-flight engagement using them.
Prerequisites
Two things from your image builder
The node image — OVA, VMDK, VHDX, or QCOW2. Ask the AI agent for the current download link and pick the format for your hypervisor.
The first-login credentials for the spartanx user. See the callout below.
CREDENTIALS — READ FIRST
Used only for the initial setup of a new internal node. After the first successful login, change the password on the installed machine and use that new password from then on.
The default user and first-login password rotate on every build. They are not embedded in the image.
Ask the AI agent inside the SpartanX platform for the current default user and password before every new setup. Credentials from a previous build will not work on a freshly built image.
Step 1: Import the Image
Pick the format for your hypervisor. The OVA carries a baked hardware envelope (4 vCPU / 8 GB RAM).
The raw disk formats (VMDK / VHDX / QCOW2) carry no hardware config, so set CPU / RAM when you create the VM — use at least 4 vCPU / 8 GB.
For GCP, AWS, or Kubernetes, skip this step and see the Cloud & Kubernetes section below.
VirtualBox (.ova) — File ▸ Import Appliance…, select the .ova, accept the baked defaults, raise CPU/RAM for heavy scans, and import.
VMware Workstation / Fusion / Player (.ova) — File ▸ Open…, select the .ova, name the VM and choose a storage path, then Import. Accept the OVF-spec warning if one appears.
VMware ESXi / vSphere (.ova) — in the vSphere / Host Client: Create ▸ Deploy from OVF, upload the .ova, pick the datastore and a bridged port group, and finish. CLI: ovftool spartanx-node-<version>.ova vi://<esxi-host>.
Hyper-V (.vhdx) — Hyper-V Manager ▸ New ▸ Virtual Machine. Use Generation 1 (the image is BIOS; Gen 2 UEFI will not boot). Startup memory ≥ 4096 MB. Attach to an External virtual switch. Use an existing VHD and select the .vhdx. Under Settings ▸ Processors, set virtual processors to ≥ 4.
KVM / QEMU (virt-manager) (.qcow2) — New VM ▸ Import existing disk image, select the .qcow2, set memory / CPU (≥ 8 GB / 4 vCPU), keep firmware on BIOS, attach the NIC to a bridge (e.g. br0), not the default NAT network.
Proxmox VE (.qcow2) — create a VM with no disk, then import and attach the disk:
bash
qm importdisk <vmid> spartanx-node-<version>.qcow2 <storage>
Attach the imported disk, set it first in Boot Order, leave the firmware on SeaBIOS (default), put the NIC on a Linux bridge (vmbr0), and boot.
Step 2: Set the Network Mode
A Connector Node must reach two networks at once:
Outbound internet — to reach the SpartanX platform (pairing, heartbeat, tunnel).
The private segment you want to scan — for example, 192.168.0.0/24.
Use a Bridged Adapter, not NAT. Bridged puts the VM directly on your physical LAN, so it gets an IP on the target segment and routes to the internet through your LAN gateway. NAT would give internet access but hide the node behind the host, so it could not reach the local segment as a peer.
VirtualBox — Settings ▸ Network ▸ Adapter 1 ▸ Attached to: Bridged Adapter, then pick the physical NIC on the segment to scan.
VMware — set the adapter to Bridged (replicate physical network state).
Hyper-V — connect the adapter to an External virtual switch bound to the physical NIC (Virtual Switch Manager ▸ New ▸ External).
KVM / libvirt — attach the NIC to a bridge (e.g. br0), not the default NAT network (virbr0).
Proxmox — put the NIC on a Linux bridge (vmbr0) bridged to the physical NIC.
Cloud VMs (GCP / AWS) reach the internet by default; ensure the instance also has a route or interface onto the private segment you want to scan.
Outbound endpoints — allow these through any corporate firewall (HTTPS on 443, tunnel on 443/8443):
Host | Purpose |
api.spartanx.ai | Pairing handshake |
nodes.spartanx.ai | Heartbeat + node control plane (mTLS) |
relay.spartanx.ai | Tunnel transport (WSS) |
Step 3: Boot and Log In
Boot the VM. On first boot a one-shot service locks the public Kali account; the only way in is the spartanx user.
Get the latest credentials first. Before logging in, request the current default user and first-login password from the AI agent inside the SpartanX platform. These credentials rotate on every build. If you downloaded a new image, ask again — older credentials will not work.
Log in over SSH (or the VirtualBox / VMware console):
bash
ssh <default-user>@<node-ip>
Use the first-login password provided by the AI agent.
The first login forces a password change (PAM). Enter the build password, then set a new one. This is expected.
Find <node-ip> from your DHCP server, your router's client list, or by running ip a on the console.
Step 4: Get a Pairing Code from the Dashboard
In the SpartanX platform:
Go to Red Teaming ▸ Connector Nodes ▸ Add Node.
Fill the form:
Node Name — a descriptive label (e.g. HQ_DataCenter_Segment).
Description — optional.
Network Segments (CIDR) — the segment this node provides access to (e.g. 192.168.0.0/24). Press Enter or click + to add each one.
Click Register Node. The node appears as Pairing in Progress.
In the Pairing Token panel, enter a reason for revealing the token (minimum 10 characters — recorded for audit), then click Reveal pairing token.
Copy the token now. It looks like sxn_pair_… and is single-use by the agent. Once the node finishes pairing it cannot be revealed again. While the node is still pairing you can re-reveal it with a new justification.
Step 5: Run the Pairing Command on the Node
The pairing command must run as root. On the node:
bash
sudo -i # root shell (uses the spartanx password)
spartanx-pair sxn_pair_<your_token>
For a production node against api.spartanx.ai the defaults are correct — no environment variables are needed. The control-plane endpoint is learned automatically from the pairing response.
A successful run prints all seven steps and ends with:
Pairing complete!
Node ID: <uuid>
Proxy: Phalanx transparent proxy active
Status: Connecting to relay...
The command enables and starts three services: phalanx, jupyter-kg, and spartanx-agent.
Step 6: Verify
On the node:
bash
systemctl status spartanx-agent phalanx
journalctl -u spartanx-agent -f
A healthy agent logs tunnel connected to relay and a heartbeat every 30 s with no rejections.
In the dashboard the node flips from Pairing in Progress to Connected, shows a recent Last seen, and reports its agent version as Up to date.
Advanced Deployment: Cloud & Kubernetes (GCP / AWS / Kubernetes)
The node also ships as a GCP GCE image, an AWS AMI, and an OCI container image for Kubernetes. These are not public downloads — access is granted per build. For engagements that require AEGIS runtime protection, choose the Kubernetes deployment (see Deployment Recommendation above).
Request access first. Ask the AI agent inside the SpartanX platform for connector-node image access, and send the identifier for your platform. Read access is granted to that identity — no credential is exchanged.
Platform | What you send us | What we grant |
GCP (GCE image) | Email of the IAM principal that will launch the VM — a service account (preferred, e.g. [email protected]) or a Google user account. | roles/compute.imageUser on the image for that principal. |
AWS (AMI) | Your 12-digit AWS account ID + the region you will launch in. | Your account added to the AMI's launch permissions (we copy the AMI into your region if needed); we reply with the AMI ID. |
Kubernetes (Artifact Registry) | Email of the GCP service account your cluster pulls with — on GKE the node pool SA or a Workload-Identity SA; on EKS or on-prem a GCP SA for your imagePullSecret. | roles/artifactregistry.reader on the image repository for that service account. |
A bare GCP project ID is not sufficient — GCP IAM grants access to principals (service accounts or users), not to projects.
GCP — Launch and Pair
bash
gcloud compute instances create spartanx-node \
--project=YOUR_PROJECT --zone=YOUR_ZONE \
--image-project=spartanx-public-images \
--image=spartanx-node-<version> \
--machine-type=e2-standard-4
The identity running this command must be the principal granted compute.imageUser. Then SSH into the instance and pair as in Steps 3 and 5. Give the instance a route or interface onto the private segment you want to scan.
AWS — Launch and Pair
bash
aws ec2 run-instances --region YOUR_REGION \
--image-id ami-XXXXXXXXXXXX \ # the AMI ID we send you
--instance-type t3.xlarge \
--key-name YOUR_KEY --subnet-id subnet-XXXXXXXX
SSH in as spartanx and pair as in Steps 3 and 5. Place the instance on a subnet that can reach the segment you want to scan.
Kubernetes — Recommended Deployment
The Kubernetes deployment is the only mode with AEGIS runtime protection. Deploy here for engagements against production-adjacent systems, financial infrastructure, healthcare, or any target where governance requires "the platform cannot destructively modify the target".
The pull identity must already have artifactregistry.reader (see the table above). The container needs NET_ADMIN + NET_RAW for the transparent proxy and must be able to reach the segment you want to scan (commonly hostNetwork: true).
yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: spartanx-node
spec:
replicas: 1
selector:
matchLabels: { app: spartanx-node }
template:
metadata:
labels: { app: spartanx-node }
spec:
hostNetwork: true
containers:
- name: spartanx-node
image: gcr.io/spartanx-public-images/nodex:<version>
securityContext:
capabilities:
add: ["NET_ADMIN", "NET_RAW"]
On GKE the node pool's service account (granted artifactregistry.reader) pulls directly. On EKS or on-prem, create an imagePullSecret from your puller service account and add imagePullSecrets to the pod spec. Pair by exec-ing into the pod:
bash
kubectl exec -it deploy/spartanx-node -- spartanx-pair sxn_pair_<token>
Reference: Troubleshooting
Symptom | Likely cause / fix |
First-login password rejected | Credentials rotate on every build and are only valid for initial setup. Ask the AI agent for the latest default user and password. If you already changed the password on the machine, use that one. |
Dashboard stays Pairing in Progress | The pairing command was not run, or it errored before completing. Re-check the node console output. |
spartanx-pair: must run as root | Run it under sudo -i (or sudo -E with the env vars inline). |
[4/7] … Error: pairing failed | The platform rejected the handshake. Confirm the token is correct and still Awaiting agent pairing, and that the node can reach api.spartanx.ai. |
Agent up, but heartbeat rejected by server status=403 | The agent is hitting the public API endpoint instead of the mTLS control-plane gateway. Production learns it automatically from the pairing response — re-pair to refresh it. |
Heartbeat tls: certificate signed by unknown authority | Outdated agent — the control-plane gateway serves a public (Let's Encrypt) cert. Rebuild the node from a current image. |
Node version shows Blocked | The agent build is too old or not advertising a version the platform accepts. Rebuild from a current image. |
Cannot reach the target segment | Network adapter is on NAT or the wrong physical NIC. Switch to Bridged on the NIC on the segment (Step 2). |